SNA Transport Provider

Introduction

• Protocol-specific information that is relevant for Systems Network Architecture (SNA) transport providers.

  It assumes native SNA users, that is, those prepared to use SNA addresses and other SNA transport characteristics (for example, mode name for specifying quality of service).

• Information on the mapping of XTI functions to Full Duplex (FDX) LU 6.2.

  Systems that do not support LU 6.2 full duplex can simulate them using twin-opposed half-duplex conversations. Protocols for doing so will be published separately.

  The half-duplex verbs have been published for several years. The full duplex verbs are documented in the CPI-C Reference, Version 2.1¹.

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

Note:

Applications written to compilation environments earlier than those required by this issue of the specification (see The Compilation Environment) and defining _XOPEN_SOURCE to be less than 500, may have these data structures and constants exposed through the inclusion of <xti.h>.

SNA Transport Protocol Information

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

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 T_SNA_MAX_LU_LEN      8
#define T_SNA_MAX_TPN_LEN     

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

Connection-Mode Service Options

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

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 T_SNA_USER_DISCONNECT
#define T_SNA_SYSTEM_DISCONNECT
#define T_SNA_TIMEOUT
#define T_SNA_CONNECTION_OUTAGE

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

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

• In the following flow diagrams, notice that the XTI mapper always has a RECEIVE_AND_WAIT posted. This is done so that when data comes into the SNA transport provider, the XTI mapper is able to set an event indicator. Then, when a T_LOOK is issued, the XTI application can be informed that there is data to be received.

• The XTI mapper keeps a table that maps an XTI fd to a RESOURCE(variable) on the FDX verbs.

• In this section, we assume the XTI mapper will be using the FDX LU 6.2 basic conversation verb interface. The following table FDX LU 6.2 Verb Definitions gives an explanation for each FDX verb that is used in these mappings.

Flows Illustrating Full Duplex Mapping

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

Parameter Mappings

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.

Compatibility.

SNA_MAX_NETID_LEN, SNA_MAX_LU_LEN, SNA_MAX_TPN_LEN SNA_CONNECTION_SETUP_FAILURE, SNA_USER_DISCONNECT, SNA_SYSTEM_DISCONNECT, SNA_TIMEOUT, SNA_CONNECTION_OUTAGE

Footnotes

1.

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