Transaction Interface

Transaction Interface

Preface

Abstract

This document is a Application Program Interface containing technical details concerning the implementation of the Transaction Interface (TRI) for OpenSS7. It contains recommendations on software architecture as well as platform and system applicability of the Transaction Interface (TRI).

Purpose

The purpose of this document is to provide technical documentation of the Transaction Interface (TRI). This document is intended to be included with the OpenSS7 STREAMS software package released by OpenSS7 Corporation. It is intended to assist software developers, maintainers and users of the Transaction Interface (TRI) with understanding the software architecture and technical interfaces which are made available in the software package.

Intent

It is the intent of this document that it act as the primary source of information concerning the Transaction Interface (TRI).

Audience

The audience for this document is software developers, maintainers and users and integrators of the Transaction Interface (TRI).

Revision History

Take care that you are working with a current version of this documentation: you will not be notified of updates. To ensure that you are working with a current version, check the OpenSS7 Project website for a current version.

1 Introduction

This document specifies a STREAMS-based kernel-level instantiation of the ITU-T Transaction Capabilities Application Part (TCAP) Transaction (TR) Sub-Layer. The Transaction Interface (TRI) enables the user of a transaction sub-layer service to access and use any of a variety of conforming transaction providers without specific knowledge of the provider's protocol. The service interface is designed to support any transaction protocol. This interface only specifies access to transaction sub-layer services providers, and does not address issues concerning transaction sub-layer management, protocol performance, and performance analysis tools.

The specification assumes that the reader is familiar with the ISO reference model terminology, ISO/ITU-T transaction service definitions (ROSE, ACSE, TCAP), and STREAMS.

1.1 Related Documentation

• ITU-T Recommendation X.200 (White Book) — ISO/IEC 7498-1:1994
• ITU-T Recommendation X.219 (White Book) — ISO/IEC
• ITU-T Recommendation X.229 (White Book) — ISO/IEC
• ITU-T Recommendation X.217 (White Book) — ISO/IEC 8649 : 1996
• ITU-T Recommendation X.227 (White Book) — ISO/IEC 8650-1 : 1995
• ITU-T Recommendation X.237 (White Book) — ISO/IEC 10035-1 : 1995
• ITU-T Recommendation Q.771 (White Book)
• System V Interface Definition, Issue 2 - Volume 3

1.1.1 Role

This document specifies an interface that supports the service provided by the Association Control Service Element (ACSE) for Open Systems Interconnect for ITU-T Applications as specified in ITU-T Recommendation X.217 (ISO/IEC 8649). It is also intended to support the Transaction Sub-layer provided by the Transaction Capabilities Application Part (TCAP) for Signalling System Number 7 (SS7) as specified in ITU-T Recommendation Q.771. These specifications are targeted for use by developers and testers of protocol modules that require transaction sub-layer service.¹

1.2 Definitions, Acronyms, and Abbreviations

Originating TR User

A TR-User that initiates a transaction.

Destination TR User

A TR-User with whom an originating TR user wishes to establish a transaction.

ISO

International Organization for Standardization

TR User

Kernel level protocol or user level application that is accessing the services of the transaction sub-layer.

TR Provider

Transaction sub-layer entity/entities that provide/s the services of the transaction interface.

TRI

Transaction Interface

TIDU

Transaction Interface Data Unit

TSDU

Transaction Service Data Unit

OSI

Open Systems Interconnection

QOS

Quality of Service

STREAMS

A communication services development facility first available with UNIX System V Release 3

2 The Transaction Sub-Layer

The Transaction Sub-Layer provides the means to manage the association of TR-User into transactions. It is responsible for the routing and management of transaction associations between TR-user entities.

2.1 Model of the TRI

The TRI defines the services provided by the transaction sub-layer to the transaction-user at the boundary between the Transaction Component (TC) Sub-Layer and the Transaction (TR) Sub-Layer in the model presented in ITU-T Recommendation Q.771. The interface consists of a set of primitives defined as STREAMS messages that provide access to the transaction sub-layer services, and are transferred between the TR user entity and the TR provider. These primitives are of two types: ones that originate from the TR user, and others that originate from the TR provider, or respond to an event of the TR provider. The primitives that originate from the TR provider are either confirmations of a request or are indications to the NS user that the event has occurred. Figure 1 shows the model of the TRI.

Figure 1. Model of the TRI

The TRI allows the TR provider to be configured with any transaction sub-layer user (such as the Transaction Component (TC) Sub-Layer) that also conforms to the TRI. A transaction sub-layer user can also be a user program that conforms to the TRI and accesses the TR provider via putmsg(2) and getmsg(2) system calls.

STREAMS messages that are used to communicate transaction service primitives between the transaction user and the transaction provider may have one of the following formats:

1. A M_PROTO message block followed by zero or more M_DATA message blocks. The M_PROTO message block contains the type of service primitive and all relevant arguments associated with the primitive. The M_DATA blocks contain user data associated with the service primitive.
2. One M_PCPROTO message block containing the type of service primitive and all the relevant arguments associated with the primitive.
3. One or more M_DATA message blocks containing user data.

The following sections describe the service primitives which define both connection-mode and connectionless-mode service.

For both types of service, two types of primitives exist: primitives that originate from the service user and primitives that originate from the service provider. The primitives that originate from the service user make requests to the service provider or response to an event of the service provider. The primitive that originate from the service provider are either confirmations of a request or are indications to the service user that an event has occurred. The primitive types along with the mapping of those primitives to the STREAMS message types and the service primitives of the ISO/IEC xxxxx and service definitions are listed in TRI Primitives. The format of these primitives and the rules governing the use of them are described in Management Primitives, Connection-Oriented Mode Primitives, and Connectionless Mode Primitives.

2.2 TRI Services

The features of the TRI are defined in terms of the services provided by the service provider, and the individual primitives that may flow between the service user and the service provider.

The services supported by the TRI are based on two distinct modes of communication, connection-mode transaction service (COTS) and connectionless transaction service (CLTS). Also, the TRI supports services for local management.

2.2.1 COTS

The main features of the connection mode communication are:

1. It is virtual circuit oriented;
2. it provides transfer of data via a pre-established path; and,
3. it provides reliable data transfer.²

There are three phases to each instance of communication: Transaction Establishment, Data Transfer, and Transaction Release. Units of data arrive at the destination in the same order as they departed their source and the data is protected against duplication or loss of data units within some specified quality of service.

2.2.2 CLTS

The main features of the connectionless mode communication are:

1. It is datagram oriented;
2. it provides transfer of data in self contained units;
3. there is no logical relationship between these units of data; and,
4. it is unreliable.

Connectionless mode communication has no separate phases. Each unit of data is transmitted from source to destination independently, appropriate addressing information is included with each unit of data. As the units of data are transmitted independently from source to destination, there are, in general, no guarantees of proper sequence and completeness of the data stream.

2.2.3 Local Management

The TRI specifications also define a set of local management functions that apply to both COTS and CLTS modes of communication. These services have local significance only.

Table 1 and Table 2 summarizes the TRI service primitives by their state and service.

3 TRI Services Definition

This section describes the services of the TRI primitives. Time-sequence diagrams ³ that illustrate the sequence of primitives are used. The format of the primitives will be defined later in this document.

3.1 Local Management Services Definition

The services defined in this section are outside the scope of the international standards. These services apply to both connection-mode as well as connectionless modes of communication. They are involved for the initialization/de-initialization of a stream connected to the TR provider. They are also used to manage options supported by the TR provider and to report information on the supported parameter values.

3.1.1 Transaction Information Reporting Service

