Networking and Data Communications Library Tandem OSI/AS Programming Manual Product Version OSI/AS C30 Release ID C30.08/D10 Edition Print Date Part Number Abstract July 1992 056783 This manual shows programmers how to use the OSI Session Layer, Presentation Layer, and ACSE procedural interface provided by the Tandem OSI/AS subsystem. This interface allows applications to communicate in the OSI environment.
Document History Edition Part Number Product Version Release ID Print Date First Edition Second Edition Third Edition 84274 24501 056783 OSI/AS C20 OSI/AS C21 OSI/AS C30 C20 C20 C30.08/D10 March 1989 March 1990 July 1992 New editions incorporate any updates issued since the previous edition. Release ID Note Release ID specifies the release in which the software functions described in an edition are the first available on a standard SUT (site update tape).
New and Changed Information This is the third edition of the Tandem OSI/AS Programming Manual. This revision reflects technical enhancements to the Tandem OSI product and includes some organizational and content enhancements to the manual as well. Product The product enhancements described in this revision are as follows: Enhancements A major new feature, which you enable through the use of configuration parameters, allows your application to reuse a subdevice from one connection to the next.
New and Changed Information iv 056783 Tandem Computers Incorporated
Contents About This Manual xiii Notation Conventions Section 1 xix Introduction What Are the APS Procedures? What Is the API? 1-1 1-2 What Is an OSI/AS Subsystem? 1-2 The OSI Manager Process 1-4 Management Information Base (MIB) The OSI Layers 1-4 What OSI/AS Connections Are Possible? 1-4 1-5 Overview of OSI/AS Session Layer Support 1-6 What Are the Functions of the Session Layer? 1-6 Which Functional Units Are Supported? 1-6 How Is the Session Version Selected? 1-7 Overview of OSI/AS Presentation
Contents Dynamic and Static Subdevices 2-20 Reusing Static Subdevices 2-21 Wait and Nowait Mode 2-22 Wait Mode 2-22 Nowait Mode 2-22 Fault Tolerance 2-23 Before Running Your Application Program 2-24 Calling an APS Procedure 2-25 Types of APS Procedures 2-25 Status and Error Information 2-25 Initializing the API 2-27 Establishing a Connection 2-27 Establishing a Connection as the Calling User 2-28 Establishing a Connection as the Responding User 2-30 Sending and Retrieving User Data 2-33 Defining User
Contents APS_ACTIVITY_ENDREQ_ 3-10 APS_ACTIVITY_ENDRSP_ 3-12 APS_ACTIVITY_GETPARAM_ 3-14 APS_ACTIVITY_INTERRUPTREQ_ 3-16 APS_ACTIVITY_INTERRUPTRSP_ 3-18 APS_ACTIVITY_RESUMEREQ_ 3-20 APS_ACTIVITY_STARTREQ_ 3-23 APS_ASSOC_ABORTREQ_ 3-25 APS_ASSOC_ATTACH_ 3-27 APS_ASSOC_CONNECTREQ_ 3-31 APS_ASSOC_CONNECTRSP_ 3-38 APS_ASSOC_GETPARAM_ 3-44 APS_ASSOC_RELEASEREQ_ 3-53 APS_ASSOC_RELEASERSP_ 3-55 APS_CAPDATA_REQ_ 3-57 APS_CAPDATA_RSP_ 3-59 APS_CONTROL_GIVEREQ_ 3-61 APS_DATA_GETPARAM_ 3-63 APS_DATA_REQ_ 3-67 APS_DIS
Contents Appendix A DDL Definitions Basic Data Types A-2 First-Level Data Types A-2 Second-Level Data Types A-3 Third-Level Data Types A-5 Parameter Structures Named Values A-6 A-20 Cross-Reference Tables Appendix B A-33 Status and Error Codes Using the Codes Status Codes B-1 B-1 Error Codes B-5 General API Error Codes B-5 Session Service Error Codes B-20 Error Subcodes B-24 Error Subcode Tables Appendix C Module File Management (MFM) Procedure Calls MFM_AWAITIOX_ C-2 MFM_CANCELREQ_ Appendix
Contents Abbreviations Abbreviations–1 Glossary Glossary–1 Index Figures Index–1 Figure 0-1. Documentation Road Map Figure 1-1. The Tandem OSI/AS Environment Figure 2-1. Primitives, Confirmed Service Figure 2-2. Primitives, Unconfirmed Service Figure 2-3. Primitives, Provider Indication Figure 2-4. Buffer Containing a Single Data Element Figure 2-5. Buffer Containing Multiple Data Elements Figure 2-6. PDV Types Figure 2-7. Two Single ASN.
Contents x Table 2-8. Sequence of Procedures to Obtain Tokens Table 2-9. Summary of Activity Management Procedures Table 2-10. Procedures Giving Completion Information Table 2-11. Types of APS Procedures Table 2-12. Sequence of Procedures to Establish a Connection as the Calling User 2-28 Table 2-13. Sequence of Procedures to Establish a Connection as the Responding User 2-31 Table 2-14. Other Procedures That Can Send User Data Table 2-15.
Contents Table B-2. General API Error Values Table B-3. Session Service Error Values Table B-4. Resource Limit Subcodes Table B-5. Parameter Subcodes Table B-6. State Machine Subcodes Table B-7. Provider Exception Subcodes Table B-8. Functional Unit Subcodes Table B-9. OSI Manager Subcodes Table B-10. Session Token Subheads B-29 Table B-11. Session Token Subheads B-30 Table B-12. Session Protocol Variable Subcodes Table B-13. PI or PGI Unit Subcodes Table B-14.
Contents xii 056783 Tandem Computers Incorporated
About This Manual About the OSI/AS and The OSI/AS subsystem and the OSI/TS subsystem together provide core services that OSI/TS Manual Set support the seven-layer OSI Reference Model. The set of manuals for these two products are listed in Table 0-1. The table lists the tasks that the OSI/AS and OSI/TS manuals are designed to support and the type of information provided in each manual. Table 0-1. Overview of Contents of OSI/AS and OSI/TS Manuals Is Provided by These Manuals in The OSI Manual Set ...
About This Manual About This Manual This manual describes the Tandem APS (application, presentation, and session) procedures, which enable application programs to establish and use Open Systems Interconnection (OSI) connections using the Session Layer, the Presentation Layer, and the Association Control Service Element (ACSE) of the Application Layer. These procedures are part of the Tandem OSI/AS (Open Systems Interconnection/Application Services) data communications subsystem.
About This Manual Programming for the Guardian 90 operating system Programming in the Transaction Application Language (TAL) or in C Reading declarations written in the Data Definition Language (DDL), as described in the “Overview of DDL for SPI” appendix in the Distributed Systems Management (DSM) Programming Manual Other publications you should read before reading this manual are listed in “What Related Publications Are Available?” later in this preface.
About This Manual What Related The other publications related to this manual fall into three categories: standards Publications Are documents, with which you should first be familiar; prerequisite manuals, which you Available? should read before you read this manual; and other Tandem OSI manuals.
About This Manual Figure 0-1.
About This Manual Other Tandem OSI Manuals In addition to the prerequisite manuals shown in Figure 0-1, you may need to be familiar with some of the other manuals in the Tandem OSI/AS manual set. These manuals describe various aspects of the management of OSI/AS subsystems. The Tandem OSI/AS Configuration and Management Manual describes how to configure and manage the OSI/AS subsystem. It is intended for system managers and operators.
Notation Conventions The following list summarizes the conventions for syntax presentation in this manual. Notation Meaning UPPERCASE LETTERS lowercase italic letters Brackets [ ] Uppercase letters represent keywords and reserved words; enter these items exactly as shown. Lowercase italic letters represent variable items that you supply. I/O Spaces Punctuation 056783 Tandem Computers Incorporated Brackets enclose optional syntax items.
1 Introduction This section presents an overview of the Tandem OSI/AS (Open Systems Interconnection/Application Services) product. It begins by introducing the APS (application, presentation, and session) procedures, the API (application programmatic interface), and other significant software components of an OSI/AS subsystem. It then summarizes the support provided by OSI/AS for the Session, Presentation, and Application Layers of the OSI Reference Model.
Introduction What Is the API? What Is the API? The application programmatic interface (API) provided by OSI/AS is the Tandem interface between applications and the OSI upper-layer environment. You access the OSI/AS subsystem through the API by calling the APS procedures. When you call an APS procedure to initiate a session, presentation, or ACSE operation, the API passes on the request for services, if necessary, to one or more OSI/AS subsystem processes.
Introduction What Is the API? Figure 1-1.
Introduction What Is the API? The OSI Manager Process The OSI manager process manages the OSI/AS configuration information necessary to set up OSI/AS connections. Each OSI/AS subsystem has exactly one OSI manager process. The OSI manager process provides management functions for TAPS processes. It also provides some management functions for the TSP processes and very limited management functions for the NSP processes.
Introduction What OSI/AS Connections Are Possible? Layer, and the Network Layer. For local area networks, TLAM performs the functions of the Physical Layer and the Data Link Layer. (However, note that the functions of the OSI internet protocol (IP) in the Network Layer are performed not by NSP processes, but by TSP processes.) The Transport Layer functions are provided by TSP (transport service provider) processes.
Introduction Overview of OSI/AS Session Layer Support Overview of OSI/AS As mentioned earlier, the procedures described in this manual provide the functions of Session Layer Support the Session Layer of the OSI Reference Model. The formal definitions of the session service and protocol are given in the international standard documents ISO 8326 and ISO 8327. OSI/AS supports both version 1 and version 2 of the session service and protocol.
Introduction Overview of OSI/AS Session Layer Support The duplex functional unit allows you to operate in duplex mode over a connection. In this mode, data can be transferred in both directions simultaneously. A particular connection uses either the half-duplex or the duplex functional unit, but not both. The typed data functional unit allows you to send typed data over a connection, ignoring any token restrictions.
Introduction Overview of OSI/AS Presentation Layer Support Overview of OSI/AS Presentation Layer Support The procedures described in this manual also provide access to the functions described in the Presentation Layer of the OSI Reference Model. The formal definitions of the presentation service and protocol are given in the OSI standards ISO 8822 and ISO 8823. In addition, ISO 8824 (Abstract Syntax Notation-1, or ASN.1) and ISO 8825 (Basic Encoding Rules for ASN.1) are related to the Presentation Layer.
Introduction Overview of OSI/AS Support for ACSE Overview of OSI/AS Support for ACSE The procedures described in this manual also provide access to the functions of the association control service element (ACSE) within the Application Layer (Layer 7) of the OSI Reference Model. The formal definitions of the ACSE service and protocol are given in the OSI standards ISO 8649 and ISO 8650. OSI/AS supports version 1 of the ACSE service and protocol.
2 APS Procedures Programming Concepts This section introduces you to some concepts you need to know to use the APS procedures.
APS Procedures Programming Concepts Naming Conventions A functional unit is a set of one or more related services. For example, the activity management functional unit consists of the activity start service, the activity resume service, the activity end service, the activity interrupt service, and the activity discard service.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Although you will find numeric values for error and status codes in this manual, we strongly recommend that you always use symbolic names. When creating data names for your own fields, we recommend that you avoid names that start with the letter Z (uppercase or lowercase). Such names could conflict with names defined in Tandem software.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Figure 2-1 shows the full sequence of four primitives exchanged for a confirmed service—a service for which a response is returned. Figure 2-1. Primitives, Confirmed Service 1 Request Service Provider Your Application Indication 2 Response 3 Remote Application 4 Confirm 015 An example of the sequence of primitives for a confirmed service is described below, using as the starting point a connect request issued by your application.
APS Procedures Programming Concepts OSI Upper-Layer Concepts An example of the sequence of primitives for an unconfirmed service is described below, using as the starting point a data request issued by your application. 1. To send data to the remote application over an established connection, you call APS_DATA_REQ_. OSI/AS generates a data request primitive, which contains the data you are sending, and issues it to the service provider. 2.
APS Procedures Programming Concepts OSI Upper-Layer Concepts All the primitives in these tables are available through the Session Layer and the Presentation Layer. ACSE supports only the following primitives: Associate Release User abort Provider abort All other primitives sent and received over ACSE connections use ACSE transparently—that is, OSI/AS passes them directly to the Presentation Layer. (Similarly, for Presentation Layer connections, some primitives are passed directly to the Session Layer.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Table 2-2.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Table 2-3. Procedures for Response Primitives Response Primitive Procedure Initiating the Response Activity discard Activity end Activity interrupt Capability data Connect or Associate Release Resynchronize Synchronize major Synchronize minor APS_ACTIVITY_DISCARDRSP_ APS_ACTIVITY_ENDRSP_ APS_ACTIVITY_INTERRUPTRSP_ APS_CAPDATA_RSP_ APS_ASSOC_CONNECTRSP_ APS_ASSOC_RELEASERSP_ APS_RESYNCRSP_ APS_SYNC_MAJORRSP_ APS_SYNC_MINORRSP_ Table 2-4.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Tokens The Session Layer standards define the concept of a token. A token is an attribute of a connection giving the application that holds it the exclusive right to perform a given function. For example, in half-duplex mode, if you hold the data token, your application can send normal data. Before the remote application can send data in halfduplex mode, it must acquire the data token from your application.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Table 2-6.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Table 2-7. Procedures That Return Token States Procedure State of Tokens APS_ASSOC_GETPARAM_ APS_SYNC_GETPARAM_ After a connect indication or confirm After a resynchronize indication or confirm, a token please indication, or a token give indication Table 2-8.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Synchronization and Activity Management Synchronization allows you to structure the exchange of data between your application and a remote application by establishing fixed points in your work on a connection. Depending on the functional units available on the connection, there are several ways to perform synchronization. Activity management is a similar concept, dividing the work into activities.
APS Procedures Programming Concepts OSI Upper-Layer Concepts If you interrupt or discard an activity (using APS_ACTIVITY_INTERRUPTREQ_ or APS_ACTIVITY_DISCARDREQ_), you cannot initiate other services (except for a user abort request) until you receive the corresponding confirm event. If you discard an activity (using APS_ACTIVITY_DISCARDREQ_), it is implied that the content of the activity is canceled. However, this action is left up to your application and is not controlled by the service provider.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Names for Service Users The OSI standards and the OSI/AS manuals refer to the calling user, the called user, and the responding user for a connection. These terms are explained briefly in the following subsections. Note that corresponding terms are used for the addresses of each of these kinds of users; for instance, the calling address is the address of the calling user.
APS Procedures Programming Concepts OSI Upper-Layer Concepts Table 2-10.
APS Procedures Programming Concepts OSI Upper-Layer Concepts The action you can take depends on the functional units and tokens available, but must be one of the following actions: Resynchronize the connection using APS_RESYNCREQ_. Abort the connection using APS_ASSOC_ABORTREQ_. Interrupt the activity using APS_ACTIVITY_INTERRUPTREQ_. Discard the activity using APS_ACTIVITY_DISCARDREQ_. Give the data token (and, optionally, other tokens) to the remote application using APS_TOKEN_GIVE_.
APS Procedures Programming Concepts OSI Upper-Layer Concepts of BER, see “Encoding ACSE and Presentation User Data,” later in this section. Other transfer syntaxes have been proposed, including compression, encryption, and the Japanese INTAP-1. Transfer syntaxes for each proposed abstract syntax are negotiated at presentation connect time.
APS Procedures Programming Concepts OSI Upper-Layer Concepts If you are using the OSI/AS implementation of ACSE, you must not propose a presentation context for ACSE itself in the connect request; OSI/AS will supply it in the presentation context definition list.
APS Procedures Programming Concepts OSI Upper-Layer Concepts For the ACSE presentation context, OSI/AS sets the the following values in the presentation context definition result list: The result is set to indicate acceptance of the proposed presentation context. The transfer syntax name is set to the value for ASN.1 BER. The reason is set to no value. For each element in the presentation context definition result list in the indication, you must include a corresponding element in the response.
APS Procedures Programming Concepts Connection Endpoint Identifier (CEPI) Connection Endpoint The connection endpoint identifier, or CEPI, identifies your OSI/AS connection or Identifier (CEPI) connection attempt. It is normally an integer in the range -10 through -32767; exceptions to this range are described below. You use the CEPI in APS procedure calls as you would use the file number in file-system calls.
APS Procedures Programming Concepts Connection Endpoint Identifier (CEPI) A dynamic subdevice exists until you call APS_DISCARD_ to discard the connection context. With dynamic subdevices, the linkage between a TAPS process and the lower layers must be reestablished whenever you call APS_ASSOC_ATTACH_ or APS_ASSOC_CONNECTREQ_; that takes time. A static subdevice, by contrast, is not deleted when you call APS_DISCARD_.
APS Procedures Programming Concepts Wait and Nowait Mode 7. When you are completely finished using the static subdevice, call APS_SUBDEVICE_DISCARD_ to delete the subdevice. Wait and Nowait Mode The APS procedures use the Guardian 90 file system by calling the file-system procedures internally for file-system I/O operations.
APS Procedures Programming Concepts Fault Tolerance Caution Never use AWAITIO or AWAITIOX in application processes that access the API. Doing so can interfere with the correct operation of the API. Use MFM_AWAITIOX_ instead. Do not call MFM_AWAITIOX_ to complete those APS procedure calls that never cause file-system I/O operations. These calls need no completion, even if the connection is operating in nowait mode.
APS Procedures Programming Concepts Before Running Your Application Program Before Running Your Application Program Before your application establishes a connection, your system manager (or whoever is responsible for system management at your installation) should make the preparations summarized below. The Tandem OSI/AS Configuration and Management Manual provides detailed instructions for performing these tasks.
APS Procedures Programming Concepts Calling an APS Procedure Calling an APS Procedure Note You use the same set of APS procedures to access services of the Session Layer, the Presentation Layer, and ACSE. You can establish and use connections at different layers in the same program; use service-id in APS_ASSOC_ATTACH_ or APS_ASSOC_CONNECTREQ_ calls to indicate whether each connection is to be a session, presentation, or ACSE connection. Some procedure parameters apply only to particular layers.
APS Procedures Programming Concepts Calling an APS Procedure Table 2-11.
APS Procedures Programming Concepts Establishing a Connection Initializing the API When your application is running, but before it can establish its first OSI/AS connection, it must call the APS_INITIALIZE_ procedure. This procedure asks the API to allocate and initialize a reserved extended segment for this instance of your application—that is, for this particular Guardian 90 process.
APS Procedures Programming Concepts Establishing a Connection Establishing a Connection as the Calling User Table 2-12 gives the sequence of procedure calls needed to establish a connection as the calling user, together with a statement of what you are asking OSI/AS to do in each case. The procedure calls in square brackets can sometimes be omitted, depending on the context. The sequence of procedures is explained after the table.
APS Procedures Programming Concepts Establishing a Connection 4. Optionally, call APS_ASSOC_GETPARAM_ to obtain the OSI addresses of your application and the remote application (if you specified only the application names in the call to APS_ASSOC_CONNECTREQ_), and to obtain other information for a presentation or ACSE connection. 5. Next, to be able to receive a connect confirm event, call APS_EVENT_RECEIVE_.
APS Procedures Programming Concepts Establishing a Connection If the connection was accepted, you can now start to use it. For example, if activity management is available and you hold the relevant tokens, you may wish to start an activity using APS_ACTIVITY_STARTREQ_. Or, you may wish to send data over the connection, using APS_DATA_REQ_. If the connection was rejected, clear the context information for the connection by calling APS_DISCARD_.
APS Procedures Programming Concepts Establishing a Connection Table 2-13. Sequence of Procedures to Establish a Connection as the Responding User Procedure What You’re Asking OSI/AS [ APS_INITIALIZE_ ] APS_ASSOC_ATTACH_ [ MFM_AWAITIOX_ ] [ APS_ASSOC_GETPARAM_ ] APS_EVENT_RECEIVE_ [ MFM_AWAITIOX_ ] APS_STATUS_ APS_ASSOC_GETPARAM_ [ APS_DATA_GETPARAM_ ] APS_ASSOC_CONNECTRSP_ [ MFM_AWAITIOX_ ] (Once only) Initialize the API. Prepare to accept a connection. (Nowait) Await completion; check status.
APS Procedures Programming Concepts Establishing a Connection 7. If you have received an event, call APS_STATUS_ to find out which event it is. If the event code is ZAPS-VAL-EVT-CONNECT-IND, you have received a connect indication. If you receive ZAPS-VAL-EVT-P-ABORT-IND (provider abort indication), the connect indication has failed at some layer. If this happens, reissue the attach. Note OSI/AS issues a provider abort indication when a session, presentation, or ACSE connect indication fails.
APS Procedures Programming Concepts Sending and Retrieving User Data Sending and This subsection describes how to define the user data buffers you need and then Retrieving User Data explains how to send and retrieve user data over an OSI/AS connection. To send user data, you call one of the APS procedures that has a user-data input parameter. To retrieve user data that you have received, you call the APS_DATA_GETPARAM_ procedure.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-5. Buffer Containing Multiple Data Elements All data elements reside in the buffer: ZAPS-DDL-DATA-HDR ZAPS-DDL-DATA-ELEMENT-HDR data ZAPS-DDL-DATA-ELEMENT-HDR data . . . ZAPS-DDL-DATA-ELEMENT-HDR data All data elements reside elsewhere in memory: ZAPS-DDL-DATA-HDR ZAPS-DDL-DATA-ELEMENT-HDR data ZAPS-DDL-DATA-ELEMENT-HDR data ZAPS-DDL-DATA-ELEMENT-HDR data . . .
APS Procedures Programming Concepts Sending and Retrieving User Data You can include as many data elements as you wish. Each data-element header must start on a word boundary. The following conceptual example in TAL declares two data-element headers and two fixed-length data elements, one of 20,000 bytes and one of 30,000 bytes. (Since data elements are of variable length, most real applications will dynamically calculate the address of each data-element header after the first.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-6 illustrates the use of the two categories of PDV types. Figure 2-6. PDV Types Three PDV lists, each containing a single ASN.1 type (SAT) PDV: PDV list #1 Single ASN.1 PDV (PCID=x) PDV list #2 Single ASN.1 PDV (PCID=x) PDV list #3 Single ASN.1 PDV (PCID=x) Two PDV lists, each containing two or more octet-aligned PDVs: PDV list #1 Octet-aligned PDV (PCID=x) Octet-aligned PDV (PCID=x) ...
APS Procedures Programming Concepts Sending and Retrieving User Data Figures 2-7 through 2-9 illustrate the way in which various combinations of single ASN.1 and octet-aligned user data elements are packaged into PDV lists in a protocol data unit (PDU) when sending data. Note that you can spread a single PDV over multiple user data elements by specifying the same PCID in adjacent elements. Figure 2-7. Two Single ASN.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-8.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-9. One Single ASN.1 and One Octet-Aligned User Data Element With the Same PCID APS User Data User Data Header Number of Elements = 2 User Data Element Header PCID = px Type = Single ASN.
APS Procedures Programming Concepts Sending and Retrieving User Data Figures 2-10 through 2-12 illustrate the way in which various combinations of single ASN.1 and octet-aligned PDV lists are unpacked from a presentation protocol data unit (PPDU) when receiving data. Note that OSI/AS may treat adjacent PDV lists of the same type (SAT or OCTET) and with the same PCID as a single data element. Figure 2-10. Two Single ASN.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-11.
APS Procedures Programming Concepts Sending and Retrieving User Data Figure 2-12. One Single ASN.1 and One Octet-Aligned User Data Element With the Same PCID User Data from PPDU APS User Data User Data Header Number of Elements = 2 PDV list PCID: px Type: SAT Length: lx User Data Element Header PCID = px Type = Single ASN.
APS Procedures Programming Concepts Sending and Retrieving User Data User Data Encoding Examples The following examples illustrate the encoding of user data on an ACSE connection using OSI/AS. Example 1. This example performs an FTAM F-INITIALIZE operation using the ACSE service provided by OSI/AS. FTAM builds an F-INIT FPDU (with a PCID of 7), encoding all parameters according to the BER transfer syntax, and includes the EXTERNAL in the user data element.
APS Procedures Programming Concepts Sending and Retrieving User Data (user data from FTAM user) ] -- end data element 1 Example 2. Building on the previous example, FTAM begins sending a file. This requires two different abstract syntaxes: one for the FTAM control PDU, and one for the document (file) type. FTAM builds the FTAM control syntax in a user data element with a PCID selected at connect (A-ASSOCIATE) request time.
APS Procedures Programming Concepts Sending and Retrieving User Data These procedures have the following characteristics: APS_DATA_REQ_ sends as many bytes of user data as your program can handle, and it is subject to token restrictions, as described in Section 3. APS_CAPDATA_REQ_ and APS_CAPDATA_RSP_ can send a limited amount of user data when activity management is available, but no activity is in progress. You can call these procedures only if the capability data exchange functional unit is available.
APS Procedures Programming Concepts Sending and Retrieving User Data Table 2-15.
APS Procedures Programming Concepts Sending and Retrieving User Data 2. To send the data, call APS_DATA_REQ_. 3. If the connection is in nowait mode, call MFM_AWAITIOX_ to wait for the completion of the procedure. MFM_AWAITIOX_ gives you the status code for the completed procedure call. If the status is not ZAPS-VAL-STATUS-OK, call APS_STATUS_. 4. If you are using APS_DATA_REQ_ or APS_TYPEDDATA_REQ_ , you can repeat steps 2 and 3 until you have sent all the data.
APS Procedures Programming Concepts Sending and Retrieving User Data When your application receives one of these primitives on a call to APS_EVENT_RECEIVE_ , the data is stored in the API internal data area. To read the data into your buffer, you then call APS_DATA_GETPARAM_. (If you call APS_DATA_GETPARAM_ when no user data is available, you receive the error code ZAPS-ERR-NO-DATA.
APS Procedures Programming Concepts Basic Concatenation Avoiding Concatenation of Incoming User Data If your buffer is too small to contain all of the user data from an incoming primitive, you must call APS_DATA_GETPARAM_ several times, as shown above. Your application program must then concatenate the data to make it usable.
APS Procedures Programming Concepts Releasing a Connection and one for the give tokens or please tokens primitive, just as if they had arrived separately. Releasing a A connection can be terminated by your own application, by the remote application, or Connection by the service provider. It is also terminated if your application terminates abnormally (abends).
APS Procedures Programming Concepts Releasing a Connection Responding to a Release Indication 3. Next, to be able to receive a release confirm event, call APS_EVENT_RECEIVE_. In wait mode, this procedure returns a status code of ZAPS-VAL-STATUS-EVENT when you have received an event. 4. If the connection is in nowait mode, call MFM_AWAITIOX_ to wait for the completion of the procedure and to obtain the status code. As above, a status code of ZAPS-VAL-STATUS-EVENT means you have received an event. 5.
APS Procedures Programming Concepts Releasing a Connection The following steps explain the release response sequence given in Table 2-20: Aborting a Connection 1. In the course of normal processing, you call APS_EVENT_RECEIVE_ to be notified when you have received an event. 2. If the connection is in nowait mode, call MFM_AWAITIOX_ to wait for the completion of the procedure and to obtain the status code. 3. When you have received an event, call APS_STATUS_ to find out which event it is.
APS Procedures Programming Concepts Releasing a Connection Discarding the Context for a Connection 1. If you decide to abort the connection, call APS_ASSOC_ABORTREQ_. This procedure lets you send user data with the request so that you can, for example, give the reason for the abort. 2. If the connection is in nowait mode and you are interested in receiving any outstanding events, call MFM_AWAITIOX_ to wait for the completion of the procedure and to obtain the status code. 3.
APS Procedures Programming Concepts Releasing a Connection 2. If the connection is in nowait mode, call MFM_AWAITIOX_ to wait for the completion of the procedure and to obtain the status code. 3. When you have received an event, call APS_STATUS_ to find out which event it is. If the event code is ZAPS-VAL-EVT-P-ABORT-IND, you have received a provider abort from the Session Layer or the Presentation Layer.
APS Procedures Programming Concepts Releasing a Connection 3. When you have received an event, call APS_STATUS_ to find out which event it is. APS_STATUS_ also returns additional relevant information for presentation and ACSE connections; see the description of APS_STATUS_ in Section 3 for details. 4. For an ACSE connection, if the event code is ZAPS-VAL-EVT-U-ABORT-IND, you have received either a remote user abort or a provider abort from ACSE.
3 APS Procedure Calls This section contains detailed reference information for all of the APS procedures provided with the OSI/AS subsystem. The information includes: A description of each procedure The syntax of each procedure Parameter descriptions for each procedure Considerations (added information about the procedure) Before using this section, you should be familiar with the material in Section 2.
APS Procedure Calls Procedure Names Miscellaneous procedures do not fall into any of the first three categories. There are five miscellaneous procedures: APS_ASSOC_ATTACH_ APS_DISCARD_ APS_EVENT_RECEIVE_ APS_INITIALIZE_ APS_STATUS_ In addition, other keywords (listed below) within some procedure names further identify the functionality provided by the procedure: Procedures whose names include “ACTIVITY” enable you to break your work into logical pieces.
APS Procedure Calls Procedure Call Descriptions Procedure Call Figure 3-1 shows the syntax notation used to describe procedure calls in this manual. Descriptions This notation gives the syntax for calling the procedures from TAL programs. You can also call these procedures from C programs; for information on how to translate TAL calling sequences into C, refer to the Tandem C Reference Manual.
APS Procedure Calls Procedure Call Descriptions Figure 3-1. Sample APS Procedure Call Description (Page 1 of 2) 1 2 3 status := APS_ASSOC_ATTACH_ ( , , ,[ ,[ ,[ status cepi api-environment local-appl tag ] service-id ] subdevice-name ] ); 4 ! ! ! ! ! ! O I I I I I returned value INT indicates the outcome of the call... output 5 cepi 6 INT .EXT:ref:1 7 is the connection endpoint identifier (CEPI)... Legend status := 1 2 3 This indicates the type of value that the procedure returns.
APS Procedure Calls Procedure Call Descriptions Figure 3-1. Sample APS Procedure Call Description (Page 2 of 2) 4 The exclamation point indicates that a comment follows. The comment is either an “I” or an “O” (or both), indicating that the parameter is either an input (I) or an output (O) parameter (or both). Input parameters are those passing data to the called procedure; output parameters are those that return data to the calling program.
APS Procedure Calls APS_ACTIVITY_DISCARDREQ_ APS_ACTIVITY_DISCARDREQ_ his procedure allows you to abnormally terminate the current activity. Any undelivered data may be lost. You can issue an activity discard request only if there is an activity in progress and you hold the major/activity token. For a normal end to an activity, call APS_ACTIVITY_ENDREQ_ instead.
APS Procedure Calls APS_ACTIVITY_DISCARDREQ_ Considerations The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentation and ACSE connections) whether your connection is in normal mode or X.410-1984 mode.
APS Procedure Calls APS_ACTIVITY_DISCARDRSP_ APS_ACTIVITY_DISCARDRSP_ This procedure allows you to respond to an activity discard indication received from the remote application. You cannot refuse the discard. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the activity discard response primitive.
APS Procedure Calls APS_ACTIVITY_DISCARDRSP_ please-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are requesting from the remote application in the token please request primitive to be concatenated with the activity discard response primitive. To request tokens from the remote application, set the field values for the requested tokens to ZAPS-VAL-TOKEN-PLEASE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_ACTIVITY_ENDREQ_ APS_ACTIVITY_ENDREQ_ his procedure allows you to request the end of the current activity. You can issue an activity end request only if an activity is in progress and you hold the major/activity token. You must also hold the data token and the synchronize-minor token, if they are available on the connection. This procedure also allows you, optionally, to use basic concatenation to send a token give request primitive along with the activity end request primitive.
APS Procedure Calls APS_ACTIVITY_ENDREQ_ give-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are giving to the remote application in the token give request primitive to be concatenated with the activity end request primitive. To give tokens to the remote application, set the field values for the tokens you are giving to ZAPS-VAL-TOKEN-GIVE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_ACTIVITY_ENDRSP_ APS_ACTIVITY_ENDRSP_ This procedure allows you to acknowledge an activity end indication. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the activity end response primitive. status := APS_ACTIVITY_ENDRSP_ ( cepi ,[ user-data ] ,[ tag ] ,[ please-tokens ] ); status ! ! ! ! I I I I returned value INT indicates the outcome of the call.
APS Procedure Calls APS_ACTIVITY_ENDRSP_ Considerations After receiving an activity end indication, and before calling APS_ACTIVITY_ENDRSP_ , you cannot call any of the following procedures: APS_ACTIVITY_DISCARDREQ_ APS_ACTIVITY_ENDREQ_ APS_ACTIVITY_INTERRUPTREQ_ APS_SYNC_MAJORREQ_ APS_SYNC_MINORREQ_ APS_ASSOC_RELEASEREQ_ The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentati
APS Procedure Calls APS_ACTIVITY_GETPARAM_ APS_ACTIVITY_GETPARAM_ This procedure makes the parameters of one of the following primitives available to you: Activity discard indication Activity discard confirm Activity end indication Activity interrupt indication Activity resume indication Activity start indication Call this procedure when the event-code parameter of APS_STATUS_ tells you that one of these primitives has been received.
APS Procedure Calls APS_ACTIVITY_GETPARAM_ output sync INT(32) .EXT:ref:1 is the synchronization point serial number. It is available only after an activity end request completion or after you have received one of the following primitives: Activity end indication Activity resume indication See ZAPS-DDL-SYNC in Appendix A for further information about this parameter. old-conid output INT .EXT:ref:(ZAPS-DDL-L5-CONID) shows the identifier of the connection over which the activity was originally started.
APS Procedure Calls APS_ACTIVITY_INTERRUPTREQ_ APS_ACTIVITY_INTERRUPTREQ_ his procedure allows you to abnormally terminate the current activity, but without canceling work completed before the interruption. Note that an interrupt request may cause undelivered data to be lost. You can issue an activity interrupt request only if an activity is in progress and you hold the major/activity token. To resume work on an activity after suspending it, call APS_ACTIVITY_RESUMEREQ_.
APS Procedure Calls APS_ACTIVITY_INTERRUPTREQ_ user-data input INT .EXT:ref:* for session version 2 only, contains the user data you wish to send to the remote application; see “Considerations” for the maximum amount of data you can send. You must define the structure of the data buffer, as described in “Defining User Data Buffers” in Section 2. For a normal-mode presentation or ACSE connection, you must also encode the data, as described in “Encoding ACSE and Presentation User Data” in Section 2.
APS Procedure Calls APS_ACTIVITY_INTERRUPTRSP_ APS_ACTIVITY_INTERRUPTRSP_ This procedure allows you to respond to an activity interrupt indication received from the remote application. Any undelivered data may be lost. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the activity interrupt response primitive.
APS Procedure Calls APS_ACTIVITY_INTERRUPTRSP_ please-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are requesting from the remote application in the token please request primitive to be concatenated with the activity interrupt response primitive. To request tokens from the remote application, set the field values for the requested tokens to ZAPS-VAL-TOKEN-PLEASE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_ACTIVITY_RESUMEREQ_ APS_ACTIVITY_RESUMEREQ_ This procedure allows you to request the resumption of an activity that had previously been interrupted. The activity could previously have been in use on this connection or on another connection. You can issue an activity resume request only if no activity is in progress and you hold the major/activity token. You must also hold the data token and the synchronizeminor token, if they are available on the connection.
APS Procedure Calls APS_ACTIVITY_RESUMEREQ_ old-conid input INT .EXT:ref:(ZAPS-DDL-L5-CONID) identifies the session connection over which the activity was originally started. Note that this is a session connection identifier and not a CEPI. The difference between a connection identifier and a CEPI is explained in Section 2. user-data input INT .EXT:ref:* contains the user data you wish to send to the remote application; see “Consideration” for the maximum amount of data you can send.
APS Procedure Calls APS_ACTIVITY_STARTREQ_ For a normal-mode presentation or ACSE connection, you can send as much data as will fit in a 512-byte PPDU (for session version 1) or a 10240-byte PPDU (for session version 2); the maximum length depends on the encoding. For a presentation or ACSE connection in X.410-1984 mode, the maximum amount of data is the same as that for a session connection.
APS Procedure Calls APS_ACTIVITY_STARTREQ_ APS_ACTIVITY_STARTREQ_ This procedure allows you to request the start of a new activity on a connection. You can issue an activity start request only if you hold the major/activity token. You must also hold the data token and the synchronize-minor token, if they are available on the connection. This procedure also allows you, optionally, to use basic concatenation to send a token give request primitive along with the activity start request primitive.
APS Procedure Calls APS_ACTIVITY_STARTREQ_ input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. give-tokens input INT .
APS Procedure Calls APS_ASSOC_ABORTREQ_ APS_ASSOC_ABORTREQ_ This procedure allows you to abort a connection at any time after you have received a valid CEPI. Any undelivered data is lost. For a more graceful release after the connection is established, use the APS_ASSOC_RELEASEREQ_ procedure instead. Note that no token restrictions apply to APS_ASSOC_ABORTREQ_ , whereas you can call APS_ASSOC_RELEASEREQ_ only if you hold all available tokens.
APS Procedure Calls APS_ASSOC_ABORTREQ_ Consideration The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentation and ACSE connections) whether your connection is in normal mode or X.410-1984 mode.
APS Procedure Calls APS_ASSOC_ATTACH_ APS_ASSOC_ATTACH_ This procedure allows you to tell the OSI/AS subsystem that you are ready to establish a session, presentation, or ACSE connection if a remote application requests one. After the APS_ASSOC_ATTACH_ procedure has completed successfully, use the APS_EVENT_RECEIVE_ procedure to wait for a connect indication to arrive. To be able to accept more than one connect indication, call APS_ASSOC_ATTACH_ once for each connect indication you wish to accept.
APS Procedure Calls APS_ASSOC_ATTACH_ input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. service-id input INT:value identifies the service to which you are ready to establish a connection.
APS Procedure Calls APS_ASSOC_ATTACH_ Considerations Note that the completion of APS_ASSOC_ATTACH_ (even in wait mode) does not mean a connection has been established. You must call APS_EVENT_RECEIVE_ in order to be notified when you have received a connect indication. For full details on how to establish a connection, see “Establishing a Connection” in Section 2. A valid CEPI (one with a value other than -1) remains allocated until you call the APS_DISCARD_ procedure.
APS Procedure Calls APS_ASSOC_ATTACH_ If you are ready to accept more than one connect request, call APS_ASSOC_ATTACH_ as many times as necessary. Note, however, that some connect requests might be rejected because you may have failed to issue an attach for that particular local application in time. The first event following a successful attach may be a provider abort rather than a connect indication, because the connect indication may have failed at some layer. If that happens, reissue the attach.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ APS_ASSOC_CONNECTREQ_ This procedure allows you to issue a session, presentation, or ACSE connect request to a remote application. For more information about connection establishment, see “Establishing a Connection” in Section 2.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ local-appl input INT .EXT:ref:(ZAPS-DDL-APPL-ADDR) specifies the name and/or OSI address of your application. For more information about this parameter, see “Considerations.” remote-appl input INT .EXT:ref:(ZAPS-DDL-APPL-ADDR) specifies the name and/or OSI address of the remote application you wish to connect to. For more information about this parameter, see “Considerations.” session-rqmnts input INT .
APS Procedure Calls APS_ASSOC_CONNECTREQ_ service-id input INT:value identifies the service you want for your connect request to a remote application. You can specify ZAPS-VAL-SERVICE-SESSION, ZAPS-VAL-SERVICEPRESENTATION, or ZAPS-VAL-SERVICE-ACSE. The default value is ZAPSVAL-SERVICE-SESSION. For more information about this parameter, see ZAPSVAL-SERVICE-xxx in Appendix A. mode input INT:value is the mode of operation for your connection.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ acse-remote-ae-title input INT .EXT:ref:(ZAPS-DDL-AE-TITLE) is the ACSE called application entity title for your connection. This parameter applies only to ACSE connections and is optional. For more information about this parameter, see ZAPS-DDL-AE-TITLE in Appendix A. acse-local-invocation-ids input INT .EXT:ref:(ZAPS-DDL-INVOCATION-IDS) is the ACSE application entity and application process invocation identifiers of the calling entity for your connection.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ Considerations A valid CEPI (one with a value other than -1) remains allocated until you call APS_DISCARD_. If, however, the APS_ASSOC_CONNECTREQ_ procedure returns a cepi value of -1, APS_DISCARD_ is unnecessary. To obtain error information when a cepi value of -1 is returned, call APS_STATUS_ with the cepi parameter set to -1. The local-appl and remote-appl parameters each consist of the application name and the corresponding OSI address.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ If mode is set to ZAPS-VAL-MODE-X410-1984, all other parameters specific to presentation and ACSE connections are ignored, and no user data is encoded or decoded. The pres-context-list and pres-default-context-name parameters are optional. However, to do any useful work on a presentation connection, you must specify one or both of these two parameters in the connect request.
APS Procedure Calls APS_ASSOC_CONNECTREQ_ Table 3-1 shows the five functional units that each use a token. If you select a functional unit from this list, you must give a value to the corresponding token. Table 3-2 shows the values you can give and how the token is assigned as a result. If a token is not applicable because you have not selected the corresponding functional unit, give it the value ZAPS-VAL-TOKEN-NOVALUE. Table 3-1.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ APS_ASSOC_CONNECTRSP_ This procedure allows you to respond to a session, presentation, or ACSE connect indication you have received from a remote application. For more information about connection establishment, see “Establishing a Connection” in Section 2.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ connect-result input INT:value contains your response to the connect request.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ conid input INT .EXT:ref:(ZAPS-DDL-L5-CONID) is the session connection identifier. Its use is not strictly defined and should be agreed upon in advance with the remote application. See Appendix A for the structure of this parameter. user-data input INT .EXT:ref:* contains the user data you wish to send to the remote application; see “Considerations” for the maximum amount of data you can send.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ acse-appl-context-name input INT .EXT:ref:(ZAPS-DDL-APPL-CNTXT) is the ACSE application context name for your connection. This parameter applies only to ACSE connections and is required for ACSE connections. For more information about this parameter, see ZAPS-DDL-APPL-CNTXT in Appendix A. acse-local-ae-title input INT .EXT:ref:(ZAPS-DDL-AE-TITLE) is the ACSE responding application entity title for your connection.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ manager process looks up an application name, it checks in the MIB to retrieve the PSAP address and the application entity title if it is present. The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentation and ACSE connections) whether your connection is in normal mode or X.410-1984 mode.
APS Procedure Calls APS_ASSOC_CONNECTRSP_ Request either half-duplex or duplex. If the remote application has selected both, you must choose between them and select only one of the two. Do not request the expedited data functional unit. It is not currently supported. Do not request capability data unless you also request activity management. Capability data is not relevant without activity management. Do not request exceptions unless you also request half duplex.
APS Procedure Calls APS_ASSOC_GETPARAM_ APS_ASSOC_GETPARAM_ This procedure makes the parameters of the following primitives available to you: Connect indication Connect confirm Release indication Release confirm Provider abort indication User abort indication This procedure also provides OSI address information following the completion of an APS_ASSOC_CONNECTREQ_ or an APS_ASSOC_ATTACH_ procedure call.
APS Procedure Calls APS_ASSOC_GETPARAM_ conid output INT .EXT:ref:(ZAPS-DDL-L5-CONID) is the session connection identifier. For more information about this parameter, see “Considerations” and Appendix A. This parameter is available only after you have received one of the connect primitives listed at the beginning of this procedure description. local-appl output INT .EXT:ref:(ZAPS-DDL-APPL-ADDR) contains the OSI address of your application (and the application name if you previously supplied it).
APS Procedure Calls APS_ASSOC_GETPARAM_ release-result output INT .EXT:ref:1 indicates the result of your connect release attempt. This parameter is available only after you have received a release confirm primitive. This parameter can have the following possible values: ZAPS-VAL-RLS-NOVALUE ZAPS-VAL-RLS-ACCEPT ZAPS-VAL-RLS-NOTACCEPT See ZAPS-VAL-RLS-xxx in Appendix A for the meanings of these values. abort-reason output INT .EXT:ref:1 indicates the reason the service provider aborted the connection.
APS Procedure Calls APS_ASSOC_GETPARAM_ pres-context-result-list output INT .EXT:ref:(ZAPS-DDL-PRES-CNTXT-RLIST) indicates the presentation context definition result list for your connection. This parameter applies only to presentation and ACSE connections. It is available after a connect indication or confirm if it was specified in the connect request. For more information about this parameter, see ZAPS-DDL-PRES-CNTXT-RLIST in Appendix A and “Encoding ACSE and Presentation User Data” in Section 2.
APS Procedure Calls APS_ASSOC_GETPARAM_ acse-appl-context-name output INT .EXT:ref:(ZAPS-DDL-APPL-CNTXT) is the ACSE application context for your connection. This parameter applies only to ACSE and is available after a connect indication or confirm. For more information about this parameter, see ZAPS-DDL-APPL-CNTXT in Appendix A. acse-local-ae-title output INT .EXT:ref:(ZAPS-DDL-AE-TITLE) is the ACSE application entity title (AE title) of the called entity for a connect indication.
APS Procedure Calls APS_ASSOC_GETPARAM_ acse-remote-invocation-ids output INT .EXT:ref:(ZAPS-DDL-INVOCATION-IDS) is the ACSE application entity and application process invocation identifiers of the calling entity for a connect indication, or of the responding entity for a connect confirm. This parameter applies only to ACSE connections. It is available for an indication if it was specified in the connect request; it is available for a confirm if it was specified in the connect response.
APS Procedure Calls APS_ASSOC_GETPARAM_ Considerations Because this procedure does not perform any file-system I/O operations, the request is always completed immediately after the procedure call. Even in nowait mode, do not call MFM_AWAITIOX_ to complete this procedure.
APS Procedure Calls APS_ASSOC_GETPARAM_ After you have received a connect confirm primitive: ZAPS-VAL-TOKEN-NOTAVAILABLE ZAPS-VAL-TOKEN-NOTOWNED ZAPS-VAL-TOKEN-OWNED Tables 3-4 and 3-5 summarize the APS_ASSOC_GETPARAM_ parameters that are (always or sometimes) available after specific procedure calls and primitives. Note that as specified previously in the parameter descriptions, some parameters are valid only for some layers. Table 3-4.
APS Procedure Calls APS_ASSOC_GETPARAM_ Table 3-5.
APS Procedure Calls APS_ASSOC_RELEASEREQ_ APS_ASSOC_RELEASEREQ_ his procedure allows you to request the release of a session, presentation, or ACSE connection to a remote application. This procedure initiates an orderly release, as described under “Releasing a Connection” in Section 2. You can issue a release request only if you hold all of the available tokens.
APS Procedure Calls APS_ASSOC_RELEASERSP_ acse-release-reason input INT:value is the level of urgency of the release request for an ACSE connection. This parameter applies only to ACSE and is optional; it is ignored in X.410-1984 mode. For the possible values of this parameter, see ZAPS-VAL-RLS-RSN-xxx in Appendix A. The default value is ZAPS-VAL-RLS-RSN-NOVALUE.
APS Procedure Calls APS_ASSOC_RELEASERSP_ APS_ASSOC_RELEASERSP_ This procedure allows you to respond to a session, presentation, or ACSE release indication from a remote application. If the negotiated release functional unit is available, you have the option of rejecting the release. Otherwise, the procedure only enables you to acknowledge the release and to send appropriate closing data for the connection.
APS Procedure Calls APS_CAPDATA_REQ_ input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. acse-release-reason input INT:value indicates why the release for an ACSE connection is being accepted or rejected.
APS Procedure Calls APS_CAPDATA_REQ_ APS_CAPDATA_REQ_ This procedure allows you to send a limited amount of user data while you are not within an activity. You can issue this primitive only if all of the following conditions are true: Activity services are available on the connection, but no activity is in progress. You hold the major/activity token. You hold the data token and the synchronize-minor token, if these tokens are available on the connection.
APS Procedure Calls APS_CAPDATA_REQ_ Considerations The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentation and ACSE connections) whether your connection is in normal mode or X.410-1984 mode.
APS Procedure Calls APS_CAPDATA_RSP_ APS_CAPDATA_RSP_ This procedure allows you to respond to a capability data indication and to send a limited amount of user data while you are not within an activity. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the capability data response primitive.
APS Procedure Calls APS_CAPDATA_RSP_ please-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are requesting from the remote application in the token please request primitive to be concatenated with the capability data response primitive. To request tokens from the remote application, set the field values for the requested tokens to ZAPS-VAL-TOKEN-PLEASE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_CONTROL_GIVEREQ_ APS_CONTROL_GIVEREQ_ This procedure allows you to request the service provider to give all available tokens to the remote application. You can issue this primitive only if both of the following conditions are true: Activity services are available on the connection, but no activity is in progress. You hold the major/activity token and all other tokens that are available on the connection.
APS Procedure Calls APS_CONTROL_GIVEREQ_ Consideration The maximum amount of user data you can send with this primitive depends on the layer of your connection, whether you are using session version 1 or session version 2, and (for presentation and ACSE connections) whether your connection is in normal mode or X.410-1984 mode.
APS Procedure Calls APS_DATA_GETPARAM_ APS_DATA_GETPARAM_ This procedure allows you to obtain the user data parameter from the last indication or confirm primitive received. This procedure can be used after any indication or confirm primitive that carries user data. Table 2-17 in Section 2 identifies these primitives; Tables 2-2 and 2-4 in Section 2 give the names of the corresponding events.
APS Procedure Calls APS_DATA_GETPARAM_ more-data output INT(32) .EXT:ref:1 gives you the size, in bytes, of the user data you have not yet received. To obtain the remaining data, call APS_DATA_GETPARAM_ again. A value of 0 indicates that no more user data remains. next-position output INT(32) .EXT:ref:1 gives you the offset, in bytes, of the next byte of user data available in the API. In other words, it gives you the position of the first byte not yet retrieved.
APS Procedure Calls APS_DATA_GETPARAM_ If the buffer contains multiple data elements, it has the following structure: ZAPS-DDL-DATA-HDR ZAPS-DDL-DATA-ELEMENT-HDR data ZAPS-DDL-DATA-ELEMENT-HDR data • • • ZAPS-DDL-DATA-ELEMENT-HDR data 090 For further information about user data buffers, see “Defining User Data Buffers” in Section 2. For a normal-mode presentation or ACSE connection, you must decode the user data. For details, see “Encoding ACSE and Presentation User Data” in Section 2.
APS Procedure Calls APS_DATA_GETPARAM_ To find out the size of the user-data parameter (including ZAPS-DDL-DATAHDR and all occurrences of ZAPS-DDL-DATA-ELEMENT-HDR) without retrieving any data, call APS_DATA_GETPARAM_ with both data-buffer-size and start-position set to 0. The API returns the size of the user data, using the more-data parameter.
APS Procedure Calls APS_DATA_REQ_ APS_DATA_REQ_ his procedure allows you to send normal data to the remote application. If the connection is operating in half-duplex mode, you must hold the data token to issue a data request. On each call to this procedure, you can send as much data as your program can handle; in addition, you can send an unlimited amount of data in a single data request primitive by using multiple calls. See “Sending and Retrieving User Data” in Section 2.
APS Procedure Calls APS_DATA_REQ_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. data-operation input INT:value is an optional parameter that determines how the user data is to be sent. You can send the data in a single procedure call or in a series of calls.
APS Procedure Calls APS_DATA_REQ_ primitive. To give tokens to the remote application, set the field values for the tokens you are giving to ZAPS-VAL-TOKEN-GIVE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE. block-size input INT:value is an optional parameter that determines how user data is to be sent. By default, APS sends data to the TAPS process in 30,042-byte blocks.
APS Procedure Calls APS_DISCARD_ APS_DISCARD_ This procedure allows you to delete the API context information for a connection. After APS_DISCARD_ has completed successfully, you can no longer use the CEPI. In normal circumstances, call APS_DISCARD_ after the connection has been released or aborted by your application, by the remote application, or by the service provider. In exceptional circumstances, you may wish to call APS_DISCARD_ without previously releasing or aborting the connection.
APS Procedure Calls APS_EVENT_RECEIVE_ APS_EVENT_RECEIVE_ This procedure allows you to receive an event. In other words, it notifies you when an indication or confirm primitive becomes available to you. If the connection is in nowait mode, complete this operation by calling the MFM_AWAITIOX_ procedure, described in Appendix B. When you have received an event, call APS_STATUS_ to find out which event it is. For further information about the use of this procedure, see “Receiving an Event” in Section 2.
APS Procedure Calls APS_EVENT_RECEIVE_ input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. block-size input INT:value is an optional parameter that determines how events are to be retrieved. By default, APS retrieves events in 30,000-byte blocks.
APS Procedure Calls APS_EXCEPTIONREQ_ APS_EXCEPTIONREQ_ This procedure allows you to send an exception report when an error has occurred on a connection operating in half-duplex mode. All undelivered data will be lost. You can issue an exception request only if the data token is available on the connection and is held by the remote user, not by you. If the activity management service is available on the connection, you can issue an exception request only if an activity is in progress.
APS Procedure Calls APS_EXCEPTIONREQ_ input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. please-tokens input INT .
APS Procedure Calls APS_INITIALIZE_ APS_INITIALIZE_ This procedure allocates and initializes a segment that holds context information for all of your API connections. This procedure must be the first APS procedure you call. Call it only once. error := APS_INITIALIZE_ ( [ swapvol ] ); error ! I returned value INT indicates the outcome of the call. This value can be either a negative error code defined by OSI/AS or a positive file-system error number.
APS Procedure Calls APS_RESYNCREQ_ APS_RESYNCREQ_ This procedure allows you to request a resynchronization, thus helping you reestablish the context of a connection in an orderly way after a problem. Resynchronization sets the connection to an agreed upon defined state, including the ownership of the available tokens and the value of the next synchronization point serial number to be used. All undelivered data is purged.
APS Procedure Calls APS_RESYNCREQ_ input tokens INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies how you wish the tokens to be assigned after the resynchronization. Omit this parameter if no tokens are available on the connection. Otherwise, set each token to one of the following values: ZAPS-VAL-TOKEN-OWNED ZAPS-VAL-TOKEN-NOTOWNED ZAPS-VAL-TOKEN-ACCEPTOR-CHOICE ZAPS-VAL-TOKEN-NOVALUE For more information about this parameter, see “Considerations.” user-data input INT .
APS Procedure Calls APS_RESYNCREQ_ associated with the specified synchronization point is the responsibility of your application and the remote application. If resync-type = ZAPS-VAL-RESYNC-SET, you are asking the service provider to synchronize to any valid synchronization point serial number specified by your application and the remote application. If there are unacknowledged minor synchronization points at the time of the resynchronize request and indication, the points remain unacknowledged.
APS Procedure Calls APS_RESYNCREQ_ Table 3-6. Functional Units and Corresponding Tokens For This Functional Unit Assign This Token Half-duplex Activity management Major synchronize Minor synchronize Negotiated release Data token Major/activity token Major/activity token Synchronize-minor token Release token Table 3-7.
APS Procedure Calls APS_RESYNCRSP_ APS_RESYNCRSP_ This procedure allows you to respond to a resynchronize indication. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the resynchronize response primitive. status := APS_RESYNCRSP_ ( , ,[ ,[ ,[ ,[ status cepi sync tokens ] user-data ] tag ] please-tokens ] ); ! ! ! ! ! ! I I I I I I returned value INT indicates the outcome of the call.
APS Procedure Calls APS_RESYNCRSP_ input tokens INT .EXT:ref:(ZAPS-DDL-TOKENS) contains your response to the token settings received in the resynchronize indication. Omit this parameter if no tokens are available on the connection.
APS Procedure Calls APS_RESYNCRSP_ Considerations After you have received a resynchronize indication, you cannot call any APS procedure that invokes a primitive, except the following procedures: APS_ASSOC_ABORTREQ_ APS_ACTIVITY_DISCARDREQ_ APS_ACTIVITY_INTERRUPTREQ_ APS_RESYNCREQ_ APS_RESYNCRSP_ Note also that APS_ACTIVITY_DISCARDREQ_ , APS_ACTIVITY_INTERRUPTREQ_ , and APS_RESYNCREQ_ cause a collision of resynchronize requests, and you can issue these requests only if you will win the collision.
APS Procedure Calls APS_STATUS_ APS_STATUS_ This procedure allows you to obtain status information for an established connection or a connection attempt.
APS Procedure Calls APS_STATUS_ event-code output INT .EXT:ref:1 indicates the most recent event received on the connection. See ZAPS-VAL-EVTxxx in Appendix A for a list of the values and their definitions. See Tables 2-2 and 2-4 in Section 2 for the procedure(s) to call to retrieve information after each indication or confirm primitive. subdevice-name output INT .EXT:ref:(ZAPS-DDL-FILENAME) is the fully-qualified subdevice name of the connection for the CEPI you specified.
APS Procedure Calls APS_STATUS_ original-error-info output INT .EXT:ref:(ZAPS-DDL-ORIGINAL-ERROR) indicates the first detected error. It is intended to help problem diagnosis. transport-state output INT .EXT:ref:1 indicates the current transport state (if applicable) for the specified CEPI. This parameter, which passes information from the Transport Layer, is present only when the returned error-code is ZAPS-ERR-L5-TRANS-FS-ERROR (-1001) and the returned error-subcode is FEDISCONNECT (140).
APS Procedure Calls APS_STATUS_ To help you analyze errors when the returned error-code is ZAPS-ERR-L5-TRANS-FS-ERROR (-1001) and the returned error-subcode is FEDISCONNECT (140), the diagnostic-buffer parameter contains the structure ZAPS-DDL-LL-ERROR-BUF, defined in Appendix A. For all error codes other than ZAPS-ERR-L5-TRANS-FS-ERROR and all subcodes other than FEDISCONNECT , the contents of this structure are not applicable.
APS Procedure Calls APS_SUBDEVICE_DISCARD_ APS_SUBDEVICE_DISCARD_ This procedure discards a static subdevice. status := APS_SUBDEVICE_DISCARD_ ( end-system-name , subdevice-name ); status ! I ! I returned value INT indicates the outcome of the call. For the possible values of ZAPS-VAL-STATUSxxx, see “Status Codes” in Appendix B. end-system-name input INT .
APS Procedure Calls APS_SYNC_GETPARAM_ APS_SYNC_GETPARAM_ This procedure allows you to obtain the parameters received with one of the following primitives: Provider exception report indication Resynchronize indication Resynchronize confirm Synchronize major indication Synchronize minor indication Synchronize minor confirm Token give indication Token please indication User exception report indication Call this procedure when the event-code parameter of APS_STATUS_ informs you that one of these primitives h
APS Procedure Calls APS_SYNC_GETPARAM_ tokens output INT .EXT:ref:(ZAPS-DDL-TOKENS) indicates the availability and ownership of the tokens, and specifies any changes in ownership that the remote application is proposing. This parameter is available after you have received a resynchronize indication or confirm primitive, a token give indication, or a token please indication. For the possible values of this parameter, see “Considerations.” resync-type output INT .
APS Procedure Calls APS_SYNC_GETPARAM_ The following values are possible for tokens: After a resynchronize indication primitive: ZAPS-VAL-TOKEN-ACCEPTOR-CHOICE You must choose who owns this token after resynchronization. ZAPS-VAL-TOKEN-NOTAVAILABLE This token cannot be used on this connection. ZAPS-VAL-TOKEN-NOTOWNED The remote user owns this token after resynchronization. ZAPS-VAL-TOKEN-OWNED You own this token after resynchronization.
APS Procedure Calls APS_SYNC_MAJORREQ_ APS_SYNC_MAJORREQ_ This procedure allows you to define a major synchronization point. As a result of your call, the service provider calculates a new synchronization point serial number and notifies the remote application of the new synchronization point. You can issue this primitive only if all of the following conditions are true: You hold the major/activity token. An activity is in progress, if activity services are available on the connection.
APS Procedure Calls APS_SYNC_MAJORREQ_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. give-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are giving to the remote application in the token give request primitive to be concatenated with the synchronize major request primitive.
APS Procedure Calls APS_SYNC_MAJORRSP_ APS_SYNC_MAJORRSP_ This procedure allows you to respond to a synchronize major indication. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the synchronize major response primitive. status := APS_SYNC_MAJORRSP_ ( cepi ,[ user-data ] ,[ tag ] ,[ please-tokens ] ); status ! ! ! ! I I I I returned value INT indicates the outcome of the call.
APS Procedure Calls APS_SYNC_MAJORRSP_ Considerations After you have received the synchronize major indication, you cannot call any of the following procedures until you have called APS_SYNC_MAJORRSP_: APS_ACTIVITY_DISCARDREQ_ APS_ACTIVITY_ENDREQ_ APS_ACTIVITY_INTERRUPTREQ_ APS_ASSOC_RELEASEREQ_ APS_SYNC_MAJORREQ_ APS_SYNC_MAJORREQ_ A synchronize major confirm primitive also confirms all previously unconfirmed minor synchronization points.
APS Procedure Calls APS_SYNC_MINORREQ_ APS_SYNC_MINORREQ_ This procedure allows you to define a minor synchronization point. As a result of your call, the service provider calculates a new synchronization point serial number and notifies the remote application of the new synchronization point. You can issue this primitive only if all of the following conditions are true: You hold the synchronize-minor token. An activity is in progress, if activity services are available on the connection.
APS Procedure Calls APS_SYNC_MINORREQ_ must also encode the data, as described in “Encoding ACSE and Presentation User Data” in Section 2. input tag INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing you to match the completion with the correct instance of the procedure call. give-tokens input INT .
APS Procedure Calls APS_SYNC_MINORREQ_ For a normal-mode presentation or ACSE connection, you can send as much data as will fit in a 512-byte PPDU (for session version 1) or a 10240-byte PPDU (for session version 2); the maximum length depends on the encoding. For a presentation or ACSE connection in X.410-1984 mode, the maximum amount of data is the same as that for a session connection.
APS Procedure Calls APS_SYNC_MINORRSP_ APS_SYNC_MINORRSP_ This procedure allows you to respond to a synchronize minor indication. This procedure also allows you, optionally, to use basic concatenation to send a token please request primitive along with the synchronize minor response primitive. status := APS_SYNC_MINORRSP_ ( , ,[ ,[ ,[ status cepi sync user-data ] tag ] please-tokens ] ); ! ! ! ! ! I I I I I returned value INT indicates the outcome of the call.
APS Procedure Calls APS_SYNC_MINORRSP_ please-tokens input INT .EXT:ref:(ZAPS-DDL-TOKENS) specifies the tokens you are requesting from the remote application in the token please request primitive to be concatenated with the synchronize minor response primitive. To request tokens from the remote application, set the field values for the requested tokens to ZAPS-VAL-TOKEN-PLEASE, and set the field values for all other tokens to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_SYNC_MINORRSP_ For a normal-mode presentation or ACSE connection, you can send as much data as will fit in a 512-byte PPDU (for session version 1) or a 10240-byte PPDU (for session version 2); the maximum length depends on the encoding. For a presentation or ACSE connection in X.410-1984 mode, the maximum amount of data is the same as that for a session connection.
APS Procedure Calls APS_TOKEN_GIVEREQ_ APS_TOKEN_GIVEREQ_ This procedure allows you to transfer one or more tokens to the remote application. You must own the tokens you are giving. status := APS_TOKEN_GIVEREQ_ ( cepi , tokens ,[ tag ] ,[ user-data ] ); status ! ! ! ! I I I I returned value INT indicates the outcome of the call. For the possible values of ZAPS-VAL-STATUSxxx, see “Status Codes” in Appendix B. cepi input INT:value is the connection endpoint identifier (CEPI) for this connection.
APS Procedure Calls APS_TOKEN_PLEASEREQ_ Considerations The tokens parameter is a structure that contains a field for every token, including tokens not used on the current connection. To give a token to the remote application, set the corresponding value in the structure to ZAPS-VALTOKEN-GIVE. Set all of the other token fields to ZAPS-VAL-TOKEN-NOVALUE.
APS Procedure Calls APS_TOKEN_PLEASEREQ_ APS_TOKEN_PLEASEREQ_ This procedure allows you to request one or more tokens from the remote application. The tokens you request must be available and must not be owned by you. status := APS_TOKEN_PLEASEREQ_ ( cepi , tokens ,[ user-data ] ,[ tag ] ); status ! ! ! ! I I I I returned value INT indicates the outcome of the call. For the possible values of ZAPS-VAL-STATUSxxx, see “Status Codes” in Appendix B.
APS Procedure Calls APS_TOKEN_PLEASEREQ_ Considerations The tokens parameter is a structure that contains a field for every token, including tokens not used on the current connection. To request a token from the remote application, set the corresponding value in the structure to ZAPS-VALTOKEN-PLEASE. Set all of the other token fields to ZAPS-VAL-TOKENNOVALUE.
APS Procedure Calls APS_TYPEDDATA_REQ_ APS_TYPEDDATA_REQ_ This procedure allows you to send typed data to the remote application. Typed data transfers are subject to the same service restrictions as normal data transfers, except that typed data transfers are not subject to token restrictions. On each call to this procedure, you can send as much data as your program can handle; in addition, you can send an unlimited amount of data in a single typed data request primitive by using multiple calls.
APS Procedure Calls APS_TYPEDDATA_REQ_ data-operation input INT:value is an optional parameter that determines how the user data is to be sent. You can send the data in a single procedure call or in a series of calls. The following values are acceptable for this parameter: ZAPS-VAL-DATA-MORE ZAPS-VAL-DATA-ABORT ZAPS-VAL-DATA-NOVALUE If you do not supply this parameter or if you specify ZAPS-VAL-DATANOVALUE, the API sends data to the TAPS process and ends the primitive.
APS Procedure Calls APS_TYPEDDATA_REQ_ block-size input INT:value is an optional parameter that determines how user data is to be sent. By default, APS sends data to the TAPS process in 30,042-byte blocks. This parameter enables you to specify smaller block sizes for individual requests, and thereby increase throughput. The valid values for this parameter are 1,000 to 30,042. If you supply a value outside that range, OSI/AS returns the error condition ZAPS-ERR-PARAMRANGE.
Appendix A DDL Definitions This appendix contains Data Definition Language (DDL) definitions of the data structures used in parameters to the procedure calls described in Section 3. The information in this appendix is in DDL format.
DDL Definitions Basic Data Types Basic Data Types Some DDL data types are built upon other data types. First-level data types are the lowest-level building blocks. Second-level data types are made from one or more firstlevel data types. Third-level data types are made from one or more second-level data types. First-Level Data Types ZAPS-DDL-BOOLEAN defines the boolean fields used by the procedures. Note that this definition is not compatible with the Subsystem Programmatic Interface (SPI).
DDL Definitions Basic Data Types Second-Level Data Types Second-level basic data types are made up of one or more of the first-level data types described in the previous subsection. ZAPS-DDL-CHAR16 is a string of 16 ASCII characters. You can address them as a STRUCT, as bytes, or as integers. DEFINITION ZAPS-DDL-CHAR16. 02 ZLEN TYPE ZAPS-DDL-INT1. 02 ZC PIC X(16). 02 ZS REDEFINES ZC. 03 ZI TYPE BINARY 16 OCCURS 8 TIMES. 02 ZB REDEFINES ZC PIC X OCCURS 16 TIMES.
DDL Definitions Basic Data Types ZAPS-DDL-CHAR128 is a string of 128 ASCII characters. You can address them as a STRUCT, as bytes, or as integers. DEFINITION ZAPS-DDL-CHAR128. 02 ZLEN TYPE ZAPS-DDL-INT1. 02 ZC PIC X(128). 02 ZS REDEFINES ZC. 03 ZI TYPE BINARY 16 OCCURS 64 TIMES. 02 ZB REDEFINES ZC PIC X OCCURS 128 TIMES. END ZAPS-DDL-CURRENT-ERROR, ZAPS-DDL-DIAG-BUF, ZAPS-DDL-ERRORCODE, and ZAPS-DDL-FILENAME are described under “Parameter Structures,” later in this appendix.
DDL Definitions Basic Data Types ZAPS-DDL-OPTL-INT2 is used for the ACSE invocation identifiers selected by the application. See ZAPS-DDL-INVOCATION-IDS, later in this appendix, for more information about invocation identifiers. DEFINITION ZAPS-DDL-OPTL-INT2. 02 ZINT-ISPRESENT TYPE ZAPS-DDL-IS-PRESENT. 02 ZINT TYPE ZAPS-DDL-INT2. END ZAPS-DDL-PRES-CNTXT-ID is the presentation context identifier (PCID) that gives the presentation context used for data transfer on a presentation or ACSE connection.
DDL Definitions Parameter Structures Parameter Structures Some reference parameters to the APS procedures are defined by structures from the ZAPSDDL file. These structures are used as data types for the procedure parameters, and are named in parentheses in the descriptions of those parameters in Section 3. The following pages provide general information about these structures.
DDL Definitions Parameter Structures ZAE-QUALIFIER is the application entity qualifier, if present. ZAP-TITLE is the application process title, if present. ZAPS-DDL-APPL-ADDR contains the OSI address and the locally assigned name of the application. DEFINITION ZAPS-DDL-APPL-ADDR. 02 ZPSAP TYPE ZAPS-DDL-PSAP. 02 ZAPPL-NAME TYPE ZAPS-DDL-CHAR128. END ZPSAP is the OSI address of the application. ZAPPL-NAME is the locally assigned application name. ZAPS-DDL-APPL-CNTXT is an ACSE application context name.
DDL Definitions Parameter Structures ZAPS-DDL-DATA-ELEMENT-HDR describes the length and type of a user data element in the user-data parameter. For further information on the use of this structure, see ZAPS-DDL-DATA-HDR in this subsection and “Sending and Retrieving User Data” in Section 2. DEFINITION ZAPS-DDL-DATA-ELEMENT-HDR. 02 ZLEN TYPE ZAPS-DDL-INT2. 02 ZTYPE TYPE ZAPS-DDL-ENUM1. 02 ZPCID TYPE ZAPS-DDL-PRES-CNTXT-ID. 02 ZADDR TYPE ZAPS-DDL-INT2. 02 FILLER PIC X(14).
DDL Definitions Parameter Structures ZAPS-VAL-DATA-TYPE-PDV-SAT-AD signifies that this PDV type is set to single ASN.1 type and that the contents of this element are located at the address specified in the ZADDR field. This value is for use only by typed data and data request primitives; it is only used for sending presentation data.
DDL Definitions Parameter Structures ZAPS-DDL-ENVIRONMENT defines the environment through which your OSI/AS connection will be made. DEFINITION ZAPS-DDL-ENVIRONMENT. 02 ZEND-SYSTEM-NAME TYPE ZAPS-DDL-FILENAME. 02 ZWAITMODE TYPE ZAPS-DDL-WAITMODE. END The value of ZEND-SYSTEM-NAME is the fully qualified name of the OSI manager process, in internal format. For the values of ZWAITMODE, see the description of ZAPS-DDL-WAITMODE later in this appendix.
DDL Definitions Parameter Structures ZAPS-DDL-LL-ERROR-BUF is a mapping of ZAPS-DDL-DIAG-BUF that is returned by the diagnostic-buffer parameter of APS_STATUS_ in conjunction with the error code ZAPS-ERR-L5-TRANS-FS-ERROR (-1001), subcode FEDISCONNECT (140). ZAPS-DDL-LL-ERROR-BUF contains Transport Layer information that further explains the conditions associated with the -1001/140 error. DEFINITION ZAPS-DDL-LL-ERROR-BUF. 02 ZVERSION TYPE ZAPS-DDL-INT1. 02 ZLAST-ERR TYPE ZAPS-DDL-INT1.
DDL Definitions Parameter Structures For X25AM connections, ZX25 contains diagnostic information returned by X25AM. ZX25-DISC-REASON specifies the reason for the circuit disconnection. For more information, refer to the Tandem X.25 Access Method (X25AM) Manual. ZX25-CLEAR-CAUSE specifies the clear cause. For more information, refer to the Tandem X.25 Access Method (X25AM) Manual. ZX25-DIAGCODE specifies the diagnostic code. For more information, refer to the Tandem X.25 Access Method (X25AM) Manual.
DDL Definitions Parameter Structures ZAPS-DDL-L5-RQMNTS shows an application’s session service requirements for a connection. The individual fields show which functional units have been requested, define the initial synchronization point value, and specify the initial token settings. These requirements are negotiated between your application and the remote application. DEFINITION ZAPS-DDL-L5-RQMNTS. 02 ZL5-FU-ISPRESENT TYPE 02 ZL5-FU.
DDL Definitions Parameter Structures ZAPS-DDL-ORIGINAL-ERROR tells you the first error that was detected in the current error situation. It comes from the lowest service layer in the OSI/AS subsystem at which an error occurred. This structure may help you diagnose errors at higher layers. DEFINITION ZAPS-DDL-ORIGINAL-ERROR. 02 ZDEVICE-NAME TYPE ZAPS-DDL-FILENAME. 02 ZERROR TYPE ZAPS-DDL-CURRENT-ERROR.
DDL Definitions Parameter Structures ZAPS-DDL-PRES-CNTXT-RLIST is the presentation context definition result list, indicating the acceptance or rejection of each of the presentation context definitions proposed in the presentation context definition list. It is set in a presentation or ACSE connect response through a call to APS_ASSOC_CONNECTRSP_. It can be retrieved in a presentation or ACSE connect indication and confirm with a call to APS_ASSOC_GETPARAM. DEFINITION ZAPS-DDL-PRES-CNTXT-RLIST.
DDL Definitions Parameter Structures the presentation context definition result list; you must preserve the order of the elements. For each element, you must set the following values in the presentation context definition result list: Set the result (ZRESULT) to either accept or reject the presentation context (ZAPSVAL-CNTXT-RSLT-ACCEPT or ZAPS-VAL-CNTXT-RSLT-U-REJECT).
DDL Definitions Parameter Structures ZAPS-DDL-SERVICE-ID identifies a service within the OSI/AS subsystem. DEFINITION ZAPS-DDL-SERVICE-ID TYPE ZAPS-DDL-ENUM1. The valid values are: CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT ZAPS-VAL-SERVICE-NOVALUE ZAPS-VAL-SERVICE-APS ZAPS-VAL-SERVICE-SESSION ZAPS-VAL-SERVICE-PRESENTATION ZAPS-VAL-SERVICE-ACSE VALUE VALUE VALUE VALUE VALUE 0. 1. 5. 6. 7. ZAPS-VAL-SERVICE-NOVALUE shows that no service is reported.
DDL Definitions Parameter Structures ZAPS-DDL-TOKENS has two uses. In indications, it defines the availability and ownership of session tokens. In token give and token please requests, and in requests and responses that use basic concatenation, it identifies which tokens you are giving or asking for. For an explanation of the session tokens, see Section 2. For lists of the valid values for the individual procedure calls, see Section 3.
DDL Definitions Parameter Structures ZAPS-VAL-TOKEN-NOTAVAILABLE is used by the session service provider to show that the token is not available on this connection. You use it for the same purpose in a connect or resynchronize response. ZAPS-VAL-TOKEN-OWNED has two uses. Use it in a connect request or connect response to make the initial assignment of the token to your own application. Later, the session service provider uses it to show that the token is owned by your application.
DDL Definitions Named Values Named Values The following pages present named data values defined for use by application programs when calling the APS procedures. Note that an application will receive only those values applicable to the OSI layers it is using. ZAPS-VAL-ABORT-xxx indicates the reason a connection has been aborted by the service provider.
DDL Definitions Named Values Note An abort from the remote service provider may have an abort reason that does not correspond to any of the abort reasons defined by OSI/AS. In this case, OSI/AS simply returns the value it received from the remote provider. For more information about the abort reason, see the session protocol standard, ISO 8327. ZAPS-VAL-ABORT-SRC-xxx is the ACSE abort source value for an abort indication.
DDL Definitions Named Values ZAPS-VAL-AE-TITLE-xxx is the value of the ZAE-TITLE-TYPE field of the ZAPSDDL-AE-TITLE structure. This value applies only to ACSE. CONSTANT CONSTANT CONSTANT ZAPS-VAL-AE-TITLE-FORMAT0 ZAPS-VAL-AE-TITLE-FORMAT2 ZAPS-VAL-AE-TITLE-NOCONTENT VALUE 0. VALUE 2. VALUE -1. ZAPS-VAL-AE-TITLE-FORMAT0 shows that the application entity title (AE title) is not present. ZAPS-VAL-AE-TITLE-FORMAT2 shows that the AE title is in format 2.
DDL Definitions Named Values ZAPS-VAL-CNTXT-RSN-xxx is the reason code for elements of the presentation context definition result list. This value applies only to presentation and ACSE connections. For further information on the use of these values, see ZAPS-DDL-PRESCNTXT-RLIST earlier in this appendix.
DDL Definitions Named Values The ZAPS-VAL-CON-xxx values are as follows: CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT CONSTANT ZAPS-VAL-CON-NOVALUE ZAPS-VAL-CON-ACCEPT ZAPS-VAL-CON-U-REJECT-NORSN ZAPS-VAL-CON-U-REJECT-CONG ZAPS-VAL-CON-U-REJECT-DATA ZAPS-VAL-CON-P-REJECT-NORSN ZAPS-VAL-CON-P-REJECT-CONG ZAPS-VAL-CON-P-REJECT-ADDR ZAPS-VAL-CON-P-REJECT-NOATTACH ZAPS-VAL-CON-P-REJECT-VERSION ZAPS-VAL-CON-U-REJECT ZAPS-VAL-CON-P-REJECT Z
DDL Definitions Named Values ZAPS-VAL-CON-P-REJECT-NOATTACH shows that the service provider rejects the connection because the called user is not attached to the session service access point (SSAP). This value applies to session connections. ZAPS-VAL-CON-P-REJECT-VERSION shows that the version of the session protocol proposed by your service provider has been rejected by the remote service provider. This value applies to session connections.
DDL Definitions Named Values ZAPS-VAL-DIAG-xxx provides diagnostic information for a rejected ACSE connection.
DDL Definitions Named Values ZAPS-VAL-DIAG-APPL-CALLING-AE-INVID shows that the calling application entity invocation identifier is not recognized. This value applies only when the result source is ZAPS-VAL-RSLT-SRC-USER. ZAPS-VAL-DIAG-APPL-CALLED-APTITLE shows that the called application process title is not recognized. This value applies only when the result source is ZAPS-VALRSLT-SRC-USER.
DDL Definitions Named Values Table A-1.
DDL Definitions Named Values ZAPS-VAL-EXC-JEOPARDIZED shows that the user cannot be sure that data received will be correctly handled, and that the user is temporarily unable to continue. ZAPS-VAL-EXC-SEQUENCEERR shows that the user has detected a sequence error. ZAPS-VAL-EXC-LOCALUSERERR shows that the user has detected a local (application) error. ZAPS-VAL-EXC-UNRECOVERABLE shows that the user has detected an unrecoverable procedural error.
DDL Definitions Named Values ZAPS-VAL-NSP-xxx is the connection type value that is used within the ZAPS-DDL-LL-ERROR-BUF structure. CONSTANT CONSTANT ZAPS-VAL-NSP-X25 ZAPS-VAL-NSP-LAN VALUE 1. VALUE 2. ZAPS-VAL-NSP-X25 designates an X25AM connection. ZAPS-VAL-NSP-LAN designates a TLAM connection. ZAPS-VAL-PEXC-xxx is the reason code included in a provider exception report. It is supplied by the service provider. CONSTANT CONSTANT ZAPS-VAL-PEXC-PROTOCOLERR ZAPS-VAL-PEXC-NONSPECIFIC VALUE 7. VALUE 8.
DDL Definitions Named Values ZAPS-VAL-RESYNC-SET shows that the application is asking the service provider to resynchronize to a given new value of the synchronization point serial number. In this case, the responding application can specify a different value for the serial number; if so, the responding application’s value prevails. ZAPS-VAL-RLS-xxx shows the result of a release primitive. CONSTANT CONSTANT CONSTANT ZAPS-VAL-RLS-NOVALUE ZAPS-VAL-RLS-ACCEPT ZAPS-VAL-RLS-NOTACCEPT VALUE 0. VALUE 1.
DDL Definitions Named Values ZAPS-VAL-RSLT-SRC-xxx is the ACSE result source retrieved from a connect confirm. CONSTANT CONSTANT CONSTANT CONSTANT ZAPS-VAL-RSLT-SRC-NOVALUE ZAPS-VAL-RSLT-SRC-USER ZAPS-VAL-RSLT-SRC-ACSE ZAPS-VAL-RSLT-SRC-L6 VALUE VALUE VALUE VALUE 0. 1. 2. 3. ZAPS-VAL-RSLT-SRC-NOVALUE shows that no value has been given. ZAPS-VAL-RSLT-SRC-USER shows that the ACSE user is the source.
DDL Definitions Cross-Reference Tables Cross-Reference The following tables show where each basic data type or parameter structure is used. Tables Table A-2 indicates which data types are built upon which other data types. Table A-3 indicates which procedure calls use each data type and named value. Table A-2.
DDL Definitions Cross-Reference Tables Table A-2.
DDL Definitions Cross-Reference Tables Table A-3.
DDL Definitions Cross-Reference Tables Table A-3.
DDL Definitions Cross-Reference Tables Table A-3.
DDL Definitions Cross-Reference Tables Table A-3.
DDL Definitions Cross-Reference Tables Table A-3.
Appendix B Status and Error Codes This appendix lists the status and error messages returned by the APS procedures. Where possible, explanations and recommendations for action are also given. Each status and error code is listed in a quick-reference table and then explained further following the table. In the tables, the errors are listed in numeric order. However, the explanations following each table are given in alphabetic order by the DDL name of the error.
Status and Error Codes Status Codes Table B-1. Status Code Values 0: Constant (ZAPS-VAL-STATUS-) Value Meaning OK EVENT NO-RETRY RETRY-NOW RETRY-LATER OPERATOR ABORT DISCARD UNKNOWN 0 1 2 3 4 5 6 7 8 Operation succeeded (see details below). You have received an event. Operation failed; don’t retry. Operation failed; retry immediately. Operation failed; retry after a delay. Operation failed; get operator; retry. Operation failed; abort connection. Operation failed; discard connection.
Status and Error Codes Status Codes 2: ZAPS-VAL-STATUS-NO-RETRY Cause. The requested operation failed, and you should not retry it. This typically occurs when you have called an APS procedure with invalid parameters. Effect. The request is ignored. Recommended Action. Check the parameters in the affected APS procedure call. 3: ZAPS-VAL-STATUS-RETRY-NOW Cause. The requested operation failed, but you can retry it immediately. Effect. The request is ignored. Recommended Action.
Status and Error Codes Status Codes 7: ZAPS-VAL-STATUS-DISCARD Cause. The requested operation failed because the connection was lost. Effect. The request is ignored. Recommended Action. Discard the connection context, as described under “Discarding a Connection Context” in Section 2. 8: ZAPS-VAL-STATUS-UNKNOWN Cause. The requested operation failed, but the status is unknown or no recommendation for further action is available. Effect. The request is ignored. Recommended Action. Unspecified.
Status and Error Codes Error Codes Error Codes The numeric values of the API error codes fall in two ranges. The range for general errors (common to the API itself and the session, presentation, and ACSE services) is -101 through -999. The range for errors specific to the session, presentation, and/or ACSE services is -1000 through -3099. General API Error Codes Table B-2 summarizes the error values that are common to the API and the session, presentation, and ACSE services, and explains what they mean.
Status and Error Codes Error Codes Table B-2.
Status and Error Codes Error Codes -101: ZAPS-ERR-NO-SEGMENT-SPACE Cause. No more virtual memory space was available when the API attempted to initialize or resize the segment. Subcodes. None. Effect. The current request, and possibly all API requests for your application instance, cannot be satisfied. Recovery. If this error occurs when you call APS_INITIALIZE_ , no recovery is possible. Otherwise, release and discard any unused connections, and retry the operation. -102: ZAPS-ERR-NO-POOL-SPACE Cause.
Status and Error Codes Error Codes -104: ZAPS-ERR-INTERNAL Cause. A logic or data-consistency error occurred. Subcodes. Any of the following: ZAPS-ERR-INTERN-xxx ZAPS-ERR-INTERN-L5-xxx ZAPS-ERR-INTERN-PRES-xxx ZAPS-ERR-INTERN-ACSE-xxx ZAPS-ERR-INTERN-ASN1-xxx Effect. Unspecified. Recovery. Take a trace, then report the error and the exact subcode (if any) to the appropriate support personnel. -105: ZAPS-ERR-PARAMETER Cause.
Status and Error Codes Error Codes -107: ZAPS-ERR-STATE-MACHINE Cause. Either your application attempted to invoke a primitive that was not valid in the current state, or an internal error occurred in the API state machine. Subcodes. The subcodes are ZAPS-ERR-SM-BAD-STATE and ZAPS-ERR-SM-BADEVENT. (See Table B-6.) Effect. The request is ignored. Recovery. Check your application’s calling sequence. If the calling sequence is correct, take a trace and report the error to the appropriate support personnel.
Status and Error Codes Error Codes -111: ZAPS-ERR-NOT-IMPLEMENTED Cause. The requested function is not implemented. Subcodes. None. Effect. The request is ignored. Recovery. No recovery is possible. -112: ZAPS-ERR-FU-NOT-SELECTED Cause. The request cannot be satisfied because the functional unit specified in the subcode is not available for use on the connection. Subcodes. See Table B-8. Effect. The requested operation is not performed. Recovery. Depends upon the subcode received.
Status and Error Codes Error Codes -115: ZAPS-ERR-SU-LAST-CLOSE Cause. The connection has been aborted because the subdevice associated with it has been closed by all openers. Subcodes. None. Effect. The current operation fails. Recovery. No recovery is possible. -116: ZAPS-ERR-NO-DATA Cause. You requested data, but no data is available to satisfy the request. Possible causes for this error include: You requested data, but none was received with the incoming primitive.
Status and Error Codes Error Codes -118: ZAPS-ERR-MFM-ERROR Cause. The module file management (MFM) software returned an unrecoverable error. Subcodes. The error subcodes are Guardian 90 file-system error codes, indicating the error code returned from MFM. For descriptions of the file-system errors, refer to the System Procedure Errors and Messages Manual. Effect. The affected MFM call is ignored. Recovery. Abort or discard the connection.
Status and Error Codes Error Codes -121: ZAPS-ERR-SSNULL Cause. An SPI error was encountered during the execution of the SSNULL procedure. This is an internal error involving SPI buffer management. Subcodes. The subcode indicates the error returned by SSNULL. For descriptions of the SPI errors, refer to the System Procedure Errors and Messages Manual. Effect. The request is ignored. Recovery. Follow the standard procedures at your site for contacting the appropriate support personnel.
Status and Error Codes Error Codes -124: ZAPS-ERR-BAD-MGR Cause. You specified an invalid name in the ZEND-SYSTEM-NAME field of the API environment parameter in a call to APS_ASSOC_ CONNECTREQ_ or APS_ASSOC_ATTACH_. The process specified is not an OSI manager process of the correct version. Subcodes. None. Effect. The requested operation is not performed. Recovery. Specify a valid OSI manager process name. -125: ZAPS-ERR-MGR-FS-ERROR Cause.
Status and Error Codes Error Codes -127: ZAPS-ERR-TABLE-ERROR Cause. An internal error showing that an API table is in an inconsistent state. Subcodes. None. Effect. The current operation fails. Recovery. No recovery is possible. -128: ZAPS-ERR-HASHTABLE-ERROR Cause. An APS internal table is in an inconsistent state. Subcodes. None. Effect. Unspecified. Recovery. Follow the standard procedures at your site for contacting the appropriate support personnel.
Status and Error Codes Error Codes -131: ZAPS-ERR-NO-CONNECTION Cause. No connection exists. Subcodes. None. Effect. The request is ignored. Recovery. Call APS_DISCARD_ to discard the connection context and release the CEPI. Then call APS_ASSOC_CONNECTREQ_ or APS_ASSOC_ATTACH_ to reinitiate the connection. -132: ZAPS-ERR-UNSUP-TAPS-IF-VERS Cause. The target entity does not support the requested TAPS interface version. Subcodes. The subcode specifies the maximum supported TAPS interface version. Effect.
Status and Error Codes Error Codes -135: ZAPS-ERR-NONE-PENDING Cause. A request failed because no operation was pending on the connection. Subcodes. None. Effect. The request is ignored. Recovery. No recovery is possible. -136: ZAPS-ERR-PARAM-MISSING Cause. One or more mandatory parameters were missing. Subcodes. None. Effect. The request is ignored. Recovery. This is a coding error. Correct your application. -137: ZAPS-ERR-PARAM-BOUNDS Cause. One or more reference parameters were out of bounds.
Status and Error Codes Error Codes -139: ZAPS-ERR-UNSUP-MAX-FIELD-VERS Cause. An application bound with a given version of the APS procedures is attempting to communicate with an earlier version of the TAPS process. Subcodes. The subcode indicates the latest version of the APS procedures that is supported by the TAPS process for the given request.
Status and Error Codes Error Codes -143: ZAPS-ERR-PRIMITIVE-UNFINISHED Cause. A data request or typed data request primitive is not finished. Subcodes. None. Effect. The request is ignored. Recovery. Recode your application to finish the primitive before invoking another primitive. For more information, see the description of APS_DATA_REQ_ or APS_TYPEDDATA_REQ_ in Section 3. -144: ZAPS-ERR-INVALID-SESSION-VERS Cause.
Status and Error Codes Error Codes Session Service Error Codes Table B-3 summarizes the error values you can receive only from the session service, and explains what they mean. These errors can occur on session, presentation, or ACSE connections, but they are always issued by the underlying session service. The name of each value starts with ZAPS-ERR-L5-. A more detailed description of each value follows the table in ascending numerical order. Table B-3.
Status and Error Codes Error Codes -1002: ZAPS-ERR-L5-TOKEN-STATE Cause. The API cannot satisfy the request because a session token is not in the correct state. This error occurs in the following situations: You do not own a token that you need for the request. You own a token that you must not own for the request. A token that is needed for the request is not available on the connection. A token that must not be available for this request is available on the connection.
Status and Error Codes Error Codes -1005: ZAPS-ERR-L5-ACT-IN-PROGRESS Cause. The request failed because an activity is in progress. Subcodes. None. Effect. The request is ignored. Recovery. No recovery is possible. -1006: ZAPS-ERR-L5-BAD-PI-UNIT-LENGTH Cause. The remote session protocol sent an SPDU with an invalid length identifier in a PI or PGI unit. Subcodes. The subcode identifies the PI or PGI unit involved. (See Table B-13.) Effect. The session connection is lost. Recovery.
Status and Error Codes Error Codes -1009: ZAPS-ERR-L5-BAD-PI-UNIT-VALUE Cause. The remote session protocol sent an SPDU with an invalid parameter value in a PI or PGI unit. Subcodes. The subcode identifies the PI or PGI unit involved. (See Table B-13.) Effect. The session connection is lost. Recovery. No recovery is possible. -1010: ZAPS-ERR-L5-SEGM-NOT-SUPP Cause. The remote session protocol sent an SPDU that requires segmentation. OSI/AS does not support segmentation. Subcodes. None. Effect.
Status and Error Codes Error Subcodes Error Subcodes The tables in this subsection list the error subcodes for the API and the session, presentation, and ACSE services. When an error with no applicable subcode occurs, the subcode is set to ZAPS-ERRNOVALUE, with a value of 0.
Status and Error Codes Error Subcodes Error Subcode Tables Tables B-4 through B-15 list the error subcodes for various types of errors. Table B-4. Resource Limit Subcodes Constant (ZAPS-ERR-RESOURCE-) Value Meaning DCB DCB-HEADER L5-TMSG-BUF MCB -101 -103 -1003 -102 Data control block Data control block header area Transport message buffer Message control block The corresponding error code is ZAPS-ERR-RESOURCE-LIMIT (value -103).
Status and Error Codes Error Subcodes Table B-5.
Status and Error Codes Error Subcodes Table B-5.
Status and Error Codes Error Subcodes Table B-7. Provider Exception Subcodes Constant (ZAPS-ERR-P-EXC-) Value Meaning PROTOCOL-ERROR TIM-TIMER-POP -101 -102 Provider identified a protocol error While closing the session, presentation, or ACSE service, the service provider did not receive a response from the remote application within the defined time limit The corresponding error code is ZAPS-ERR-P-EXCEPTION (value -110). Table B-8.
Status and Error Codes Error Subcodes Table B-9.
Status and Error Codes Error Subcodes Table B-11. Session Token Subheads Constant (ZAPS-ERR-L5-TKN-) Value Token in Incorrect State DATA MAJOR-ACTIVITY MINOR-SYNC RELEASE UNSPECIFIED -1004 -1002 -1003 -1005 -1001 Data token Major/activity token Synchronize minor token Release token The token is unspecified The corresponding error code is ZAPS-ERR-L5-TOKEN-STATE (value -1002). Table B-12.
Status and Error Codes Error Subcodes Table B-13.
Status and Error Codes Error Subcodes Table B-14.
Appendix C Module File Management (MFM) Procedure Calls This section contains detailed reference information for the two module file management (MFM) procedure calls you can use with the APS procedures. The external declarations for the current version of the MFM procedures are provided in the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL declarations) and $SYSTEM.SYSTEM.CEXTDECS (C declarations).
Module File Management (MFM) Procedure Calls MFM_AWAITIOX_ MFM_AWAITIOX_ This procedure allows you, when in nowait mode, to obtain the returned information from a previous file-system or APS procedure call. If your application uses OSI/AS connections, you cannot call AWAITIOX directly; you must call MFM_AWAITIOX_ instead. Except where stated otherwise, the parameters to MFM_AWAITIOX_ have the same syntax and use as the corresponding parameters for AWAITIOX.
Module File Management (MFM) Procedure Calls MFM_AWAITIOX_ output tag INT(32) .EXT:ref:1 returns the application-defined tag that was stored by the file system when the I/O operation associated with this completion was initiated. If you did not specify a tag when the operation was initiated, the value of this parameter is -1D. timelimit input INT(32):value specifies the length of time you are willing to wait for a completion. For the possible values of this parameter, see “Considerations.
Module File Management (MFM) Procedure Calls MFM_AWAITIOX_ Perform error checking as follows: 1. Immediately after the call to MFM_AWAITIOX_ , check the filenum returned. 2. If filenum is a CEPI (a value in the range -10 through -32767), then check the status returned by MFM_AWAITIOX_. If filenum is not a CEPI, check the condition code and/or call FILEINFO with the filenum returned by MFM_AWAITIOX_. For a file-system completion, the condition code is identical to that set by AWAITIOX.
Module File Management (MFM) Procedure Calls MFM_CANCELREQ_ MFM_CANCELREQ_ This procedure allows you to cancel a nowait operation started by a previous APS procedure. To cancel a file-system operation, call CANCELREQ instead. error := MFM_CANCELREQ_ ( pseudofn ,[ tag ] ); error ! I ! I returned value INT indicates the outcome of the call. For the possible values of error, see “Error Codes” in Appendix B. pseudofn input INT:value is the pseudofile number for which you want to cancel an operation.
Appendix D Using the APS Procedures in a C Application Program Section 3 provides the TAL syntax for the APS procedures. You must observe the following additional rules when calling the APS procedures from a program coded in C. The C external declarations for the current version of the APS procedures are in the file CEXTDECS (the default volume and subvolume are $SYSTEM.ZOSIAS). You must include CEXTDECS in your program, preferably before making any calls to the procedures.
Appendix E Sample Programs This appendix presents sample programs that illustrate the use of the APS procedures. They are simplified to show more clearly the sequence in which applications should call the procedures; your application programs will typically perform more complex operations. Each sample program is presented first in TAL and then in C.
Sample Programs Example 1: Session Layer Example 1: Session Layer The following program establishes a wait-mode Session Layer connection between two Tandem OSI/AS applications, sends 100 bytes of data in a data request, and then releases the connection. All primitives that can send data also send 100 bytes of data. This example combines both applications in a single program.
Sample Programs Example 1: Session Layer --- APS procedure identification labels. -LITERAL error_assoc_getparam_proc , error_attach_proc , error_connectreq_proc , error_connectrsp_proc , error_data_getparam_proc , error_datareq_proc , error_discard_proc , error_event_proc , error_initialize_proc , error_releasereq_proc , error_releasersp_proc , error_status_proc ; --- A DEFINE to make it easy to print a string--- e.g.
Sample Programs Example 1: Session Layer -- Swap volume for API extended data segment -INT .swapvol[0:3] := ["$SYSTEM "]; --- APS procedure call variables -- (APS_... in margin indicates procedure usage.
Sample Programs Example 1: Session Layer STRUCT .session_rqmnts_1 ( zaps^ddl^l5^rqmnts^def ); .session_rqmnts_2 ( zaps^ddl^l5^rqmnts^def ); STRUCT STRUCT .EXT STRUCT .EXT STRUCT .EXT user_data ( user_data_def ); user_data_1 ( user_data_def ); user_data_2 ( user_data_def ); --- Source in APS external declarations. --- This program assumes that the EXTDECS0 file is in this -- program's volume and subvolume unless you ASSIGN it to -- be elsewhere.
Sample Programs Example 1: Session Layer -------------------------------------------------------------- Convert a signed integer into a displayable format.
Sample Programs Example 1: Session Layer END; -- proc display_aps_error ? PAGE -------------------------------------------------------------- Display a text message for those APS procedures that -- return "status". ------------------------------------------------------------PROC display_aps_status( cepi, error_proc ); INT cepi; -- i : cepi for error INT error_proc; -- i : aps proc label BEGIN --- Get error code, etc...
Sample Programs Example 1: Session Layer END; -- case error_proc outptr ':=' " status: " -> @outptr; CALL local_numout( status ); outptr ':=' ", event: " -> @outptr; CALL local_numout( event_code ); outptr ':=' ", error:" -> @outptr; CALL local_numout( error_code ); outptr ':=' ", errorSub: " -> @outptr; CALL local_numout( error_subcode ); outptr ':=' ", serviceId: " -> @outptr; CALL local_numout( service_id ); CALL WRITE( output, outline_w, @outptr '-' @outline ); --- A real application would take appro
Sample Programs Example 1: Session Layer -- Wait for an event and make certain it is the one that -- is expected.
Sample Programs Example 1: Session Layer INT INT INT INT STRING END; msg_code; default_vol[0:7]; input_file_name[0:11]; output_file_name[0:11]; params[0:131]; --- Open $RECEIVE. -CALL OPEN( receive_name, receive ); IF <> THEN BEGIN CALL MYTERM( startup.output_file_name ); CALL OPEN( startup.output_file_name, output ); outline ':=' "$RECEIVE OPEN error." -> @outptr; CALL WRITE( output, outline_w, @outptr '-' @outline ); CALL ABEND; END; --- Read the startup message.
Sample Programs Example 1: Session Layer END; -- proc initialize_appl ? PAGE -------------------------------------------------------------- Main procedure of Example 1 ------------------------------------------------------------PROC sample_1_osias MAIN; BEGIN --- read startup message, open output, and initialize APS. -CALL initialize_appl; --- Set the OSI manager process name. -api_environment.zend^system^name.zs.zi ':=' [ "$OMGR ", 8*[" "] ]; api_environment.
Sample Programs Example 1: Session Layer -- APPLICATION 1 -- Inform the OSI/AS subsystem that the application is -- willing to establish a connection if a remote user -- requests one. The fourth parameter, service^id, is -- not used here, because its default is session. -print_aps( "APPL1: attach" ); status := APS_ASSOC_ATTACH_( cepi_1 , api_environment , local_appl_1 ); IF ( status <> ZAPS^VAL^STATUS^OK ) THEN CALL display_aps_status( cepi_1, error_attach_proc ); --- Get OSI address information.
Sample Programs Example 1: Session Layer session_rqmnts_2.zl5^fu^ispresent := ZAPS^VAL^TRUE; -- Select only the half-duplex functional unit. session_rqmnts_2.zl5^fu.zhalfduplex := ZAPS^VAL^TRUE; session_rqmnts_2.zl5^fu.zduplex := ZAPS^VAL^FALSE; session_rqmnts_2.zl5^fu.zexceptions := ZAPS^VAL^FALSE; session_rqmnts_2.zl5^fu.ztyped^data := ZAPS^VAL^FALSE; session_rqmnts_2.zl5^fu.zneg^release := ZAPS^VAL^FALSE; session_rqmnts_2.zl5^fu.zminorsync := ZAPS^VAL^FALSE; session_rqmnts_2.zl5^fu.
Sample Programs Example 1: Session Layer IF ( error <> ZAPS^ERR^OK ) THEN CALL display_aps_error( error_assoc_getparam_proc ); --- APPLICATION 1 -- Connect indication --- Initialize the user data to a string of the character -- "1." Because this is an application using the OSI/AS -- Session Layer, we don't set the PCID field of the -- user^data structure. This field is used only by -- Presentation and ACSE and is ignored by the OSI/AS -- Session Layer. user_data_1.header.znum^elements := 1; user_data_1.
Sample Programs Example 1: Session Layer , connect_result , session_rqmnts_1 , conid_1 , user_data_1 ); IF ( status <> ZAPS^VAL^STATUS^OK ) THEN CALL display_aps_status( cepi_1, error_connectrsp_proc ); --- APPLICATION 2. -- Wait for connect confirm. -CALL wait_for_event( cepi_2, ZAPS^VAL^EVT^CONNECT^CNF ); --- Get the parameters of the connect confirm.
Sample Programs Example 1: Session Layer -- large enough to retrieve all of the data sent. -- A real application would normally check the more^data -- parameter and repeat the call using the current value -- of the next^pos parameter as the value of the start^pos -- parameter for the next call until all of the data was -- retrieved. -CALL retrieve_user_data( cepi_2 ); --- APPLICATION 1 -- Issue release request.
Sample Programs Example 1: Session Layer , ! remote-appl ! , ! connect-result ! , ! session-rqmnts ! , release_result , ! abort-reason ! ); IF ( error <> ZAPS^ERR^OK ) OR ( release_result <> ZAPS^VAL^RLS^ACCEPT ) THEN CALL display_aps_error( error_assoc_getparam_proc ); --- Get release confirm user data. -CALL retrieve_user_data( cepi_1 ); --- APPLICATION 1 and APPLICATION 2 -- Delete the API context information.
Sample Programs Example 1: Session Layer C Version #pragma INSPECT, SYMBOLS #pragma PAGE "OSI/AS Sample Program 1" /* /* File: EXAPSC1 /* /* OSI/AS Sample Program 1 /* /* This sample program establishes a wait-mode Session /* Layer connection between two Tandem OSI/AS /* applications, sends 100 bytes of data, and releases /* the connection. All primitives that can send data /* also send 100 bytes of data.
Sample Programs Example 1: Session Layer #define #define num_bytes_to_transfer timelimit 100 -1 /* /* user data template. /* struct user_data_def { zaps_ddl_data_hdr_def header; zaps_ddl_data_element_hdr_def element; char value[ max_user_data ]; }; */ */ */ /* /* Swap volume for APS extended data segment. /* char swapvol[] = "$SYSTEM "; */ */ */ /* /* APS variables. /* ( APS_...
Sample Programs Example 1: Session Layer zaps_ddl_appl_addr_def zaps_ddl_l5_rqmnts_def zaps_ddl_l5_rqmnts_def zaps_ddl_l5_rqmnts_def remote_appl_2; session_rqmnts; session_rqmnts_1; session_rqmnts_2; struct struct struct user_data; user_data_1; user_data_2; user_data_def user_data_def user_data_def /* /* Source in APS external declarations. /* /* This program assumes that the CEXTDECS file is in this /* program's volume and subvolume unless you ASSIGN it to /* be elsewhere.
Sample Programs Example 1: Session Layer break; case error_status_proc : proc_name = "APS_STATUS_"; break; }; /* case error_proc */ printf( "%s error: %d\n", proc_name, error ); /* /* A real application would take appropriate action. /* DEBUG(); } /* proc display_aps_error */ */ */ */ #pragma PAGE /*--------------------------------------------------------*/ /* */ /* Display a text message for those APS procedures that */ /* return 'status'.
Sample Programs Example 1: Session Layer case error_connectrsp_proc: proc_name = "APS_ASSOC_CONNECTRSP_"; break; case error_datareq_proc: proc_name = "APS_DATA_REQ_"; break; case error_discard_proc: proc_name = "APS_DISCARD_"; break; case error_event_proc: proc_name = "APS_EVENT_RECEIVE_"; break; case error_releasereq_proc: proc_name = "APS_ASSOC_RELEASEREQ_"; break; case error_releasersp_proc: proc_name = "APS_ASSOC_RELEASERSP_"; break; }; /* case error_proc */ printf( "%s status: %d, event: %d, err: %
Sample Programs Example 1: Session Layer , sizeof( user_data ) , (int *) &user_data , &more_data , &next_position , start_position ); if ( error != ZAPS_ERR_OK && error != ZAPS_ERR_NO_DATA ) display_aps_error( error_data_getparam_proc ); } /* proc retrieve_user_data */ #pragma PAGE /*--------------------------------------------------------*/ /* */ /* wait for an event and make certain that it's the one */ /* that is expected.
Sample Programs Example 1: Session Layer } /* proc wait_for_event */ #pragma PAGE /*--------------------------------------------------------*/ /* */ /* initialize APS. */ /* */ /*--------------------------------------------------------*/ void initialize_appl() { /* */ /* Ask APS to allocate and initialize a reserved */ /* extended segment for this process.
Sample Programs Example 1: Session Layer remote_appl_1.zpsap.zpsel.zlen = 0; /* not used remote_appl_1.zpsap.zssel.zlen = 0; /* not used remote_appl_1.zpsap.ztsel.zlen = 0; /* not used remote_appl_1.zpsap.znsap.zlen = 0; /* not used remote_appl_1.zappl_name.zlen = 5; memcpy( remote_appl_1.zappl_name.u_zc.zb, "APPL2", 5 ); */ */ */ */ local_appl_2.zpsap.zpsel.zlen = 0; /* local_appl_2.zpsap.zssel.zlen = 0; /* local_appl_2.zpsap.ztsel.zlen = 0; /* local_appl_2.zpsap.znsap.zlen = 0; /* local_appl_2.
Sample Programs Example 1: Session Layer /* Initialize the user data to a string of the */ /* character "2." Because this is an application using */ /* the OSI/AS Session Layer, we don't set the PCID */ /* field of the user_data structure. This field is */ /* used only by Presentation and ACSE and is ignored by */ /* the OSI/AS Session Layer. */ /* */ user_data_2.header.znum_elements = 1; user_data_2.element.zlen = num_bytes_to_transfer; user_data_2.element.
Sample Programs Example 1: Session Layer , (int *) &local_appl_2 , (int *) &remote_appl_2 , (int *) &session_rqmnts_2 , (int *) &conid_2 , (int *) &user_data_2 ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( cepi_2, error_connectreq_proc ); /* /* Get OSI address information.
Sample Programs Example 1: Session Layer , (int *) &remote_appl , /* connect-result */ , (int *) &session_rqmnts_1 , /* release-result */ , /* abort-reason */ ); if ( error != ZAPS_ERR_OK ) display_aps_error( error_assoc_getparam_proc ); E–28 /* /* Get connect indication user data.
Sample Programs Example 1: Session Layer retrieve_user_data( cepi_2 ); /* /* APPLICATION 1 /* Data request /* printf( "APPL1: data request\n" ); status = APS_DATA_REQ_( cepi_1 , (int *) &user_data_1 ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( cepi_1, error_datareq_proc ); */ */ */ */ /* /* APPLICATION 2 /* Wait for data indication. /* wait_for_event( cepi_2, ZAPS_VAL_EVT_DATA_IND ); */ */ */ */ /* /* Get the data.
Sample Programs Example 1: Session Layer release_result = ZAPS_VAL_RLS_ACCEPT; printf( "APPL2: release response\n" ); status = APS_ASSOC_RELEASERSP_( cepi_2 , release_result , (int *) &user_data_2 ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( cepi_2, error_releasersp_proc ); /* /* APPLICATION 1 /* Wait for release confirm /* wait_for_event( cepi_1, ZAPS_VAL_EVT_RELEASE_CNF ); */ */ */ */ /* /* Get parameters of the release confirm.
Sample Programs Example 2: Presentation Layer and ACSE Example 2: Presentation Layer and ACSE This example consists of a requester program and a server program that communicate with each other to demonstrate the use of the Presentation Layer, ACSE, and basic concatenation. The programs, as written, both run on the same Tandem system.
Sample Programs Example 2: Presentation Layer and ACSE -1) The OSI manager process name is $OMGR. -2) ENTRY #APPL.APPL1 is defined (this program). -3) ENTRY #APPL.APPL2 is defined (for EXAPST2B). -4) Either session version 1 or session version 2 -can be configured. --- To run: -1) Be sure to run EXAPST2B (APPL2) first. (It will -issue an attach and wait for a connect indication.) -2) Run this application second. --- This program does the following: -1) Issues an ACSE associate request.
Sample Programs Example 2: Presentation Layer and ACSE , error_releasersp_proc , error_status_proc ; --- A DEFINE to make it easy to print a string--- e.g.
Sample Programs Example 2: Presentation Layer and ACSE -- (APS_... in margin indicates procedure usage.
Sample Programs Example 2: Presentation Layer and ACSE STRUCT .EXT INT .EXT STRING .EXT user_data ( user_data_def ); user_data_element ( user_data_element_def ); user_data_ptr; --- Source in APS external declarations. -- EXTDECS0 comes from the appropriate volume and subvolume.
Sample Programs Example 2: Presentation Layer and ACSE CALL NUMOUT( outptr, integer, 10, 5 ); @outptr := @outptr[5]; END; -- proc local_numout ? PAGE -------------------------------------------------------------- Display an error message for those APS procedures that -- return "error".
Sample Programs Example 2: Presentation Layer and ACSE --- Get error code, etc...
Sample Programs Example 2: Presentation Layer and ACSE --- Retrieve user data from the API. ------------------------------------------------------------PROC retrieve_user_data; BEGIN --- user_data is large enough to hold all of the data. -- Real applications might call this procedure several -- times, using next_position and more_data. -start_position := 0D; -- Start at the beginning.
Sample Programs Example 2: Presentation Layer and ACSE , original_error_info ); IF ( error <> ZAPS^ERR^OK ) THEN CALL display_aps_error( error_status_proc ); --- Check for the expected event. -- A real application would take appropriate action. -IF ( event_code <> expected_event_code ) THEN CALL DEBUG; END; -- proc wait_for_event ? PAGE -------------------------------------------------------------- Read the startup message, open the output file, and -- initialize the API.
Sample Programs Example 2: Presentation Layer and ACSE CALL OPEN( startup.output_file_name, output ); outline ':=' "$RECEIVE READ error." -> @outptr; CALL WRITE( output, outline_w, @outptr '-' @outline ); CALL ABEND; END; CALL CLOSE( receive ); --- Open the OUT file. -CALL OPEN( startup.output_file_name, output ); IF <> THEN BEGIN CALL MYTERM( startup.output_file_name ); CALL OPEN( startup.output_file_name,output ); outline ':=' "Output file OPEN error.
Sample Programs Example 2: Presentation Layer and ACSE local_appl.zpsap.zpsel.zlen local_appl.zpsap.zssel.zlen local_appl.zpsap.ztsel.zlen local_appl.zpsap.znsap.zlen local_appl.zappl^name.zlen local_appl.zappl^name.zs := := := := := ':=' 0; -- not 0; -- not 0; -- not 0; -- not 5; ["APPL1"]; used used used used remote_appl.zpsap.zpsel.zlen := remote_appl.zpsap.zssel.zlen := remote_appl.zpsap.ztsel.zlen := remote_appl.zpsap.znsap.zlen := remote_appl.zappl^name.zlen := remote_appl.zappl^name.
Sample Programs Example 2: Presentation Layer and ACSE 1; pres_context_list.zelement[0].zas^name.zobj^id[1] := 0; pres_context_list.zelement[0].zas^name.zobj^id[2] := 8571; pres_context_list.zelement[0].zas^name.zobj^id[3] := 2; pres_context_list.zelement[0].zas^name.zobj^id[4] := 1; pres_context_list.zelement[0].znum^ts := 1; pres_context_list.zelement[0].zts^name[0].znum^elements := 3; pres_context_list.zelement[0].zts^name[0].zobj^id[0] := 2; pres_context_list.zelement[0].zts^name[0].
Sample Programs Example 2: Presentation Layer and ACSE acse_appl_context_name.zobj^id[1] acse_appl_context_name.zobj^id[2] acse_appl_context_name.zobj^id[3] acse_appl_context_name.zobj^id[4] := := := := 0; 8571; 1; 1; --- Set the mode and service ID for an ACSE association. -mode := ZAPS^VAL^MODE^NORMAL; service_id := ZAPS^VAL^SERVICE^ACSE; --- Set up ACSE associate request user data. -- Normally, this would be generated by an ASN.1 compiler. -user_data.header.znum^elements := 1; user_data.element.
Sample Programs Example 2: Presentation Layer and ACSE , ! acse-remote-invocation-ids ! ); IF ( status <> ZAPS^VAL^STATUS^OK ) THEN CALL display_aps_status( error_connectreq_proc ); --- Get and save OSI address information.
Sample Programs Example 2: Presentation Layer and ACSE , pres_default_context_result , acse_appl_context_name , ! acse-local-ae-title ! , acse_remote_ae_title , ! acse-local-invocation-ids ! , acse_remote_invocation_ids , acse_result_source , acse_diagnostic , ! acse-release-reason ! , ! acse-abort-source ! ); IF ( error <> ZAPS^ERR^OK ) THEN CALL display_aps_error( error_assoc_getparam_proc ); --- A real application would check the session-rqmnts, -- pres-context-result-list, and so forth to make sure tha
Sample Programs Example 2: Presentation Layer and ACSE , give_tokens ); IF ( status <> ZAPS^VAL^STATUS^OK ) THEN CALL display_aps_status( error_datareq_proc ); --- Wait for P-DATA indication. -CALL wait_for_event( ZAPS^VAL^EVT^DATA^IND ); --- Get P-DATA indication user data. -CALL retrieve_user_data; --- Wait for ACSE release indication. -CALL wait_for_event( ZAPS^VAL^EVT^RELEASE^IND ); --- Get the ACSE release reason of the release indication.
Sample Programs Example 2: Presentation Layer and ACSE -- Set up ACSE release response user data. -- Normally, this would be generated by an ASN.1 compiler. -user_data.header.znum^elements := 1; user_data.element.ztype := ZAPS^VAL^DATA^TYPE^VALUE; user_data.element.zpcid := 1; -- ignored by ACSE user_data.
Sample Programs Example 2: Presentation Layer and ACSE /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* General: This is an example ACSE/Presentation program. It illustrates how to call the APS procedures. Some liberties have been taken in error checking; real applications would include error checking. This program calls the APS procedures in wait mode. OSI/AS Configuration: 1) The OSI manager process name is $OMGR. 2) ENTRY #APPL.APPL1 is defined (this program).
Sample Programs Example 2: Presentation Layer and ACSE /* #define #define */ max_user_data timelimit 1000 -1 /* /* user data template. /* struct user_data_def { zaps_ddl_data_hdr_def header; zaps_ddl_data_element_hdr_def element; char value[ max_user_data ]; }; */ */ */ /* /* user data element template. /* struct user_data_element_def { zaps_ddl_data_element_hdr_def char }; */ */ */ header; value [ max_user_data ]; /* /* Swap volume for APS extended data segment.
Sample Programs Example 2: Presentation Layer and ACSE zaps_ddl_ae_title_def zaps_ddl_invocation_ids_def zaps_ddl_environment_def zaps_ddl_l5_conid_def zaps_ddl_filename_def zaps_ddl_diag_buf_def zaps_ddl_tokens_def zaps_ddl_appl_addr_def zaps_ddl_original_error_def zaps_ddl_pres_cntxt_list_def zaps_ddl_pres_cntxt_rlist_def zaps_ddl_pres_deflt_cntxt_def zaps_ddl_appl_addr_def zaps_ddl_l5_rqmnts_def acse_remote_ae_title; acse_remote_invocation_ids; api_environment; conid; device_name; diagnostic_buffer; gi
Sample Programs Example 2: Presentation Layer and ACSE case error_initialize_proc : proc_name = "APS_INITIALIZE_"; break; case error_status_proc : proc_name = "APS_STATUS_"; break; }; /* case error_proc */ printf( "%s error: %d\n", proc_name, error ); /* /* A real application would take appropriate action.
Sample Programs Example 2: Presentation Layer and ACSE case error_discard_proc: proc_name = "APS_DISCARD_"; break; case error_event_proc: proc_name = "APS_EVENT_RECEIVE_"; break; case error_releasersp_proc: proc_name = "APS_ASSOC_RELEASERSP_"; break; }; /* case error_proc */ printf( "%s status: %d, event: %d, err: %d, errSub: %d, svcId: %d\n" , proc_name, status, event_code , error_code, error_subcode, service_id ); /* /* A real application would take appropriate action.
Sample Programs Example 2: Presentation Layer and ACSE #pragma PAGE /*--------------------------------------------------------*/ /* */ /* wait for an event and make certain that it is the one */ /* that is expected.
Sample Programs Example 2: Presentation Layer and ACSE if ( error != ZAPS_ERR_OK ) display_aps_error( error_initialize_proc ); } /* proc initialize_appl */ #pragma PAGE /*--------------------------------------------------------*/ /* */ /* Main procedure for Example 2, Application 1. */ /* */ /*--------------------------------------------------------*/ main () { /* */ /* read startup message, open output, and initialize APS*/ /* */ initialize_appl(); E–54 /* /* Set the OSI manager process name.
Sample Programs Example 2: Presentation Layer and ACSE session_rqmnts.zl5_fu.zmajorsync = ZAPS_VAL_FALSE; session_rqmnts.zl5_fu.zresync = ZAPS_VAL_FALSE; session_rqmnts.zl5_fu.zexpedited = ZAPS_VAL_FALSE; session_rqmnts.zl5_fu.zactivity = ZAPS_VAL_FALSE; session_rqmnts.zl5_fu.zcapability_data = ZAPS_VAL_FALSE; session_rqmnts.zinit_sync = 1; session_rqmnts.zinit_tokens.zrelease = ZAPS_VAL_TOKEN_NOVALUE; session_rqmnts.zinit_tokens.zdata = ZAPS_VAL_TOKEN_OWNED; session_rqmnts.zinit_tokens.
Sample Programs Example 2: Presentation Layer and ACSE pres_context_list.zelement[1].zts_name[0].zobj_id[0] = 2; pres_context_list.zelement[1].zts_name[0].zobj_id[1] = 1; pres_context_list.zelement[1].zts_name[0].zobj_id[2] = 1; /* /* Set the ACSE application context name for this req. /* { iso standard 8571 /* application-context(1) iso-ftam(1) } /* acse_appl_context_name.znum_elements = 5; acse_appl_context_name.zobj_id[0] = 1; acse_appl_context_name.zobj_id[1] = 0; acse_appl_context_name.
Sample Programs Example 2: Presentation Layer and ACSE , (int *) &remote_appl , (int *) &session_rqmnts , /* conid */ , (int *) &user_data , /* tag */ , service_id , mode , (int *) &pres_context_list , /* pres-default-context-name */ , (int *) &acse_appl_context_name , /* acse-local-ae-title */ , /* acse-remote-ae-title */ , /* acse-local-invocation-ids */ , /* acse-remote-invocation-ids */ ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( error_connectreq_proc ); /* /* Get and save OSI address in
Sample Programs Example 2: Presentation Layer and ACSE error = APS_ASSOC_GETPARAM_( cepi , /* conid */ , /* local-appl */ , (int *) &remote_appl , &connect_result , (int *) &session_rqmnts , /* release-result */ , /* abort-reason */ , /* mode */ , /* pres-context-list */ , (int *) &pres_context_result_list , /* pres-default-context-name */ , &pres_default_context_result , (int *) &acse_appl_context_name , /* acse-local-ae-title */ , (int *) &acse_remote_ae_title , /* acse-local-invocation-ids */ , (int *)
Sample Programs Example 2: Presentation Layer and ACSE /* give_tokens.zdata = ZAPS_VAL_TOKEN_GIVE; give_tokens.zrelease = ZAPS_VAL_TOKEN_NOVALUE; give_tokens.u_zmajorsync.zmajorsync = ZAPS_VAL_TOKEN_NOVALUE; give_tokens.zminorsync = ZAPS_VAL_TOKEN_NOVALUE; */ /* /* Issue P-DATA request, including the P-GIVE-TOKENS /* by using basic concatenation.
Sample Programs Example 2: Presentation Layer and ACSE , /* acse-appl-context-name , /* acse-local-ae-title , /* acse-remote-ae-title , /* acse-local-invocation-ids , /* acse-remote-invocation-ids , /* acse-result-source , /* acse-diagnostic , &acse_release_reason , /* acse-abort-source ); if ( error != ZAPS_ERR_OK ) display_aps_error( error_assoc_getparam_proc ); */ */ */ */ */ */ */ /* /* Get ACSE release indication user data.
Sample Programs Example 2: Presentation Layer and ACSE /* /* Delete the API context information. /* printf( "APPL1: discard\n" ); status = APS_DISCARD_( cepi ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( error_discard_proc ); */ */ */ printf( "APPL1: complete\n" ); } Server Program /* proc sample_osias_appl_1 (main) */ The following pages give the source code for the server program (Application 2), which is configured as APPL2.
Sample Programs Example 2: Presentation Layer and ACSE -- subvolume.
Sample Programs Example 2: Presentation Layer and ACSE -- user data template. -STRUCT user_data_def(*); BEGIN STRUCT header( zaps^ddl^data^hdr^def ); STRUCT element( zaps^ddl^data^element^hdr^def ); STRING value[0:max_user_data-1]; END; --- User data element template -STRUCT user_data_element_def(*); BEGIN STRUCT header( zaps^ddl^data^element^hdr^def ); STRING value[0:-1]; END; --- Output variables -STRING .outline[0:131]; INT .outline_w := @outline '>>' 1; STRING .
Sample Programs Example 2: Presentation Layer and ACSE INT(32) INT(32) INT(32) INT(32) more_data; next_position; start_position; tag; STRUCT ----- APS_DATA_GETPARAM_ APS_DATA_GETPARAM_ APS_DATA_GETPARAM_ tag for APS calls .acse_appl_context_name ( zaps^ddl^appl^cntxt^def ); .acse_local_ae_title ( zaps^ddl^ae^title^def ); .acse_local_invocation_ids ( zaps^ddl^invocation^ids^def ); .acse_remote_ae_title ( zaps^ddl^ae^title^def ); .acse_remote_invocation_ids ( zaps^ddl^invocation^ids^def ); .
Sample Programs Example 2: Presentation Layer and ACSE ? ? ? ? ? ? ? ? ? ? LIST , , , , , , , , ) APS_DATA_GETPARAM_ APS_DATA_REQ_ APS_DISCARD_ APS_EVENT_RECEIVE_ APS_INITIALIZE_ APS_STATUS_ APS_SYNC_GETPARAM_ MFM_AWAITIOX_ --- Source in GUARDIAN 90 external declarations. -- EXTDECS0 comes from the appropriate volume and subvolume.
Sample Programs Example 2: Presentation Layer and ACSE PROC display_aps_error( error_proc ); INT error_proc; -- i : aps proc label BEGIN CASE( error_proc ) OF BEGIN error_assoc_getparam_proc -> outline ':=' "APS_ASSOC_GETPARAM_" -> @outptr; error_data_getparam_proc -> outline ':=' "APS_DATA_GETPARAM_" -> @outptr; error_initialize_proc -> outline ':=' "APS_INITIALIZE_" -> @outptr; error_status_proc -> outline ':=' "APS_STATUS_" -> @outptr; error_sync_getparam_proc -> outline ':=' "APS_SYNC_GETPARAM_" -> @ou
Sample Programs Example 2: Presentation Layer and ACSE , original_error_info ); IF ( error <> ZAPS^ERR^OK ) THEN CALL display_aps_error( error_status_proc ); CASE( error_proc ) OF BEGIN error_attach_proc -> outline ':=' "APS_ATTACH_" -> @outptr; error_connectrsp_proc -> outline ':=' "APS_ASSOC_CONNECTREQ_" -> @outptr; error_datareq_proc -> outline ':=' "APS_DATA_REQ_" -> @outptr; error_discard_proc -> outline ':=' "APS_DISCARD_" -> @outptr; error_event_proc -> outline ':=' "APS_EVENT_RECEIVE_" -> @outptr;
Sample Programs Example 2: Presentation Layer and ACSE --- user_data is large enough to hold all of the data. -- Real applications might call this procedure several -- times using next_position and more_data.
Sample Programs Example 2: Presentation Layer and ACSE IF ( filenum <> cepi ) THEN CALL DEBUG; -- shouldn't happen for this example END; END; -- else... -- proc wait_for_aps_completion ? PAGE -------------------------------------------------------------- Wait for an event and make certain it is the one that -- is expected.
Sample Programs Example 2: Presentation Layer and ACSE --- Read the startup message, open the output file, and -- initialize the API. ------------------------------------------------------------PROC initialize_appl; BEGIN INT receive; INT .receive_name[0:11] := [ "$RECEIVE", 8*[" "] ]; STRUCT .startup; BEGIN INT msg_code; INT default_vol[0:7]; INT input_file_name[0:11]; INT output_file_name[0:11]; STRING params[0:131]; END; --- Open $RECEIVE.
Sample Programs Example 2: Presentation Layer and ACSE CALL WRITE( output, outline_w, @outptr '-' @outline ); CALL ABEND; END; --- Ask APS to allocate and initialize a reserved extended -- segment for this process.
Sample Programs Example 2: Presentation Layer and ACSE tag := $UDBL( error_attach_proc ); print_aps( "APPL2: attach" ); status := APS_ASSOC_ATTACH_( cepi , api_environment , local_appl , tag , service_id ); CALL wait_for_aps_completion( error_attach_proc ); IF ( status <> ZAPS^VAL^STATUS^OK ) THEN CALL display_aps_status( error_attach_proc ); --- At this point, local-appl and acse_local_ae_title -- are available through APS_ASSOC_GETPARAM_, but -- we can wait for the indication to get them.
Sample Programs Example 2: Presentation Layer and ACSE -- all is well. --- However, in this program we'll accept whatever the -- remote application sent. ---- Set the transfer syntax in the pres-context-result-list. --- We'll just choose the first transfer syntax, -- since we know that the first one is acceptable. -FOR pc := 0 TO pres_context_list.znum^elements-1 DO BEGIN pres_context_result_list.zelement[pc].zts^name ':=' pres_context_list.zelement[pc].
Sample Programs Example 2: Presentation Layer and ACSE --- Issue ACSE associate response.
Sample Programs Example 2: Presentation Layer and ACSE -- Set up data (two PDVs) for P-DATA request. -- Normally, this would be generated by an ASN.1 compiler. -user_data.header.znum^elements := 2; --- Fill out 1st user data element (1st PDV). -- This PDV is for FTAM control. -@user_data_element := @user_data.element; user_data_element.header.ztype := ZAPS^VAL^DATA^TYPE^VALUE; user_data_element.header.zpcid := 1; user_data_element.
Sample Programs Example 2: Presentation Layer and ACSE -user_data.header.znum^elements := 1; user_data.element.ztype := ZAPS^VAL^DATA^TYPE^VALUE; user_data.element.zpcid := 1; -- ignored by ACSE user_data.value ':=' [ %H28 -- EXTERNAL , 17 -- length , %H02 -- INTEGER , 1 -- length of INTEGER , 1 -- pcid , %H80 -- single-asn1-type , 12 -- length of user-info , %H04 -- octet string , 10 -- length of octet string , "releasereq" -- data ] -> @user_data_ptr; user_data.element.
Sample Programs Example 2: Presentation Layer and ACSE , ! acse-appl-context-name ! , ! acse-local-ae-title ! , ! acse-remote-ae-title ! , ! acse-local-invocation-ids ! , ! acse-remote-invocation-ids ! , ! acse-result-source ! , ! acse-diagnostic ! , acse_release_reason , ! acse-abort-source ! ); IF ( error <> ZAPS^ERR^OK ) THEN CALL display_aps_error( error_assoc_getparam_proc ); --- Get ACSE release confirm user data. -CALL retrieve_user_data; --- Delete the API context information.
Sample Programs Example 2: Presentation Layer and ACSE /* /* /* /* /* /* /* /* /* /* /* 2) Run EXAPSC2A (APPL1) second. This 1) 2) 3) 4) 5) 6) 7) program does the following: Waits for an ACSE associate indication. Issues an ACSE associate response. Waits for a P-DATA indication. Waits for a P-GIVE-TOKENS indication. Issues a P-DATA request. Issues an ACSE release request. Waits for an ACSE release confirm.
Sample Programs Example 2: Presentation Layer and ACSE { zaps_ddl_data_element_hdr_def char header; value [ max_user_data ]; }; /* /* Miscellaneous variable. /* int pc; */ */ */ /* Presentation cntxt */ /* /* Swap volume for API extended data segment. /* char swapvol[] = "$SYSTEM "; */ */ */ /* /* APS variables. /* ( APS_... in margin indicates proc usage ).
Sample Programs Example 2: Presentation Layer and ACSE zaps_ddl_l5_rqmnts_def session_rqmnts; struct struct char user_data; *user_data_element; *user_data_ptr; user_data_def user_data_element_def /* */ /* Source in APS external declarations. */ /* CEXTDECS comes from the appropriate volume and subvol.
Sample Programs Example 2: Presentation Layer and ACSE break; }; /* case error_proc */ printf( "%s error: %d\n", proc_name, error ); /* /* A real application would take appropriate action. /* DEBUG(); } /* proc display_aps_error */ */ */ */ #pragma PAGE /*--------------------------------------------------------*/ /* */ /* Display a text message for those APS procedures that */ /* return 'status'.
Sample Programs Example 2: Presentation Layer and ACSE proc_name = "APS_DISCARD_"; break; case error_event_proc: proc_name = "APS_EVENT_RECEIVE_"; break; case error_releasereq_proc: proc_name = "APS_ASSOC_RELEASEREQ_"; break; }; /* case error_proc */ printf( "%s status: %d, event: %d, err: %d, errSub: %d, svcId: %d\n" , proc_name, status, event_code , error_code, error_subcode, service_id ); /* /* A real application would take appropriate action.
Sample Programs Example 2: Presentation Layer and ACSE #pragma PAGE /*--------------------------------------------------------*/ /* */ /* Wait for APS completion by first checking that the */ /* initial status was ok and then by calling */ /* MFM_AWAITIOX_.
Sample Programs Example 2: Presentation Layer and ACSE status = APS_EVENT_RECEIVE_( cepi , timelimit , tag ); wait_for_aps_completion( error_event_proc ); if ( status != ZAPS_VAL_STATUS_EVENT ) display_aps_status( error_event_proc ); } /* /* Find out which event was received.
Sample Programs Example 2: Presentation Layer and ACSE /* */ /*--------------------------------------------------------*/ main() { /* */ /* read startup message, open output, and initialize APS*/ /* */ initialize_appl(); /* /* Set the OSI manager process name. /* memcpy( api_environment.zend_system_name.u_zc.zb , "$OMGR " , 24 ); api_environment.zwaitmode = ZAPS_VAL_NOWAITED; */ */ */ /* /* Set the local application name. /* local_appl.zpsap.zpsel.zlen = 0; /* not used local_appl.zpsap.zssel.
Sample Programs Example 2: Presentation Layer and ACSE /* /* Wait for ACSE associate indication. /* wait_for_event( ZAPS_VAL_EVT_CONNECT_IND ); */ */ */ /* */ /* Get and save the parameters of the associate */ /* indication.
Sample Programs Example 2: Presentation Layer and ACSE /* /* Get ACSE associate indication user data. /* retrieve_user_data(); */ */ */ /* /* Set the ACSE application context name for this /* request. /* { iso standard 8571 /* application-context(1) iso-ftam(1) } /* acse_appl_context_name.znum_elements = 5; acse_appl_context_name.zobj_id[0] = 1; acse_appl_context_name.zobj_id[1] = 0; acse_appl_context_name.zobj_id[2] = 8571; acse_appl_context_name.zobj_id[3] = 1; acse_appl_context_name.
Sample Programs Example 2: Presentation Layer and ACSE , (int *) &user_data , tag , (int *) &pres_context_result_list , pres_default_context_result , (int *) &acse_appl_context_name ); wait_for_aps_completion( error_connectrsp_proc ); if ( status != ZAPS_VAL_STATUS_OK ) display_aps_status( error_connectrsp_proc ); /* /* Wait for P-DATA indication. /* wait_for_event( ZAPS_VAL_EVT_DATA_IND ); */ */ */ /* /* Get P-DATA indication user data.
Sample Programs Example 2: Presentation Layer and ACSE , "pdv1" , 4 ); /* data */ user_data_element->header.zlen = 6; /* We know that the length is not odd, so we don't have */ /* to worry about adding a pad byte. */ /* Fill out 2nd user data element (2nd PDV). */ /* This PDV is for FTAM FDAU PDU. */ /* */ user_data_element = (void *) &user_data_element->value [user_data_element->header.zlen]; user_data_element->header.ztype = ZAPS_VAL_DATA_TYPE_VALUE; user_data_element->header.
Sample Programs Example 2: Presentation Layer and ACSE user_data.value[ 5] = 0x80; /* user_data.value[ 6] = 12; /* user_data.value[ 7] = 0x04; /* user_data.value[ 8] = 10; /* memcpy( &user_data.value[ 9 ] , "releasereq" /* , 10 ); user_data.element.zlen = 19; E–90 single-asn1-type length of user-info octet string length of octet string */ */ */ */ data */ /* /* Issue ACSE release response.
Sample Programs Example 2: Presentation Layer and ACSE ); if ( error != ZAPS_ERR_OK ) display_aps_error( error_assoc_getparam_proc ); /* /* Get ACSE release confirm user data. /* retrieve_user_data(); */ */ */ /* /* Delete the API context information.
Abbreviations The following list defines abbreviations and acronyms used in this manual and in the other Tandem OSI/AS and Tandem OSI/TS manuals. Not all terms listed here are used in this particular manual. AA-SPDU. Abort accept SPDU AARE-APDU. A-associate response APDU AARQ-APDU. A-associate request APDU AB-SPDU. Abort SPDU ABRT-APDU. A-abort APDU AC-PPDU. Alter context PPDU AC-SPDU. Accept SPDU ACA-PPDU. Alter context acknowledge PPDU ACPM. Association control protocol machine ACSE.
Abbreviations CPA-PPDU. Connect presentation accept PPDU CPR-PPDU. Connect presentation reject PPDU CR-PPDU. Connect request PPDU CSMA. Carrier sense multiple access CSMA/CD. CSMA with collision detection CUG. Closed user group DC-TPDU. Disconnect confirm TPDU DCB. Data control block DDL. Data Definition Language DN-SPDU. Disconnect SPDU DR-TPDU. Disconnect request TPDU DSC. Dynamic System Configuration DSM. Distributed Systems Management DSP. Directory system protocol DSP.
Abbreviations IPPDU. IP protocol data unit IS. Intermediate system ISO. International Organization for Standardization LAN. Local area network LAPB. Link access protocol—balanced LDIB. Local Directory Information Base LLC1. Logical link control type 1 LMIB. Local Management Information Base LSAP. Link layer service access point MAC. Media access control MCB. Message control block MCW. Message control word MFM. Module file management MIB. Management Information Base MLAM. Multilan access method NCB.
Abbreviations PVC. Permanent virtual circuit RCB. Request control block RF-SPDU. Refuse SPDU RJ-TPDU. Reject TPDU RLRE-APDU. A-release response accept APDU RLRQ-APDU. A-release request APDU RS-PPDU. Resynchronize PPDU RSA-PPDU. Resynchronize acknowledge PPDU SAP. Service access point SCB. Subdevice control block SCF. Subsystem Control Function SCP. Subsystem Control Point SDU. Service data unit SNDCF. Subnetwork dependent convergence function SNPA. Subnetwork point of attachment SPDU.
Abbreviations TMDS. Tandem Maintenance and Diagnostic Subsystem TPDU-NR. A TPDU field that contains the DT-TPDU number TPDU. Transport protocol data unit TSAP. Transport service access point TSDU. Transport service data unit TSEL. Transport selector TSP. Transport service provider TTD-PPDU. Presentation typed data PPDU TTR. Time-to-resynchronize timer TWR. Time-to-wait-for resynchronize timer WAN. Wide area network X25AM. X.
Glossary The following glossary defines terms used both in this manual and in the other Tandem OSI/AS and Tandem OSI/TS manuals. Not all terms listed here are used in this particular manual. Abstract syntax. A representation of the way in which components of information are to be specified in a communication. It defines a set of primitive elements whose range of values is fully defined—for example, integers, characters, and Boolean values—and ways of combining these elements. See also transfer syntax.
Glossary Application entity. The part of an application process that interacts with a remote application process. In an OSI application itself, the application entity is the part that represents the communication functionality necessary for interoperation. Application entity title. The name, used with ACSE, that identifies an application entity to the OSI network. See also application entity. Contrast application name. Application Layer. Layer 7 of the OSI Reference Model.
Glossary Basic concatenation. A feature of the Session Layer protocol that allows two SPDUs to be contained in one TSDU. This feature is available through the APS procedures, which allows applications to invoke a give token primitive or a please token primitive to be concatenated with the requested primitive. See also PDU. C-series system. A system running any Cxx version of the Guardian 90 operating system, such as C21 or C30. Called address. The address to which a connect request is addressed.
Glossary Collector. An EMS process that accepts event messages from subsystems and logs them in the event log. See EMS. Compare distributor. Command interpreter. For OSI/AS and OSI/TS, an general term that refers to the Tandem Advanced Command Language (TACL). Command message. An SPI message, containing a command, sent from an application program to a subsystem. See also SPI message. Compare response message or event message. Common definition.
Glossary Connectionless mode. A type of communication in which all the packets of data (over the duration of the communications session) are treated independently and in which functions such as error recovery and flow control are not practical. Contrast connection mode. Consumer distributor. An EMS distributor process that returns selected event messages to management applications upon request. See also distributor. Context. See application context. Context token.
Glossary Data communications standard definitions. In DSM, the set of declarations provided by Tandem for use in all management programs that manage or retrieve event messages from Tandem data communications subsystems. The names of these definitions start with either ZCOM or ZCMK. See also definition or definition files. Compare SPI standard definitions or EMS standard definitions. Data Link Layer. Layer 2 in the OSI Reference Model.
Glossary Distributor. An EMS process that distributes event messages from event logs to requesting management applications, to Guardian 90 console message destinations, or to a collector on another node. See also consumer distributor, compatibility distributor, forwarding distributor, or printing distributor. Contrast collector. DNS (Distributed Name Service).
Glossary Error list. In DSM programmatic interfaces, a group of tokens used within a response record to provide error and warning information. An error list consists of a list token that denotes an error list (different from the token that starts a data list or a generic list), followed by an error token, other tokens explaining the error (optional), and an end-list token. Error lists can be nested within other error lists. The return token cannot be included in an error list. See also return token.
Glossary Expedited data. Data that bypasses normal flow-control procedures and is controlled by separate, specially designated procedures. Data normally flows from one end system to another in an orderly, first-in-first-out (FIFO) fashion. Expedited data moves through the system, overtaking previously submitted data, to reach the end system as fast as possible. Extensible structure. In DSM programmatic interfaces, a structure declared for the value of an extensible structured token.
Glossary Header. The initial part of an SPI message. The first word of this header always contains the value -28; the remainder of the header contains descriptive information about the SPI message, most of which is accessible as header tokens. The tokens in an SPI message header differ according to the type of message: the header of a message that contains a command or response differs somewhat from the header of an event message.
Glossary Interface. (1) With respect to the OSI Reference Model, a set of rules by which a given layer passes information to the adjoining layer below or above. (2) With respect to Tandem products, a set of rules by which a human operator or a program interacts with a hardware or software product, such as Tandem OSI/AS. Intermediate system. Any combination of subnetworks and relay systems used to connect two or more end systems. Tandem systems are not used as intermediate systems. See also end system.
Glossary Major activity token. One of the four types of Session Layer tokens that are associated with functional units. See Token and Functional unit. Major synchronization. In the Session Layer, the separation of the exchange of data into a series of dialog units. A major synchronization point indicates the end of one dialog unit and the beginning of the next. Each major synchronization point is confirmed explicitly. Compare minor synchronization. Management application.
Glossary Network service access point. See NSAP or NSAP address. Noncritical event. A DSM event not to crucial to system or network operations. Each subsystem determines which of its events are noncritical, by setting the value of the emphasis token to FALSE. Compare critical event. Nonsensitive command. A DSM command that can be issued by any user or program allowed access to the target subsystem—that is, a command on which the subsystem imposes no further security restrictions.
Glossary Object-name template. In DSM, a name that stands for more than one object. Such a name includes one or more wild-card characters, such as * and ?. See also wild-card character. Octet. Eight bits or one byte. Open system. Any computer system that adheres to the OSI standards. OSI (Open Systems Interconnection). A set of standards used for the interconnection of heterogeneous computer systems, thus providing universal connectivity. OSI address.
Glossary PDU (protocol data unit). Information delivered as a unit between peer entities that contains data and/or control and address information.
Glossary Presentation default context name. For Tandem OSI/AS, a structure that contains the default abstract syntax and transfer syntax to be used if the presentation context definition list is not present. Presentation default context result. For Tandem OSI/AS, a parameter that indicates the called application’s acceptance or rejection of the presentation default context name. Presentation Layer. Layer 6 in the OSI Reference Model.
Glossary PSAP (presentation service access point). A network-unique, physical address in the Presentation Layer through which connections are established and maintained. Also called presentation address. PSEL (presentation selector). A logical address in the Presentation Layer through which presentation services are made available. A single PSEL can service one or more connections simultaneously. PTrace. A Tandem program used to display trace files created through the use of the CMI or SCF Trace commands.
Glossary Response record. In DSM programmatic interfaces, a set of response tokens, usually describing the results of performing a command on one object. Every response record in a response from a Tandem subsystem contains a return token; a response record can also contain error lists that include error tokens. A response can consist of multiple response records, spread across one or more response messages. A response record cannot be split between two response messages.
Glossary Service primitive. An abstract, implementation-independent interaction between a service user and a service provider. Service primitives describe the sequences of events between adjacent layers that occur through the service access point (SAP). There are four types of service primitives; see confirm primitive, indication primitive, request primitive, or response primitive. See also SAP. Session. (1) In the context of OSI data transmission, the period during which two entities can exchange data.
Glossary SPI procedures. In DSM, the set of Guardian 90 procedures used to build and decode buffers for use in system and network management and in certain other applications. These procedures are SSINIT, SSNULL, SSPUT, SSPUTTKN, SSGET, SSGETTKN, SSMOVE, and SSMOVETKN. SPI standard definitions. In DSM programmatic interfaces, the set of declarations available for use with the SPI procedures, regardless of the subsystem.
Glossary Subnetwork dependent convergence function. See SNDCF. Subnetwork. One or more intermediate systems that provide relaying and through which end open systems may establish network connections. See also intermediate system or end system. Subordinate names option. In DSM interfaces to Tandem data communications subsystems, the designation that the object name given in a command stands not just for itself but also for the names of objects at lower levels in a hierarchy.
Glossary Synchronization point. A marker that a Session Layer application can insert into the data it is transmitting, to structure the exchange of data. There are two types: major synchronization points and minor synchronization points. See also major synchronization or minor synchronization. Synchronize minor token. One of the four types of Session Layer tokens that are associated with functional units. See Token and Functional unit. SYSGEN.
Glossary Token bus. The IEEE 802.4 standard for the both Data Link Layer (media access control sublayer only) and Physical Layer of the OSI Reference Model, which defines a tokenpassing bus access method for connections over LAN networks. See also CSMA/CD. Token code. In DSM programmatic interfaces, a 32-bit value that identifies a token. A token code consists of a token type (16 bits) and a token number (16 bits).
Glossary Transport Layer. Layer 4 in the OSI Reference Model. This layer provides reliable, transparent transfer of data between end systems and ensures that the data arrives at the correct destination. It provides reliable data transfer independent of the underlying Network Layer, but does, however in the CONS case, depend on the Network Layer to provide the network connection. Transport protocol data unit. See PDU. Transport selector. See TSEL. Transport service access point. See TSAP.
Glossary Warning. In DSM interfaces, a condition, encountered in performing a command or other operation, that can be significant but does not cause the command or operation to fail. A warning is less serious than an error. Compare error. Wild-card character. A character that stands for any possible character(s) in a search string or in a name applying to multiple objects.
Index A Abnormal termination of an activity See Discarding an activity and Interrupting an activity Abort reason A-20 Abort source 2-55, 3-49, A-21 Abort, provider See Provider abort abort-reason parameter 2-54, 3-46 Aborting a connection 2-52/53, 2-55, B-3 See also APS_ASSOC_ABORTREQ_ procedure and Connection Aborting an activity See Discarding, activity and Interrupting an activity Abstract syntax ACSE, for 2-18 description 2-16 name in presentation default context name A-16 Abstract syntax notation-1 See
Index acse-abort-source parameter 3-49 acse-appl-context-name parameter 3-33, 3-41, 3-48 acse-diagnostic parameter 3-41, 3-49 acse-local-ae-title parameter 3-33, 3-41, 3-48 acse-local-invocation-ids parameter 3-34, 3-41, 3-48 acse-release-reason parameter 3-49, 3-54, 3-56 acse-remote-ae-title parameter 3-34, 3-48 acse-remote-invocation-ids parameter 3-34, 3-49 acse-result-source parameter 3-49 Activities discarding (abnormal ending) 3-6/9 ending (normal ending) 3-10/13 in progress, error B-22 interrupting
Index AE title See Application entity title AP title See Application process title API environment, declaration for A-10 extended segment, access error B-11 extended segment, no space error B-7 file-system error B-14 general error values, table of B-5 initializing and allocating segment 2-27, 3-75 overview 1-2 stack space needed 3-3 swap volume declaration structure A-17 api-environment parameter 3-27, 3-31 Application configuration preparation for 2-24 context name See acse-appl-context-name parameter con
Index APS_ACTIVITY_DISCARDREQ_ procedure 2-10, 3-6/7 APS_ACTIVITY_DISCARDRSP_ procedure 3-8/9 APS_ACTIVITY_ENDREQ_ procedure 3-11 APS_ACTIVITY_ENDRSP_ procedure 3-12/13 APS_ACTIVITY_GETPARAM_ procedure 3-14/15 APS_ACTIVITY_INTERRUPTREQ_ procedure 3-16/17 APS_ACTIVITY_INTERRUPTRSP_ procedure 2-10, 3-18/19 APS_ACTIVITY_RESUMEREQ_ procedure 3-20/22 APS_ACTIVITY_STARTREQ_ procedure 3-23/24 APS_ACTIVITY_xxx procedure summary 2-13 APS_ASSOC_ABORTREQ_ procedure 2-52/53, 3-25/26 APS_ASSOC_ATTACH_ procedure overvie
Index APS_SUBDEVICE_DISCARD_ procedure 3-87 APS_SYNC_GETPARAM_ procedure 2-11, 2-15, 3-88/90 APS_SYNC_MAJORREQ_ procedure 3-91/92 APS_SYNC_MAJORRSP_ procedure 3-93/94 APS_SYNC_MINORREQ_ procedure 3-95/97 APS_SYNC_MINORRSP_ procedure 3-98/100 APS_TOKEN_GIVEREQ_ procedure 3-101/102 APS_TOKEN_PLEASEREQ_ procedure 3-103/104 APS_TYPEDDATA_REQ_ procedure 2-45, 2-47, 3-105/107 Architecture, OSI/AS subsystem 1-2/5 Asking for tokens See APS_TOKEN_PLEASEREQ_ procedure and Tokens ASN.
Index B Bad installation error B-19 Basic concatenation description 2-49 sample requestor program in C E-47/61 sample requestor program in TAL E-31/47 sample server program in C E-77/91 sample server program in TAL E-61/77 Basic Encoding Rules for ASN.
Index CAPDATA procedures category 3-2 Categories of APS procedures 3-1/2 CEPI comparison to session connection identifier 2-20 description 2-20 transport state and substate 3-85 unknown, error B-9 value of -1 2-20 values for completing a pending nowait operation 2-22 CEXTDECS file 3-1, D-1 Checkpointing 2-23 Collision of resynchronize requests 3-78, 3-82 Common application service elements 1-9 Completing a pending nowait operation 2-22, C-2/4 Completion information from requests 2-14 Completion, time limit
Index Connection See also Association aborted, status code for B-3 aborting 2-52/53, 2-55, 3-25/26 acceptance of 2-32, A-23/25 accepting 3-39 ACSE association, comparison to 1-1 already exists, error B-15 context information, discarding 2-53, 3-70 context information, initializing segment 2-27, 3-75 establishing attach procedure 3-27/30 calling user, procedure sequence for 2-28/30 overview 2-27 request procedure 3-31/37 response procedure 3-38/43 response procedure sequence 2-30/32 lost, status code for B-
Index Connection identifier, session See also conid and old-conid parameters comparison to CEPI 2-20 declaration for A-12 Connection indication primitive presentation context definition result list fields in 2-18/19 retrievable parameters after, table of 3-52 Connection response primitive 2-19 Context for connection discarding 2-53, 3-70 initializing and allocating segment 2-27, 3-75 relationship to CEPI 2-20 Control give request, procedure for 3-61/62 count-transferred parameter in MFM_AWAITIOX_ C-2 Curre
Index DDL data types built upon other data types, table of A-33/34 data types used by each procedure, table of A-35/37 definition file 2-2, 3-1 first-level data types A-2 named values A-20/32 named values used by each procedure, table of A-37/39 naming conventions 2-2 overview A-1 parameter structures A-6/19 second-level data types A-3/5 third-level data types A-5 Declarations, APS external 2-19, 3-1 Defining user data buffers 2-33/44 Deleting activity, abnormal See Discarding, activity and Interrupting an
Index Discarding activity 2-13 See also APS_ACTIVITY_DISCARDREQ_ procedure, APS_ACTIVITY_DISCARDRSP_ procedure, Interrupting an activity, and Ending, activity connection context See APS_DISCARD_ procedure and Connection static subdevice See APS_SUBDEVICE_DISCARD_ procedure Disconnecting a connection abnormal See Aborting a connection and Discarding, connection context normal See Releasing, connection Duplex functional unit 1-7 Dynamic subdevices See Subdevices E Encoding ACSE and Presentation User Data 2-4
Index Error codes common to API and OSI upper layers B-5/19 declaration for A-10 general API error values, table of B-5 overview 2-25 ranges of values B-5 retrieving 3-83, 3-84 session service B-20/23 using B-1 Error subcodes functional units, for B-28 MCW, for B-32 OSI manager, for B-29 overview B-24 parameters, for B-26/27 PI and PGI unit, for B-31 provider exception, for B-28 resource limit B-25 retrieving 3-84 session protocol variable, for B-30 session token, for B-29 state machine, for B-27 TSDU, for
Index Events block size 3-72 code values for and primitives, table of A-27/28 none received, error B-15 receiving 2-15, 3-71/72 retrieving codes 3-83 status value for receipt of B-1/2 timer 3-71 Exception report reason for provider, values of A-30 specifying 3-73, 3-89 user, values of A-28 receiving 2-15/16 sending 2-15, 3-73/74 exception-reason parameter 3-73, 3-89 Exceptions functional unit 1-7 EXTDECS0 file 3-1 Extended segment access error B-11 initializing 2-27, 3-75 no space error B-7 segment-id para
Index filenum parameter in MFM_AWAITIOX_ C-2/4 Files provided by Tandem for procedures 3-1 FTAM, examples of user data encoding for 2-42/44 Function not implemented error B-10 Functional units activity management 1-7, 2-12 capability data exchange 1-7 duplex 1-7 error codes for B-10 error subcodes B-28 exceptions 1-7 half-duplex 1-6 kernel 1-6, 1-8 major synchronize 1-7, 2-12 minor synchronize 1-7, 2-12 negotiated release 1-6, 2-51 negotiation of 2-29, 3-50 relationship to service 2-2 resynchronize 1-7, 2-
Index Initiating a connection See Establishing a connection Initiating an activity See APS_ACTIVITY_STARTREQ_ procedure Interface, procedural See Procedures, APS Interface, programmatic See API Internal error B-8 Interrupting an activity 2-13 See APS_ACTIVITY_INTERRUPTREQ_ and APS_ACTIVITY_INTERRUPTRSP_ procedures Invalid MCW error B-23 Invalid operation error B-9 Invalid service ID error B-18 Invalid session version error B-19 Invalid TAPS process version error B-16, B-18 Invocation identifiers, ACSE See
Index M Major synchronization point See Synchronization, major point Major synchronize functional unit 1-7, 2-9, 2-12 Major/activity token 2-9 Management Information Base See MIB Manager process See OSI manager process MAXCONNECTIONS configuration attribute 2-24 MCW error B-23 error subcodes B-32 Message control word See MCW MFM procedures error returned by B-12 overview C-1 syntax and descriptions C-2/5 MFM_AWAITIOX_ procedure status information returned by 2-25 syntax and description C-2/4 using 2-22, C-
Index Module file management procedures See MFM procedures more-data parameter buffer size too small 3-65 capability data request, in 3-64 overview 2-48 setting for typed data request 3-107 typical values for 3-69 N Named values A-20/32, A-37/39 Names application See local-appl parameter and remote-appl parameter APS procedures, for 2-2, 3-1/2 data declarations, for 2-2 service users, terms for 2-14 subdevices, for 3-28, 3-34, 3-87 Naming conventions 2-2/3 Negotiated release functional unit 1-6, 2-9, 2-51
Index O Object identifier A-4, A-5 Obtaining tokens, procedure sequence for 2-11 old-activity-id parameter 3-15, 3-20 old-conid parameter 3-15, 3-21 Open Systems Interconnection See OSI Operation invalid error B-9 Operator abort error B-10 Operator intervention status code B-3 Original error A-14 original-error-info parameter 3-85 OSI layers, overview 1-4/5 Reference Model 1-4 upper layer concepts 2-3/19 OSI address See also Address, local and Address, remote identifying 3-35, 3-41 relationship to applicat
Index PCID data element header, in A-9 declaration for A-5 description 2-17 examples 2-43/44 presentation context list, in A-14 specifying no value for A-29 use of 2-19 PDV list 3-69, 3-107 relationship to PCID 2-19 PDV types 2-35 Pending requests, none error B-17 Physical Layer 1-4 PI and PGI unit error subcodes B-31 errors B-22/23 Please tokens request 2-11 Please tokens request procedure 3-103/104 See also Tokens Pool space unavailable, error B-7 unusable, error B-12 pres-context-list parameter 3-33, 3-
Index Presentation (continued) default context name See also pres-default-context-name parameter description 2-17 structure for A-16 default context result See also pres-default-context-result parameter description 2-18 values of A-22 selector See PSEL service access point See PSAP service provider process See TAPS process Presentation Layer example requestor program in C E-47/61 example requestor program in TAL E-31/47 example server program in C E-77/91 example server program in TAL E-61/77 functional un
Index Primitives (continued) supported by ACSE 2-6 types of 2-3 unfinished, error B-19 Procedural interface See Procedures, APS Procedures, APS See also individual procedures beginning with APS_ accessing services of different layers 2-25 categories of 3-1/2 completion information, table of 2-14 confirm primitives, for 2-8 connect request sequence 2-28/30 connect response (attach) sequence 2-30/32 data sending sequence 2-46 data types used by, table of A-35/37 error in version of B-19 example program using
Index Procedures (continued) token please sequence 2-11 token states returned by, table of 2-10 tokens, effect on 2-9 types, table of 2-25/26 user abort sequence 2-52/53 using in C application programs D-1 Procedures, MFM See also individual procedures beginning with MFM_ error returned B-12 overview C-1 syntax and descriptions C-2/5 Procedures, SSxxx, errors during B-12/13 Process pair 2-23 Processes See NSP processes, OSI manager process, TAPS processes, and TSP processes Programmatic interface See API P
Index PSAP structure for A-16 using to identify an OSI address 3-35, 3-41 PSEL connect response, in 3-41 PSAP structure, in A-16 pseudofn parameter in MFM_CANCELREQ_ C-5 R Receiving events description 2-15 procedure for 3-71/72 Receiving exception reports 2-15/16 Recovery action B-1 Release confirm primitive retrievable parameters after, table of 3-52 Release indication primitive retrievable parameters after, table of 3-52 values of A-31 Release reason, ACSE release request, in 3-54 release response, in 3-
Index Report, exception See Exception report Request primitive 2-3, 2-6 Requesting a connection See also Establishing a connection calling user, procedure sequence for 2-28/30 request procedure 3-31/37 responding user, procedure sequence for 2-30/32 response procedure 3-38/43 Requesting tokens See APS_TOKEN_PLEASEREQ_ procedure and Tokens Requests, completion information from 2-14 Requests, too many pending error B-8 REQ_ procedures category 3-1 Resource limit error B-7 Resource limit, error subcodes for B
Index S segment-id parameter in MFM_AWAITIOX_ C-3 Segmentation not supported, error B-23 Sending an exception report 2-15, 3-73/74 Sending data See User data SEQUENCE OF EXTERNAL 1-8, 2-19, 2-42 Service ID unrecognized, error B-18 values of A-17 Service users, terms for 2-14 service-id parameter attach, in 3-28 connect request, in 3-33 overview 2-25 status request, in 3-84 Services See also Primitives comparison to protocol 2-1 confirmed, sequence of primitives for 2-4 unconfirmed, sequence of primitives f
Index Session Layer example program in C E-18/30 example program in TAL E-2/17 functional units supported functional units, specifying See session-rqmnts parameter ISO standards for 1-6 overview 1-5 services provided by this layer 1-6 version supported 1-7 session-rqmnts parameter 2-29 connect request, in 3-32 connect response, in 3-39 connection parameter retrieval, in 3-45 usage guidelines 3-36/37 SNPA 2-24 SPDU 2-49 SPI error B-14 error returned by OSI manager process B-29 error subcodes B-24 errors B-2
Index State machine error B-9 error subcodes for B-27 Static subdevices See Subdevices Status code values, table of B-2 codes, detailed description B-1/4 codes, overview 2-25 codes, using B-1 connection, retrieving 3-83/86 Stopping activity, abnormal See Discarding, activity and Interrupting an activity activity, normal See Ending, activity connection, abnormal See Aborting a connection and Discarding, connection context connection, normal See Releasing, connection static subdevice See Discarding, static s
Index sync parameter activity parameter retrieval, in 3-15 activity resume request, in 3-20 minor synchronization response, in 3-98 resynchronize request, in 3-76 resynchronize response, in 3-80 synchronization parameter retrieval, in 3-88 SYNC procedures category 3-2 Synchronization See also Resynchronization functional units 1-7 major point request 3-91/92 response 3-93/94 token for 2-9 minor point acknowledgment request 3-95, 3-96 confirmation of 3-99 request 3-95/97 response 3-98/100 token for 2-9 over
Index Tandem LAN Access Method (TLAM) 1-4/5 TAPS process invalid version error B-18 TAPS processes configuring 2-24 invalid version error B-16 TAPS subdevices See also Subdevices deleting static vs.
Index Tokens (continued) initial settings for A-13 negotiation of 2-29 overview and concepts 2-9/11 procedure sequence to obtain, table of 2-11 procedures that affect, table of 2-9 procedures that show token states, table of 2-10 state, error in B-21 tokens parameter 3-77, 3-81, 3-89, 3-101, 3-103 Transfer syntax ACSE, for 2-18 description 2-16 Transfer syntax name declaration for A-5 in presentation default context name A-16 Transport selector See TSEL Transport service data unit See TSDU Transport servic
Index User data block size 3-69 buffers ASN.1 2-42 ASN.
Index user-data parameter, maximum length (continued) capability data response, in 3-60 connect request, in 3-35 connect response, in 3-42 connection abort, in 3-26 connection release request, in 3-54 connection release response, in 3-56 control give request, in 3-62 exception report request, in 3-74 major synchronization point request, in 3-92 major synchronization point response, in 3-94 minor synchronization point request, in 3-96 minor synchronization point response, in 3-99 resynchronize request, in 3
Index Z ZACTIVITY field A-13, A-18 ZADDITIONAL-REF field A-12 ZAE-INVOCATION-ID field A-10 ZAE-QUALIFIER field A-7 ZAE-QUALIFIER-IS-PRESENT field A-6 ZAE-TITLE-FORMAT2 field A-6 ZAE-TITLE-TYPE field A-6, A-22 ZAP-INVOCATION-ID field A-10 ZAP-TITLE field A-7 ZAPPL-NAME field A-7 ZAPS-DDLABSTRACT-SYN-NAME A-5 ACTIVITY-ID A-6 AE-TITLE A-6 APPL-ADDR A-7 APPL-CNTXT A-7 BOOLEAN A-2 CHAR128 A-4 CHAR16 A-3 CHAR20 A-3 CHAR32 A-3 CURRENT-ERROR A-7 DATA-ELEMENT-HDR 2-33/44, A-8 DATA-HDR 2-33/44, A-9 DIAG-BUF A-9, A-1
Index ZAPS-DDL- (continued) PRES-CNTXT-RLIST A-15 PRES-DEFLT-CNTXT A-16 PSAP A-16 SERVICE-ID A-17 SWAP-VOLUME A-17 SYNC A-17 TOKENS A-18 TRANSFER-SYN-NAME A-5 WAITMODE A-19 ZAPS-ERRBAD-INSTALLATION B-19 BAD-MGR B-14 DATA-OP-INVALID B-18 EXISTING-CONNECTION B-15 FU-L5-xxx error subcodes B-28 FU-NOT-SELECTED B-10, B-28 FU-SELECTED B-10, B-28 HASHTABLE-ERROR B-15 INCOMPLETE-REQUEST B-16 INTERN-xxx B-24 INTERNAL-xxx B-8 INVALID-OPERATION B-9 INVALID-SERVICE B-18 INVALID-SESSION-VERS B-19 L5-BAD-PI-UNIT-LENGTH
Index ZAPS-ERR- (continued) MFM-ERROR B-12 MGR-ERROR B-14, B-29 MGR-FS-ERROR B-14 MGR-xxx error subcodes B-29 NO-CONNECTION B-16 NO-DATA B-11 NO-EVENT B-15 NO-POOL-SPACE B-7 NO-SEGMENT-SPACE B-7 NONE-PENDING B-17 NOT-IMPLEMENTED B-10 NOVALUE B-24 OK B-6 OPERATOR-ABORT B-10 P-EXCEPTION B-9, B-28 P-xxx error subcodes B-28 PARAM-BOUNDS B-17 PARAM-MISSING B-17 PARAM-RANGE B-17 PARAM-xxx error subcodes B-26/27 PARAMETER B-8, B-27 POOL-CLOBBERED B-12 PRIMITIVE-UNFINISHED 3-106, B-19 RESOURCE-LIMIT B-7, B-25 RESO
Index ZAPS-ERROR-PARAMETER 3-87 ZAPS-VAL NSP-xxx A-11 ZAPS-VALABORT-SRC-xxx A-21 ABORT-xxx 2-54, A-20 ABSENT A-4 ACT-xxx A-21 AE-TITLE-xxx A-22 CNTXT-RSLT-xxx 3-47, A-22 CNTXT-RSN-xxx A-23 CONACCEPT 2-27 CON-xxx 3-39, 3-45, A-23/25 DATA-TYPE-xxx A-8 DATA-xxx 3-68, 3-106, A-25 DIAG-xxx A-26/27 EVTACT-DISCARD-IND 2-13 ACT-END-IND 2-13 ACT-INTERRUPT-IND 2-13 P-ABORT-IND 2-54 RLS-CNF 2-51 RLS-IND 2-52 SYNC-MINOR 3-89 SYNC-MINORACK 3-89 table of A-27/28 TOKEN-GIVE-IND 2-11 U-ABOR.i(.
Index ZAPS-VAL- (continued) RESYNC-xxx 3-77/78, 3-80, A-30 RLS-RSN-xxx A-31 RLS-xxx 2-51, 3-46, A-31 RSLT-SRC-xxx A-32 SERVICE-xxx A-17 STATUSABORT B-3 DISCARD 2-53, B-4 EVENT 2-25, B-1/2 NO-RETRY B-3 OPERATOR B-3 RETRY-LATER B-3 RETRY-NOW B-3 UNKNOWN B-4 SYNC-NOVALUE A-17 TOKEN-xxx 3-37, 3-50, 3-79, 3-90, A-18/19 TRUE A-2 WAITED A-19 ZAPSC file 2-2, 3-1 ZAPSDDL file 2-2, 3-1 ZAPSTAL file 2-2, 3-1 ZAS-NAME field A-14, A-16 ZCALLED-REF field A-12 ZCALLING-REF field A-12 ZCAPABILITY-DATA field A-13 ZCLASS fi
Index ZINIT-SYNC field A-13 ZINIT-TOKENS field A-13 ZINT field A-5 ZINT-IS-PRESENT field A-5 ZL5-FU field A-13 ZL5-FU-ISPRESENT field A-13 ZLAST-ERR field A-11 ZLEN field A-8 ZMAJOR-SYNC field A-13 ZMAJORSYNC field A-18 ZMINOR-SYNC field A-13 ZMINORSYNC field A-18 ZNEG-RELEASE field A-13 ZNSAP field A-16 ZNSP-xxx fields A-11 ZNUM-ELEMENTS field A-4, A-9, A-14, A-15 ZNUM-TS field A-14 ZOBJ-ID field A-4 ZOSIAS file 2-2 ZPCID field A-9, A-14 ZPSAP field A-7 ZPSEL field A-16 ZREASON field A-15/16 ZRELEASE fiel
