Previous section.

Networking Services (XNS) Issue 5
Copyright © 1997 The Open Group

SNA Transport Provider

Introduction

This Appendix includes:

This Appendix also defines data structures and constants required for NetBIOS transport providers which are exposed through <xti_sna.h> header file.

Applications written to compilation environments earlier than those required by this issue of the specification (see Headers and Definitions for XTI ) and defining _XOPEN_SOURCE to be less than 500, will have these data structures and constants exposed through the inclusion of <xti.h> on platforms where XTI interface use is supported for SNA transports.

SNA Transport Protocol Information

This section describes the protocol-specific information that is relevant for Systems Network Architecture (SNA) transport providers.

General

  1. Protocol address

    For information about SNA addresses, see SNA Addresses .

  2. Connection establishment

    Native SNA has no confirmed allocation protocol for full duplex conversations. When a conversation is allocated, the connection message is buffered and sent with the first data that is sent on the conversation. When the t_connect() or t_rcvconnect() function completes, connectivity has been established to the partner node, but not to the partner program. Since notification that the partner is not available may occur later, the disconnection reasons returned on t_rcvdis() include [T_SNA_CONNECTION_SETUP_FAILURE], indicating that the connection establishment never completed successfully.

    An SNA program that needs to know that the partner is up and running before it proceeds sending data must have its own user-level protocol to determine if this is so.

  3. Parallel connections

    LU 6.2 allows multiple, simultaneous connections between the same pair of addresses. The number of connections possible between two systems depends on limits defined by system administrators.

  4. Sending data of zero octets is supported.

  5. Expedited data

    In connection-oriented mode, expedited data transfer can be negotiated by the two transport providers during connection establishment. Expedited data transfer is supported if both transport providers support it. However negotiation between transport users is not supported. Therefore the expedited option is read-only.

  6. t_close()

    The semantics of t_close() on an SNA Transport Provider is simplex orderly, that is, the send pipe of the XTI application issuing the t_close() is closed, but the receive pipe remains open. Any data sent prior to the t_close() will be delivered to the partner.

  7. SNA buffers data from multiple t_snd() functions until the SNA send buffer is full, allowing multiple records to be sent in one transmission. However, users sometimes have reasons for ensuring that a record is sent immediately. By setting the T_PUSH flag on the t_snd() function, the transport user causes data to be transferred without waiting for the buffer to be filled.

    In order to take advantage of the performance improvement that SNA buffering offers, the XTI user must set the T_SNA_ALWAYS_PUSH option to T_NO (default is T_YES). If this option is not set to T_NO, a push will be done for every t_snd() and the T_PUSH flag will have no effect.

  8. Programs migrated to SNA from other transport providers may want every t_snd() to cause a message to be sent immediately in order to match behaviour on the original provider. The default of this option is T_YES; thus the default is that a t_snd() will always be sent out immediately.

SNA Addresses

In an SNA environment, the protocol address always includes a network-ID-qualified logical unit (LU) name. This is the address of the node where the program resides.

For the t_connect() and t_sndudata() functions, the address also contains a transaction program name (TPN), identifying the program addressed in the partner node. A file descriptor used to accept incoming connection requests should have a complete SNA name, including TPN, bound to it with t_bind().

A file descriptor used for outgoing connection requests may optionally have only a network-id-qualified LU name bound to it.

Since the t_listen() returns only the LU name part of the address, this address is not adequate for opening up a connection back to the source. The transport user must know the TPN of its partner by some mechanism other than XTI services.

However, t_rcvudata() returns the complete address of the partner that can be used to send a datagram back to it.

An SNA address has the following structure. When the TPN is not included, the TPN length (sna_tpn_length) is set to zero, and the string that follows is null. 

 

/* The definitions for maximum LU name and netid lengths have specific  */
/* values because these maxima are a fixed SNA characteristic,          */
/* not an implementation option.  Maximum TP length is a implementation */
/* option, although the maximum maximum is 64.                          */

#define T_SNA_MAX_NETID_LEN   8

#define SNA_MAX_NETID_LEN     8    (LEGACY)
#define T_SNA_MAX_LU_LEN      8

#define SNA_MAX_LU_LEN        8    (LEGACY)
#define T_SNA_MAX_TPN_LEN     

#define SNA_MAX_TPN_LEN            (LEGACY)

struct sna_addr{
    u_char  sna_netid    (T_SNA_MAX_NETID_LEN),
    u_char  sna_lu       (T_SNA_MAX_LU_LEN),
    u_short sna_tpn_len,    /* less than or equal to T_SNA_MAX_TPN_LEN */
    u_char  sna_tpn      (sna_tpn_len)
   }