This service provides information on the options supported by the TR provider.

• TR_INFO_REQ: This primitive request that the TR provider returns the values of all the supported protocol parameters. This request may be invoked during any phase.
• TR_INFO_ACK: This primitive is in response to the TR_INFO_REQ primitive and returns the values of the supported protocol parameters to the TR user.

The sequence of primitives for transaction information management is shown in Figure 2.

Figure 2. Sequence of Primitives Transaction Information Reporting Service

3.1.2 TR User Bind Service

This service allows an originating address to be associated with a stream. It allows the TR user to negotiate the number of transaction begin indications that can remain unacknowledged for that TR user (a transaction begin indication is considered unacknowledged while it is awaiting a corresponding transaction response or abort request from the TR user). This service also defines a mechanism that allows a stream (bound to the address of the TR user) to be reserved to handle incoming transactions only. This stream is referred to as the listener stream.

• TR_BIND_REQ: This primitive request that the TR user be bound to a particular originating address, and negotiate the number of allowable outstanding transaction indications for that address.
• TR_BIND_ACK: This primitive is in response to the TR_BIND_REQ primitive and indicates to the user that the specified TR user has been bound to a protocol address.

The sequence of primitives for the TR user bind service is shown in Figure 3.

Figure 3. Sequence of Primitives TR User Bind Service

3.1.3 TR User Unbind Service

This service allows the TR user to be unbound from a protocol address.

• TR_UNBIND_REQ: This primitive requests that the TR user be unbound from the protocol address it had previously been bound to.

The sequence of primitives for the TR user unbind service is shown in Figure 4.

Figure 4. Sequence of Primitives TR User Unbind and Receipt Acknowledgement Services

3.1.4 Receipt Acknowledgement Service

• TR_OK_ACK: This primitive indicates to the TR user that the previous TR user originated primitive was received successfully by the TR provider.

An example showing the sequence of primitives for successful receive acknowledgement is depicted in Figure 4.

3.1.5 Options Mangement Service

This service allows the TR user to manage the QOS parameter values associated with the TR provider.

• TR_OPTMGMT_REQ: This primitive allows the TR user to select default values for QOS parameters within the range supported by the TR provider, and to indicate the default selection of return option.

Figure 5 shows the sequence of primitives for transaction options management.

Figure 5. Sequence of Primitives Options Management Service

3.1.6 Error Acknowledgement Service

• TR_ERROR_ACK: This primitive indicates to the TR user that a non-fatal error has occurred in the last TR user originated request or response primitive (listed in Figure 6) on the stream.

Figure 6 shows the sequence of primitives for the error management primitive.

Figure 6. Sequence of Primitives Error Acknowledgement Service

3.2 Connection-Oriented Mode Services Definition

This section describes the required transaction service primitives that define the connection mode interface.

The queue model for connection-oriented services are discussed in more detail in ITU-T X.217 and ITU-T Q.771.

The queue model represents the operation of a transaction association in the abstract by a pair of queues linking two transaction users. There is one queue for each direction of data flow. Each queue represents a flow control function in one direction of transfer. The ability of a user to add objects to a queue will be determined by the behaviour of the user removing objects from that queue, and the state of the queue. The pair of queues is considered to be available for each potential transaction association. Objects that are entered or removed from the queue are either as a result of interactions at the two transaction addresses, or as the result of TR provider initiatives.

• A queue is empty until a transaction object has been entered and can be returned to this state, with loss of its contents, by the TR provider.
• Objects may be entered into a queue as a result of the actions of the source TR user, subject to control by the TR provider.
• Objects may also be entered into a queue by the TR provider.
• Objects are removed from the queue under the control of the TR user in the same order as they were entered except:
  1. If the object is of type defined to be able to advance ahead of the preceding object (however, no object is defined to be able to advance ahead of another object of the same type), or
  2. If the following object is defined to be destructive with respect to the preceding object on the queue. If necessary, the last object on the queue will be deleted to allow a destructive object to be entered - they will therefore always be added to the queue. For example, “abort” objects are defined to be destructive with respect to all other objects.

Table 3 shows the ordering relationships among the queue model objects.

3.2.1 Transaction Initiation Phase

A pair of queues is associated with a transaction association between two transaction users when the TR provider receives a TR_BEGIN_REQ primitive at one of the TR users resulting in a begin object being entered into the queue. The queues will remain associated with the transaction until a TR_END_REQ or TR_ABORT_REQ primitive (resulting in an end or abort object) is either entered or removed from a queue. Similarly, in the queue from the destination TR user, objects can be entered into the queue only after the begin object associated with the TR_BEGIN_RES has been entered into the queue. Alternatively, the destination TR user can enter an end or abort object into the queue instead of the begin object to terminate the transaction.

The transaction establishment procedure will fail if the TR provider is unable to establish a transaction association, or if the destination TR user is unable to accept the TR_BEGIN_IND (see Transaction Termination primitive definition in TR_END_IND).

3.2.1.1 User Primitives Successful Transaction Establishment

The following user primitives support COTS Phase I (Transaction Establishment) services:

• TR_BEGIN_REQ: This primitive requests that the TR provider form a transaction association with the specified destination TR user.
• TR_BEGIN_RES: This primitive requests that the TR provider accept a previous transaction indication.

3.2.1.2 Provider Primitives Successful Transaction Establishment

The following provider primitives support COTS Phase I (Transaction Establishment) services:

• TR_BEGIN_IND: This primitive indicates to the TR user that a transaction association request has been made by a user at the specified source address.
• TR_BEGIN_CON: This primitive indicates to the TR user that a transaction initiation request has been confirmed on the specified responding address.

The sequence of primitives in a successful transaction initiation is defined by the time sequence diagrams as shown in Figure 7.

Figure 7. Sequence of Primitives: Successful Transaction Initiation

The sequence of primitives for the transaction initiation response token value determination is shown in Figure 8 (procedures for transaction initiation response token value determination are discussed in TR_BIND_REQ, and TR_BIND_ACK).

Figure 8. Sequence of Primitives: Transaction Response Token Value Determination

3.2.2 Transaction Data Transfer Phase

Flow control on the transaction association is done by management of the queue capacity, and by allowing objects of certain types to be inserted to the queues, as shown in Table 4.

3.2.2.1 Primitives for Data Transfer

The following primitives support COTS Phase II (Transaction Data Transfer) services:

• TR_CONT_REQ: This primitive requests that the TR provider transfer the specified user data.
• TR_CONT_IND: This primitive indicates to the TR user that this message contains user data.

Figure 9 shows the sequence of primitives for successful user data transfer. The sequence of primitives may remain incomplete if a TR_END_REQ, TR_END_IND, TR_ABORT_REQ, or TR_ABORT_IND primitive occurs.

Figure 9. Sequence of Primitives: Data Transfer

3.2.3 Transaction Termination Phase

The transaction association procedure is initialized by insertion of an end or abort object (associated with a TR_END_REQ or TR_ABORT_REQ) into the queue. As shown in Table?, the termination procedure is destructive with respect to other objects in the queue, and eventually results in the emptying of queues and termination of the transaction association.

The sequence of primitives depends on the origin of the termination action. The sequence may be:

1. invoked by on TR user, with a request from that TR user leading to an indication to the other;
2. invoked by both TR users, with a request from each of the TR users;
3. invoked by the TR provider, with an indication to each of the TR users;
4. invoked independently by one TR user and the TR provider, with a request from the originating TR user and an indication to the other.

3.2.3.1 Primitives for Transaction Termination

The following primitives support CONS Phase III (Transaction Termination) services:

• TR_END_REQ: This primitive requests that the TR provider deny an outstanding request for a transaction association or normal termination of an existing transaction.
• TR_ABORT_REQ: This primitive requests that the TR provider deny an outstanding request for a transaction association or abnormal termination of an existing transaction.
• TR_END_IND: This primitive indicates to the TR user that either a request for transaction initiation has been denied or an existing transaction has been terminated normally.
• TR_ABORT_IND: This primitive indicates to the TR user that either a request for transaction initiation has been denied or an existing transaction has been terminated abnormally.

The sequence of primitives are shown in the time sequence diagrams in the figures that follow:

Figure 10. Sequence of Primitives: TR User Invoked Termination

Figure 11. Sequence of Primitives: Simultaneous TR User Invoked Termination

Figure 12. Sequence of Primitives: TR Provider Invoked Termination

Figure 13. Sequence of Primitives: Simultaneous TR User and TR Provider Invoked Termination

A TR user may reject a transaction initiation attempt by issuing a TR_ABORT_REQ. The originator parameter in the TR_ABORT_REQ will indicate TR user invoked termination. The sequence of primitives is shown in Figure 14.

Figure 14. Sequence of Primitives: TR User Rejection of a Transaction Initiation Attempt

If the TR provider is unable to establish a transaction, it indicates this to the requester by an TR_ABORT_IND. The originator of the primitive indicates a TR provider invoked release. This is shown in Figure 15.

Figure 15. Sequence of Primitives: TR Provider Rejection of a Transaction Initiation Attempt

3.3 Connectionless Mode Services Definition

The connectionless mode service allows for the transfer of transaction user data in one and both directions simultaneously without establishing a transaction dialogue. A set of primitives are defined that carry transaction user data and control information between the TR user and the TR provider entities. The primitives are modelled as requests initiated by the TR user and indications initiated by the TR provider. Indications may be initiated by the TR provider independently from requests by the TR user.

The connectionless mode service consists of one phase.

3.3.1 Request and Response Primitives

• TR_UNI_REQ: This primitive requests that the TR provider send the transaction user data to the specified destination.
• TR_UNI_IND: This primitive indicates to the TR user that a user data sequence has been received from the specified originating address.

Figure 16 shows the sequence of primitives for the connectionless mode of transfer.

Figure 16. Sequence of Primitives: Connectionless Mode Data Transfer

• TR_NOTICE_IND: This primitive indicates to the TR user that the user data with the specified destination address and QOS parameters produced an error. This primitive is specific to CLTS.

Figure 17 shows the sequence of primitives for the CLTS error management primitive.

Figure 17. Sequence of Primitives: CLTS Error Indication Service

4 TRI Primitives

This section describes the format and parameters of the TRI primitives. In addition, it discusses the states in which the primitive is valid, the resulting state, and the acknowledgement that the primitive expects.

The mapping of TRI of TRI primitives to the primitives defined in ITU-T Q.771, ITU-T X.219 and ANSI T1.114 are shown in Mapping TRI Primitives. The state/event tables for these primitives are shown in State/Event Tables. The precedence tables for the TRI primitives are shown in Primitive Precedence Tables.

The following tables provide a summary of the TR primitives and their parameters.

4.1 Management Primitives

These primitives apply to all transaction modes.

4.1.1 Transaction Information

4.1.1.1 Transaction Information Request

TR_INFO_REQ

This primitive request the TR provider to return the values of all supported protocol parameters (see TR_INFO_ACK), and also the current state of the TR provider (as defined in State/Event Tables). This primitive does not affect the state of the TR provider and does not appear in the state tables.

Format

The format of the message is one `M_PCPROTO' message block and its structure is as follows:

     typedef struct TR_info_req {
         ulong PRIM_type;          /* Always TR_INFO_REQ */
     } TR_info_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type. Always `TR_INFO_REQ'.

Valid States

This primitive is valid in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged.

Rules

For the rules governing the requests made by this primitive, see the `TR_INFO_ACK' primitive described in TR_INFO_ACK.

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_INFO_ACK primitive described in TR_INFO_ACK.
• Non-fatal Errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  There are no errors associated with the issuance of this primitive.

4.1.1.2 Transaction Information Acknowledgement

TR_INFO_ACK

This primitive indicates to the TR user any relevant protocol-dependent parameters.⁴ It should be initiated in response to the TR_INFO_REQ primitive described above under TR_INFO_REQ.

Format

The format of the message is one `M_PCPROTO' message block and its structure is as follows:

     typedef struct TR_info_ack {
         long PRIM_type;           /* Always TR_INFO_ACK */
         long ASDU_size;           /* maximum ASDU size */
         long EASDU_size;          /* maximum EASDU size */
         long CDATA_size;          /* connect data size */
         long DDATA_size;          /* discon data size */
         long ADDR_size;           /* address size */
         long OPT_size;            /* options size */
         long TIDU_size;           /* transaction i/f data unit size */
         long SERV_type;           /* service type */
         long CURRENT_state;       /* current state */
         long PROVIDER_flag;       /* type of TR provider */
         long TRI_version;         /* version # of tri that is supported */
     } TR_info_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type.

ASDU_size

Specifies the maximum size (in octets) of Transaction Service User Data supported by the TR provider.

EASDU_size

Specifies the maximum size (in octets) of Expedited Transaction Service User Data supported by the TR provider.

CDATA_size

Specifies the maximum number of octets of data that may be associated with a transaction initiation primitive.

DDATA_size

Specifies the maximum number of octets of data that may be associated with a transaction termination primitive.

ADDR_size

Specifies the maximum size (in decimal digits) of a protocol address.

ADDR_length

ADDR_offset

Specifies the length in bytes and offset from the beginning of the `M_PCPROTO' message block of the protocol address bound on the stream on which the TR_INFO_REQ was issued (a protocol address is bound to a stream via a TR_BIND_REQ).

QOS_length

QOS_offset

QOS_range_length

QOS_range_offset

OPTIONS_flags

TIDU_size

SERV_type

CURRENT_state

PROVIDER_type

NODU_size

PROTOID_length

PROTOID_offset

TRI_version

4.1.2 Transaction Protocol Address Management

4.1.2.1 Transaction Bind Request

TR_BIND_REQ

This primitive requests that the TR provider bind a protocol address to the stream, negotiate the number of dialogue indications allowed to be outstanding by the TR provider for the specified protocol address, and activate⁵ the stream associated with the protocol address.

Format

The format of the message is one `M_PROTO' message block. The format of the `M_PROTO' message block is as follows:⁶

     typedef struct TR_bind_req {
         ulong PRIM_type;          /* Always TR_BIND_REQ */
         ulong ADDR_length;        /* address length */
         ulong ADDR_offset;        /* address offset */
         ulong XACT_number;        /* maximum outstanding transaction reqs. */
         ulong BIND_flags;         /* bind flags */
     } TR_bind_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_BIND_REQ'.

ADDR_length

Specifies the length⁷ of the protocol address to be bound to the stream.

ADDR_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol address begins. The proper alignment of the address in the `M_PROTO' message block is not guaranteed. The address in the `M_PROTO' message block is, however, aligned the same as it was received from the TR user.

XACT_number

⁸The requested number of dialogue begin indications⁹ allowed to be outstanding by the TR provider for the specified protocol address. Only one stream per protocol address is allowed to have a XACT_number greater than zero. This indicates to the TR provider that the stream is a listener stream for the TR user. This stream will be used by the TR provider for dialogue “begin” indications for that protocol address, see TR_BEGIN_IND.

BIND_flags