Notes:

  1. network-identifier (sna_netid): The address can contain either an SNA network identifier or the defined value, SYS_NET, which indicates that the predefined network identifier associated with the local system should be used.

  2. IBM Corporation provides a registration facility for SNA network identifiers to guarantee global uniqueness. (See IBM document G325-6025-0, SNA Network Registry).

  3. LU name (sna_lu): The address can contain either a specific LU name or the defined value, SYS_LU, which indicates that the system default LU name is to be used.

  4. LU name and network identifier fields are fixed length. For values shorter than 8 characters, they are blank filled to the right.

  5. Transaction program name (sna_tpn): This field can take one of three values:

    • Null value: No transaction program name is to be associated with the file descriptor.

      This is adequate for file descriptors used for outgoing connection requests.

      If no transaction program is associated with a file descriptor when a t_listen(), t_rcvudata(), or t_sndudata() is issued, the function will return a TPROTO error.

    • Specified value: A value that will be known by a partner program; for example, a well-known transaction program name used by a server.

    • Defined value, DYNAMIC_TPN: An indication that the system should generate a TP name for the file descriptor.

  6. The values SYS_NET, SYS_LU and DYNAMIC_TPN may not be used as real values of the sna_netid, sna_lu or sna_tpn fields, respectively.

Options

Options are formatted according to the structure t_opthdr as described in The Use of Options in XTI . A transport provider compliant to this specification supports none, all, or any subset of the options defined in Connection-Mode Service Options .
Connection-Mode Service Options
The protocol level of all subsequent options is SNA.

All options have end-to-end significance. Some may be negotiated in the XTI states T_IDLE and T_INCON, and all are read-only in all other states except T_UNINIT.

Options for Service Quality and Expedited Data
SNA Options shows the SNA options that affect the quality of a connection and the transport service level provided.

Option Name Type of Legal Option Value Meaning
  Option Value    
T_SNA_MODE char T_SNA_BATCH
T_SNA_BATCHSC
T_SNA_INTER
T_SNA_INTERSC
T_SNA_DEFAULT
any user-defined SNA mode value 		SNA mode, which controls the underlying class of service selected for the connection. The SNA mode is specified only by the active side of the connection.

If not specified, the default mode is T_SNA_DEFAULT.

The default mode characteristics may vary from system to system.

T_SNA_ALWAYS_PUSH t_uscalar_t T_YES / T_NO If T_YES, every t_snd() operation will cause the message to be sent immediately.

If T_NO, the data from a t_snd() operation may be buffered and sent later. The transport user can set the T_PUSH flag on a t_snd() function call to cause the data to be sent immediately.

Default value is T_NO.

This option is primarily for programs migrated to SNA from other protocol stacks that always send data immediately. It allows them to request behaviour similar to that on the original provider. However, setting T_SNA_ALWAYS_PUSH to T_YES may affect its performance.

Table: SNA Options

Functions

t_accept()
Since user data is not exchanged during connection establishment, the parameter call->udata.len must be 0.

t_bind()
The addr field of the t_bind structure represents the local network-id-qualified LU name of the local logical unit and the transaction program name of the program issuing the t_bind() function.

If the endpoint was bound in the passive mode (that is, qlen > 0) and the requested address has a null transaction program subfield, the function completes with the T_BADADDR error.

t_connect()
The sndcall->addr specifies the network-ID-qualified LU name and transaction program name of the remote connection partner.

An SNA transport provider allows more than one connection between the same address pair.

Since user data cannot be exchanged during the connection establishment phase, sndcall->udata.len must be set to 0. On return, rcvcall->udata.maxlen should be set to 0.

t_getinfo()
In all states except T_DATAXFER, the function t_getinfo() returns in the parameter info the same information that was returned by t_open(). In T_DATAXFER state, however, the information returned may differ from that returned by t_open(), depending on whether the remote transport provider supports expedited data transfer. The fields of info are set as defined in the table below.

Parameters Before Call After Call
fd x /
info->addr / 82
info->options / x 1
info->tsdu / T_INFINITE (-1)
info->etsdu / T_INVALID (-2) / 86 2
info->connect / T_INVALID (-2)
info->discon / T_INVALID (-2)
info->servtype / T_COTS_ORD
info->flags / T_SNDZERO

Table: Fields for info Parameter
Notes:

  1. x means an integral number greater than zero.

  2. Depending on the negotiation of expedited data transfer.

t_getprotaddr()
The boundaddr value includes the transaction program name of the local program.

The peeraddr value (if any) includes only the network-ID-qualified LU name of the partner.

t_listen()
The call->addr structure contains the network-ID-qualified LU name of the remote partner.

t_open()
The default characteristics returned by t_open() are shown in the table below.

Parameters Before Call After Call
name x /
oflag x /
info->addr / 82
info->options / x 1
info->tsdu / T_INFINITE (-1)
info->etsdu / T_INVALID (-2) / 86 2
info->connect / T_INVALID (-2)
info->discon / T_INVALID (-2)
info->servtype / T_COTS_ORD
info->flags / T_SNDZERO

Table: Default Characteristics returned by t_open()
Notes:

  1. x means an integral number greater than 0.

  2. Expedited data may or may not be supported by the local transport provider.