Unused.

Valid State

This primitive is valid in state `TRS_UNBND'.

New State

The new state is `TRS_WACK_BREQ'.

Rules

For the rules governing the requests made by this primitive, see the TR_BIND_ACK primitive described in TR_BIND_ACK.

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_BIND_ACK primitive described in TR_BIND_ACK.
• Non-fatal errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TRBAADDR

  Indicates that the protocol address was in an incorrect format or the address contained illegal information. It is not intended to indicate protocol errors.

  
  

  TRNOADDR

  Indicates that the TR provider could not allocate an address.

  
  

  TRACCES

  Indicates that the user did not have proper permissions for the use of the requested address.

  
  

  TROUTSTATE

  The primitive would place the transaction interface out of state for the indicated transaction.

  
  

  TRSYSERR

  A system error occurred and the UNIX System error is indicated in the primitive.

  
  

  TRADDRBUSY

  Indicates that the requested address is already in use.

4.1.2.2 Transaction Bind Acknowledgement

TR_BIND_ACK

This primitive indicates to the TR user that the specified protocol address has been bound to the stream, that the specified number of dialogue indications are allowed to be queued by the TR provider for the specified protocol address, and that the stream associated with the specified protocol address has been activated.

Format

The format of the message is one `M_PCPROTO' message block. The format of the `M_PCPROTO' message block is as follows:

     typedef struct TR_bind_ack {
         ulong PRIM_type;          /* Always TR_BIND_ACK */
         ulong ADDR_length;        /* address length */
         ulong ADDR_offset;        /* address offset */
         ulong XACT_number;        /* open transactions */
         ulong TOKEN_value;        /* value of "token" assigned to stream */
     } TR_bind_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type.

ADDR_length

Indicates the length of the protocol address that was bound to the stream.

ADDR_offset

Indicates the offset from the beginning of the `M_PCPROTO' message block where the protocol address begins. The proper alignment of the address in the `M_PCPROTO' message block is not guaranteed.

XACT_number

¹⁰ Indicates the accepted number of dialogue indications allowed to be outstanding by the TR provider for the specified protocol address.

TOKEN_value

Indicates a token value to be used when accepting dialogues indicated on other streams using this stream.

Valid State

This primitive is issued in response to a `TR_BIND_REQ' and is valid in state `TRS_WACK_BREQ'.

New State

On success, the new state is `TRS_IDLE'; on error, `TRS_UNBND'.

Rules

The following rules apply to the binding of the specified protocol address to the stream:

• If the ADDR_length field in the `TR_BIND_REQ' primitive is zero (0), then the TR provider must assign a protocol address to the user.
• The TR provider is to bind the protocol address as specified in the `TR_BIND_REQ' primitive. If the requested protocol address is in use or if the TR provider cannot bind the specified address, it must return an error.

The following rules apply to negotiating the XACT_number argument:

• The returned value must be less than or equal to the corresponding requested number as indicated in the `TR_BIND_REQ' primitive.
• If the requested value is greater than zero, the returned value must also be greater than zero.
• Only one stream that is bound to the indicated protocol address any have a negotiated accepted number of maximum transaction requests greater than zero. If a `TR_BIND_REQ' primitive specifies a value greater than zero, but another stream has already bound itself to the given protocol address with a value greater than zero, the TR provider must return an error.
• If a stream with XACT_number greater than zero is used to accept a dialogue (without specifying a TRANS_id), the stream will be found busy during the duration of that connection and no other streams may be bound to that protocol address with a XACT_number greater than zero. This will prevent more than one stream bound to the identical protocol address from accepting dialogue indications. See also TR_BEGIN_RES.
• A stream requesting a XACT_number of zero should always be legal. This indicates to the TR provider that the stream is to be used to request dialogues only.
• stream with a negotiated XACT_number greater than zero may generate dialogue requests (see TR_BEGIN_REQ,) or accept dialogue indications (see TR_BEGIN_RES.)

If the above rules result in an error condition, then the TR provider must issue a `TR_ERROR_ACK' primitive to the TR user specifying the error as defined in the description of the `TR_BIND_REQ' primitive, TR_BIND_REQ.

4.1.2.3 Transaction Unbind Request

TR_UNBIND_REQ

This primitive requests that the TR provider unbind the protocol address previously associated with the stream and deactivate the stream.

Format

The format of the message is one `M_PROTO' message block structured as follows:

     typedef struct TR_unbind_req {
         ulong PRIM_type;          /* Always TR_UNBIND_REQ */
     } TR_unbind_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type.

Valid State

This primitive is valid in state `TRS_IDLE'.

New State

The new state is `TRS_WACK_UREQ'.

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_OK_ACK primitive described in TR_OK_ACK.
• Non-fatal errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TROUTSTATE

  The primitive would place the transaction interface out of state for the indicated transaction.

  
  

  TRSYSERR

  A system error occurred and the UNIX System error is indicated in the primitive.

4.1.2.4 Transaction Protocol Address Request

TR_ADDR_REQ

This primitive requests that the TR provider return the local protocol address that is bound to the stream and the address of the remote ASE if a transaction association has been established.

Format

The format of the message is one `M_PROTO' message block structured as follows:

     typedef struct TR_addr_req {
         long PRIM_type;           /* always TR_ADDR_REQ */
         ulong TRANS_id;           /* Transaction id */
     } TR_addr_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_ADDR_REQ'.

TRANS_id

Specifies the transaction association identifier for which address service is requested. If address service is requested for local bind address only, then the transaction identifier must be `-1'.

Valid State

This primitive is valid in any state where a local acknowledgement is not pending.

New State

The new state is unchanged.

Rules

For the rules governing the requests made by this primitive, see the TR_ADDR_ACK primitive described in TR_ADDR_ACK.

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_ADDR_ACK primitive described in TR_ADDR_ACK.
• Non-fatal errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TRBADID

  The transaction identifier specified in the primitive was incorrect or invalid.

  
  

  TRNOTSUPPORT

  This primitive is not supported by the transaction provider.

  
  

  TRSYSERR

  A system error has occured and the Linux system error is indicated in the primitive.

4.1.2.5 Transaction Protocol Address Acknowledgement

TR_ADDR_ACK

This primitive indicates to the TR user the addresses of the local and remote ASE. The local address is the protocol address that has been bound to the stream. If an transaction association has been established, the remote address is the protocol address of the remote ASE.

Format

The format of the message is one `M_PCPROTO' message block structured as follows:

     typedef struct TR_addr_ack {
         long PRIM_type;           /* always TR_ADDR_ACK */
         long LOCADDR_length;      /* length of local address */
         long LOCADDR_offset;      /* offset of local address */
         long REMADDR_length;      /* length of remote address */
         long REMADDR_offset;      /* offset of remote address */
     } TR_addr_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_ADDR_ACK'.

LOCADDR_length

Indicates the length of the protocol address that was bound to the stream.

LOCADDR_offset

Indicates the offset from the beginning of the `M_PCPROTO' message block where the protocol address begins.

REMADDR_length

Indicates the length of the protocol address of the remote ASE.

REMADDR_offset

Indicates the offset from the beginning of the `M_PCPROTO' message block where the protocol address begins.

The proper alignement of the addresses in the `M_PCPROTO' message block is not guaranteed.

Modes

Both connection-mode and connectionless-mode.

Originator

Transaction provider.

Valid State

This primitive is issued in response to a `TR_ADDR_REQ' primitive and is valid in any state where a response is pending to a `TR_ADDR_REQ'.

New State

The new state remains unchanged.

Rules

The following rules apply:

• If the requested transaction identifier was `-1' in the corresponding `TR_ADDR_REQ' primitive, and the transaction endpoint is not bound to a local address, (i.e. it is in the `TRS_UNINIT' or `TRS_UNBND' state) the LOCADDR_length and LOCADDR_offset fields must be set to `0'.
• If the requested transaction exists as identifed in the corresponding `TR_ADDR_REQ' primitive, LOCADDR_length and LOCADDR_offset fields will be populated to reflect the local association address for the specified transaction.
• If the requested transaction identifier was `-1' in the corresponding `TR_ADDR_REQ' primitive, the REMADDR_length and REMADDR_offset fields must be set to `0'.
• If the requested transaction exists as identified in the corresponding `TR_ADDR_REQ' primitive, REMADDR_length and REMADDR_offset fields will be populated to reflect the remote association address for the specified transaction.

4.1.3 Transaction Options Management

4.1.3.1 Transaction Options Management Request

TR_OPTMGMT_REQ

Format

The format of the message is one `M_PCPROTO' message block structured as follows:

     typedef struct TR_optmgmt_req {
         ulong PRIM_type;          /* Always TR_OPTMGMT_REQ */
         ulong OPT_length;         /* options length */
         ulong OPT_offset;         /* options offset */
         ulong MGMT_flags;         /* options data flags */
     } TR_optmgmt_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_OPTMGMT_REQ'.

OPT_length

OPT_offset

MGMT_flags

Flags

Valid State

New State

Rules

For the rules governing the requests made by this primitive, see the TR_OPTMGMT_ACK primitive described in TR_OPTMGMT_ACK.

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement is indicated with the TR_OPTMGMT_ACK primitive described in TR_OPTMGMT_ACK.
• Non-fatal errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TROUTSTATE

  The primitive would place the transaction interface out of state for the indicated transaction.

  
  

  TRSYSERR

  A system error occurred and the UNIX System error is indicated in the primitive.

4.1.3.2 Transaction Options Management Acknowledgement

TR_OPTMGMT_ACK

Format

The format of the message is one `M_PCPROTO' message block structured as follows:

     typedef struct TR_optmgmt_ack {
         ulong PRIM_type;          /* Always TR_OPTMGMT_ACK */
         ulong OPT_length;         /* options length */
         ulong OPT_offset;         /* options offset */
         ulong MGMT_flags;         /* options data flags */
     } TR_optmgmt_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_OPTMGMT_ACK'.

OPT_length

OPT_offset

MGMT_flags

Flags

Valid State

New State

Rules

4.1.4 Transaction Error Management

4.1.4.1 Transaction Successful Receipt Acknowledgement

TR_OK_ACK

This primitive indicates to the TR user that the previous TR-user-originated primitive was received successfully by the TR provider. It does not indicate to the TR user any TR protocol action taken due to the issuance of the last primitive. This may only be initiated as an acknowledgement for those primitives that require one.

Format

The format of the message is one `M_PCPROTO' message block structured as follows:

     typedef struct TR_ok_ack {
         ulong PRIM_type;          /* Always TR_OK_ACK */
         ulong CORRECT_prim;       /* correct primitive */
     } TR_ok_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_OK_ACK'.

CORRECT_prim

Indicates the primitive type that was successfully received.

Valid State

Valid in any state where a local acknowledgement requiring `TR_OK_ACK' response is pending.

New State

Depends on the current state; see State/Event Tables.

4.1.4.2 Transaction Error Acknowledgement

TR_ERROR_ACK

This primitive indicates to the TR user that a non-fatal¹¹ error has occurred in the last TR-user-originated primitive. This may only be initiated as an acknowledgement for those primitives that require one. It also indicates to the TR user that no action was taken on the primitive that cause the error.

Format

The format of the message is one `M_PCPROTO' message block structured as follows:

     typedef struct TR_error_ack {
         ulong PRIM_type;          /* Always TR_ERROR_ACK */
         ulong ERROR_prim;         /* primitive in error */
         ulong TRI_error;          /* TRI error code */
         ulong UNIX_error;         /* UNIX error code */
         ulong TRANS_id;           /* Transaction id */
     } TR_error_ack_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_ERROR_ACK'.

ERROR_prim

Indicates the primitive type that was in error.

TRI_error

Indicates the Transaction Sub-Layer Interface error code.

UNIX_error

Indicates the UNIX System error code. This field is zero (0) unless the TRI_error is equal to `TRSYSERR'.

TRANS_id

Valid State

This primitive is valid in any state where a local acknowledgement is pending and an error has occurred.

New State

The new state is the state that the interface was in before the primitive in error was issued, see State/Event Tables.

Rules

The TR provider is allowed to return any of the following TR error codes:

TRBADADDR

Indicates that the protocol address as specified in the primitive was of an incorrect format or the address contained illegal information.

TRBADOPT

Indicates that the options as specified in the primitive were in an incorrect format, or they contained illegal information.

TRBADF

Indicates that the stream queue pointer as specified in the primitive was illegal.

TRNOADDR

Indicates that the TR provider could not allocate a protocol address.

TRACCES

Indicates that the user did not have proper permissions to use the protocol address or options specified in the primitive.

TROUTSTATE

Indicates that the primitive would place the interface out of state.

TRBADSEQ

Indicates that the transaction identifier specified in the primitive was incorrect or illegal.

TRBADFLAG

Indicates that the flags specified in the primitive were incorrect or illegal.

TRBADDATA

Indicates that the amount of user data specified was illegal.

TRSYSERR

Indicates that a system error has occurred and that the UNIX System error is indicated in the primitive.

TRADDRBUSY

Indicates that the requested address is already in use.

TRRESADDR

Indicates that the TR provider requires the responding stream be bound to the same protocol address as the stream on which the dialogue “begin” indication (see TR_BEGIN_IND) was received.

TRNOTSUPPORT

Indicates that the TR provider does not support the requested capability.

4.2 Connection-Oriented Mode Primitives

4.2.1 Transaction Establishment