t_rcv()
If expedited data arrives after part of a TSDU (logical record) has been retrieved, receipt of the remainder of the TSDU will be suspended until after the ETSDU has been processed. Only after the full ETSDU has been retrieved (T_MORE not set), will the remainder of the TSDU be available to the user.

t_rcvconnect()
Since no user data can be returned on t_rcvconnect(), the call->udata.len should be set to 0 before the function is invoked.

t_rcvdis()
Since user data is not sent during disconnection, the value discon->udata.len should be set to 0 before t_rcvdis() is called.

The following disconnection reason codes are valid for any implementation of an SNA transport provider under XTI: 

 

#define T_SNA_CONNECTION_SETUP_FAILURE.

#define SNA_CONNECTION_SETUP_FAILURE.     (LEGACY)
#define T_SNA_USER_DISCONNECT

#define SNA_USER_DISCONNECT               (LEGACY)
#define T_SNA_SYSTEM_DISCONNECT

#define SNA_SYSTEM_DISCONNECT             (LEGACY)
#define T_SNA_TIMEOUT

#define SNA_TIMEOUT                       (LEGACY)
#define T_SNA_CONNECTION_OUTAGE

#define SNA_CONNECTION_OUTAGE             (LEGACY)

These definitions are exposed by the inclusion of <xti_sna.h>.

t_snd()
Unless the T_SNA_ALWAYS_PUSH option is set to T_YES or the T_PUSH flag on the t_snd() function is set, the SNA transport provider may collect data in a send buffer until it accumulates a sufficient amount for transmission. The amount of data that is accumulated can vary from one connection to another.

In order to take advantage of the performance improvement that SNA buffering offers, the XTI user must set the T_SNA_ALWAYS_PUSH option to T_NO (Default is T_YES). If this option is not set to T_NO, a push will be done for every t_snd() and the T_PUSH flag will have no effect.

t_snddis()
Since no user data is sent during a disconnection operation, call->udata.len should be set to 0 before the call to t_snddis().

t_sndudata()
The unitdata->addr field contains the full SNA address, including network-id-qualified LU name and transaction program identifier, of the remote partner.

If address associated with the file descriptor has a null transaction program name subfield, the function completes with the TPROTO error.

The unitdata->opt structure may contain an SNA mode governing the transmission of the data. For example, the program may confine data transmission to secure lines by selecting the T_SNA_INTERSC or T_SNA_BATCHSC modes.

Mapping XTI to SNA Transport Provider

This section presents the mapping of XTI functions to Full Duplex (FDX) LU 6.2.

First, several flow diagrams are given to illustrate the function of the XTI Mapper. Following this, mapping tables are given that show the FDX LU 6.2 verbs that the XTI Mapper needs to generate for each XTI function. For each XTI function that maps to a FDX verb, an additional table is referenced that gives the mappings of each parameter. Finally, a table shows mapping of LU 6.2 FDX return codes to XTI events.

The use of FDX LU 6.2 verbs in this section is for illustrative purposes only and is analogous to OSI's use of service primitives, that is, as a way to explain the semantics provided by the protocol. The FDX LU6.2 verbs are used only to help in understanding the SNA protocol, and are not a required part of an implementation.

General Guidelines

General guidelines for mapping XTI to an SNA transport provider are listed below:
Table: FDX LU 6.2 Verb Definitions

FDX Verb Description
ALLOCATE Allocates a conversation between the local transaction program and a remote (partner) transaction program.
DEALLOCATE DEALLOCATE with TYPE(FLUSH) closes the local program's send queue. Both the local and remote program must close their send queues independently.

DEALLOCATE with TYPE(ABEND_PROG) is an abrupt termination that will close both sides of the conversation simultaneously.

FLUSH Flushes the local LU's send buffer.
GET_ATTRIBUTES Returns information pertaining to the specified conversation.
GET_TP_PROPERTIES Returns information pertaining to the transaction program issuing the verb.
RECEIVE_ALLOCATE Receives a new conversation with a partner transaction program that issued ALLOCATE.
RECEIVE_AND_WAIT Waits for data to arrive on the specified conversation and then receives the data. If data is already available, the program receives it without waiting.
RECEIVE_EXPEDITED_DATA Receives data sent by the remote transaction program in an expedited manner, via the SEND_EXPEDITED_DATA verb.
SEND_DATA Sends data to the remote transaction program.
SEND_EXPEDITED_DATA Sends data to the remote transaction program in an expedited manner. This means that it may arrive at the remote transaction program before data sent earlier via a send queue verb - for example, SEND_DATA.
WAIT_FOR_COMPLETION Waits for posting to occur on one or more non-blocking operations represented in the specified wait objects. Posting of a non-blocking operation occurs when the LU has completed the associated non-blocking verb and filled all the return values.

Flows Illustrating Full Duplex Mapping

The following diagrams show mappings from the XTI function calls for active connection establishment to SNA verb sequences. The first Active Connection Establishment, Blocking Version (1 of 2) is used for blocking XTI calls; the second Active Connection Establishment, Non-blocking Version (2 of 2) is used for non-blocking calls.
Figure: Active Connection Establishment, Blocking Version (1 of 2)
Annotations

  1. GET_ATTRIBUTES is issued after the session is established and before the return for the t_connect. This is only done if the mode name, or partner LU name are required on the return to t_connect. This would be indicated by a non-zero value in either the rcvcall->addr.buf or eercvcall->opt.buf fields on t_connect.

Figure: Active Connection Establishment, Non-blocking Version (2 of 2)
Annotations

  1. The XTI application will issue a t_rcvconnect as a poll to see if the t_connect has completed. The t_rcvconnect will cause a WAIT_FOR_COMPLETION, with time=0, to be issued. The WAIT_FOR_COMPLETION will check on the wait object from the previous non-blocking ALLOCATE.

    When the t_connect has completed successfully a GET_ATTRIBUTES is issued if the mode name, or partner LU name are required on the return of the t_rcvconnect.

    After the GET_ATTRIBUTES, a non-blocking RECEIVE_AND_WAIT is issued to post a receive for any incoming data.

The next three diagrams show possible mappings of SNA Attach processing for an incoming connection to the series of XTI calls on the passive side of a connection.

The first Passive Connection Establishment, Instantiation Version (1 of 3) uses the native SNA instantiation mechanism; that is, programs are instantiated when the connection request arrives. This requires that the TP name (that is, the XTI application name) is known as part of the LU definition. This is before the t_bind is issued.

The second Passive Connection Establishment, Blocking Version (2 of 3) is a blocking use of the interface, where the SNA transport provider allows a connection request to be received by an existing program. This model, although not described in the architecture, is supported by many SNA products.

The third Passive Connection Establishment, Non-blocking Version (3 of 3) is a non-blocking use of the interface, where the SNA transport provider allows a connection request to be received by an existing program. This model is described as part of the FDX architecture.

Figure: Passive Connection Establishment, Instantiation Version (1 of 3)
Annotations

  1. If qlen in t_bind is > 0, a RECEIVE_ALLOCATE will be issued for each connection request that can be queued. When the RECEIVE_ALLOCATE completes successfully a GET_ATTRIBUTES is issued only if the mode name, or partner LU name are required on the return to t_listen.

  2. The t_accept will cause a RECEIVE_AND_WAIT to be issued. The RECEIVE_AND_WAIT is issued to post a receive for any incoming data.

Figure: Passive Connection Establishment, Blocking Version (2 of 3)
Annotations

  1. The t_bind will cause a blocking RECEIVE_ALLOCATE to be issued for each connection request that can be queued.

  2. When the RECEIVE_ALLOCATE completes successfully a GET_ATTRIBUTES is issued only if the mode name, or partner LU name are required on the return to t_listen.

  3. The t_accept will cause a RECEIVE_AND_WAIT to be issued. The RECEIVE_AND_WAIT is issued to post a receive for any incoming data.

Figure: Passive Connection Establishment, Non-blocking Version (3 of 3)
Annotations

  1. The t_bind will cause a non-blocking RECEIVE_ALLOCATE to be issued for each connection request that can be queued.

  2. A t_listen is used as a poll to see if a connection request has been received. The t_listen will cause a WAIT_FOR_COMPLETION, with time=0, to be issued. The WAIT_FOR_COMPLETION will check on the wait object from the previous non-blocking RECEIVE_ALLOCATE. In this example, when the first t_listen is issued, the RECEIVE_ALLOCATE is still outstanding; but the RECEIVE_ALLOCATE has completed before the second t_listen is issued.

  3. When the WAIT_FOR_COMPLETION indicates that the RECEIVE_ALLOCATE has completed successfully, a GET_ATTRIBUTES is issued only if the mode name, or partner LU name are required on the return to t_listen.

  4. The t_accept will cause a RECEIVE_AND_WAIT to be issued. The RECEIVE_AND_WAIT is issued to post a receive for any incoming data.

The next diagram, XTI Function to LU 6.2 Verb Mapping: Blocking t_snd , shows the mapping for the blocking XTI t_snd() call. The diagram after this, XTI Function to LU 6.2 Verb Mapping: Non-blocking t_snd , shows the non-blocking mapping of the XTI t_snd() call.
Figure: XTI Function to LU 6.2 Verb Mapping: Blocking t_snd

  1. The blocking t_snd will cause a blocking SEND_DATA to be issued. This will block until the LU accepts and queues all the data being sent.

    If EXPEDITED=YES, the mapper will issue a SEND_EXPEDITED_DATA verb rather than the SEND_DATA.

  2. When the SEND_DATA returns, a WAIT_FOR_COMPLETION, with time=0, is issued to see if the wait object for any outstanding non-blocking LU 6.2 verbs have been posted. At a minimum, there will be an outstanding RECEIVE_AND_WAIT, waiting for any incoming data, that needs to be checked. If any wait objects have been posted, the return code on the t_snd is set to TLOOK. This will inform the XTI application to issue a t_look to see what has been posted.