The transaction begin service provides means to start a transaction between two TR-users. This may be accompanied by the transfer of TR-user information contained in `M_DATA' message blocks accompanying the primitive.

4.2.1.1 Transaction Begin Request

TR_BEGIN_REQ

This primitive requests that the TR provider form an transaction association to the specified destination protocol address.

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks if any user data is specified by the TR user. The format of the `M_PROTO' message block is as follows:

     typedef struct TR_begin_req {
         ulong PRIM_type;          /* Always TR_BEGIN_REQ */
         ulong CORR_id;            /* Correlation Id */
         ulong ASSOC_flags;        /* Association flags */
         ulong DEST_length;        /* Destination address length */
         ulong DEST_offset;        /* Destination address offset */
         ulong ORIG_length;        /* Originating address length */
         ulong ORIG_offset;        /* Originating address offset */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_begin_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_BEGIN_REQ'.

CORR_id

Specifies the correlation identifier for the newly formed transaction. The correlation identifier is an identifier chose by the TR user that uniquely identifies this transaction association establishment request from other establishment requests on the same stream. If the CORR_id is zero (0), it specifies that this is the only transaction to be formed on the requesting stream and attempts to form additional transactions before this transaction is complete will fail. The value of CORR_id will be returned in

ASSOC_flags

Specifies the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

DEST_length

Specifies the length of the protocol address to which to establish an transaction association.

DEST_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol address begins.

ORIG_length

Specifies the length of the protocol address from which to establish an transaction association.

ORIG_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol address begins.

OPT_length

Specifies the length of the protocol options associated with the transaction.

OPT_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol options begin.

Flags

TR_SEQ_ASSURANCE

By setting this flag on the primitive, the originating transaction user can indicate that “sequence assured” service is requested from the underlying network service provider.

TR_NO_PERMISSION

By setting this flag on the primitive, the originating transaction user can either deny (set) or grant (clear) permission for the transaction peer to terminate the transaction association upon receipt of the corresponding primitive at the peer (see TR_BEGIN_IND). This flag can only be used with transaction provider that support it (see Addendum for ANSI Conformance).

Valid State

This primitive is valid in transaction state TRS_IDLE. This primitive is only valid in connection-oriented mode.

New State

The new state for the interface is TR_WACK_CREQ.

Rules

The following rules apply to the specification of parameters to this primitive:

• When the originating address is not specified, ORIG_length and ORIG_offset must be specified as zero (0).
• When the ORIG_length and ORIG_offset are zero (0), the originating address is the local address that is implicitly associated with the access point from the local bind service (see TR_BIND_REQ).
• The destination address must be specified and the TR provider will return error `TRNOADDR' if the DEST_length and DEST_offset are zero (0).

Acknowledgements

This primitive requires the transaction provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful Association Establishment: This is indicated with the `TR_BEGIN_CON' primitive described in TR_BEGIN_REQ. This results in the TRS_DATA_XFER state for the transaction. Successful establishment and tear down can also be indicated with the `TR_END_IND' primitive described in TR_END_IND. This results in the TRS_IDLE state for the transaction.
• Unsuccessful Association Establishment: This is indicated with the `TR_ABORT_IND' primitive described in TR_ABORT_IND. For example, an association may be rejected because either the called transaction user cannot be reached, or the transaction provider or the called transaction user did not agree on the specified options. This results in the TRS_IDLE state for the transaction.
• Non-fatal errors: These are indicated with the `TR_ERROR_ACK' primitive. The applicable non-fatal errors are defined as follows:

  TRACCES

  This indicates that the user did not have proper permissions for the use of the requested protocol address or protocol options.

  
  

  TRBADADDR

  This indicates that the protocol address was in an incorrect format or the address contained illegal information. It is not intended to indicate protocol connection errors, such as an unreachable destination. Those types of errors are indicated with the `TR_ABORT_IND' primitive described in TR_ABORT_IND.

  
  

  TRBADOPT

  This indicates that the options were in an incorrect format or they contained illegal information.

  
  

  TROUTSTATE

  The primitive would place the transaction interface out of state.

  
  

  TRBADDATA

  The amount of user data specified was illegal (see TR_INFO_ACK).

  
  

  TRSYSERR

  A system error has occured and the UNIX System error is indicated in the primitive.

4.2.1.2 Transaction Begin Indication

TR_BEGIN_IND

This primitive indicates to the destination TR user that a transaction association begin request has been made by the user at the specified source protocol address.

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_begin_ind {
         ulong PRIM_type;          /* Always TR_BEGIN_IND */
         ulong TRANS_id;           /* Transaction id */
         ulong ASSOC_flags;        /* Association flags */
         ulong DEST_length;        /* Destination address length */
         ulong DEST_offset;        /* Destination address offset */
         ulong ORIG_length;        /* Originating address length */
         ulong ORIG_offset;        /* Originating address offset */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_begin_ind_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_BEGIN_IND'.

TRANS_id

Indicates the transaction identifier associated by the transaction provider with this begin indication.

ASSOC_flags

Specifies the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

DEST_length

Indicates the length of the protocol address to which a transaction association was requested established by the peer.

DEST_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the protocol address begins.

ORIG_length

Indicates the length of the protocol address from which a transaction association was requested established.

ORIG_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the protocol address begins.

OPT_length

Indicates the length of the protocol options associated with the transaction begin indication.

OPT_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the protocol options begin.

Flags

TR_NO_PERMISSION

The value of this flag may indicate either that the transaction peer gives permission (clear) to end the transaction association or refuses permission (set) to end the transaction association. This flag is only valid for transaction providers that support it (see Addendum for ANSI Conformance).

Valid State

This primitive is valid in state TRS_IDLE. This primitive is only valid in connection-oriented mode.

New State

The new state for the identified transaction is TR_WRES_CIND.

Rules

The following rules apply to the issuance of this primitive by the transaction provider:

• The transaction identifier provided by the transaction provider uniquely identifies this transaction begin indication within the stream upon which the primitive is issued. This must be a positive, non-zero value. The high bit of the transaction identifier is reserved for exclusive use by the transaction user in generating correlation identifiers.
• It is not necessary to indicate a destination address in DEST_length, and DEST_offset when the protocol address to which the begin indication corresponds is the same as the local protocol address to which the listening stream is bound. In the case that the destination protocol address is not provided, DEST_length and DEST_offset must both be set to zero (0). When the local protocol address to which the begin indication corresponds is not the same as the bound address for the stream, the transaction provider must indicate the destination protocol address using DEST_length and DEST_offset.
• The origination protocol address is a mandatory field. The transaction provider must indicate the originating protocol address corresponding to the begin indication using the ORIG_length and ORIG_offset fields.
• Any indicated options are included in the OPT_length and OPT_offset fields.
• When the `TR_NO_PERMISSION' flag is set, the transaction user must not issue a `TR_END_REQ' primitive in response to this indication.

4.2.1.3 Transaction Begin Response

TR_BEGIN_RES

This primitive allows the destination TR user to request that the transaction provider accept a previous transaction association begin indication.

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_begin_res {
         ulong PRIM_type;          /* Always TR_BEGIN_RES */
         ulong TRANS_id;           /* Transaction id */
         ulong ASSOC_flags;        /* Association flags */
         ulong ORIG_length;        /* Originating address length */
         ulong ORIG_offset;        /* Originating address offset */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_begin_res_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_BEGIN_RES'.

TRANS_id

Specifies the transaction identifier of an outstanding begin indication to which the transaction user is responding.

ASSOC_flags

Specifies the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

ORIG_length

Specifies the length of the protocol address to be used as the responding address.

ORIG_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol address begins.

OPT_length

Specifies the length of the protocol options to be associated with the begin response.

OPT_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol options begin.

Flags

TR_SEQ_ASSURANCE

By setting this flag on the primitive, the originating transaction user can indicate that “sequence assured” service is requested from the underlying network service provider.

TR_NO_PERMISSION

By setting this flag on the primitive, the originating transaction user can either deny (set) or grant (clear) permission for the transaction peer to terminate the transaction association upon receipt of the corresponding primitive at the peer (see TR_BEGIN_IND). This flag can only be used with transaction provider that support it (see Addendum for ANSI Conformance).

Valid State

This primitive is valid in transaction state TR_WRES_CIND. This primitive is only valid in connection-oriented mode.

New State

The new state for the specified transaction is TRS_DATA_XFER.

Rules

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_OK_ACK primitive described in TR_OK_ACK.
• Unsuccessful (Non-fatal errors): These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TRBADF

  The token specified is not associated with an open stream.

  
  

  TRBADOPT

  The options were in an incorrect format, or they contained illegal information.

  
  

  TRACCES

  The user did not have proper permissions for the use of the responding protocol address or protocol options.

  
  

  TROUTSTATE

  The primitive would place the transaction interface out of state for the indicated transaction.

  
  

  TRBADDATA

  The amount of user data specified was outside the range supported by the transaction provider.

  
  

  TRBADSEQ

  The transaction identifier specified in the primitive was incorrect or illegal.

  
  

  TRSYSERR

  A system error occurred and the UNIX System error is indicated in the primitive.

  
  

  TRRESADDR

  The transaction provider requires that the responding stream is bound to the same address as the stream on which the transaction association begin indication was received.

  
  

  TRBADADDR

  This indicates that the protocol address was in an incorrect format or the protocol address contained illegal information.

4.2.1.4 Transaction Begin Confirmation

TR_BEGIN_CON

This primitive indicates to the source transaction user that a previous transaction association begin request has been confirmed on the specified responding protocol address.

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_begin_con {
         ulong PRIM_type;          /* Always TR_BEGIN_CON */
         ulong CORR_id;            /* Correlation Id */
         ulong TRANS_id;           /* Transaction id */
         ulong ASSOC_flags;        /* Association flags */
         ulong ORIG_length;        /* Originating address length */
         ulong ORIG_offset;        /* Originating address offset */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_begin_con_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_BEGIN_CON'.

CORR_id

Indicates the correlation identifier used by the transport user to uniquely identify the transaction begin request of the stream to which this confirmation corresponds. This is the transaction user assigned transaction identifier of the corresponding `TR_BEGIN_REQ' that this message is confirming.

TRANS_id

Indicates the transaction identifier provided by the transport provider to uniquely identify the transaction on this stream.

ASSOC_flags

Indicates the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

ORIG_length

Indicates the length of the responding protocol address from which the confirmation was received.

ORIG_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the responding protocol address begins.

OPT_length

Indicates the length of the confirmed protocol options negotiated by the transaction peer.

OPT_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the confirmed protocol options begin.

The proper alignment of the responding address and options in the `M_PROTO' message block is not guaranteed.

Flags

The following association flags are defined:

TR_NO_PERMISSION

The value of this flag may indicate either that the transaction peer gives permission (clear) to end the transaction association or refuses permission (set) to end the transaction association. This flag is only valid for transaction providers that support it (see Addendum for ANSI Conformance).

Mode

This primitive is only valid in connection-oriented mode.

Originator

Transaction provider.

Valid State

This primitive is valid in transaction state TRS_WCON_CREQ.

New State

The new state for the transaction is TRS_DATA_XFER.

Rules

The following rules apply to the issuance of this primitive:

• It is not always necessary for the transport provider to provide the responding address in the ORIG_length and ORIG_offiset fields. Where the responding protocol address is the same as the destination protocol address for which the transaction initialization was requested, it is not necessary to provide the responding address in the TR_BEGIN_CON. Where the responding protocol address is not provided, the ORIG_length and ORIG_offset fields are set to zero (0).
• When the `TR_NO_PERMISSION' flag is set, the transaction user must not issue a `TR_END_REQ' primitive in response to this indication.

4.2.2 Transaction Data Transfer

The data transfer service primitives provide for an exchange of transaction user data known as TSDUs, in either direction or in both directions simultaneously on a transaction association. The transaction service preserves both the sequence and the boundaries of the TSDUs.

4.2.2.1 Transaction Continue Request

TR_CONT_REQ

This user-originated primitive specifies to the transaction provider that this message contains transaction user data. It allows the transfer of transaction user data between transaction users, without modification by the transaction provider.

The transaction user must send an integral number of octets of data greater than zero. In a case where the size of the TSDU exceeds the TIDU (as specified by the size of the TIDU_size parameter of the `TR_INFO_ACK' primitive described in TR_INFO_ACK), the TSDU may be broken up into more than one TIDU. When a TSDU is broken up into more than one TIDU, the `T_MORE' flag will be set on each TIDU except the last one.

Format

The format of the message is one or more `M_DATA' message blocks. Use of a `M_PROTO' message block is optional. The `M_PROTO' message block is used for two reasons:

1. to indicate that the TSDU is broken into more than one TIDU, and that the data carried in the following `M_DATA' message block constitutes one TIDU;
2. to indicate whether receipt confirmation is desired for the TSDU.

     typedef struct TR_cont_req {
         ulong PRIM_type;          /* Always TR_CONT_REQ */
         ulong TRANS_id;           /* Transaction id */
         ulong ASSOC_flags;        /* Association flags */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_cont_req_t;
     

Guidelines for use of M_PROTO

The following guidelines must be followed with respect to the user of the `M_PROTO' message block:

1. The M_PROTO message block need not be present when the TSDU size is less that or equal to the TIDU size and one of the following is true:
   • receipt confirmation has been negotiated for non-use; or
   • receipt confirmation has been successfully negotiated for use or non-use and the default selection as specified via the `TR_OPTMGMT_REQ' primitive is to be used.
2. The M_PROTO message block must be present when:
   • the TSDU size is greater than the TIDU size;
   • receipt confirmation has been successfully negotiated for use and the default selection as specified with the `TR_OPTMGMT_REQ' primitive needs to be overridden.

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_CONT_REQ'.

TRANS_id

Specifies the transaction identifier previously indicated by the transport provider to uniquely identify the transaction. The transaction identifier must be specified by the transaction user unless there is only one transaction supported by the stream in transaction state TRS_DATA_XFER. When specified, the transaction identifier must be the same as the transaction identifier that was indicated by the transaction provider in the corresponding `TR_BEGIN_IND' or `TR_BEGIN_CON'.

ASSOC_flags

Specifies the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

OPT_length

Specifies the length of the protocol options associated with the user data transfer. Supplying protocol options with the primitive is optional. If the transaction user does not provide protocol options with the primitive, the OPT_length and OPT_offset fields must be set to zero (0) by the transaction user. The format of the protocol options are provider specific.

OPT_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol options begin. Alignment of the protocol options in the `M_PROTO' message block is not guaranteed. However, the alignment of the protocol options in the `M_PROTO' message block are the same as was specified by the transport user.

Flags

TR_MORE_DATA_FLAG

When set, the MORE_DATA_FLAG indicates that the next `TR_CONT_REQ' primitive (TIDU) is also part of this TSDU.

TR_RC_FLAG

By setting this flag on the `TR_CONT_REQ', the originating transaction user can request confirmation of receipt of the TR_CONT_REQ primitive.

TR_SEQ_ASSURANCE

By setting this flag on the primitive, the originating transaction user can indicate that “sequence assured” service is requested from the underlying network service provider.

TR_NO_PERMISSION

By setting this flag on the `TR_CONT_REQ', the originating transaction user can either deny (set) or grant (clear) permission for the transaction peer to terminate the transaction association upon receipt of the corresponding `TR_CONT_IND' primitive. This flag is only used for transaction providers that support this feature (see Addendum for ANSI Conformance).

Valid State

This primitive is valid in transaction state TRS_DATA_XFER. This primitive is only valid in connection-oriented mode.

New State

The new state for the transaction remains unchanged.

Acknowledgements

This primitive does not require acknowledgement. If a non-fatal error occurs, it is the responsibility of the peer ASE to report it within the upper-layer protocol or using the TR_ABORT_IND primitive (see TR_ABORT_IND). Fatal errors are indicated with the `M_ERROR' message type which results in the failure of all operating system service routines on the stream. The allowable fatal errors are as follows:

EPROTO

This error indicates on of the following unrecoverable protocol conditions:

• The transaction interface was found to be in an incorrect state.
• The amount of transaction user data associated with the primitive is outside the range supported by the transaction provider (as specified by the TIDU_size parameter of the `TR_INFO_ACK' primitive described in TR_INFO_ACK.)
• The options requested are either not support by the transaction provider or their use is not specified with the TR_BEGIN_REQ primitive.
• The `M_PROTO' message block was not follows by one or more `M_DATA' message blocks.
• The amount of transaction user data associated with the current NSDU is outside the range supported by the transaction provider (as specified by the TSDU_size parameter in the `TR_INFO_ACK' primitive described in TR_INFO_ACK.)
• The TR_RC_FLAG and TR_MORE_DATA_FLAG were both set in the primitive, or the flags field contained an unknown value.

NOTE: If the interface is in the TRS_IDLE state when the provider receives the `TR_CONT_REQ' primitive, then the transaction provider should discard the request without generating a fatal error.

4.2.2.2 Transaction Continue Indication

TR_CONT_IND

This transaction provider originated primitive indicates to the transaction user that this message contains transaction user data. As in the `TR_CONT_REQ' primitive (see TR_CONT_REQ), the TSDU can eb segmented into more than one TIDU. The TIDUs are assocated with the TSDU by using the TR_MORE_DATA_FLAG. The TR_RC_FLAG and TR_NO_PERMISSION flags are allowed to be set only on the last TIDU. Use of the `M_PROTO' message blocks is optional (see guidelines describe in see TR_CONT_REQ).

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_cont_ind {
         ulong PRIM_type;          /* Always TR_CONT_IND */
         ulong TRANS_id;           /* Transaction id */
         ulong ASSOC_flags;        /* Association flags */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_cont_ind_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_CONT_IND'.

TRANS_id

Indicates the transaction identifier previously indicated by the transport provider to uniquely identify the transaction. The transaction identifier must be indicated by the transaction provider. The transaction identifier must be the same as the transaction identifier that was indicated in the corresponding `TR_BEGIN_IND' or `TR_BEGIN_CON'.

ASSOC_flags

Specifies the option flags provided with the primitive. See “Flags” below. Some flags may be provider specific.

OPT_length

Indicates the length of the protocol options associated with the user data transfer. Protocol options are only indicated by the transaction provider when they were supplied by the underlying protocol. If the transport provider does not indicate protocol options, the OPT_length and OPT_offset fields must be set to zero (0). The format of the protocol options are provider specific.

OPT_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the protocol options begin.

Flags

TR_MORE_DATA_FLAG

When set, indicates taht the next `TR_CONT_IND' message (TIDU) is part of this TSDU.

TR_RC_FLAG

The value of the flag may indicate either that confirmation is requested or that it is not requested. The flag is allowed to be set only if use of the Receipt Confirmation was agreed between both the transaction users and the transaction provider during transaction association establishment. The value of this flag is always identical to that supplied in the corresponding `TR_CONT_REQ'.

TR_NO_PERMISSION

The value of this flag may indicate either that the transaction peer gives permission (clear) to end the transaction association or does not give permission (set) to end the transaction association. This flag is only valid for transaction providers that support it (see Addendum for ANSI Conformance).

Valid State

This primitive is valid in transaction state TRS_DATA_XFER. This primitive is only valid in connection-oriented mode.

New State

The new state for the transaction is unchanged.

Rules

• When the `TR_NO_PERMISSION' flag is set, the transaction user must not issue a `TR_END_REQ' primitive in response to this indication.

4.2.3 Transaction Termination

4.2.3.1 Transaction End Request

TR_END_REQ

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_end_req {
         ulong PRIM_type;          /* Always TR_END_REQ */
         ulong TRANS_id;           /* Transaction id */
         ulong TERM_scenario;      /* Termination scenario */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_end_req_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Specifies the primitive type: always `TR_END_REQ'.

TRANS_id

Specifies the transaction identifier previously indicated by the transport provider to uniquely identify the transaction. The transaction identifier must be specified by the transaction user unless there is only one transaction supported by the stream in transaction state TRS_DATA_XFER. When specified, the transaction identifier must be the same as the transaction identifier that was indicated by the transaction provider in the corresponding `TR_BEGIN_IND' or `TR_BEGIN_CON'.

TERM_scenario

Specifies the termination scenario. Termination scenarios are provider specific.

OPT_length

Specifies the length of the protocol options associated with the transaction association termination. Supplying protocol options with the primitive is optional. If the transaction user does not provide protocol options with the primitive, the OPT_length and OPT_offset fields must be set to zero (0) by the transaction user. The format of the protocol options are provider specific.

OPT_offset

Specifies the offset from the beginning of the `M_PROTO' message block where the protocol options begin. Alignment of the protocol options in the `M_PROTO' message block is not guaranteed. However, the alignment of the protocol options in the `M_PROTO' message block are the same as was specified by the transport user.

Valid State

This primitive is valid in transaction state TRS_DATA_XFER. This primitive is only valid in connection-oriented mode.

New State

The new state of the transaction is TRS_IDLE.

Rules

Acknowledgements

This primitive requires the TR provider to generate one of the following acknowledgements upon receipt of the primitive:

• Successful: Correct acknowledgement of the primitive is indicated with the TR_OK_ACK primitive described in TR_OK_ACK.
• Non-fatal errors: These errors will be indicated with the TR_ERROR_ACK primitive described in TR_ERROR_ACK. The allowable errors are as follows:

  TROUTSTATE

  The primitive would place the transaction interface out of state for the indicated transaction.

  
  

  TRSYSERR

  A system error occurred and the UNIX System error is indicated in the primitive.

4.2.3.2 Transaction End Indication

TR_END_IND

Format

The format of the message is one `M_PROTO' message block, followed by zero or more `M_DATA' message blocks containing user data for the association, structured as follows:

     typedef struct TR_end_ind {
         ulong PRIM_type;          /* Always TR_END_IND */
         ulong CORR_id;            /* Correlation id */
         ulong TRANS_id;           /* Transaction id */
         ulong OPT_length;         /* Options structure length */
         ulong OPT_offset;         /* Options structure offset */
     } TR_end_ind_t;
     

Parameters

The primitive has the following arguments:

PRIM_type

Indicates the primitive type: always `TR_END_IND'.

CORR_id

Indicates the correlation identifier previously specified by the transport user to uniquely identify an outstanding transaction request that has not yet received transaction confirmation. For all other cases, this field must be set to zero (0).

TRANS_id

Indicates the transaction identifier previously indicated by the transport provider to uniquely identify the transaction. The transaction identifier must be indicated by the transaction provider. The transaction identifier must be the same as the transaction identifier that was indicated in the corresponding `TR_BEGIN_IND' or `TR_BEGIN_CON' (if any).

OPT_length

Indicates the length of the protocol options associated with the transaction association termination. Protocol options are only indicated by the transaction provider when they were supplied by the underlying protocol. If the transport provider does not indicate protocol options, the OPT_length and OPT_offset fields must be set to zero (0). The format of the protocol options are provider specific.

OPT_offset

Indicates the offset from the beginning of the `M_PROTO' message block where the protocol options begin.

Valid State

This primitive is valid in transaction states TRS_WCON_CREQ or TRS_DATA_XFER. This primitive is only valid in connection-oriented mode.

New State

The new state for the transaction is TRS_IDLE.

Rules

The following rules apply to the issuance of this primitive:

• This primitive may be issued in response to a TR_BEGIN_REQ primitive. When issued in this case, the transaction provider is indicating that a transaction is both confirmed and terminated.
• This primitive may be issued after receiving a TR_BEGIN_RES or issuing a TR_BEGIN_CON, but before receiving a TR_END_REQ or TR_ABORT_REQ primitive, or issuing a TR_UABORT_IND or TR_PABORT_IND primitive.
• When issued, this primitive indicates the tear-down of the transaction association corresponding to the TRANS_id indicated in the primitive.

4.2.3.3 Transaction User Abort Request

TR_ABORT_REQ

Format

The format of the message is one `M_PROTO'