Figure: XTI Function to LU 6.2 Verb Mapping: Non-blocking t_snd

  1. The XTI mapper needs to either accept all the data being sent, or none of it. In this case, all the data is accepted, thus the non-blocking t_snd causes a non-blocking SEND_DATA to be issued.

    The XTI mapper then needs to issue a WAIT_FOR_COMPLETION to see if any other blocking LU 6.2 verbs have completed. This case is not shown in this diagram.

    If EXPEDITED=YES, the mapper will issue a SEND_EXPEDITED_DATA verb rather than the SEND_DATA.

  2. When a subsequent XTI verb is issued (for example, t_rcv or t_send), a WAIT_FOR_COMPLETION, with time=0, is issued to see if the wait object for any outstanding non-blocking LU 6.2 verbs have been posted. In this case, one of the wait objects will be the one associated with the non-blocking SEND_DATA. If any wait objects have been posted, the return code on the t_snd is set to TLOOK. This will inform the XTI application to issue a t_look to see what has been posted.

    There may be an additional LU 6.2 verb issued due to the subsequent XTI verb that was issued. This is not shown in the above diagram.

The next diagram, XTI Function to LU 6.2 Verb Mapping: Blocking t_rcv , shows the mapping for blocking XTI receive call, and the diagram after this, Mapping from XTI Calls to LU 6.2 Verbs (Passive side) , shows the mapping for non-blocking XTI receive call.
Figure: XTI Function to LU 6.2 Verb Mapping: Blocking t_rcv

  1. There is always an outstanding non-blocking RECEIVE_AND_WAIT, this is true whether the XTI application is using blocking or non-blocking mode. This is to post a receive for any incoming data.

    In this diagram, the outstanding RECEIVE_AND_WAIT was issued when the connection was setup. This could be as a result of either a t_accept or t_connect.

  2. When the XTI issues a blocking t_rcv, the XTI mapper will issue a blocking WAIT_FOR_COMPLETION to wait on the wait object associated with the outstanding RECEIVE_AND_WAIT. This will block until data is received on this connection.

  3. When data is received, the mapper needs to issue a non-blocking RECEIVE_AND_WAIT to replace the one that just completed.

  4. Issue a WAIT_FOR_COMPLETION, with time=0, to see if any other outstanding wait objects have been posted.

Figure: Mapping from XTI Calls to LU 6.2 Verbs (Passive side)

  1. There is always an outstanding non-blocking RECEIVE_AND_WAIT, this is true whether the XTI application is using blocking or non-blocking mode. This is to post a receive for any incoming data.

    In this diagram, the outstanding RECEIVE_AND_WAIT was issued when the connection was setup. This could be as a result of either a t_accept or t_connect.

  2. When the XTI application issues a non-blocking t_rcv, the XTI mapper will issue a WAIT_FOR_COMPLETION, with T=0, to see if the wait object for the outstanding RECEIVE_AND_WAIT has been posted. When the wait object has been posted, the XTI mapper needs to pass the data to the XTI application buffer.

    It is possible that the amount of incoming data in the XTI mapper buffer is more than the XTI application stated on the t_rcv. In this case, the XTI Mapper will set the TMORE flag. Then, when the next t_rcv is issued, the remaining data will be passes to the XTI application BEFORE issuing the WAIT_FOR_COMPLETION to check the wait object on the outstanding RECEIVE_AND_WAIT.

  3. When data is received, the mapper needs to issue a non-blocking RECEIVE_AND_WAIT to replace the one that just completed.

  4. Issue a WAIT_FOR_COMPLETION, with time=0, to see if any other outstanding wait objects have been posted.

Full Duplex Mapping

The following table shows the mapping from XTI function calls to full duplex LU 6.2 verbs.

Table: XTI Mapping to LU 6.2 Full Duplex Verbs

XTI Function SNA FDX LU6.2 verb Comments
t_accept() RECEIVE_AND_WAIT User data is not exchanged during connection establishment.

Refer to Relation Symbol Description .

t_alloc() Local  
t_bind() If qlen>0: RECEIVE_ALLOCATE for each connection request that can be queued.

Optionally: DEFINE_TP

With the instantiation model, the TP name (that is, XTI application name) must be known by the LU before the TP can be instantiated. This is prior to the t_bind being issued. (Refer to Passive Connection Establishment, Instantiation Version (1 of 3) .)

Refer to Relation Symbol Description .
t_close() If connection still up issue DEALLOCATE TYPE(FLUSH) Refer to Relation Symbol Description .
t_connect() ALLOCATE RETURN_CONTROL

GET_ATTRIBUTES

RECEIVE_AND_WAIT

Refer to Relation Symbol Description .
t_error() Local  
t_free() Local  
t_getinfo() Local  
t_getprotaddr() GET_TP_PROPERTIES to get OWN_FULLY_ QUALIFIED_LU_ NAME and OWN_TP_NAME

GET_ATTRIBUTES to get PARTNER_FULLY_ QUALIFIED_LU_ NAME

The partner's TP name must be learned by some mechanism other than XTI services. In connectionless mode, there is no partner name.

Refer to Relation Symbol Description .

t_getstate() Local  
t_listen() WAIT_FOR_COMPLETION Refer to Relation Symbol Description .
t_look() WAIT_FOR_COMPLETION  
t_open() Local t_open sets blocking mode (that is, blocking or non-blocking)
t_optmgmt() GET_ATTRIBUTES To get Mode name

Refer to Relation Symbol Description .

t_rcv() WAIT_FOR_COMPLETION

RECEIVE_AND_WAIT

[RECEIVE_EXPEDITED_DATA]

WAIT_FOR_COMPLETION

Refer to Relation Symbol Description .
t_rcvconnect() WAIT_FOR_COMPLETION

GET_ATTRIBUTES

RECEIVE_AND_WAIT

Refer to Active Connection Establishment, Non-blocking Version (2 of 2) .
t_rcvdis() Local Event caused by DEALLOCATE_ABEND_* or RESOURCE_FAILURE_* return code on any verb
t_rcvrel() Local Event caused by DEALLOCATE_NORMAL return code on RECEIVE_* verb
t_snd() SEND_DATA (expedited data)

[FLUSH]

[SEND_EXPEDITED_DATA]

Every t_snd causes a SEND_DATA to be issued - even if T_MORE set. If T_MORE is set, the LL continuation bit is set.

A zero-length TSDU causes the following LL to be sent: hex 0002. This can be used to turn off the LL continuation set on the previous send.

Refer to Relation Symbol Description .

t_snddis() DEALLOCATE TYPE(ABEND_PROG) Takes down both directions of the connection

Refer to Relation Symbol Description .

t_sndrel() DEALLOCATE TYPE(FLUSH) Takes down send direction of conversation only.

Refer to Relation Symbol Description .

t_sndudata() SEND_DATA on datagram server conversation Refer to Relation Symbol Description .
t_strerror() local  
t_sync() local  
t_unbind() local  

Parameter Mappings
Table: Relation Symbol Description

Relation Symbol Meaning
Used Locally Value is used locally by XTI Mapper
Created Locally XTI Mapper creates the value
Constant Only one value is acceptable in this field. It is an error condition if any other value is passed.
& 60;&
-> FDX Verb parameter maps directly to XTI Application parameter.

Table: t_accept <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_accept   RECEIVE_AND_WAIT
Input    
fd Used Locally  
resfd -> RESOURCE(variable)
call->addr.len Used Locally  
call->addr.buf Used Locally  
call->opt.len Used Locally  
call->opt.buf Used Locally  
call->udata.len Constant =0
call->udata.buf Constant =nullptr
  Created Locally LENGTH(variable)
  Created Locally FILL(addr of local bufr)
  Constant WAIT_OBJECT(BLOCKING)
Output    
t_errno & 60;&

Table: t_bind <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_bind with qlen>0   RECEIVE_ALLOCATE
Input    
fd Used Locally  
req->addr.len Used Locally  
req->addr.buf & 60;&
LOCAL_LU_NAME(variable)    
TP_NAME(variable)    
T}    
req->qlen Used Locally >0, RECEIVE_ALLOCATE issued for each connection request that can be queued.
ret->addr.maxlen Used Locally  
  Constant RETURN_CONTROL (WHEN_ALLOCATE_RECEIVED)
  Constant SCOPE(ALL)
  Created Locally WAIT_OBJECT(BLOCKING)
Output    
ret->addr.len Created Locally  
ret->addr.buf -> LOCAL_LU_NAME(variable)

TP_AL_LU_NAME(variable)

ret->addr.qlen Created Locally  
  Used Locally RESOURCE(variable)
t_errno -> RETURN_CODE(variable)

Table: t_close <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_close

If connection is still in T_DATAXFER state

  DEALLOCATE
Input    
fd -> RESOURCE(variable)
  Constant TYPE(FLUSH)
Output    
t_errno & 60;&

Table: t_connect <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_connect   ALLOCATE RETURN_CONTROL
Input    
fd    
sndcall->addr.len Used Locally  
sndcall->addr.buf -> LU_NAME(), TP_NAME()
sndcall->opt.len Used Locally  
sndcall->opt.buf -> MODE_NAME()
sndcall->udata.len Constant =0, user data not allowed
sndcall->udata.buf Constant =nullptr
rcvcall->addr.maxlen Used Locally  
rcvcall->addr.buf Used Locally  
rcvcall->opt.maxlen Constant =0, user data not allowed
rcvcall->opt.buf Used Locally  
rcvcall->udata.maxlen Constant =0, user data not allowed
rcvcall->udata.buf Constant =nullptr
  Constant TYPE(FULL_DUPLEX_BASIC_CONV)
  Created Locally RETURN_CODE
(WHEN_SESSION_FREE)

If platform does not support this tower (Tower 205), use
(WHEN_SESSION_ALLOCATED).

  Created Locally WAIT_OBJECT(BLOCKING) if blocking

WAIT_OBJECT(VALUE(variable)) if non-blocking

Output    
  Used Locally RESOURCE(variable)
t_errno & 60;&
t_connect;;GET_ATTRIBUTES    
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
Output    
rcvcall->addr.len & 60;&
PARTNER_FULLY_QUALIFIED_ LU_NAME(variable)    
T}    
rcvcall->addr.buf & 60;&
PARTNER_FULLY_QUALIFIED_ LU_NAME(variable)    
T}    
rcvcall->opt.len & 60;&
rcvcall->opt.buf & 60;&
t_errno & 60;&
t_connect   RECEIVE_AND_WAIT
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
Output    
  Created Locally LENGTH(variable)
  Created Locally FILL(addr of local bufr)
  Constant WAIT_OBJECT(BLOCKING)

Table: t_getprocaddr <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_getprotaddr   GET_ATTRIBUTES to get partner LU name
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
boundaddr->maxlen Used Locally  
boundaddr->addr.buf Used Locally  
peeraddr->maxlen Used Locally  
peeraddr->addr.buf Used Locally  
Output    
peeraddr->addr.len Created Locally  
buf(peeraddr->addr.buf) & 60;&
PARTNER_FULLY_QUALIFIED_ LU_NAME(variable)    
T}    
t_errno & 60;&
t_getprotaddr   GET_TP_PROPERTIES to get local TP name
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
Output    
boundaddr->addr.len Created Locally  
buf(boundaddr->addr.buf) & 60;&
OWN_FULLY_QUALIFIED_ LU_NAME(variable)    
OWN_TP_NAME(variable)    
T}    
t_errno & 60;&

Table: t_listen <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_listen   WAIT_FOR_COMPLETION
Input    
  Created Locally WAIT_OBJECT_LIST(variable)
  Constant TIMEOUT(VALUE(variable=0))
Output    
t_errno & 60;&
  Used Locally STATUS_LIST(variable)
t_listen   GET_ATTRIBUTES
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
Output    
call->addr.len & 60;&
PARTNER_FULLY_QUALIFIED _LU_NAME(variable)    
T}    
bufr&larrow.(call->addr.buf) & 60;&
PARTNER_FULLY_QUALIFIED _LU_NAME(variable)    
T}    
call->opt.len & 60;&
bufr&larrow.(call->opt.buf) & 60;&

Table: t_optmgmt <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_optmgmt   GET_ATTRIBUTES
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
req->opt.maxlen Used Locally  
req->opt.len Used Locally  
req->opt.buf Used Locally  
req->opt.flags Used Locally  
ret->opt.maxlen Used Locally  
ret->opt.buf Used Locally  
Output    
ret->opt.len & 60;&
ret->opt.buf & 60;&
ret->flags Created Locally  
t_errno & 60;&

Table: t_rcv <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_rcv   RECEIVE_AND_WAIT
A RECEIVE_AND_WAIT has been issued prior to this t_rcv. The data received on this RECEIVE_AND_WAIT will be returned to the XTI application via the t_rcv.

Before the return to the t_rcv, the mapper will issue another RECEIVE_AND_WAIT to post a receive for any incoming data.

Input   This is the RECEIVE_AND_WAIT that will be issued before the return to t_rcv.
fd Used Locally  
  Created Locally RESOURCE(variable)
nbytes Used Locally  
  Created Locally LENGTH(variable)
  Created Locally FILL(XTI mapper buffer)
  Created Locally WAIT_OBJECT(VALUE(variable))
t_rcv   RECEIVE_AND_WAIT
Output   These are fields from the previously issued RECEIVE_AND_WAIT
buf & 60;&
Return Value for function & 60;&
flags

  • T_MORE

  • T_EXPEDITED=NO/YES

Created Locally WHAT_RECEIVED(variable)

If there is expedited data to be received, a RECEIVE_EXPEDITED_DATA verb will be issued to receive it.

t_errno & 60;&
t_rcv   WAIT_FOR_COMPLETION
Input    
  Created Locally WAIT_OBJECT_LIST(variable)
  Constant TIMEOUT(VALUE(variable=0))
Output    
errno & 60;&
T_LOOK Used Locally STATUS_LIST(variable)

Table: t_rcvconnect <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_rcvconnect   GET_ATTRIBUTES
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
Output    
call->addr.len & 60;&
PARTNER_FULLY_QUALIFIED_ LU_NAME(variable)    
T}    
call->addr.buf & 60;&
PARTNER_FULLY_QUALIFIED_ LU_NAME(variable)    
T}    
call->opt.len & 60;&
call->opt.buf & 60;&
t_errno & 60;&
t_rcvconnect   RECEIVE_AND_WAIT
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
  Created Locally LENGTH(variable)
  Created Locally FILL(addr of local bufr)
  Constant WAIT_OBJECT(VALUE(variable))
t_rcvconnect   WAIT_FOR_COMPLETION
Input    
  Created Locally WAIT_OBJECT_LIST(variable)
  Constant TIMEOUT(VALUE(variable=0))
Output    
t_errno & 60;&
T_LOOK Used Locally STATUS_LIST(variable)

Table: t_snd <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_snd()   SEND_DATA
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
buf -> DATA(variable)
nbytes -> LENGTH(variable)
flags

  • T_EXPEDITED=NO

  • T_MORE

  • T_FLUSH

-> LL continuation bit
  Created Locally WAIT_OBJECT(BLOCKING) if blocking

WAIT_OBJECT(VALUE(variable)) if non-blocking

Output    
(TLOOK) & 60;&
t_errno & 60;&
t_snd()   SEND_EXPEDITED_DATA
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
buf -> DATA(variable)
nbytes -> LENGTH(variable)
flags

  • T_EXPEDITED=YES

  • T_MORE

  • T_FLUSH

-> LL continuation bit

FLUSH Verb

  Created Locally WAIT_OBJECT(BLOCKING) if blocking
WAIT_OBJECT(VALUE(variable)) if non-blocking    
Output    
(TLOOK) & 60;&
t_errno & 60;&

Table: t_snddis (Existing Connection) <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_snddis()

For existing connection

  DEALLOCATE
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
call Constant =nullptr
  Constant TYPE(ABEND_PROG)
Output    
t_errno & 60;&

Table: t_snddis (Incoming Connect Req.) <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_snddis()

To reject incoming connection request

  DEALLOCATE
Input    
call->sequence Used Locally  
Output    
t_errno & 60;&

Table: t_sndrel <-&#62; FDX Verbs and Parameters

XTI Function and Parameters & 60;&
t_sndrel()   DEALLOCATE
Input    
fd Used Locally  
  Created Locally RESOURCE(variable)
  Created Locally TYPE(FLUSH)
Output    
t_errno & 60;&

Half Duplex Mapping

The interface to the SNA transport provider is the FDX LU 6.2 interface. If the SNA transport provider does not support FDX LU 6.2, the FDX verbs can be mapped to two half-duplex LU 6.2 connections, one used to send in each direction. This gives the appearance of a full duplex connection without requiring any conversation direction turn-arounds on the half-duplex conversations.

The mapping of FDX LU 6.2 verbs to two half-duplex connections is described in FDX Kit.

Return Code to Event Mapping

The following table Mapping of XTI Events to SNA Events shows how the return codes on LU 6.2 verbs are mapped to XTI events.

Any return code for which there no mapping given in this table will create a disconnect.

Table: Mapping of XTI Events to SNA Events

XTI Event Full Duplex SNA Event
T_CONNECT ALLOCATE completes with RETURN_CODE=OK
T_DATA RECEIVE_AND_WAIT completes with OK return code and WHAT_RECEIVED =

  • DATA_COMPLETE

  • DATA_INCOMPLETE

T_DISCONNECT One of the following has occurred:

SEND_DATA issued with RETURN_CODE = ERROR_INDICATION with subcode from list below:

  • ALLOCATION_ERROR

  • DEALLOCATE_ABEND_PROG

  • DEALLOCATE_ABEND_SVC

  • DEALLOCATE_ABEND_TIMER

  • RESOURCE_FAILURE_NO_RETRY

  • RESOURCE_FAILURE_RETRY

Any other verb issued with RETURN_CODE of

  • ALLOCATION_ERROR

  • DEALLOCATE_ABEND_PROG

  • DEALLOCATE_ABEND_SVC

  • DEALLOCATE_ABEND_TIMER

  • RESOURCE_FAILURE_NO_RETRY

  • RESOURCE_FAILURE_RETRY

T_EXDATA RECEIVE_EXPEDITED_DATA completes with OK return code
T_GODATA Flow control restrictions on normal data flow that lead to a [TFLOW] error have been lifted. Normal data may be sent again.
T_GOEXDATA Flow control restrictions on expedited data flow that lead to a [TFLOW] error have been lifted. Expedited data may be sent again.
T_LISTEN When the partner program is instantiated when the connection request arrives (the typical LU 6.2 model), this event is posted as soon as the program issues the t_listen() function call.

When the partner program already exists, this event is posted when the connection request arrives and is matched with the program.

T_ORDREL Set when a RECEIVE_* verb completes with RETURN_CODE = DEALLOCATE_NORMAL.

Footnotes

1.
CPI-C Reference, Version 2.1; publicly available from IBM branch offices under the IBM reference SC26-4399.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index