IBM X.25 Co-Processor Support Program:
Programmer's Reference Manual

Fourth Edition, June 1996


Table of Contents

Special notices

About this book

  • Contents
  • Related publications
  • Introducing X.25 communications

  • About this Topic
  • The IBM X.25 Co-Processor Support Program
  • Hardware required
  • Software required
  • Software support
  • Concepts of packet switching data networks
  • Recommendation X.25
  • How a PSDN operates
  • Use of different packets in a call
  • Sequence of packets in a call
  • How packets are created
  • A conversation between two computers
  • Using the X.25 application programming interfaces

  • Applications and tasks
  • The IBM X.25 Co-Processor Support Program environment
  • The X.25 subsystem supervisor
  • The management task
  • Link management
  • Summary of X.25 API verbs
  • How to use the X.25 API
  • Initializing the IBM X.25 Co-Processor Support Program
  • Calling the API
  • API return and completion codes
  • XVRB output fields
  • Procedure for sending data
  • Initializing a task
  • Terminating tasks
  • Terminating the IBM X.25 Co-Processor Support Program
  • Connection IDs
  • Switched virtual circuits
  • Permanent virtual circuits
  • Data transfer
  • Resetting virtual circuits
  • Interrupts
  • Flow control
  • How confirmation of delivery works
  • Routing of calls
  • Directory
  • Routing of incoming calls
  • Facilities and Call User Data fields
  • Multiple links
  • X.25 application restrictions
  • X.25 application programming verbs

  • Using the application programming verbs
  • Contents of the verb request block
  • Data buffers
  • Description of the X.25 API verbs
  • X25Ack
  • X25AppInit
  • X25AppTerm
  • X25Call
  • X25CallAccept
  • X25CallClear
  • X25CallReceive
  • X25DataReceive
  • X25DataSend
  • X25Deafen
  • X25Event
  • X25Init
  • X25Interrupt
  • X25LinkAuto
  • X25LinkConnect
  • X25LinkDisconnect
  • X25LinkStatus
  • X25Listen
  • X25Name
  • X25PVCAlloc
  • X25PVCFree
  • X25Reset
  • X25ResetConfirm
  • X25SemClear
  • X25SemWait
  • X25Status
  • X25Term
  • X25Trace
  • X25VCStatus
  • Summary of API return and completion codes
  • Return codes
  • Completion codes
  • X.3, X.28, and X.29 support

  • Introducing X.3, X.28, and X.29 support
  • Description of the X.28 API
  • General
  • PAD states
  • Communicating with the API PAD
  • Descriptions of the X.28 API verbs
  • X28CallReceive
  • X28Close
  • X28DataReceive
  • X28DataSend
  • X28Open
  • X28SendBreak
  • X.28 String commands
  • Status
  • PAD parameters
  • Standard PAD profiles
  • Profile 0 (default)
  • Profile 1
  • Profile 90 (CCITT simple standard profile)
  • Profile 91 (CCITT transparent standard profile)
  • Description of the X.29 API
  • Descriptions of the X.29 API verbs
  • X29Call
  • X29CallReceive
  • X29ReadParam
  • X29SendBreakInd
  • X29SendInvitationToClear
  • X29SendReselectInvn
  • X29SetAndReadParam
  • X29SetParam
  • Developing and executing application programs

  • X.25 API programming language support
  • Assembler support
  • C language support
  • Pascal language support
  • Linking X.25 applications
  • The example application
  • General points
  • Task initialization
  • The task
  • Processing calls
  • Receiving calls
  • Clearing the call
  • The example application program
  • Glossary

    INTERNATIONAL BUSINESS MACHINES PROVIDES THIS PUBLICATION "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in revisions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

    It is possible that this publication may contain references to, or information about, IBM products (machines or programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

    (C) Copyright IBM Corporation 1989, 1990
    All rights reserved.


    Special notices

    Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility.

    IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license enquiries, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.

    The warranty terms and conditions applicable in the country of purchase in respect of an IBM product are available from the supplier. Please retain them with your proof of purchase.

    The following terms, denoted by an asterisk ( * ), used in this publication, are trademarks or service marks of the IBM Corporation in the United States or other countries: (Ref #1.)

    IBM,  Personal System/2,  PS/2,  Operating System/2,  OS/2,
    Micro Channel,  Macro Assembler/2,  C/2,  Pascal/2
    
    The following terms, denoted by a double asterisk ( ** ), used in this publication, are trademarks or service marks of the following companies in the United States or other countries:
    Lattice C           Microsoft Corporation
    Turbo C             Borland International
    Turbo Pascal        Borland International
    Transpac            Transpac S.A.
    
    No statements contained in this documentation shall affect the statutory rights of consumers.

    About this book

    For a list of trademarks, see topic reference #1. This book is intended for application programmers who use IBM X.25 Co-Processor Support Program to write application programs that communicate over X.25 packet switching data networks (PSDNs). It describes how you use the X.25, X.28, and X.29 application programming interfaces (APIs) to access such networks. It is assumed that you are familiar with the IBM (*) Personal System/2 (*) (PS/2) (*) and with X.25, although there is a brief introduction to this in Chapter 1.


    Contents

    The book contains the following:

    A glossary is provided at the back of the book.


    Related publications

    You can find information on installing your IBM X.25 Interface Co-Processor/2 adapter in the IBM X.25 Interface Co-Processor/2: Installation Instructions manual.

    Full technical information about the IBM X.25 Interface Co-Processor/2 adapter is contained in the IBM X.25 Interface Co-Processor/2: Technical Reference manual.

    The IBM X.25 Co-Processor Support Program: User's Guide tells you how to install, configure, and initialize the IBM X.25 Co-Processor Support Program on your PS/2. This manual is provided as part of the IBM X.25 Co-Processor Support Program package.

    Besides the supplied literature listed above, you may find it useful to refer to other published material on packet switching and X.25. The definitive X.25 reference is the International Telegraph and Telephone Consultative Committee (CCITT) Recommendation X.25.

    Your network provider may publish introductory material or booklets containing network-specific information. You may also find it useful to consult appropriate published books on the subject.


    Introducing X.25 communications


    About this Topic

    This topic describes the components of the IBM X.25 Co-Processor Support Program and the hardware and software required for its use. It also gives an introduction to packet switching data networks (PSDNs) and to X.25 from a programmer's view.


    The IBM X.25 Co-Processor Support Program

    For a list of trademarks, see topic reference #1.

    The IBM X.25 Co-Processor Support Program supports the CCITT X.25 recommendation (1980) and CCITT X.25 recommendation (1984) on any IBM Personal System/2 (PS/2) with a Micro Channel. (*)

    Hardware required

    The IBM X.25 Co-Processor Support Program requires one or more IBM X.25 Interface Co-Processor/2 adapters. Each adapter can support one link, using one of X.21 bis/V.24, X.21 bis/V.35, or X.21 (digital) interfaces.

    The IBM X.25 Co-Processor Support Program supports up to eight adapters, the total number for a particular PS/2 model being limited by the spare slots available in the system unit.

    Appropriate cables are required to attach each adapter to the network.

    Software required

    Software support

    The IBM X.25 Co-Processor Support Program consists of these components:

    The X.25 subsystem supervisor is the part of the IBM X.25 Co-Processor Support Program that controls the other parts of the system (see topic reference #3).

    Three application programming interfaces (APIs) are provided: X.25, X.28, and X.29.

    The APIs are "terminate-and-stay-resident" (TSR) applications. You decide which combination of the three APIs are to be loaded during initialization, as described in the IBM X.25 Co-Processor Support Program: User's Guide.

    The X.25 protocol code is the code that actually runs on the adapter. It implements level 1, 2, and 3 X.25 protocols. The code is loaded onto the adapters configured to use X.25 when the X.25 subsystem is initialized.

    The configurator is described in the IBM X.25 Co-Processor Support Program: User's Guide.

    The X.25 link manager and X.25 event manager are described in the IBM X.25 Co-Processor Support Program: User's Guide. You need not use these two supplied tasks, but if you do not you must supply the link management facilities with your own management task. (See "The management task".)

    Features of the IBM X.25 Co-Processor Support Program

    The IBM X.25 Co-Processor Support Program provides support for:


    Concepts of packet switching data networks

    Packet switching data networks (PSDNs) enable subscribers to exchange data quickly and reliably over a network. Connections can be made between any pair of subscribers.

    Data is transmitted over the network in packets; the packets are sent over virtual circuits set up through the network. Each pair of subscribers has what appears to be a dedicated circuit during a call.

    Terminology

    Packet switching has its own terminology; you need to be familiar with the following terms:

    Data terminal equipment (DTE)

    This is a computer, or other terminal, which uses the network for communication.

    Data circuit-terminating equipment (DCE)

    This is the device at the point of access to the network through which the DTE is connected to the PSDN.

    Switched virtual circuit (SVC)

    This is a virtual circuit that is established by a virtual call request. It is released when the virtual call is cleared.

    Permanent virtual circuit (PVC)

    This is a virtual circuit that has a logical channel permanently assigned to it at each DTE. A protocol to establish the call is not required.

    Applications and tasks

    In this book, an "application" means a DOS program (in a file with an extension of .EXE). An application that uses the IBM X.25 Co-Processor Support Program consists of one or more "tasks". Tasks are user-written, or system-supplied, routines that access the network; they use X.25 API verbs to set up virtual circuits, transfer data, and perform other actions.

    Tasks are described fully in "Using the X.25 application programming interfaces".

    Recommendation X.25

    The International Telegraph and Telephone Consultative Committee (CCITT) Recommendation X.25 defines a standard for information exchange in packet mode between a DTE and a DCE.

    Levels of X.25

    The X.25 recommendation concerns itself with three levels of DTE to DCE connection:

    1. Physical level. The physical level describes the mechanical and electrical connection between a DTE and a DCE, for example the cables and connectors between the two.

    2. Link level. The link-level protocol is designed to ensure that data and control information are accurately exchanged over the physical circuit between the DTE and DCE. Its function includes recovery procedures. When you use the IBM X.25 Co-Processor Support Program, the code that controls the link level operates on the &card.; a task cannot access it directly.

    3. Packet level. The packet-level protocol specifies how virtual circuits between DTEs are established, maintained, and cleared. It also defines the structure of the packets that are transmitted between a DTE and the network. This is the level that concerns you most, as an application programmer. When you use the IBM X.25 Co-Processor Support Program, you control packet-level action in a task with API verbs.

    How a PSDN operates

    An example of a PSDN, with one virtual circuit in operation, is shown in Figure 1.

    Figure 1. A packet switching data network

                   +--------+       +---------+
                   |   A    |       |    B    |
                   +---+----+       +----+----+
                       |                 |
                       |              ---+-----               +-----------+
                 ------+----         /         \              |           |
                /      V    \       /           \             +-----+-----+
        -------/       V     -------             \                  |
       /               V                    ------                  |
      /                V                   /                      --+--
     \     PSDN        V  Virtual Circuit  \       +--------+    /     \
      \                VVVVVVVVVVVVVVVVVVVVV+------+   E    +---/       \
       \                                     \     +--------+   \       /
        \          ---------------+----       \                  \     /
         -----+---/               |    \-------\                  --+--
              |                   |                                 |
        +-----+-----+        +----+-----+                           |
        |     C     |        |    D     |                    +------+------+
        +-----------+        +----------+                    |             |
                                                             +-------------+
    
    In the illustration, A, B, C, D, and E represent computers, or other data terminals (DTEs), connected to the network.

    When computer A communicates with computer B, it does so by sending packets of information into the network and receiving packets from the network.

    Computer B can also receive and send packets. The only interaction that computers A and B have with the network is their ability to send and receive packets. The packets could contain data or control information.

    When a "logical connection" (a virtual call) is established between two computers, the network identifies packets belonging to this virtual call using the logical channel number (a field that is present in all packets). The computer creating the packet puts the logical channel number into the packet.

    Use of different packets in a call

    Packets of different types fulfill different functions. Typical uses of packets are:

    Sequence of packets in a call

    A possible sequence of packets in a call on a switched virtual circuit is shown in

    Figure 2. Possible sequence of packets in a call

                               | Network |
                               |         |
      Computer A              DCE       DCE              Computer B
     --------------------------+---------+--------------------------
                               |         |                    START
                               |         |
      Call Request -----------------+    |
                               |    +---------------> Incoming Call
                               |         |
                               |    +---------------- Call Accepted
      Call Connected <--------------+    |
                               |         |
                               |         |
      Data -------------------------+    |
                               |    +---------------> Data
                               |         |
                               |    +---------------- Data
      Data <------------------------+    |
                               |         |
                               |         |
                               |    +--+------------- Clear Request
      Clear Indication <------------+  | |            Packet
                               |       | |
                               |       +------------> Clear Confirm
                               |         |            (from local DCE)
                               |         |
    
    Some fields in a packet are changed by the network. For example, the "logical channel number" is usually different for computer A and computer B within the same virtual call. The network changes this field in the packet before sending it on to the receiving terminal.

    How packets are created

    The API creates all the packets needed by a task. You do not have to know the detailed content of each packet - you only have to supply the information that the API cannot work out for itself.

    The contents of some types of packet used in a conversation are shown below.

    A conversation between two computers

    The use of different packets in a "conversation" between two computers on a switched virtual circuit is described in the following sections.

    Request a call

    Assume computer A wants to start the conversation. It must tell the network that it wants to make a call to computer B. It does this by sending a Call Request packet that contains the information shown in Figure 3.

    Figure 3. Call Request/Incoming Call packet

    +--------+------------+-------------+---------+------------+------------+
    | packet | logical    | destination | source  | Call User  | optional   |
    | header | channel no.| address     | address | Data       | facilities |
    +--------+------------+-------------+---------+------------+------------+
    
    The packet tells the network the address of the target computer (destination address). It also gives the network a logical channel number, which is used to identify this connection in all packets it sends in the future.

    The Call Request packet is then transmitted by the network as an Incoming Call packet to the receiving computer or terminal.

    Accept the call

    If computer B decides to accept the call request from computer A (which it receives as an Incoming Call packet), it sends a Call Accepted packet to the network. The network then accepts that there is a logical connection between computer A and computer B; in this case, a switched virtual circuit.

    Figure 4. Call Accepted/Call Connected packet

    +--------+------------+------------+
    | packet | logical    | optional   |
    | header | channel no.| facilities |
    +--------+------------+------------+
    
    The logical channel number is used by computer B to identify the conversation (it is usually a different number from that used by computer A for the same virtual call). Computer A then receives the (possibly modified) packet as a Call Connected packet. (See Figure 4.)

    Transfer data

    Computers A and B can now send Data packets to each other. Data packets are of fixed length (typically 128 bytes), so longer messages must be broken down into packet-sized segments.

    Figure 5. Data packet

    +--------+------------+--------+
    | packet | logical    | user   |
    | header | channel no.| data   |
    +--------+------------+--------+
    
    Data packets can be sent in both directions: computer B can send data packets to computer A, using the switched virtual circuit that has been established. The data can consist of messages, files, or any other type of data. (See Figure 5.)

    When computer A sends Data packets into the network, the DCE, which links it to the network, normally acknowledges each packet as it receives it. The network is then responsible for transferring the Data packet to the remote user.

    Users can demand acknowledgment of Data packets from the remote user. The receiver then has to send an acknowledgment after each Data packet has been received.

    Clearing the call

    Either computer can send a Clear Request packet to request the close down of the logical connection. The local DCE sends a Clear Confirmation packet back to the requesting computer and the virtual call is terminated. (See Figure 6.)

    Figure 6. Clear Request/Clear Confirmation packet

    +--------+------------+
    | packet | logical    |
    | header | channel no.|
    +--------+------------+
    
    The network sends a Clear Indication packet to the remote computer, telling it that the call has been cleared.

    Notes:

    1. Even a simple conversation consists of several stages; these require a sequence of program steps in the task. In real tasks, the stages might be more complicated than those shown.

    2. With the IBM X.25 Co-Processor Support Program, the PS/2 can have several tasks all using the network at once. Each task may have several virtual calls active at any one time, so some method is needed to ensure that packets do not go to the wrong tasks. The API uses a routing method, which is described in "Using the X.25 application programming interfaces".

    3. The conversation described above showed what happens on a switched virtual circuit. Permanent virtual circuits (PVCs) are regarded as being permanently available for use, so the "transfer data" steps may be all that is required. (A task must identify the PVC to the API before it can use it.)

    Using the X.25 application programming interfaces


    Applications and tasks

    The purpose of this topic is to explain how to write applications and tasks that use the X.25 API. However, before writing an application, you must understand how your application and the IBM X.25 Co-Processor Support Program work together. (In this environment, applications are user-written programs consisting of one or more tasks. Tasks are routines that interact with the network through calls to an API.)

    Note: In this topic, for ease of explanation, some of the work done by other parts of the IBM X.25 Co-Processor Support Program is described as being done by the API.


    The IBM X.25 Co-Processor Support Program environment

    The position of a user application in the IBM X.25 Co-Processor Support Program environment is illustrated in Figure 7.

    Figure 7. The IBM X.25 Co-Processor Support Program environment

     +--------------------+-------------+                +-------------+
     |====================|             |                |             |
     |====================|             |                |             |
     |====================|             |                |             |
     |====================|             |<-------------->|             |
     |====================|             |  Work Request  |             |
     |====================|             |  and           |             |
     |====================|   X.25 API  |  Reply Queues  |             |
     |====================|             |<-------------->|   Adapter   |
     |= User Application =|             |                |   with      |
     |====================|             |                |   Protocol  |
     |====================|             |                |   Code      |
     |====================|             |                |             |
     |====================|             |                |             |
     |====================+-------------+                |             |
     |====================|             |                |             |
     |====================|             |                |             |
     +--------------------+             |                +-------------+
     |                    | Subsystem   |
     |                    | Supervisor  |
     |                    |             |
     |  DOS               |             |
     |                    |             |
     |                    |             |
     |                    |             |
     +--------------------+-------------+
    
    (Ref #2.) The IBM X.25 Co-Processor Support Program is made resident in the PS/2 when you use the X25 command, as described in the IBM X.25 Co-Processor Support Program: User's Guide. The code of the IBM X.25 Co-Processor Support Program is reentrant and can manage multiple command requests from one or more applications simultaneously. An X.25 application calls the IBM X.25 Co-Processor Support Program by making a call to the API using a supplied subroutine. This subroutine makes a software interrupt, which is handled by the API, and passes a parameter, which is a pointer to a verb request block (XVRB). This XVRB indicates the command to be performed and the parameters of the command.

    Much of the X.25 support is performed on the IBM X.25 Interface Co-Processor/2 adapter. The API passes work requests to the adapter using work queues. The results of completed requests are returned from the adapter using other queues.

    The X.25 subsystem supervisor

    (Ref #3.) The X.25 subsystem supervisor controls the execution of the X.25 support tasks that handle the passing of requests from and to the adapter. The supervisor ensures that the X.25 support tasks are allowed to run at regular intervals, and that DOS is not interrupted during critical operations. The presence of the supervisor means that your application need not make regular calls to the API to manage the work, or to stop execution while waiting for completion of a command.

    When an application uses the API, it must identify itself to the API using an initialization verb. These verbs are X25Init and X25AppInit (see "Initializing a task" for more details). Each occurrence of an initialization verb causes the supervisor to create a new task, which is given a unique task identifier. An application can create more than one task.

    Note: The IBM X.25 Co-Processor Support Program cannot protect a task's memory area from being overwritten by other tasks or DOS applications. You must ensure that tasks are fully tested individually and with DOS applications that may run concurrently.

    Foreground and background tasks

    You can create applications, the tasks of which run either in foreground mode or background mode.

    It is possible for one foreground X.25 task to run concurrently with one or more background tasks.

    Foreground tasks

    You start the application that contains the foreground task by typing its name at the DOS prompt. For example:

       C:> EXAMPLEF parameter1, parameter2
    
    loads the application held in the file EXAMPLEF.EXE. (Two parameters are shown in the example, but the number of parameters, if any, depends on the application.)

    The X.25 API allows only one foreground task to be active at any time.

    When you write a foreground task, it should typically have the following structure:

    1. Program code and DOS calls.

    2. Initialization verb (X25AppInit or X25Init).

    3. X.25 and DOS calls.

    4. Termination verb (X25AppTerm or X25Term).

    5. Program code and DOS calls.

    6. Exit to DOS.

    Background tasks

    A background task runs under the control of the X.25 subsystem supervisor. You start an application, containing one or more tasks that are to run in background, by using the X25 LOAD command, as described in the IBM X.25 Co-Processor Support Program: User's Guide. For example:

      C:> X25 LOAD EXAMPLEB parameter1, parameter2
    
    loads the application in the file EXAMPLEB.EXE. (The parameters are optional, as in the previous example.)

    Using a separate X25 LOAD command for each application, you can have several applications loaded at the same time. Each application can contain several tasks, and each task is under the control of the X.25 subsystem supervisor.

    When you write an application that contains background tasks, it should typically have the following structure:

    1. Program code and DOS calls.

    2. An initialization verb (X25AppInit or X25Init) for each background task.

    3. Program code and exit to DOS. (This is executed only if initialization fails.)
    Each background task should typically have the following structure:

    1. X.25 and DOS calls.

    2. Termination verb (X25AppTerm or X25Term).
    Initially, the application runs as a DOS application. During this time any initialization, including that of any X.25 background task, is performed. An X.25 background task is initialized by issuing either an X25AppInit or an X25Init verb. This initialization defines the entry point for the background task and the length of the stack, which the background task uses for storing such items as dynamic variables and routine parameters, and return addresses. The background task's stack is allocated from the unused section of the calling application's current stack. The X.25 subsystem supervisor starts a new task at this point in the stack, while the main (EXAMPLEB) application continues to execute.

    If more than one background task is running, there must be a separate initialization call, either X25AppInit or X25Init, for each task. The last initialization call must set a flag to show that it is the final call.

    At this stage, all the application is made resident and the DOS part of the application terminates, leaving the background tasks running under the control of the X.25 subsystem supervisor. Background tasks can be started by the supervisor before the DOS part of the application finishes.

    Note: When using the X.25 Co-Processor Support Program to load a background task, you may have to execute the code from a directory other than the \X25 directory. If this is the case, you should copy the GQKENGLI.TXT file into the directory being used and the include line:

        path \X25
    
    in the X.25 parameter file. (The User's Guide contains details of the parameter file.)

    Background Task memory usage

    When a task is loaded into the background, it is made resident under DOS and owns all memory that was defined to it by the file load. The memory, owned by the task when it is terminated, may be altered by using an appropriate DOS SetBlocks call before the X25Init or X25AppInit verb is called to make the task resident. Alternatively, the program may be compiled/linked, where possible, with reduced stack or heap requirements, or both. It is your responsibility to ensure that adequate memory is defined for use by your task.

    X.25 application restrictions

    DOS function calls may be used within a background task with the following exceptions:

    1. DOS function calls 0h through 0Ch.

    2. DOS functions that allocate, deallocate, or adjust dynamic memory.

    3. DOS function calls that terminate a program (int29h, int27h, functions 4Ch, 31h, 0h).

    4. The DOS function to execute a program (function 4Bh).

    Stack size calculations

    (Ref #4.)

    The following stack sizes must be calculated when background tasks are being used:

    Stack size for each background task

    The stack required for each background task can be calculated as the sum of the following values:

    Stack size for the application

    The stack required for the application must be allocated at link time. It is calculated as the sum of the following values:

    When a new task is initialized, it is allocated a currently unused part of the stack allocated to the application.

    Memory allocation

    The possible memory allocation when an application is loaded as a background task is shown in

    Figure 8. Possible memory allocation for a background task

                     |                                   |
                     | Memory available to DOS           |
                     | applications when background      |
                     | tasks are made resident           |
                     |                                   |
                     +-----------------------------------+
                     |                                   |
                     | Global data accessible to the     |
                     | initialization program and        |
                     | background task                   |
                     |                                   |
                     +-----------------------------------+
                     |                                   |
                     | Initialization program stack      |
                     |                                   |
                     +-----------------------------------+
                     |                                   |
                     | Stack allocated to the background |
                     | task out of the initialization    |
                     | program stack                     |
                     |                                   |
                     +-----------------------------------+
     Task Entry      |                                   |
     Point --------->| API call                          |
                     | = = = = = = = = = = = = = = = = = | <-+
                     | X25Appinit                        |   |
                     |     .                             |   |
                     |     .                             |   |  Code run
     Program Entry   |     .                             |   +- as part of
     Point --------->| Initialization                    |   |  X25 LOAD
                     | = = = = = = = = = = = = = = = = = |   |
                     | Libraries                         |   |
                     |                                   |   |
                     +-----------------------------------+ <-+
                     |                                   |
                     | x.25 API                          |
                     |                                   |
                     +-----------------------------------+
                     |                                   |
    
                     +-----------------------------------+
                     |                                   |
                     | DOS                               |
                     |                                   |
    

    Notes:

    1. Stacks are allocated to the background tasks from within the creating application's stack. Any data passed to the tasks must be placed in statically defined or global data areas; dynamic data is not accessible.

    2. Memory allocation between the initialization code and data areas, and background task code and data areas is dependent on the programming language and linkage editor used. Low-level languages such as Assembler language give greater flexibility than high-level languages such as C.

    3. No inter-task communication or coordination facilities are provided. However, background tasks that are started from the same X25 LOAD command can share X.25 connection identifiers and statically allocated memory.

    4. The IBM X.25 Co-Processor Support Program itself contains several background tasks, so the X.25 subsystem supervisor is always present even if you are running a single foreground task. (You cannot save memory space by not using it.)

    Task scheduling

    Although an API is not provided for the X.25 subsystem supervisor, you have some control over its operation through the load time parameters. When the supervisor is called, it runs any background tasks that are not awaiting an event. Execution of a foreground task is suspended during this period. Control returns from the supervisor to the foreground task when:

    The foreground task has control until a specified period (called the timer tick period) has elapsed; control is then returned to the supervisor.

    The episode limit and timer tick period are set in the X.25 parameter file at load time using the EP_TICKS and TT_PERIOD parameters respectively (see the IBM X.25 Co-Processor Support Program: User's Guide for details).

    Note: The supervisor is not started if you call it when DOS is doing a critical operation. Therefore, the exact starting time of a background task cannot be predicted accurately.

    The management task

    Because the links to X.25 are shared between all the X.25 tasks in the system, one special task, the management task, must be present to coordinate the use of the links. Only the management task can use the API verbs that control the link(s) to the network. You can have only one management task active at any one time.

    An application creates the management task by requesting the X25Init verb instead of the X25AppInit verb when it creates the task. The management task must be the first task to be initialized and the last task to terminate.

    The management task can be either a foreground or background task. However, if it is a foreground task, you cannot load background tasks because the DOS part of the X25 LOAD application cannot be run without terminating the foreground management task. A background management task needs to perform special processing if it is to operate interactively with the user.

    When a single X.25 application is to be loaded at any time, it can organize its own link management. However, when several applications are to be loaded concurrently, it may be better to have a separate X.25 application specifically designed to control the X.25 links.

    A general-purpose management task, called the link manager, is supplied as part of the IBM X.25 Co-Processor Support Program. If you load this supplied management task, the API does not let you create another. To avoid using the supplied management task, insert the parameter line HOTkey=NULL in the X.25 parameter file during the initialization of the IBM X.25 Co-Processor Support Program. (See IBM X.25 Co-Processor Support Program: User's Guide for details.) The link manager runs in background mode.

    Link management

    A link must have been configured before you can use it. How to configure a link is described in the IBM X.25 Co-Processor Support Program: User's Guide.

    Link management involves connecting and disconnecting a link from the network. You can do this in one of two ways:

    1. By using the supplied management task, the link manager.

    2. By using API verbs to connect and disconnect the link. These API verbs can be requested only by a management task.

    Link modes and states

    There are three modes you can specify for a link:

    1. Connect. The API attempts to maintain the link in a connected state.

    2. Autoconnect. The API connects the link whenever a task requires the link to make a call, receive a call, or allocate a PVC on the link.

    3. Disconnect. The API disconnects the link.
    A management task can set the link to the three modes by using the verbs X25LinkConnect, X25LinkAuto, and X25LinkDisconnect, respectively.

    At any time the link is in one of seven states, which are controlled by the above three verbs. These are:

    1. Connecting: the link is being established.

    2. Connected: the link is established.

    3. Disconnecting: the link is being terminated.

    4. Disconnected: there is no established link connection.

    5. Error_level_1: an error has been detected at the physical level.

    6. Error_level_2: an error has been detected at the frame level.

    7. Error_Adapter: an error has been detected on the adapter.

    Link state events

    The link manager reports changes to the current link state (such as the link failing) with which nonmanagement tasks would not normally deal.

    If you write your own management task, it must also deal with these events. You can detect link state events by using the X25Status and X25LinkStatus verbs.

    X.32 Links

    The IBM X.25 Co-Processor Support Program supports the Transpac VX32 DCE, which carries out a variant of the X.32 protocol. No other X.32 support is provided.

    The VX32 DCE is a protocol convertor that looks like an X.25 DCE on one side and connects to the Public Switched Telephone Network (PSTN) on the other. The VX32 DCE supports either one incoming SVC (when the X.32 link is set up from the network), or up to eight outgoing SVCs (when the X.32 link has been set up from the local DTE). When an incoming call is in progress, no outgoing calls can be made. When an outgoing call is in progress, no incoming calls can be received. There is no PVC support but autoanswer and autodial are supported.

    Summary of X.25 API verbs

    These verbs are described in detail in "X.25 application programming verbs". The management verbs are available only to the management task (the task initiated by X25Init).

    Note: Throughout this manual the name of a verb is used to indicate a call to the API routine. The referenced XVRB contains the identifier of the verb.

    Management verbs

    X25Init
    Initializes a management task.

    X25LinkAuto
    Places a link in Autoconnect mode.

    X25LinkConnect
    Connects a link.

    X25LinkDisconnect
    Disconnects a link.

    X25Status
    Obtains the status of all or specified links.

    X25Term
    Terminates a management task.

    X25Trace
    Traces specified frames and packets to and from the network.

    Task control verbs

    X25AppInit
    Initializes a nonmanagement task.

    X25AppTerm
    Terminates a nonmanagement task.

    X25Deafen
    Disassociates a Routing table entry name from a task.

    X25Event
    Notifies a task of API termination or reinitialization.

    X25LinkStatus
    Obtains the status of all or specified links.

    Note: The X25Status and X25LinkStatus verbs are identical; the management task can request X25Status, other tasks must request X25LinkStatus.

    X25Listen
    Associates a Routing table entry name with a task.

    X25Name
    Queries an entry in the nicknames directory.

    X25PVCAlloc
    Allocates a PVC to a task.

    X25PVCFree
    Frees a PVC from a task.

    X25SemClear
    Terminates all outstanding verbs on a virtual circuit.

    X25SemWait
    Suspends a task until any verb completes.

    X25VCStatus
    Obtains the status of a virtual circuit.

    Network service verbs

    X25Ack
    Acknowledges receipt of data.

    X25Call
    Establish an SVC.

    X25CallAccept
    Accept an incoming call.

    X25CallClear
    Clear an SVC.

    X25CallReceive
    Wait for an incoming call.

    X25DataReceive
    Receive data or control information.

    X25DataSend
    Send data.

    X25Interrupt
    Send an Interrupt.

    X25Reset
    Reset a virtual circuit.

    X25ResetConfirm
    Acknowledges the reset of a virtual circuit.

    How to use the X.25 API

    Initializing the IBM X.25 Co-Processor Support Program

    The IBM X.25 Co-Processor Support Program must be initialized before you can use the API. You do initialization using the X25 command, as described in the IBM X.25 Co-Processor Support Program: User's Guide.

    During initialization, you specify the APIs that you want to be loaded into the memory of the PS/2 (the default is the X.25 API only). You cannot use an API unless it is loaded.

    Calling the API

    Each supported language has a single function or entry routine that you use to request the verbs in the API. "Developing and executing application programs" gives specific details of the entry routine and the header files provided for each supported language. The header files define the mnemonics used for various record types, and field names and values. These mnemonics are used throughout the current topic. "Developing and executing application programs" also gives an example of an application program written in C.

    When you call the API, you supply control information in an X.25 verb request block (XVRB). One of the items in the XVRB identifies the individual verb; for example, X25DataSend. The address of the XVRB is the single parameter to the API entry routine. The result of this routine is the immediate return code.

    The XVRB is of fixed size (34 bytes). Some verbs require an additional data buffer, for example X25DataSend needs a buffer containing the data that you want sent. With these verbs you set up the data in a buffer area and point to this buffer from a field in the verb request block.

    When you call the API, your control information is checked and, if no errors are found, the request is queued for later processing. The API then returns to your calling task with an immediate return code of X25_OK. If an error is found, the request is not queued and the API returns to your task with an immediate return code that shows an error. Also, an immediate completion code may be set in the XVRB to assist error diagnosis.

    When processing of your request has taken place, a delayed completion code is set in the XVRB. The X25SemWait verb must be used by your task to determine when a verb request has completed.

    All verbs, except for X25SemWait, must be handled by your application using the following procedure:

    1. Memory must be allocated for the XVRB and any data buffers required; the space required for data buffers is dependent on the verb used. This memory can be allocated at compile time within the application's data space from the application's stack, or, for foreground tasks only, dynamically at run time from DOS memory.

      The memory allocated to the XVRB must remain allocated until the verb completes. Therefore, you must take care when you use high-level languages that allocate and deallocate stack memory on function entry and exit. This means that it can be better to allocate static data buffers at compile time.

    2. All input parameters for the verb must be written to the XVRB. The space for reserved fields must be allocated but output and reserved fields need not be initialized.

    3. Any required data must be written to the data buffer.

    4. The entry routine is used to call the API. The immediate return code is then checked to ensure that it has a value of X25_OK.

    5. When required, use additional X.25 verbs to do further processing.

    6. When you want the task to check if any X.25 verbs have completed, use the X25SemWait verb. The task is then stopped until a verb request completes or a user-defined time-out period expires. (See "Time out" for details of where to set the time-out period.)

      When X25SemWait returns, its immediate return code and immediate completion code must be checked. When both codes do not have the value X25_OK, there has been an error processing X25SemWait. When there are no errors, a field in the X25SemWait XVRB shows which verb has completed by giving a pointer to that verb's XVRB and the value that was originally set in the semaphore field of that verb's XVRB. Any returned parameters are set in the completed verb's XVRB or in buffers referenced by that XVRB. In particular, the delayed completion code should be checked for errors. The task must not change the XVRB, or any storage to which the XVRB points, before the verb is shown as completed, because this can lead to unpredictable results.

    API return and completion codes

    (Ref #5.)

    The API supplies return codes and completion codes to a task that requests any API verb. The API uses these codes to show to the task whether the requested action has been successful.

    The API sets three types of code:

    1. Immediate return code. The immediate return code is the return value of the entry routine of the API.

      Examples of the immediate return code are:

      X25_OK indicates that initial validation has been done and the request has been accepted for further processing. Values other than X25_OK show that the API cannot process the request any further.

    2. Immediate completion code. This is set before the API entry routine returns if the API cannot progress the request further. The immediate completion code is put in the com_code field of the XVRB.

      Immediate completion codes are listed with the verb descriptions in "X.25 application programming verbs". Their meanings are in topic reference #12 of the same topic. The task needs to act appropriately on immediate completion codes.

    3. Delayed completion code When the API has performed the verb request (successfully or unsuccessfully), it puts a delayed completion code in the com_code field in the XVRB.

      The normal, acceptable delayed completion code is X25_OK.

      Unsatisfactory completion codes are listed with the verb descriptions in "X.25 application programming verbs". Their meanings are in topic reference #12 of the same topic. The task needs to act appropriately on unsatisfactory completion codes.

    Note: The delayed completion code is meaningless until the verb completes.

    Problem determination

    The completion codes can help you determine the cause of errors. Also, a trace facility, which you set up as described in the IBM X.25 Co-Processor Support Program: User's Guide, may provide you with additional information. The X25Trace verb lets you produce a trace of packets and frames on a link or circuit.

    XVRB output fields

    (Ref #6.)

    Besides the return and completion codes, other verb results are set in the XVRB and associated data buffers. These should not be examined until a verb has completed.

    Two XVRB output fields may be examined when a verb has been accepted for processing. The fields are:

    1. task_id: In an X25Init or X25AppInit XVRB.

    2. conn_id: In an X25Call, X25CallReceive, or X25PVCAlloc XVRB. The actual circuit is not set up until the verb completes.
    The semaphore field is common to all verbs. A task can set a value in the semaphore field. The value of a verb's semaphore field is returned by the X25SemWait verb when it is notifying your task of the verb's completion. Therefore, your task can use the semaphore field to distinguish between verb completions.

    If you set the semaphore field to zero, the API sets it to 255. The API clears the semaphore field when verb completion is signaled.

    Procedure for sending data

    An application has to go through a series of actions to send data on a switched or permanent virtual circuit. To send data on an SVC, the application must do the following:

    1. Initialize a task.

    2. Ensure a link is connected.

    3. Call a remote user (alternatively listen for, and accept, a call from a remote user). This establishes the switched virtual circuit.

    4. Send some data to the remote user on the SVC.

    5. Close the SVC.

    6. Terminate the task.

    The first step is performed by the application, the rest are performed inside a task.

    Initializing a task

    The application initializes a task by requesting one of the two initialization verbs. For nonmanagement tasks the verb is X25AppInit, for the management task it is X25Init.

    A foreground task initialization must set the resume address to 0, the stack size to 0, and the last task indicator to X25_LAST_TASK_YES.

    A background task initialization must set the resume address and the stack size to correspond with those of the task being started. The last task field must be set to X25_LAST_TASK_NO or X25_LAST_TASK_YES, dependent on whether there are more tasks.

    The parameters with the initialization verb are checked by the API. An immediate return code is then returned and must be tested by the application. If this is X25_OK, processing is queued to continue. If it is not X25_OK, the application must test the immediate completion code to assist error diagnosis.

    When processing continues, the task must wait for the initialization verb to complete, so after the request for the initialization verb, the task must issue a request for X25SemWait. This suspends the task until a previous verb (here X25AppInit or X25Init) completes.

    The task must test the immediate return code from X25SemWait. If this is X25_OK, the task must test the delayed completion code of X25SemWait (in the verb request block that the application supplied with X25SemWait).

    If this is also X25_OK, the task must test the delayed completion code of X25AppInit or X25Init. If this is X25_OK, the task is established.

    After initialization, tasks can listen for incoming calls, allocate PVCs, and perform other functions, by using the Task Control and Network Service verbs provided by the API.

    Notes:

    1. An X.25 task must not be initialized from within another X.25 task.

    2. All background tasks should be initialized from within the entry procedure of the DOS application (this is main for C and Pascal programs).

    Task identity

    When X25AppInit or X25Init returns successfully, the API puts a task identity (Task ID) into the verb request block. The task must use this Task ID in all following requests for API verbs from the task that has been initialized.

    The same application can request X25AppInit several times. An application can thus create several independent tasks to run in background mode. Each task might be responsible for a particular part of the processing done by the application and have a different Task ID.

    Terminating tasks

    You must use a termination verb to end a task. The X25Term verb ends a management task, and X25AppTerm ends a nonmanagement task.

    X25Term

    X25Term can be issued with an immediate or a delayed option.

    The immediate option stops all operations immediately and, except for X25SemWait, allows no further X25 verbs to be processed.

    The delayed option does not affect operations in progress but prevents the processing of any further X25 verbs that allocate new resources, X25Call for example.

    When all virtual circuits are closed, all links disconnected, and all other tasks stopped, the X25 subsystem is terminated.

    Notes:

    1. The call to X25SemWait allows processing of outstanding verbs.

    2. The call to X25SemWait can return to a foreground task but cannot return to a background task.

    3. A delayed X25Term verb never completes.

    The termination calling sequence is the same as that for other verbs. First the verb call is issued, then an X25SemWait verb must be called to enable the API to complete its processing. (See also step However, the method of completing the termination sequence is dependent on whether a foreground or background task is being terminated.

    1. The completion of a foreground task, whether successful or unsuccessful, is shown by the X25SemWait verb. The executing application then continues to run as a DOS application. However, if termination is unsuccessful, an error return code is given before processing continues.

    2. For a background task, successful completion means that the task terminates without the X25SemWait verb returning to the task. Unsuccessful completion is shown by the X25SemWait verb.

    The API frees the memory used by an X.25 task when the last task within that application terminates. This means that, although the X.25 subsystem supervisor does not schedule a background task when it has terminated, the memory allocated to the task is not freed until the final task in that application terminates.

    In exceptional circumstances the DOS EXIT command can be issued to terminate a task. In this case, the memory used by the task is not freed.

    Note: When a management task is terminated, the API must be reinitialized before more X.25 tasks can be initialized.

    Forcing verb termination

    It is possible for some API verbs never to complete; for example, an X25CallReceive or an X25Status using the "delayed" option. You can use the X25SemClear verb to force these verbs to complete. The X25SemClear verb can be used to terminate all verbs associated with a particular connection, or all connections associated with a particular task.

    When you use X25SemClear to terminate a verb, its completion is signaled through an X25SemWait verb; X25_APP_REQ_CLEAR_SEM is the delayed completion code.

    When you use X25SemClear to terminate verbs associated with a particular connection, all verbs associated with that connection are terminated.

    When you use X25SemClear to terminate verbs associated with all connections, the following verbs are terminated in addition to those given above:

    Note: When X25SemClear is used to terminate verbs associated with a particular connection, all verbs associated with that connection are terminated; this includes those issued by other tasks within an application.

    Terminating the IBM X.25 Co-Processor Support Program

    You terminate the IBM X.25 Co-Processor Support Program using the X25 TERM DOS command. See the IBM X.25 Co-Processor Support Program: User's Guide for details of this command.

    Connection IDs

    The API assigns a unique connection ID to each virtual circuit that a task establishes. Virtual circuits are established when:

    Connection IDs are only valid within a single X.25 application. However, if an application contains several tasks, all the tasks can access connection IDs set up by the other tasks in the application.

    You are not advised to have more than one task receiving data, or more than one task sending data over the same virtual circuit at the same time.

    Switched virtual circuits

    Making a call

    When it is trying to establish an SVC, a task sends a Call Request packet to a remote DTE; the remote DTE can then show if it accepts or rejects the call. The task uses the X.25 API as described here.

    The task calls the API requesting X25Call. It provides a data buffer containing the necessary parameters (such as Called Address) for the API to build the Call Request packet.

    The API builds and sends a Call Request packet. If the remote DTE accepts the call, X25Call completes with a delayed completion code of X25_OK. The connection ID for the SVC is in the XVRB.

    The switched virtual circuit is established and the task can use it to send and receive data.

    If the remote DTE does not accept the call, the verb returns a completion code other than X25_OK. For example, if the remote DTE rejects the call, X25Call completes with a delayed completion code of X25_CALL_CLEARED, and the SVC is not available for use.

    Receiving a call

    When receiving a large number of incoming calls it is possible that the X.25 Co-Processor Support Program may run short of buffers. When this situation is detected it is reported through the gqk.err file and causes the following entry in the gqk.rep file:

    PKR / XIO Error  16: Message 10
    
    Subsidiary data: 0000 0000          'date and time'
    
    If this happens it could have unpredictable effects on subsequently opened connections. An X25CallReceive verb must be issued before any more incoming calls are detected. This applies to X25, X28, and X29 applications.

    The PAD select command must be equal to, or less than, 128 bytes.

    To receive a call from a remote DTE, a task:

    1. Requests X25Listen. This verb indicates which incoming calls the task is prepared to accept. The task supplies, in a data buffer, a list of routing table entry names(s). These specify the external DTEs that are to be listened for. (The mechanism by which the API routes incoming calls is explained in

    2. Requests X25CallReceive. The task provides a data buffer large enough to receive the data from an Incoming Call. X25CallReceive completes when a suitable Incoming Call is received.

      The connection ID allocated on the immediate completion of X25CallReceive then becomes valid.

    3. Requests X25CallAccept, providing a data buffer containing the necessary data for the verb to build a Call Accepted packet.

    Clearing a call

    An SVC is cleared when a task:

    In either case, no further data can be transmitted across the network and data already in the network may be discarded. The connection ID of the SVC is no longer valid and any verbs using the connection ID are cleared.

    Task clears the call

    When a task wants to clear an SVC it requests X25CallClear.

    If a task wants to be sure that the remote DTE has received all the data that has been sent, it should request confirmation of delivery of data and close the SVC only when the remote DTE has confirmed delivery.

    Network or remote DTE clears the call

    The API knows that the network or remote DTE has cleared the SVC when it receives a Clear Indication packet. To detect this event, the task should have an X25DataReceive verb currently active even if it is not expecting data. The API passes the Clear Indication packet to the task and automatically sends a Clear Confirmation packet to the network.

    Clear collision

    A clear collision occurs when a Clear Indication packet is received from the network while an X25CallClear request is building or sending a Clear Request packet.

    The task is normally unaware of the collision; clear processing is completed by the API and the network. Depending on the network implementation, data from the X25CallClear may or may not be passed on to the remote user, because the call is already cleared.

    Calls cleared by the API

    The API can itself send a Clear Request packet if it detects specific errors (for example, a protocol error across the link). It puts appropriate Cause and Diagnostic codes in the Clear Request packet.

    Tasks should ensure there is an X25DataReceive available to receive the Clear Indication packet. To a task, this situation is similar to an SVC being cleared by a remote DTE. Data transmitted from the task before reception of the Clear Indication packet may be lost, as with any Clear processing.

    Permanent virtual circuits

    Permanent virtual circuits (PVCs) are logical connections permanently assigned between two DTEs on a packet switching network. Each PVC is identified by a number, assigned to it by the network.

    If the link remains physically connected, a PVC is always ready to send or receive packets.

    Allocating a PVC

    Before a task can communicate over a PVC, it must allocate the PVC to itself. To allocate a PVC, a task requests X25PVCAlloc specifying the number of the PVC it wants allocated. If the PVC is already allocated, X25PVCAlloc returns an error code.

    If the PVC is free, X25PVCAlloc returns a connection ID that the task must use on all following requests for processing on the PVC. When a PVC is allocated to a task, the task can use it to send and receive data in the same way as on an SVC.

    Freeing a PVC

    X25PVCFree deallocates a PVC from a task, freeing it for use by another (or the same) task. It is the responsibility of the calling task to deallocate a PVC in a controlled manner.

    Data transfer

    A task can use an established SVC or an allocated PVC to send and receive Data packets across the network.

    Sending data

    A task sends Data packets over an SVC or PVC by requesting X25DataSend, specifying an appropriate connection ID. The task must have put the data it wants to send into a data buffer and put a pointer to this data buffer into the verb request block.

    A task need not provide data in packet-sized pieces; the API splits the data into packets and transmits them to the network.

    If tasks in an application request consecutive X25DataSend verbs with the same connection ID, the API processes the requests in the order it receives them. It is up to your application to ensure that data is sent in the correct order. To help do this, you should request all X25DataSend verbs for one virtual circuit from the same task.

    The M-bit, Q-bit, and D-bit within the packet header are set according to the parameters set in the X25DataSend verb.

    Receiving data

    A task can receive data from a particular SVC or PVC by requesting X25DataReceive and specifying the connection ID of the virtual circuit.

    X25DataReceive assembles the incoming packets into the data buffer whose address the task has supplied in the verb request block. If possible, a complete, logical sequence of data packets is received in the data buffer before the verb completes. The logical sequence consists of packets with their M-bits set on. The sequence is terminated on receipt of a packet with its M-bit clear.

    Note: The buffer must be at least as large as the largest packet size that can be received, up to a maximum of 64K -16. A task can use X25VCStatus to query the packet size for a particular virtual circuit.

    Nondata packets

    Besides data, a task can receive Clear Indication, Reset Indication, and Interrupt packets over an SVC or PVC when it requests X25DataReceive. The processing of these is described later.

    Clear Confirmation, Reset Confirmation, and Interrupt Confirmation packets are handled for the task by the API. They are never sent or received directly by a task, although they are generated indirectly by some verbs.

    Notes:

    1. Up to 32 bytes of Interrupt User data can be received in an Interrupt packet. (CCITT 1984 only.)

    2. If user data is required from a Clear Indication packet, the buffer must be large enough to receive the data.

    3. Clear Confirmation packets are not returned to applications by the API. These packets may contain Charging information, which is therefore not available to applications.
    Packets received before X25DataReceive is requested

    If a Data packet, a Clear Indication packet, a Reset Indication packet, or an Interrupt packet is received and there is no X25DataReceive verb available to receive it, the packet is queued in the adapter memory until it can be received by the task.

    A task can request multiple X25DataReceive verbs concurrently, to ensure that all data is received as quickly as possible.

    Completion of X25DataReceive

    There are several events that cause an X25DataReceive verb to complete, these are described below. The XVRB output fields pkt_type, mbit, and mbit_reason show why the X25DataReceive verb completed. These fields also show whether the D-bits or Q-bits are set on in the packet sequence.

    Events that cause the X25DataReceive verb to complete are:

    Notes:

    1. To receive data packet-by-packet, the data buffer size must be set equal to the packet size.

    2. The total number of bytes of data received is returned in the data_len field of the X25DataReceive XVRB.

    3. When the last data packet to be received has the D-bit set on, the delivery must be confirmed. Confirmation may be done automatically by the API or by the task issuing the X25Ack verb.
    Multiple tasks using a virtual circuit

    If more than one task uses X25DataReceive at the same time, take care to receive complete sequences of packets, and avoid individual packets going to other tasks.

    X25DataReceive verbs complete in the order in which they were issued.

    The API passes the data packet to the next X25DataReceive verb waiting to receive from that virtual circuit.

    To avoid problems, you should receive data from all virtual circuits in the same task.

    Resetting virtual circuits

    A task can reset any virtual circuit (SVC or PVC) to resynchronize data transfer. Tasks normally reset PVCs to synchronize them before starting data transfer. Synchronization of SVCs is implicit in the call set-up procedure, so tasks need not reset SVCs before transmitting data.

    A virtual circuit is reset when one of the following occurs:

    When the Reset Request packet is sent, no further data can be sent on the virtual circuit until:

    The network may discard data already in the network. If a task needs to know that data is successfully received at the remote end before commencement of the reset, it should request delivery confirmation on Data packets.

    Reset by task

    A task resets a virtual circuit by requesting X25Reset. The API, when it processes the request, sends a Reset Request packet to the network and terminates any X25DataSend, X25Ack, and X25Interrupt verbs in progress on the virtual circuit (or requested before the reset is complete).

    X25Reset completes when a Reset Confirmation packet is received from the network. X25DataReceive does not return any data from the virtual circuit until the reset is complete.

    Reset by network

    If the API receives a Reset Indication packet, it passes it to the next X25DataReceive that is requested on this virtual circuit. The API terminates all X25DataSend, X25Ack, and X25Interrupt verbs in progress (or requested before the reset is complete).

    When it has received a Reset Indication packet, the task must acknowledge the reset by requesting X25ResetConfirm. It cannot send or receive any data on the virtual circuit until it has done this.

    Reset collision

    A reset collision occurs when X25Reset is building or sending a Reset Request packet and the API receives a Reset Indication packet from the network.

    When this happens, X25Reset terminates with a completion code of X25_RESET_COLLISION. X25DataReceive passes the Reset Indication packet to the task, which must acknowledge the Reset Indication packet by requesting X25ResetConfirm. The locally generated Reset Request packet, with its cause and diagnostic codes, may or may not be transmitted across the network, depending on where the collision was detected and the network characteristics.

    X25Reset is also terminated with a completion code of X25_RESET_COLLISION if a Reset Indication packet is received before the X25ResetConfirm has completed. The task must request X25ResetConfirm before processing can recommence, and before any further reset can be requested for the virtual circuit.

    Call cleared during reset

    On SVCs, call clear processing always overrides any resetting that is taking place.

    If the API is processing an X25Reset request and it receives a Clear Indication packet, it terminates the X25Reset with a completion code of X25_CALL_CLEARED. The API then passes the Clear Indication packet to a task with an active X25DataReceive verb for the virtual circuit.

    If the API receives a Clear Indication packet while the task has not yet acknowledged a Reset Indication packet (by using X25ResetConfirm), the API terminates the X25ResetConfirm, when the task requests it, with a completion code of X25_CALL_CLEARED. The API then passes the Clear Indication packet to any task with an active X25DataReceive verb for the virtual circuit. Processing of other verbs is as for call clearing.

    If a reset fails on an SVC (that is, the reset retry count is exhausted, and on each retry the time out expires before a Reset Confirmation packet is received from the network) the API clears the SVC.

    If a reset fails on a PVC, the API sends a Restart Request packet for the link.

    Interrupts

    X.25 allows a single Interrupt packet, with up to 32 bytes of user data, to be sent across a virtual circuit. The Interrupt packet may be delivered ahead of any data packets that are in the network for this virtual circuit.

    Only one Interrupt packet is allowed in each direction on a virtual circuit (SVC or PVC) at one time. The receiving DTE confirms the arrival of an Interrupt packet by sending an Interrupt Confirmation packet to the network.

    Sending interrupts

    A task sends an Interrupt packet on a specified virtual circuit by requesting the X25Interrupt verb. The task can send up to 32 bytes of data from a data buffer, pointed to from the verb request block.

    The API waits for the reception of an Interrupt Confirmation packet from the remote DTE before the verb completes. There is no data or other information associated with an Interrupt Confirmation packet.

    The API rejects requests to send an Interrupt packet on a virtual circuit where it is waiting for a previous Interrupt packet to be confirmed.

    Receiving interrupts

    When the API receives an Interrupt packet, it automatically sends an Interrupt Confirmation packet to the remote DTE. The API passes data from the Interrupt packet to any task with an X25DataReceive request available for the virtual circuit.

    If the API receives an Interrupt packet on a virtual circuit that is currently receiving a sequence of Data packets, the sequence is interrupted. The API returns the partially received packet sequence to the task, with the M-bit set, and with the M-bit Reason indicator showing that an Interrupt packet ended the packet sequence. The API passes the data from the Interrupt packet to the task on the next X25DataReceive request that is available for the virtual circuit.

    The next X25DataReceive after that receives the continuation of the original packet sequence.

    Flow control

    Data flow on a virtual circuit depends on the flow rate within the network and on the flow rate between the DCE and DTE at each end.

    Data flow can be affected by packet size, packet window size, and throughput class. Different values may be offered by the network and you can configure them for each X.25 link, using the appropriate configuration panels described in the IBM X.25 Co-Processor Support Program: User's Guide. By using the facilities fields in the verb request blocks of the call set-up verbs, the network may allow tasks to change configured values when they set up a call.

    Data flow is affected if a task requests confirmation of delivery during data transfer. When a task sends data without requesting confirmation of delivery, the local DCE acknowledges the packets. When the task requests confirmation, the remote DTE has to acknowledge the last packet in each sequence. This can obviously slow down data flow.

    Setting up confirmation of delivery

    At call set up

    A task requests confirmation of delivery of Data packets by setting the D-bit indicator in the verb request block. It does this when it requests the X25Call or X25CallAccept verb.

    If the remote DTE does not clear the call, the API assumes D-bit processing is agreed, and honors any D-bit requests from the task. If the remote DTE cannot handle confirmation of delivery it clears the call, with or without explanatory Cause or Diagnostic codes. The task can then try to reestablish the call without confirmation of delivery.

    When D-bit processing is requested in an Incoming Call packet, the API passes this information to the task receiving the call in the D-bit option indicator in the X25CallReceive verb request block. When the task accepts the call, it may set the D-bit in the X25CallAccept XVRB to indicate that confirmation of delivery is required.

    Acknowledgment

    A task can let the API automatically acknowledge confirmation of delivery on packets that require it. Alternatively, a task can choose to manage confirmation of delivery itself by setting the D-bit acknowledgment indicator in the verb request block of the X25Call, X25CallAccept, or X25PVCAlloc verb when it requests one of those verbs to set up or accept a call.

    How confirmation of delivery works

    Sending data packets

    When the task has not requested confirmation of delivery, X25DataSend completes after it has assembled all the data into packets and sent it to the adapter (but before all packets have been sent to the network).

    When the task has requested confirmation of delivery, X25DataSend does not complete until acknowledgment of the last Data packet in the sequence has been received from the remote DTE.

    When data flow is constrained, either by the network, or by delays in acknowledgment, there can be a delay before X25DataSend completes. If the delay becomes unacceptable to the task, it can request X25SemClear to terminate X25DataSend. You should use this procedure with caution because the state of the call data is no longer known.

    Receiving data packets with D-bit acknowledgment

    When delivery confirmation is requested, and the task has chosen not to manage it itself, the API makes the acknowledgment when it copies the Data packet to the data buffer of the task that issued the X25DataReceive. This acknowledgment is transparent to the task.

    When the task has chosen to manage confirmation of delivery itself, it must request X25Ack when it receives the data with the D-bit set. This method lets the task ensure safe storage of the data, if required, before it gives the requested end-to-end acknowledgment of receipt of data. If you adopt this method, you should request X25Ack as quickly as possible to maintain data flow.


    Routing of calls

    The following sections describe how the API directs an outgoing call to an appropriate remote DTE and how it routes incoming calls to appropriate tasks.

    Routing depends on the directory and the routing tables that are set up during configuration. The tables are described in the IBM X.25 Co-Processor Support Program: User's Guide.

    Directory

    The directory is a table that associates user-provided nicknames with X.25 user addresses, link names, and (optionally) extended addresses.

    The user creates the directory and maintains the list of nicknames as described in the IBM X.25 Co-Processor Support Program: User's Guide.

    Directory entries contain the following fields:

    If a task specifies a nickname when making a call, the API tries to find the nickname in the directory and, if it is successful, picks up the corresponding addresses and indicator from the table. The task need not know the actual network address of the DTE that it wants to call.

    Most nicknames in the X.25 directory are likely to refer to remote DTEs. Tasks can use a nickname when making calls; the API uses the nickname to put the Called Address into the Call Request packet that it creates. The API inserts the nickname (if one exists) in place of a Calling Address when a task is receiving a call.

    Users can also have a nickname entry (or entries) for the local DTE. Tasks can use a local nickname when making calls; the API inserts the address from the directory as the Calling Address in the Call Request packet.

    Duplicate nicknames are not allowed in the directory.

    Nickname with multiple links

    When there are multiple links, the user can specify nicknames for the different local address for each configured link. The API finds the appropriate Calling Address by using the link name and nickname when looking up the directory.

    Notes:

    1. The X25Name verb provides tasks with an X.25 directory inquiry facility. The API compares the inquiry fields with the directory and returns all matching entries.

    2. The directory can only be updated as described in the IBM X.25 Co-Processor Support Program: User's Guide, it cannot be directly updated by tasks.

    Routing of outgoing calls

    The normal minimum requirement with an outgoing call is that the task must provide the API with the Called Address. If more than one X.25 link is installed, the task must also supply the name of the link over which the call is to be placed. A task can omit the Called Address if the bilateral closed user group (BCUG) facility is coded.

    Tasks provide the link and address information in the appropriate fields of the X25Call verb request block, and data buffer. As described previously, tasks can use nicknames instead of network addresses.

    When a task omits the Calling Address, the Calling Address field is left blank. In most networks the Calling Address is inserted by the DCE before the Call Request packet is transmitted across the network.

    Addresses are not checked for validity; if invalid addresses are entered, the network clears the call.

    Routing of incoming calls

    The API uses a routing table and an associated routine to select the most appropriate task (if any) to receive an Incoming Call packet. Routing does not apply to permanent virtual circuits.

    Five fields in an Incoming Call packet can contain addressing information:

    1. Called Address field.

    2. Calling Address field.

    3. Called Address Extension Facility field.

    4. Calling Address Extension Facility field.

    5. Call User Data (CUD) field.
    The API uses any combination of these fields to route an Incoming Call packet to a task.

    How routing information is set up

    During configuration, the user can specify entries to the routing table. This table contains entries with fields corresponding to each field listed above in an Incoming Call packet.

    How the API uses the routing table

    The API uses the incoming call routing table to direct incoming calls to appropriate tasks. Calls are routed to a particular task by the API matching fields in the Incoming Call packet with fields in the routing table.

    A task can use more than one routing table entry name (all routing table entry names are unique). Different tasks belonging to the same application all share any routing table entries that have been specified by any task.

    The routing table entries are available to all tasks; a task specifies a list of such entries when requesting X25Listen and X25Deafen, as described below:

    X25Listen
    Associates one or more routing table entry names with a task.

    X25Deafen
    Disassociates one or more routing table entry names from a task.
    X25CallReceive routes an incoming call to a task if the fields in the Incoming Call packet match all fields in a routing table entry associated with the task.

    Mechanism

    When an incoming call is received, the API examines each routing list in turn, looking for a match between data in the Incoming Call packet and each entry in the routing list.

    The first entry with all its specified fields identical to the corresponding fields in the Incoming Call packet is deemed to be a match.

    Lists are searched in the order in which the applications were started.

    The user may have used the characters * and ? in entries in the routing table, and are used similarly when specifying file names in DOS commands, that is:

    When creating routing lists, users should put entries with most specific definitions before those that use * and ?.

    The API clears an incoming call if it cannot find a routing list entry match for the call.

    Facilities and Call User Data fields

    X.25 supports several optional user facilities. You may have to choose these when you subscribe to a network. Some networks may allow tasks to "negotiate" values when they set up a call. The network-level verbs support all specified use of address, facility, and user data options on call set up and clearing.

    Facility fields are not modified or interrogated by the API except during call set up, as follows:

    Multiple links

    You might use multiple network links to have a backup to one network, to provide better load balancing, to connect to different packet switching networks, or for a combination of all these. When multiple links are in use, tasks must make suitable allowance for them.

    Tasks requesting X25Call must specify a link name with the verb explicitly, or implicitly by using a nickname in the directory.

    The network assigns the network user address (NUA) for each link. Therefore each link in a multiple-link system has a different NUA. Thus the Calling Address supplied by a task at call set up varies, depending on which link the call is to be made.

    Multiple links to the same network

    The X.25 "multilink" protocol is not supported by the IBM X.25 Co-Processor Support Program. Applications can achieve limited load balancing by appropriate allocation of link names in the directory.


    X.25 application restrictions

    The following restrictions apply to applications that use the IBM X.25 Co-Processor Support Program:

    1. DOS function calls may be used within a background task with the following exceptions:

      1. DOS function calls 0h - 0Ch

      2. DOS functions that allocate, deallocate, or adjust dynamic memory.

      3. DOS functions that terminate a program (int 29h, int 27h, functions 4Ch, 31h, 0h).

      4. The DOS function to execute a program (function 4Bh).

    2. Total stack size per application (including overhead) must be less than 64 kilobytes.

    3. Within one application, once its first background task has been initialized (X25Init, X25AppInit), the initiating thread of the application may not use C library services (for example, printf). This is because the C library is not reentrant and the initiating thread is likely to be preempted at any time by its background task. Background tasks, however, are not themselves preempted and therefore may use C library services.

    4. Tasks may share global data within an application but should be resilient to contention for access or update of this data by other tasks.

    5. Tasks should call X25SemWait frequently. This lets them share processing time with other tasks, especially by API system tasks. Processor-intensive tasks and tasks that use a lot of disk or other I/O devices, should intersperse frequent X25SemWait verbs to allow system processes to service users and link requests.

    6. The system performance may be tuned using commands with the X.25 parameter file:

      1. ep_ticks. This is the length of time that the API can run in the background before the supervisor starts the foreground task again. The larger it is, the lower the foreground performance.

      2. tt_period. The smaller this is, the more frequently the supervisor tries to dispatch tasks. As before, higher API performance means lower foreground performance.

    7. The files=xx command in config.sys must accommodate the number of system files used in background by the API.

    8. Take care with the program segment prefix (PSP). It is potentially shared by several tasks and must not be used for the disk transfer area (DTA). The supervisor initially sets the DTA near to the bottom of the allocated stack for the task, but the task may change this using DOS function task 1Ah.

    9. Although a background task is made resident, vectors should only be "hooked" with caution. The X25Term and X25AppTerm verbs do not "unhook" any vectors if they remove the task from memory.

    10. A side effect of having more than one program running at a time is the confusion of the file redirection, current drive, and current path.

      1. Redirection of stdout and stderr. Output from resident programs (and background tasks) is discarded if redirected by DOS. Foreground output may be redirected by DOS. See the IBM X.25 Co-Processor Support Program: User's Guide for details.

      2. Current drive/path. The background task should not alter the current DOS drive (function 0Eh) and path (function 3Bh) unless it restores the value before it next makes an X.25 API verb call. This prevents the foreground application losing track of the current drive/path.

      3. Long jump. C programmers should not use the setjmp/longjmp calls in background applications.

    11. Take care when using compilers that reference global or static data items through the stack segment pointer because this is modified for each task. Always reference global or static data items from within an explicit data segment.

    X.25 application programming verbs


    Using the application programming verbs

    When a task requests an API verb, it supplies a pointer to an X.25 verb request block (XVRB) that it has set up for the verb request. The contents of the XVRB depend on the verb being requested but always include:

    Some verbs require tasks to set up a data buffer besides the XVRB. For example, with X25DataSend the task must set up a buffer containing the data it wants to send. The task puts a pointer to the data buffer in the XVRB.

    Contents of the verb request block

    Each verb request block is 34 bytes long. In this topic the contents of each XVRB are shown, as a table, with the verb being described.

    The headings in each table are as follows: (Ref #7.)

    Name:
    The name of the field as defined in the supplied header file.

    Lth:
    Length of the field in bytes.

    I/O:
    This shows if the parameter is input (I) to the API verb, output by API verb (O), or input and output (I/O).

    Description:
    This gives the name of the field, as used in the detailed description of each field given in the following sections.
    Note: The tables in the following topics do not include all the padding fields.

    Fields in the X.25 verb request block

    The XVRB for each verb is a structure in the supplied header file.

    Items that can appear in any XVRB are listed below in alphabetical order. The API verbs to which the item refers are listed between [ and ] brackets.

    Cause code

    This is the CCITT X.25 cause code returned in a Clear Indication packet [X25Call, X25CallAccept, X25CallClear] or in a Reset Indication or Clear Indication packet [X25DataReceive] when a call is reset or cleared by a remote DTE. Alternatively, with API verbs that create packets, it is the cause code that the task wants to send in a Clear Indication packet [X25CallClear] or in a Reset packet [X25Reset].

    Clear confirmation indicator

    This is set by a task when requesting that the X25CallClear verb should not complete until the API receives a Clear Confirmation packet from the network. Values are:

    X25_CLEAR_CONF_NO
    Do not wait for confirmation

    X25_CLEAR_CONF_YES
    Wait for confirmation
    Completion code

    This field contains a code that the API returns to a task either when it has validated the XVRB and found an error (the immediate completion code) or when a verb completes (the delayed completion code). It shows the success or otherwise of the verb's action. Return codes are described in "API return and completion codes" [All]. A list of completion codes appears with each verb and the meanings of each code begin in topic reference #12.

    Connection ID

    A connection ID is a number used by the API and the task to identify an SVC or PVC. The API supplies a virtual circuit's connection ID to a task when it sets up an SVC [X25Call or X25CallReceive] or when a task allocates a PVC [X25PVCAlloc X25PVCFree, X25VCStatus].

    A task must supply the connection ID, to identify the virtual circuit, when sending packets or control information [X25CallAccept, X25DataSend, X25Interrupt, X25Reset, X25ResetConfirm, X25Ack, X25CallClear, X25PVCFree, X25VCStatus] or when receiving packets [X25DataReceive].

    When terminating verbs a task can optionally specify a connection ID [X25SemClear] to clear verbs using a specific virtual circuit.

    Convert address option

    This option lets tasks select that the API should replace the Calling Address from an Incoming Call packet with a nickname from the directory when it receives a call [X25CallReceive]. When the API cannot find a match in the directory, it returns the unconverted calling address. Values are:

    X25_NAME_CONVERT_NO
    Do not replace Calling Address with nickname

    X25_NAME_CONVERT_YES
    Replace Calling Address with nickname
    D-bit acknowledgment indicator

    When a task initiates, or accepts, a call it uses this field to show if confirmation of delivery (D-bit processing) of Data packets is required [X25CallAccept, X25Call]. When a task receives a call or call connect [X25CallReceive], or requests status [X25VCStatus], this field is set to show that confirmation of delivery has been requested. Values are:

    X25_DBIT_NO
    D-bit processing not required

    X25_DBIT_YES
    D-bit processing required
    D-bit acknowledgment management indicator

    When a task sets up a call with D-bit processing requested [X25PVCAlloc, X25CallAccept, X25Call] it can choose whether the API should automatically perform acknowledgment of Data packets or whether the API should only acknowledge the data when the task issues an X25Ack. When a task requests status of a virtual circuit [X25VCStatus], this field is set to reflect this status. Values are:

    X25_DBIT_ADAPTER
    D-bit acknowledgment by API/adapter

    X25_DBIT_USER
    D-bit acknowledgment by task
    D-bit, M-bit, Q-bit control

    These are set by the task to indicate the packet header flags for this data [X25DataSend]. The defined values are bit settings and must be ORed together to get the required combination of effects.

    X25_DBIT_NO
    Acknowledgment not required

    X25_DBIT_YES
    Acknowledgment required

    X25_MBIT_NO
    Data is a complete sequence

    X25_MBIT_YES
    Data is not a complete sequence

    X25_QBIT_NO
    Data is not control information

    X25_QBIT_YES
    Data is control information
    D-bit, M-bit, Q-bit indicator

    These are set by the API to indicate the packet header flags for this data [X25DataReceive]. The defined values are bit settings:

    X25_DBIT_NO
    Acknowledgment not required

    X25_DBIT_YES
    Acknowledgment required

    X25_MBIT_NO
    Data is a complete sequence

    X25_MBIT_YES
    Data is not a complete sequence

    X25_QBIT_NO
    Data is not control information

    X25_QBIT_YES
    Data is control information
    Diagnostic code

    This is the CCITT X.25 diagnostic code received by the API in a Clear Indication or Reset packet and passed to the task [X25Call, X25DataReceive, X25CallAccept X25CallClear]. With API verbs that create packets, it is the diagnostic code that the task wants to be put into the packet [X25CallClear, X25Reset].

    Event indicator

    This indicator is used by the API to indicate the new system state. It is returned to the task when an X25Event verb completes. Values are:

    X25_EVENT_TERMINATING
    System is being terminated immediately or delayed termination has reached its final stage

    X25_EVENT_TERM_DELAYED
    System is in state of delayed termination no new resources are allocated
    Last task indicator

    This indicator is set by the application to tell the API that this is the last of a series of tasks belonging to the application [X25AppInit, X25Init]. A foreground task must set this indicator to X25_LAST_TASK_YES. Values are:

    X25_LAST_TASK_NO
    More tasks to follow

    X25_LAST_TASK_YES
    This is the last, or only, task
    Length of data buffer

    Length (in bytes) of the data buffer that contains data set up by the task [X25Call, X25CallAccept, X25CallClear, X25CallReceive, X25DataSend]. Alternatively, it is the length of the buffer where the API is to deposit data [X25DataReceive, X25Interrupt, X25LinkStatus, X25Name, X25Deafen, X25Listen, X25VCStatus, X25Status].

    Length of data in buffer

    Set by the task, this is the number of bytes of data to be sent (the maximum is 64K -16) [X25Interrupt X25DataSend, X25DataReceive].

    Link name

    This consists of eight alphanumeric characters, left justified, padded with spaces. The task provides it when making a call [X25Call], allocating a PVC [X25PVCAlloc], or specifying the name of the link to be connected, disconnected, traced or reported on [X25LinkAuto, X25LinkConnect, X25LinkDisconnect, X25VCStatus, X25LinkStatus, X25Status].

    When you leave the link name blank with the last verb, the API reports on all links.

    Alternatively, it is the link name returned by the API when a task accepts an incoming call by requesting X25CallReceive.

    Logical channel number

    This is the number of the logical channel (at the local DTE) supplied by the network in an Incoming Call packet [X25Call, X25CallReceive]. A task normally does not need to use this because it uses a connection ID to identify a virtual circuit.

    M-bit reason indicator

    This field shows if the data received is complete or part of an incomplete sequence. An incomplete sequence may be caused by the API receiving an Interrupt packet, or a packet with changed or invalid combinations of M-bit, D-bit, and Q-bit settings. This can also be set by the buffer being filled [X25DataReceive]. Values are:

    X25_MBIT_AND_DBIT
    M and D-bits set in packet

    X25_MBIT_AND_QBIT_CHANGED
    Q-bit changed in sequence

    X25_MBIT_BUFFER_TOO_SMALL
    Buffer space less than packet length

    X25_MBIT_COMPLETE
    Complete data sequence

    X25_MBIT_CLEAR_SEM
    Task requested semaphore to be cleared

    X25_MBIT_INCOMPLETE
    Incomplete data sequence

    X25_MBIT_INTERRUPT
    Interrupt packet received
    Original semaphore

    The API places the semaphore value from the completed verb in this field of the XVRB of the X25SemWait verb.

    Output discard

    If this is set to X29_OUT_DISC_YES, it indicates that the generated Indication of Break PAD message should contain a parameter field to indicate that parameter 8 should be set to 1 (discard output).

    Otherwise, there is no parameter field in the Indication of Break PAD message.

    Pointer to data buffer

    A pointer, set by the task, to a data buffer where the task has put data for the verb to send [X25Call, X25CallAccept, X25CallClear, X25Interrupt, X25DataSend, X25Deafen, X25Listen, X25Name]. Alternatively, a pointer, set by the task, to the data buffer where the API is to put data [X25DataReceive, X25CallReceive, X25LinkStatus, X25Status, X25Call, X25CallClear, X25Name, X25Deafen, X25Listen, X25VCStatus].

    Pointer to XVRB

    A pointer is set by the API in the X25SemWait XVRB. It points to the XVRB of the verb that has completed.

    PVC number

    A number identifying a PVC, as described in the IBM X.25 Co-Processor Support Program: User's Guide [X25PVCAlloc].

    Semaphore

    A semaphore field exists in the XVRB of all verbs. A task can set this when making a verb request. If set to zero, the API sets it to 255. The API sets it to zero when the verb completes.

    SNA usage indicator

    This field shows the type of traffic to be carried over the virtual circuit. [X25Call, X25CallAccept]. Values are:

    X25_NATIVE
     

    X25_SNA_1980
     

    X25_SNA_1984
     
    If SNA circuits are selected, the API forces SNA cause and diagnostic codes and does not allow Interrupt packets to be sent. The following restrictions apply to SNA usage:
    Stack size

    The size (in bytes) of the stack that the task wants to be allocated by the API [X25Init, X25AppInit]. See topic reference #4 for an explanation of stack-size calculation.

    Statistics option

    This field indicates that current statistics are to be stored [X25Trace]. It can have one of the following values:

    X25_STATS_YES
    Store the current statistics

    X25_STATS_NO
    Do not store the current statistics
    Status delay option

    This field shows if the task wants the link status to be returned immediately or whether it wants the link status after the next status change has taken place [X25LinkStatus, X25Status]. Values are:

    X25_STATUS_DELAYED
    Delayed link status required

    X25_STATUS_IMMED
    Immediate link status required
    Task entry address

    Set up by the application, this is the entry point of the task being created. The X.25 subsystem supervisor starts the task at this address. The application creating the task should set this to zero if the task is to run in foreground. [X25AppInit, X25Init].

    Task ID

    This is an identifier for a task. The API provides the Task ID when an application initializes a task [X25Init, X25AppInit]. All following requests for API verbs from the task must use this Task ID to identify it [All].

    Termination option

    This field shows if the task wants termination to be immediate or whether the API must wait until all established calls are cleared and all allocated PVCs freed before terminating [X25Term]. Values are:

    X25_TERM_IMMED
    Immediate termination requested

    X25_TERM_DELAYED
    Delayed termination requested
    Time out

    The maximum time that X25SemWait is to wait for a verb to complete. When 0 is set, X25SemWait returns immediately to indicate either that a verb has completed normally or there are no verbs to complete. When a task sets a value of -1, the X25SemWait only returns when a verb completes [X25SemWait]. Values are:

    -1
    Wait indefinitely

    0
    Return immediately

    Any other (positive) number
    Time out, in tenths of a second
    X25Trace

    The option of "Tracing to a Buffer in Memory" is not available. This is because the option uses excessive amounts of memory and the result is of little value because of the asynchronous nature of the data being traced. The following fields are therefore ignored in the X25Trace processing:

    trace_buff_st
    Trace buffer start pointer

    trace_length
    Trace buffer length

    trace_buff_end
    Trace buffer end pointer
    The following rules apply to the X25Trace verb:
    Trace buffer end pointer

    When X25Trace completes, this parameter indicates the end of the most recent trace or statistics record in the buffer.

    Trace buffer length

    This indicates the length of the trace buffer in bytes. It is set by the task.

    Trace buffer start pointer

    On input to an X25Trace verb, this indicates the starting point of the memory trace buffer to be used. It is not required if the trace destination option indicates "trace to file". When the X25Trace verb completes, this field indicates the oldest trace or statistics record in the buffer.

    Trace destination option

    This can be set to one of these values:

    X25_TRACE_FILE
    Store the trace statistics in a file

    X25_TRACE_OFF
    Stop a trace and, if using a file, close the file
    Trace name

    The name of a trace panel entry defining the frames and packets that the task wants the API to trace. Traced frames and packets are stored in the specified buffer or file [X25Trace].

    Type-of-data-received indicator

    This field is set by the API to show the type of data it has passed to the task [X25DataReceive]. Values are:

    X25_RCVD_DATA
    Received data

    X25_RCVD_APPN_CLEAR
    Clear requested by a task

    X25_RCVD_APPN_RESET
    Reset requested by a task

    X25_RCVD_REMOTE_RESET
    Received Reset indication

    X25_RCVD_DISC_INDICATION
    Received Clear indication (SVC) or Restart indication (PVC)

    X25_RCVD_INTERRUPT
    Received interrupt
    Verb identifier

    This field contains a code that identifies the API verb that the task is requesting, for example X25DataSend [All]. See the supplied header file for all possible values.

    Version identifier

    This field is provided so that the API can detect possible future versions of the software. Applications must set it to X25_API_VERSION on all verb requests [All].


    Data buffers

    Some verbs require data buffers besides the XVRB. The data buffers layouts are shown, as tables, with the verb descriptions in this topic.

    The fields in a data buffer are set up by a task when the verb is sending data (for example, with X25DataSend); they are set up by the API on verbs that receive data (for example X25DataReceive).

    Fields used in the various data buffers are described here.

    X25Call data buffer

    Called address

    This is the address of the remote DTE that the task is calling. It can be a network user address (NUA) or a nickname in the directory from which the API can derive the NUA. A task enters an NUA or a nickname unless it is using the bilateral closed user group facility, when it can be omitted.

    On completion, this field contains the Called Address from the received Call Connected or Clear Indication packet.

    Calling address

    This is the local DTE that is making the call and is optional. It can be an NUA or a nickname in the directory, from which the API can derive the NUA. A task enters an NUA in hexadecimal characters and a nickname in alphabetic characters.

    On completion, this field contains the Calling Address from the received Call Connected or Clear Indication packet.

    Call user data

    This field is optional. The API copies data from it to the Call User Data field in the Call Request packet.

    On completion, this field may contain data (if any) from the Call User Data field of the Call Connected packet, or Clear Indication packet (if extended format is selected with the Fast Select facility).

    Facilities

    The API puts any data from this field into the Facilities field of the Call Request packet. It inserts any extended addresses derived from routing table entry names in the X.25 directory into the correct format.

    On completion, this field contains the data (if any) from the Facilities field of the Call Connected packet (received when the call was connected).

    Length of call user data

    Minimum size is zero, maximum:

    Length of called address

    Minimum 0, maximum 15 bytes. Zero is only valid if the task has selected the bilateral closed user group facility in the Facilities field. The field must be large enough to hold the NUA even if a nickname is used.

    Length of calling address field

    Minimum 0, maximum 15 bytes. The field must be large enough to hold the NUA even if a nickname is used.

    Length of facilities field

    Minimum 0, maximum 109 bytes. Standard CCITT meaning.

    Offset within buffer of length of field X

    This shows where the field giving the length (in bytes) of field X can be found. When field X must be present then this field must also be present, otherwise the task should set it to zero. The field must follow the length field of field X.

    X25CallAccept data buffer (optional)

    Called address

    This is the local DTE being called. A task can set up an NUA or a nickname in the directory.

    Calling address

    This is the remote DTE that is making the call. It can be an NUA or a nickname.

    Call user data

    If present, this field contains the Call User Data that the API writes into the Call Accept packet.

    Facilities

    When present, this field contains the Facilities information that the API writes into in the Call Accept packet that it creates.

    Other fields

    The remaining fields have the same meaning as for X25Call.

    X25CallClear data buffer (optional)

    Called address

    This is the local DTE being called. A task can set up an NUA or a nickname in the directory.

    When a task has set the clear confirmation indicator in the XVRB and a clear collision occurs, the API puts the Called Address from the received Clear Indication packet in this field.

    Calling address

    This is the remote DTE that is making the call. It can be a NUA or a nickname.

    When a task has set the clear confirmation indicator in the XVRB and a clear collision occurs, the API puts the Calling Address from the received Clear Indication packet in this field.

    Call user data

    When present, this field contains the Call User Data that the API writes into the generated Call Clear packet.

    When a task has set the clear confirmation indicator in the XVRB and a clear collision occurs, the API puts the Called User Data from the received Clear Indication packet in this field.

    Facilities

    When present, this field contains the Facilities information that the API writes into the Call Clear packet.

    When a task has set the clear confirmation indicator in the XVRB and a clear collision occurs, the API puts the Facilities information from the received Clear Indication packet in this field.

    Other fields

    The remaining fields have the same meaning as for X25Call.

    X25CallReceive data buffer

    Called address

    This is the local DTE being called, as set by the remote DTE.

    Calling address

    This is the remote DTE that is making the call. The task can request that the API should return it to the task as a nickname (in the directory) by setting the convert address option in the XVRB.

    Call user data

    This field contains the Call User Data (if present) from the received Call Request packet.

    Facilities

    This field contains Facilities information (if present) from the Call Request packet.

    Other fields

    The remaining fields have the same meaning as for X25Call.

    X25DataSend data buffer

    Data to send

    Data that the task wants to send. Minimum 1 byte, maximum 64K -16.

    X25DataReceive data buffer

    Data received

    This is the actual data received. It consists of data assembled from a series of Data packets or from one of the control packets that X25DataReceive returns. The minimum is the negotiated receive-packet size, the maximum is 64K -16.

    X25Deafen and X25Listen data buffers

    These contain the following fields:

    Routing table entries

    Each contains two fields:

    1. Routing table entry name. Eight alphanumeric characters, left-justified and filled with spaces. This is the name of the routing table entry, as set up during configuration.

    2. Status indicator. This is returned by the API to show the action that the verb has taken. Values are:

      X25_NAME_ACCEPTED
      Name accepted for use by verb

      X25_NAME_ALREADY_SELECTED
      Name is already being listened for by this application (X25Listen only)

      X25_NAME_ALREADY_USED
      Name in use by another application

      X25_NAME_INVALID
      Name not in the Routing table

      X25_NAME_NOT_SELECTED
      Name not being listened for by this application, so cannot be deafened (X25Deafen only)

      X25_NAME_NOT_USED
      The name is not being listened for by any application (X25Deafen only).

    X25Interrupt data buffer

    Data to send

    Data that the task wants to send in the Interrupt packet. Minimum 1 byte, maximum 32 bytes.

    X25LinkStatus and X25Status data buffers

    This is required by the X25Status and X25LinkStatus verbs. It contains the fields:

    Link status entries

    Each entry contains the following fields:

    X25Name data buffer

    This is used by X25Name. It contains the following fields:

    Matching table entries

    Each entry contains five fields:

    1. Comments. The comments that the user entered during configuration.

    2. Link name. The name of the link that the user supplied when setting up the nickname.

    3. Nickname. The nickname that the user gave during configuration.

    4. X.25 address. The X.25 address (maximum 15 alphanumeric characters) for the user whose nickname appears in the table. When the entry is for a PVC, this field contains the PVC name.

    5. X.25 extended address. The X.25 extended address (maximum 32 alphanumeric characters) for the user whose nickname appears in the table.

    X25Trace data buffer

    This is a free-format ASCII buffer that contains trace information and statistics. It is a "circular" buffer.

    Trace file and buffer formats

    Trace and statistics data is held in ASCII records. Each record is trace terminated. The format of a frame-level packet is:

    FX NAME ADDR P/F NR NS DATA
    

    Where the characters:

    F
    Identifies a frame-level diagnostic and the X character is:
    R
    To signal a frame has been received in the link.
    S
    To signal a frame has been sent on the link.
    C
    For all the events that are related to the link control. These are the level 1 or 2 connection and disconnection diagnostics and the loss-of-carrier messages.

    NAME
    The name of the frame sent or received (or the line-control diagnostic).

    ADDR
    Is the address field of the frame end.

    P/F
    The value of the poll/final bit.

    The following field is present only for supervisory frames:

    NR
    The value of the n(r) in the frame.

    The remaining fields are present only for information frames:

    NS
    The value of the n(s) in the frame.

    DATA
    The data field for any information frame. The data field, when enabled, is always displayed in hexadecimal (four bytes are always displayed).

    The trace format of a packet-level packet is:

    PX VC NAME packet_data
    
    P
    Identifies a packet-level diagnostic; the character X is:
    R
    To signal a packet has been received on the link.
    S
    To signal a packet has been sent on the link.

    VC
    The virtual circuit number

    NAME
    The name of the packet sent or received (or the line-control diagnostic).

    The remaining fields depend on the packet type and, if applicable, include:

    Trace statistics

    Statistics are shown on individual records for each frame and packet type. Frame-level statistics show the number of each type of frame transmitted and received. They have the format:

    FRAME SABM: T=5, R=2
    
    which means that five SABM frames were sent on the link and two were received.

    Packet-level statistics show the number of each packet type sent, each packet type received, and the number of acknowledgments for each packet type. They have the format:

    PACKET CALL: T=23 , R=7 , CONFIRM: T=5 , R=17
    
    This means that 23 call packets were sent on the link, 17 of which were accepted, and seven call packets were received, five of which were accepted.

    X25VCStatus data buffer

    This contains the following fields:


    Description of the X.25 API verbs

    (Ref #8.)

    This section provides descriptions of each of the X.25 API verbs. Each description is accompanied by a table to show the contents of the XVRB and, where appropriate, a table to show the contents of the data buffer.

    Note: The table showing the contents of the XVRB does not contain offsets; it contains only the order of the fields. See the header files on the IBM X.25 Co-Processor Support Program diskette for detailed information, including offsets and reserve files.

    See "Contents of the verb request block" and "Data buffers" for details of the fields in the tables.

    X25Ack

    Purpose

    A task uses X25Ack to confirm delivery of Data packets that require D-bit acknowledgment. The task only uses this verb if it has informed the API, during call set-up, that it wants to manage D-bit acknowledgment itself. Otherwise, the API confirms delivery of such packets itself.

    The verb completes as soon as the acknowledgment is passed to the adapter. The task receives no further Data packets on the virtual circuit (identified by its connection ID) until the X25Ack verb has completed successfully.

    Verb request block for X25Ack

    Table 1. X25Ack verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Ack                                           |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Ack

    See topic  reference #12 for the meanings of these codes.

    X25AppInit

    Purpose

    An application uses X25AppInit to initialize a task that is not the management task. (X25Init is used to initialize the management task.)

    The API returns a task identity (task_ID) immediately. The application should issue X25SemWait after X25AppInit to check that initialization is complete before issuing any further X.25 verb calls.

    Verb request block for X25AppInit

    Table 2. X25AppInit verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25AppInit                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | O   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | resume_addr | 4   | I   | Task entry address                               |
    +-------------+-----+-----+--------------------------------------------------+
    | stack_size  | 2   | I   | Stack size                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | last_task   | 1   | I   | Last task indicator                              |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25AppInit

    See topic  reference #12 for the meanings of these codes.

    X25AppTerm

    Purpose

    X25AppTerm terminates a nonmanagement task.

    The verb clears all outstanding verbs, clears all connected calls, and frees all allocated PVCs. However, it is better that a task should clear all virtual circuits itself, using a protocol acceptable to the remote DTE, before requesting X25AppTerm.

    X25AppTerm closes all connections associated with the application that issued the call and terminates the application. The call to X25SemWait does not return to a background task. Other applications are not affected by this verb.

    Verb request block for X25AppTerm

    Table 3. X25AppTerm verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25AppTerm                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25AppTerm

    See topic  reference #12 for the meanings of these codes.

    X25Call

    Purpose

    A task uses X25Call to initiate a call on an SVC. The X25Call verb request sends a Call Request packet, then waits for a Call Connected packet or a Clear Indication packet to be returned from the remote DTE or the network.

    The connection ID is valid on immediate return from the verb. This cannot be used to send data until the verb completes, but it can be used in an X25SemClear to terminate the verb.

    The task provides a data buffer for the X25Call; the API uses this to build the Call Request packet. This buffer must contain the address to be called; other entries in the buffer are optional. For instance, if the task wants to specify Calling Address or Facilities it can do so.

    The task can include up to 16 bytes of Call User Data (CUD) in the buffer (128 bytes with the Fast Select facility). Any buffer fields that are to be omitted must be set to 0.

    On completion, X25Call puts the data received from the Call Accepted or Clear Indication packet into the data buffer.

    Notes:

    1. The link_name in the XVRB take precedence over any used in a nickname (if a nickname is used). Also, any extended addresses or reverse charging takes precedence over any used in a nickname.

    2. If an X25Call request is subsequently cleared, a call-cleared-delayed-completion return code is given after an OK-immediate-return. If an X25LinkDisconnect is issued after an incoming call has been received, an X25CallAccept produces an immediate return code of X25_ERROR, and a call-cleared-immediate-completion error. Hence the error may be either delayed or immediate, depending on the sequence of events.

    Verb request block for X25Call

    Table 4. X25Call verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Call                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I/O | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | lcn         | 2   | O   | Logical channel number                           |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_opt    | 1   | I/O | D-bit acknowledgment indicator                   |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_ack    | 1   | I   | D-bit acknowledgment management indicator        |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | O   | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | O   | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | sna_flag    | 1   | I   | SNA usage indicator                              |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25Call

    (Ref #9.)

    Table 5. X25Call Data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | called_addr_len    | 2   | I/O | Length of called address                  |
    +--------------------+-----+-----+-------------------------------------------+
    | called_addr        | 15  | I/O | Called Address                            |
    +--------------------+-----+-----+-------------------------------------------+
    | calling_addr_len   | 2   | I/O | Length of Calling Address                 |
    +--------------------+-----+-----+-------------------------------------------+
    | calling_addr       | 15  | I/O | Calling Address                           |
    +--------------------+-----+-----+-------------------------------------------+
    | facs_len           | 2   | I/O | Length of Facilities field                |
    +--------------------+-----+-----+-------------------------------------------+
    | facs               | 109 | I/O | Facilities                                |
    +--------------------+-----+-----+-------------------------------------------+
    | cudata_len         | 2   | I/O | Length of Call User Data                  |
    +--------------------+-----+-----+-------------------------------------------+
    | cudata             | 128 | I/O | Call User Data                            |
    +--------------------+-----+-----+-------------------------------------------+
    

    Return and completion codes for X25Call

    See topic  reference #12 for the meanings of these codes.

    X25CallAccept

    Purpose

    A task uses X25CallAccept to accept an incoming call on an SVC.

    X25CallAccept sends a Call Accepted packet to the remote DTE. The task provides the API with information about the call in an optional data buffer.

    Verb request block for X25CallAccept

    Table 6. X25CallAccept verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25CallAccept                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Data buffer pointer                              |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | O   | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | O   | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | sna_flag    | 1   | I   | SNA usage indicator                              |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25CallAccept

    Table 6A. X25CallAccept Data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | called_addr_len    | 2   | I/O | Length of called address                  |
    +--------------------+-----+-----+-------------------------------------------+
    | called_addr        | 15  | I/O | Called Address                            |
    +--------------------+-----+-----+-------------------------------------------+
    | calling_addr_len   | 2   | I/O | Length of Calling Address                 |
    +--------------------+-----+-----+-------------------------------------------+
    | calling_addr       | 15  | I/O | Calling Address                           |
    +--------------------+-----+-----+-------------------------------------------+
    | facs_len           | 2   | I/O | Length of Facilities field                |
    +--------------------+-----+-----+-------------------------------------------+
    | facs               | 109 | I/O | Facilities                                |
    +--------------------+-----+-----+-------------------------------------------+
    | cudata_len         | 2   | I/O | Length of Call User Data                  |
    +--------------------+-----+-----+-------------------------------------------+
    | cudata             | 128 | I/O | Call User Data                            |
    +--------------------+-----+-----+-------------------------------------------+
    

    Data buffer for X25CallAccept

    This data buffer is optional. It has the same layout as that for X25Call as shown in topic  reference #9.

    Return and completion codes for X25CallAccept

    See topic  reference #12 for the meanings of these codes.

    X25CallClear

    Purpose

    X25CallClear clears a virtual circuit by sending a Clear Request packet to the network. The API makes the connection ID for the call invalid, and clears any requested verbs that are using this connection ID.

    The API completes when it has sent a Clear Request packet to the network. It also completes if the Clear Configuration option is requested when the clear confirm is received from the network.

    The connection ID is the only parameter that the task needs to supply to the API. The task may specify other data (including address information) in association with X.25 Facilities processing. This data is included in the optional data buffer.

    For further information about clear processing, see "Clearing a call".

    The contents of the verb request block are shown in The optional data buffer has the same layout as that for X25Call

    Verb request block for X25CallClear

    Table 7. X25CallClear verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25CallClear                                     |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | I/O | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | I/O | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25CallClear

    This data buffer is optional. It has the same layout as that for X25Call reference #9.

    Return and completion codes for X25CallClear

    See topic  reference #12 for the meanings of these codes.

    X25CallReceive

    Purpose

    A task uses X25CallReceive to receive incoming calls on an SVC.

    X25CallReceive accepts the first incoming call that matches one of the routing table entries that the task has specified in a previously issued X25Listen. (See "Routing of incoming calls" for details.)

    The task provides a data buffer for the API to supply it with information about the call. When it receives a call, the task must accept or reject it using X25CallAccept or X25CallClear respectively.

    The connection ID is valid on immediate return from this verb. This cannot be used to send data until the verb completes, but may be used in an X25SemClear to terminate the verb.

    Processing of the X25CallReceive, X25Listen, and X25Deafen verbs is asynchronous. The task can request X25CallReceive before X25Listen, in readiness to receive a call. A task may have multiple X25CallReceive verbs waiting to receive incoming calls.

    The contents of the verb request block are shown in The data buffer has the same layout as that for X25Call

    Verb request block for X25CallReceive

    Table 8. X25CallReceive verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25CallReceive                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | addr_opt    | 1   | I   | Convert address option                           |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | O   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | lcn         | 2   | O   | Logical channel number                           |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_opt    | 1   | O   | D-bit acknowledgment indicator                   |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25CallReceive

    This data buffer has the same layout as that for X25Call as shown in topic  reference #9.

    Return codes and completion codes for X25CallReceive

    See topic  reference #12 for the meanings of these codes.

    X25DataReceive

    Purpose

    A task uses X25DataReceive to receive data on a virtual circuit.

    Received data normally consists of data from a sequence of Data packets. The task must provide a data buffer to hold the received data. The buffer must be at least as large as the packet size negotiated for the virtual circuit, and can be a maximum of 64K -16.

    When confirmation of delivery is in operation, the API gives any required confirmation to the network unless the task has opted to manage this itself. In the latter case, when the API has transferred a buffer of data to the task, it sets the D-bit indicator in the XVRB and the task must request an X25Ack verb before the data transfer can continue.

    X25DataReceive returns any Clear Indication, Reset Request, Reset Indication, or Interrupt packet received while waiting for a delivery confirmation acknowledgment.

    Verb request block for X25DataReceive

    Table 9. X25DataReceive verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25DataReceive                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | data_len    | 2   | O   | Length of data in buffer                         |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | O   | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | O   | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | pkt_type    | 1   | O   | Type of data received indicator                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25DataReceive

    See topic  reference #12 for the meanings of these codes.

    X25DataSend

    Purpose

    Tasks use X25DataSend to send data on an established virtual circuit.

    The task must have stored the data to be sent in a data buffer and set a pointer to this in the XVRB. A task does not have to supply data in packet-sized pieces because the API splits data into Data packets for the task.

    X25DataSend completes when all the data has been passed to the adapter. Unless the task requests confirmation of delivery (by setting the D-bit indicator in the XVRB), the verb waits for acknowledgment from the remote DTE before completing.

    X25DataSend verbs are queued for a virtual circuit. Each waits for all previous X25DataSend verbs on the same virtual circuit to complete.

    Verb request block for X25DataSend

    Table 10. X25DataSend verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25DataSend                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | data_len    | 2   | I   | Length of data in buffer                         |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25DataSend

    See topic  reference #12 for the meanings of these codes.

    X25Deafen

    Purpose

    A task uses X25Deafen to remove routing table entry names from the active list created by previous X25Listen verb requests. All the tasks of one application share the same list of routing table entry names.

    The API checks the names supplied by the task against the list it currently contains and removes matching names from the list. (See "Routing of incoming calls" for more explanation.)

    Verb request block for X25Deafen

    Table 11. X25Deafen verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Deafen                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25Deafen

    (Ref #10.)

    Table 12. X25Deafen data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | num_route_names    | 2   | I   | Number of routing table entry name        |
    |                    |     |     | entries following                         |
    +--------------------+-----+-----+-------------------------------------------+
    |                    |     |     | Routing table name entries                |
    +--------------------+-----+-----+-------------------------------------------+
    | route_name         | 8   | I   | Routing table entry name                  |
    +--------------------+-----+-----+-------------------------------------------+
    | status_flags       | 1   | O   | Status indicator                          |
    +--------------------+-----+-----+-------------------------------------------+
    

    Return and completion codes for X25Deafen

    See topic  reference #12 for the meanings of these codes.

    X25Event

    Purpose

    A task requests X25Event to provide it with information about asynchronous events. It informs the task of the type of event by setting the event indicator. The verb completes when one of the events listed below occurs:

    The X25Event can be called by any task.

    Verb request block for X25Event

    Table 12A. X25Event verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Event                                         |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | event_type  | 1   | O   | Event Indicator                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Event

    See topic  reference #12 for the meanings of these codes.

    X25Init

    Purpose

    An application uses X25Init to initialize the management task.

    The task should ensure that the initialization has completed successfully before using other verbs. (See "Initializing a task" for details.)

    The API only allows one management task to be active at a time, so X25Init can only be requested once.

    Verb request block for X25Init

    Table 12B. X25Init verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Init                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | O   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | resume_addr | 4   | I   | Task Entry Address                               |
    +-------------+-----+-----+--------------------------------------------------+
    | stack_size  | 2   | I   | Stack size                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | last_task   | 1   | I   | Last task indicator                              |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Init

    See topic  reference #12 for the meanings of these codes.

    X25Interrupt

    Purpose

    A task uses X25Interrupt to send an Interrupt packet to a remote DTE on a specified virtual circuit. X25Interrupt completes when it receives an Interrupt Confirmation packet from the remote DTE.

    When the task wants to send Interrupt User Data in the Interrupt packet, it must provide a data buffer containing the required data.

    Only one Interrupt packet is allowed in either direction on a virtual circuit at one time. If you request X25Interrupt while an X25Interrupt is still active on the virtual circuit, the API rejects the request.

    Verb request block for X25Interrupt

    Table 13. X25Interrupt verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Interrupt                                     |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | data_len    | 2   | I   | Length of data in buffer                         |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Interrupt

    See topic  reference #12 for the meanings of these codes.

    X25LinkAuto

    Purpose

    The manager task uses X25LinkAuto to put a specified Transpac VX32 link into Autoconnect mode.

    Autoconnect mode means that when a task sends a Call Request packet, or receives an Incoming Call packet (from a Transpac VX32 DCE only), the link is connected at level 2 (Frame).

    An error (X25_LINK_ALREADY_CONNECT) is returned if the link is already in Connect mode.

    Note: When in Autoconnect mode, the link can be:

    This link is disconnected by the modem when there are no more calls on the link (after a time out).

    PVCs are not applicable to X25LinkAuto. X25LinkAuto puts the link into autoconnect mode. The link is connected by X25Call and disconnected by X25CallClear.

    Verb request block for X25LinkAuto

    Table 14. X25LinkAuto verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25LinkAuto                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25LinkAuto

    See topic  reference #12 for the meanings of these codes.

    X25LinkConnect

    Purpose

    The management task uses X25LinkConnect to put a link into Connect mode, Connecting state. When that is done, X25LinkConnect then attempts to connect the link at level 1 (Physical) and level 2 (Frame).

    As tasks can only listen for incoming calls while the link is in Connect mode, Connected state, the manager task must keep the link in Connect mode, Connected state even when there are no virtual circuits active.

    X25LinkConnect is rejected on a link using a Transpac VX32 DCE.

    Verb request block for X25LinkConnect

    Table 15. X25LinkConnect verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25LinkConnect                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25LinkConnect

    See topic  reference #12 for the meanings of these codes.

    X25LinkDisconnect

    Purpose

    The management task uses X25LinkDisconnect to put a link into Disconnect mode, Disconnecting state. When that is done, X25LinkDisconnect then attempts to disconnect the link at level 1 (Physical) and level 2 (Frame).

    A management task must return the link to Connect or Autoconnect mode before any virtual circuits can use the link.

    Note: This verb should be used with caution because no consideration is given to any virtual circuits that are active on the link; verbs associated with active virtual circuits are terminated with the completion code X25_LINK_CLOSED. The network identifies the disconnection as a link failure, and sends Clear Indication packets (for SVCs) and Reset Indication packets (for PVCs) to the remote DTE.

    In Disconnect mode, autoanswered, incoming calls from a Transpac VX32 DCE are ignored and left to time out.

    Verb request block for X25LinkDisconnect

    Table 16. X25LinkDisconnect verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25LinkDisconnect                                |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25LinkDisconnect

    See topic  reference #12 for the meanings of these codes.

    X25LinkStatus

    Purpose

    Tasks can use X25LinkStatus to find out the status of one or all links. The status can be returned immediately, or it may be delayed until there is a change in a link mode or state. See "Link modes and states" for a description of link modes and states.

    A task can request the status of a specific link by specifying the link name in the XVRB or can request the status of all links by setting the link name to spaces.

    The task supplies a data buffer into which the API deposits link status information. The task must make the buffer large enough to hold data for all the links queried.

    Verb request block for X25LinkStatus

    Table 17. X25LinkStatus verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25LinkStatus                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier.                              |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | stat_opt    | 1   | I   | Status delay option                              |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25LinkStatus

    (Ref #11.)

    Table 18. X25LinkStatus data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | links_conf         | 2   | O   | Total number of configured links          |
    +--------------------+-----+-----+-------------------------------------------+
    | num_link_entries   | 2   | O   | Number of actual entries                  |
    +--------------------+-----+-----+-------------------------------------------+
    |                    |     |     | Link status entries                       |
    +--------------------+-----+-----+-------------------------------------------+
    | link_name          | 8   | O   | Link name                                 |
    +--------------------+-----+-----+-------------------------------------------+
    | comments           | 32  | O   | Link comments                             |
    +--------------------+-----+-----+-------------------------------------------+
    | slot               | 1   | O   | Adapter slot number                       |
    +--------------------+-----+-----+-------------------------------------------+
    | link_mode          | 1   | O   | Link mode                                 |
    +--------------------+-----+-----+-------------------------------------------+
    | link_state         | 1   | O   | Link state                                |
    +--------------------+-----+-----+-------------------------------------------+
    | num_active_pvc     | 2   | O   | Number of allocated PVCs                  |
    +--------------------+-----+-----+-------------------------------------------+
    | num_pvc            | 2   | O   | Number of configured PVCs                 |
    +--------------------+-----+-----+-------------------------------------------+
    | num_active_svc     | 2   | O   | Number of active SVCs                     |
    +--------------------+-----+-----+-------------------------------------------+
    | num_i_svc          | 2   | O   | Number of incoming SVCs                   |
    +--------------------+-----+-----+-------------------------------------------+
    | num_io_svc         | 2   | O   | Number of 2-way SVCs                      |
    +--------------------+-----+-----+-------------------------------------------+
    | num_o_svc          | 2   | O   | Number of outgoing SVCs                   |
    +--------------------+-----+-----+-------------------------------------------+
    

    Return and completion codes for X25LinkStatus

    See topic  reference #12 for the meanings of these codes.

    X25Listen

    Purpose

    A task uses X25Listen to add routing table entry names to the list that the API associates with an application.

    All the tasks in an application share the same list of routing table names. The API checks that the specified names exist in the routing table, if so the API adds the names to a list maintained for the application. Valid names can only be associated with one application at a time.

    See "Routing of incoming calls" for more about routing.

    Verb request block for X25Listen

    Table 19. X25Listen verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Listen                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25Listen

    This is the same as for X25Deafen, see topic reference #10.

    Return and completion codes for X25Listen

    See topic  reference #12 for the meanings of these codes.

    X25Name

    Purpose

    A task uses X25Name to query entries on the X.25 directory.

    The task supplies a data buffer with enquiry fields in the first entry. The enquiry fields are the link name, X.25 address, X.25 extended address, and the nickname.

    The task specifies the fields that are to be searched for. It can use a "wildcard" character (* or ?) in any or all of the search fields.

    The data buffer fields num_match_entries and num_entries are both O only. The fields in the name buffer cannot be left blank, enter an asterisk (* ) for the fields you want returned.

    For example, to find the address nickname to which FRED refers, set the user_name field to FRED.

    Link_name, x25_addr, and x25_ext_address should all be *.

    The API returns, in the data buffer, all entries in the directory that match the specified enquiry fields. The data buffer should be large enough to hold all possible returned matches.

    Verb request block for X25Name

    Table 20. X25Name verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Name                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code.                                 |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25Name

    Table 21. X25Name data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | num_match_entries  | 2   | O   | Number of matching entries                |
    +--------------------+-----+-----+-------------------------------------------+
    | num_entries        | 2   | O   | Number of actual entries                  |
    +--------------------+-----+-----+-------------------------------------------+
    |                    |     |     | Matching table entries                    |
    +--------------------+-----+-----+-------------------------------------------+
    | user_name          | 8   | I/O | Entry nickname                            |
    +--------------------+-----+-----+-------------------------------------------+
    | comments           | 32  | I/O | Comments                                  |
    +--------------------+-----+-----+-------------------------------------------+
    | link_name          | 8   | I/O | Link name                                 |
    +--------------------+-----+-----+-------------------------------------------+
    | x25_addr           | 15  | I/O | X.25 address                              |
    +--------------------+-----+-----+-------------------------------------------+
    | x25_ext_addr       | 32  | I/O | X.25 extended address                     |
    +--------------------+-----+-----+-------------------------------------------+
    

    Return and completion codes for X25Name

    See topic  reference #12 for the meanings of these codes.

    X25PVCAlloc

    Purpose

    A task requests X25PVCAlloc when it wants to allocate a specific PVC to itself.

    The verb is provided so that the API can ensure that only one task uses a specific PVC at any one time. The task identifies the PVC that it wants to allocate to itself by supplying a PVC number in the verb's XVRB. On satisfactory completion, the API returns a connection ID for the virtual circuit.

    PVC numbers are provided during configuration (see the IBM X.25 Co-Processor Support Program: User's Guide).

    Verb request block for X25PVCAlloc

    Table 22. X25PVCAlloc verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25PVCAlloc                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link Name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | pvc_number  | 1   | I   | PVC number                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_ack    | 1   | I   | D-bit acknowledgment management indicator        |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25PVCAlloc

    See topic  reference #12 for the meanings of these codes.

    X25PVCFree

    Purpose

    A task uses X25PVCFree to release a PVC that it has previously allocated to itself.

    The task identifies the PVC by supplying the connection ID supplied by the API when the task requested X25PVCAlloc.

    Verb request block for X25PVCFree

    Table 23. X25PVCFree verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25PVCFree                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | vers        | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25PVCFree

    See topic  reference #12 for the meanings of these codes.

    X25Reset

    Purpose

    A task uses X25Reset to synchronize a virtual circuit. It does this by sending a Reset Request packet to the remote DTE.

    See "Resetting virtual circuits" for more on details of the use of this verb.

    Verb request block for X25Reset

    Table 24. X25Reset verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Reset                                         |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | I   | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | I   | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Reset

    See topic  reference #12 for the meanings of these codes.

    X25ResetConfirm

    Purpose

    A task uses X25ResetConfirm when it receives a Reset Request from a remote DTE to confirm that it has been received.

    See "Resetting virtual circuits" for more on details of the use of this verb.

    Verb request block for X25ResetConfirm

    Table 25. X25ResetConfirm verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25ResetConfirm                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25ResetConfirm

    See topic  reference #12 for the meanings of these codes.

    X25SemClear

    Purpose

    A task can use X25SemClear to clear outstanding verbs.

    It is provided to clear verbs that may have to wait a long time for an asynchronous event to occur (for example, X25CallReceive or X25Event).

    The task can specify that the API should clear only verbs using a specific connection ID or it can request that the API should clear all outstanding verbs.

    Note: If an X25Call verb is terminated after it has sent a Call Request packet and before a Call Connected or Clear Indication packet has been received, the API sends a Clear Request packet.

    Use this verb with caution to preserve data integrity.

    Verb request block for X25SemClear

    Table 26. X25SemClear verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25SemClear                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25SemClear

    See topic  reference #12 for the meanings of these codes.

    X25SemWait

    Purpose

    A task uses X25SemWait to suspend itself until an outstanding verb completes or a time out expires.

    The use of this verb is described in "Calling the API".

    Verb request block for X25SemWait

    Table 27. X25SemWait verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25SemWait                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | time_out    | 2   | I   | Time out                                         |
    +-------------+-----+-----+--------------------------------------------------+
    | xvrb_ptr    | 4   | O   | Pointer to XVRB that has just completed          |
    +-------------+-----+-----+--------------------------------------------------+
    | complete	    | 2   | O   | Original semaphore                               |
    | 5;sem       |     |     |                                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25SemWait

    See topic  reference #12 for the meanings of these codes.

    X25Status

    Purpose

    The management task uses X25Status to request the status of one, or all links. The status can be returned immediately, or the task can specify that it be delayed until there is a change in a link mode or state.

    See "Link modes and states" for a description of link modes and states.

    The task can request the status of a specified link by supplying a link name in the XVRB or can request the status of all links by setting the link name to spaces.

    The task supplies a data buffer into which the API deposits link status information. This should be large enough to hold data for all the links queried.

    Verb request block for X25Status

    Table 28. X25Status verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Status                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | stat_opt    | 1   | I   | Status delay option                              |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25Status

    This data buffer is the same as for X25LinkStatus, see topic reference #11.

    Return and completion codes for X25Status

    See topic  reference #12 for the meanings of these codes.

    X25Term

    Purpose

    The management task can use X25Term to terminate the IBM X.25 Co-Processor Support Program.

    The task can specify if termination is immediate or delayed. All X.25 tasks with an outstanding X25Event verb are notified of a termination. (Termination is described in detail in "Terminating tasks".)

    Verb request block for X25Term

    Table 29. X25Term verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25Term                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | term_opt    | 1   | I   | Termination option                               |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X25Term

    See topic  reference #12 for the meanings of these codes.

    X25Trace

    Purpose

    This verb can be issued only by a management task. It is used to trace specified frames and/or packets to and/or from the network, and/or to capture statistics of the number of packets and frames sent to and received from the network.

    The task can request that the traced data be stored in the file .TRC. The trace file is cleared when the first trace (after initialization) starts on a link. Any following traces on the link are appended to the file until the subsystem is reinitialized.

    The trace profile can be set up to record no information. Here, statistics are only placed in the file, which stays active until the trace is stopped.

    An X25Trace verb that starts the collection of trace information stays active until tracing is stopped by another X25Trace verb that specifies the same trace name, but gives a trace destination of X25_TRACE_OFF.

    Statistics for a link can be collected while a trace is in progress. The trace name and the trace destination must be the same as those given in the verb that started the trace collection.

    Verb request block for X25Trace

    Table 30. X25Trace verb request block

    +==============+=====+=====+=================================================+
    | Name         | Lth | I/O | Description                                     |
    +==============+=====+=====+=================================================+
    | verb_id      | 1   | I   | X25Trace                                        |
    +--------------+-----+-----+-------------------------------------------------+
    | ver          | 1   | I   | Version identifier                              |
    +--------------+-----+-----+-------------------------------------------------+
    | task_id      | 2   | I   | Task ID                                         |
    +--------------+-----+-----+-------------------------------------------------+
    | sem          | 2   | I/O | Semaphore                                       |
    +--------------+-----+-----+-------------------------------------------------+
    | com_code     | 2   | O   | Completion code                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | trace_opt    | 1   | I   | Trace destination option                        |
    +--------------+-----+-----+-------------------------------------------------+
    | trace_name   | 8   | I   | Trace name                                      |
    +--------------+-----+-----+-------------------------------------------------+
    | Reserved     | 4   |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | Reserved     | 2   |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | Reserved     | 4   |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | stats_opt    | 1   | I   | Statistics option                               |
    +--------------+-----+-----+-------------------------------------------------+
    

    Return and completion codes for X25Trace

    See topic  reference #12 for the meanings of these codes.

    X25VCStatus

    Purpose

    A task uses X25VCStatus to request the status and other details of a specified virtual circuit.

    The status information is returned in the verb's data buffer, which the task supplies when it requests the verb.

    Verb request block for X25VCStatus

    Table 31. X25VCStatus verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X25VCStatus                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | O   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection identifier                            |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_opt    | 1   | O   | D-bit acknowledgment indicator                   |
    +-------------+-----+-----+--------------------------------------------------+
    | dbit_ack    | 1   | O   | D-bit acknowledgment management indicator        |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Data buffer for X25VCStatus

    Table 32. X25VCStatus data buffer

    +====================+=====+=====+===========================================+
    | Name               | Lth | I/O | Description                               |
    +====================+=====+=====+===========================================+
    | vc_type            | 1   | O   | Type of virtual circuit                   |
    +--------------------+-----+-----+-------------------------------------------+
    | tx_pkt_size        | 2   | O   | Transmit packet size                      |
    +--------------------+-----+-----+-------------------------------------------+
    | rx_pkt_size        | 2   | O   | Receive packet size                       |
    +--------------------+-----+-----+-------------------------------------------+
    | tx_pkt_win_size    | 1   | O   | Transmit packet window size               |
    +--------------------+-----+-----+-------------------------------------------+
    | rx_pkt_win_size    | 1   | O   | Receive packet window size                |
    +--------------------+-----+-----+-------------------------------------------+
    | tx_tp_class        | 2   | O   | Transmit throughput class                 |
    +--------------------+-----+-----+-------------------------------------------+
    | rx_tp_class        | 2   | O   | Receive throughput class                  |
    +--------------------+-----+-----+-------------------------------------------+
    

    Return and completion codes for X25VCStatus

    See topic  reference #12 for the meanings of these codes.


    Summary of API return and completion codes

    Return codes

    X25_ABEND

    X.25 processing has ended abnormally.

    X25_DOS_ERROR

    The API detected a DOS error. The DOS error code is contained in the completion code field of the XVRB.

    X25_ERROR

    The API detected an X.25 error. The X.25 error code is contained in the completion field of the XVRB.

    X25_NO_SUBSYSTEM

    The IBM X.25 Co-Processor Support Program has not been loaded.

    X25_NO_VERB_COMPLETE

    An X25SemWait request was made with a time-out value of zero and no verbs had just completed.

    X25_OK

    The verb has been accepted and is being processed.

    X25_SYS_ERROR

    The API detected an error within itself. The probable cause is a resource allocation error. The system error code is contained in the completion code field of the XVRB; it has also been logged.

    X25_TIME_OUT

    An X25SemWait request has been made with a time out in the range 1 through 65534 (in tenths of a second) and no verb has completed in the specified time.

    Completion codes

    (Ref #12.)

    X25_ABEND

    X.25 processing has ended abnormally.

    X25_ACTIVE

    The X.25 subsystem has already been initialized.

    X25_ADAPTER_ACCESS_ERROR

    The adapter for this link is not installed, or cannot be accessed.

    X25_ADAPTER_ACK_SELECTED

    The adapter is managing D-bit acknowledgment for this virtual circuit.

    X25_ADAPTER_ERROR

    An error has occurred on the adapter. The specific error code has been logged.

    X25_APP_ACTIVE

    The task has already initialized X.25 communications.

    X25_APP_INACTIVE

    The task is not initialized for X.25 communications.

    X25_APP_LIMIT_EXCEEDED

    The maximum number of tasks that the X.25 subsystem can process concurrently is already active. No other task can use the X.25 subsystem until a task has terminated.

    X25_APP_REQ_CLEAR_SEM

    The verb was terminated by an X25SemClear verb.

    X25_APP_TERMINATING

    The task has requested termination of X.25 processing.

    X25_BUFFER_TOO_SHORT

    The specified length of the buffer was insufficient to hold all the data to be returned.

    X25_CALL_ALREADY_ACCEPTED

    The call with this connection ID is already accepted.

    X25_CALL_CLEARED

    The call has been cleared. No more data can be exchanged.

    X25_CALL_CLEARING

    The call is in the process of being cleared. No more data can be exchanged.

    X25_CALLED_ADDRESS_LEN_ERROR

    The length must be less than or equal to 15 bytes.

    X25_CALLED_ADDRESS_NAME_ERROR

    The name specified was not found in the directory.

    X25_CALLED_ADDRESS_VALUE_ERROR

    An invalid character was specified in the called address. Addresses must be specified in Binary Coded Decimal (BCD).

    X25_CALLING_ADDRESS_LEN_ERROR

    Length must be less than or equal to 15 bytes.

    X25_CALLING_ADDRESS_NAME_ERROR

    The name specified was not found in the directory.

    X25_CALLING_ADDRESS_VALUE_ERROR

    An invalid character was specified in the calling address. Addresses must be specified in Binary Coded Decimal (BCD).

    X25_CALL_NOT_YET_ACCEPTED

    The call associated with this connection ID has not been accepted. This verb cannot be processed until the call is accepted.

    X25_CALL_NOT_YET_RECEIVED

    An attempt was made to access a connection ID that is still waiting for an incoming call.

    X25_CLEAR_COLLISION

    A Clear Indication packet arrived while a Clear Request packet was being processed.

    X25_CONNECTION_OUTGOING

    An X25CallAccept verb was issued with a connection ID set up by an X25Call verb.

    X25_DBIT_INDICATOR_ERROR

    The value of the parameter that specified D-bit usage was not valid.

    X25_DBIT_NOT_SELECTED

    The X25Ack verb was issued on a virtual circuit that was not set up to use D-Bit acknowledgment.

    X25_DISCARD_APP_REQ_CLEAR_SEM

    Some data was discarded when the verb was terminated by an X25SemClear verb.

    X25_DOS_ERROR

    Unexpected DOS error stopped X.25 processing. See error log.

    X25_EVENT_ALREADY_REQUESTED

    There is already an X25Event request outstanding for this task.

    X25_FACILITIES_ERROR

    The X.25 subsystem detected error in Facilities field coding.

    X25_FACILITIES_LEN_ERROR

    Length must be less than or equal to 109.

    X25_INACTIVE

    The X.25 subsystem is not initialized.

    X25_INTERRUPT_DATA_LEN_ERROR

    There must be at least one byte of interrupt data. (There may be up to 16 bytes of data using CCITT 1984.)

    X25_INTERRUPT_IN_PROGRESS

    An Interrupt packet has been sent on this virtual circuit and not yet been confirmed.

    X25_INVALID_BUFFER_LEN

    The specified buffer length is too small to contain the minimum amount of data that is returned.

    X25_INVALID_CALL_DATA

    The call buffer that has been specified contains invalid information.

    X25_INVALID_CAUSE_CODE

    The cause code must be 0 or, if CCITT 1984, the most significant bit must be set to 1.

    X25_INVALID_CONNECTION_ID

    The specified connection identifier is not associated with a virtual circuit.

    X25_INVALID_CONNECTION_MODE

    A request was made that is not valid for the type of virtual circuit associated with the specified connection identifier. For example, X25Call on a PVC.

    X25_INVALID_CONVERT_ADDR_OPT

    An invalid parameter value was used to specify the conversion of an incoming call to a nickname.

    X25_INVALID_LINK_NAME

    The specified link name is invalid.

    X25_INVALID_LINK_TYPE

    Connect mode is invalid for the specified link (for example, Transpac VX32 DCE).

    X25_INVALID_PARAMETER

    An invalid task initialization parameter has been specified.

    X25_INVALID_PVC_NUMBER

    The PVC number is not configured for the specified link.

    X25_INVALID_STATE

    An invalid processing state has been detected.

    X25_INVALID_STATUS_OPTION

    The option for immediate or delayed termination specified for the X25LinkStatus or the X25Status verb was invalid.

    X25_INVALID_TASK_ID

    The task identifier is not valid for a user task.

    X25_INVALID_TERM_OPTION

    The option for immediate or delayed termination specified for the X25Term verb was invalid.

    X25_INVALID_TRACE_DEST_OPTION

    The parameter value used to specify the destination of the trace data is not valid.

    X25_INVALID_TRACE_NAME

    Specified trace name not found.

    X25_INVALID_TRACE_STATS_OPTION

    The parameter value used to specify the required statistics information is invalid.

    X25_INVALID_VERB_ID

    The specified verb identifier is not valid. This can mean that the verb is a management verb and cannot be requested by a nonmanager task.

    X25_INVALID_VERSION_ID

    The version identifier did not match that expected by the API.

    X25_LINK_ALREADY_AUTOCONNECT

    Specified link is already in Autoconnect mode.

    X25_LINK_ALREADY_CONNECT

    Specified link is already in Connect mode.

    X25_LINK_ALREADY_DISCONNECT

    Specified link is already in Disconnect mode.

    X25_LINK_CLOSED

    Specified link is in Disconnect mode; it must be put in Connect mode or Autoconnect mode before it can be used.

    X25_LINK_ERROR_LEVEL_1

    There is an error on the link at the physical level.

    X25_LINK_ERROR_LEVEL_2

    There is an error on the link at the frame level.

    X25_LINK_ERROR_LEVEL_3

    There is an error on the link at the packet level.

    X25_MBIT_AND_INCOMPLETE_ERROR

    M-bit was specified but the data length was not an integral number of packets.

    X25_MBIT_INDICATOR_ERROR

    The value of the parameter specifying M-bit usage was not valid.

    X25_NO_CONNECTION_ALLOCATED

    An attempt was made to access a connection ID that had not yet been allocated by the API.

    X25_NO_CONNECTION_AVAILABLE

    The system limit of 250 Connection IDs has been reached. No further virtual circuits can be established until a call is cleared or a PVC freed.

    X25_NO_DATA

    A data length of zero was specified where at least one byte of data is needed. For example, X25DataSend.

    X25_NO_DATA_TO_ACK

    No D-bit acknowledgment is outstanding on this virtual circuit.

    X25_NO_DIRECTORY_MATCH

    No directory entries match the supplied fields.

    X25_NO_LINK_NAME

    There is more than one link in the system and no link name was specified.

    X25_NO_MEMORY

    The memory pool became exhausted while processing the verb.

    X25_NO_RESET_TO_CONFIRM

    An X25ResetConfirm verb was issued for a virtual circuit that had not received a Reset Indicator packet.

    X25_NO_SEMAPHORES_CLEARED

    No semaphores were cleared, because no active verbs were found that matched the request.

    X25_NO_VC_AVAILABLE

    There is no virtual circuit available on the required link. No further call can be made until an existing call is cleared.

    X25_OK

    The verb completed successfully.

    X25_PVC_FREED

    The PVC has been freed, no more data may be exchanged.

    X25_PVC_IN_USE

    The PVC is already allocated.

    X25_QBIT_INDICATOR_ERROR

    The value of the parameter specifying Q-bit usage was not valid.

    X25_RESET_COLLISION

    A Reset Indication packet arrived while this Reset Request packet was being processed.

    X25_SEM_CLEARING

    The API is processing an X25SemClear verb for this virtual circuit. No requests for this virtual circuit can be issued until the X25SemClear verb completes.

    X25_SNA_INDICATOR_ERROR

    The value of the parameter to specify an SNA or native X.25 connection was invalid.

    X25_TERM_ERROR

    One or more errors occurred during termination. Specific error(s) (freeing virtual circuits, disconnecting links, and so on) have been logged.

    X25_TERMINATING_DELAYED

    The X.25 subsystem is already in delayed termination.

    X25_TERMINATING_IMMEDIATE

    The X.25 subsystem is already in immediate termination.

    X25_TRACE_ACTIVE_ON_LINK

    A trace is already running for the specified link.

    X25_USER_DATA_LEN_ERROR

    Length must be less than or equal to 16 bytes (or less than or equal to 128 bytes for Fast Select).

    X25_VC_FREED

    One or more active PVCs or SVCs were freed or cleared to service this verb.

    X25_VC_FREE_ERROR

    One or more errors were detected while freeing PVCs or clearing SVCs.

    X25_VC_RESET

    The virtual circuit has received a remote Reset Indication packet.

    X25_VC_RESETTING

    The virtual circuit is being reset, no further data exchange is possible until the reset is complete.


    X.3, X.28, and X.29 support


    Introducing X.3, X.28, and X.29 support

    The International Telegraph and Telephone Consultative Committee (CCITT) has produced three recommendations to govern the connection of character-mode (as opposed to packet-mode) terminals to an X.25 PSDN. These terminals are supported through a packet assembler/disassembler (PAD). CCITT Recommendation X.3 and CCITT Recommendation X.28 govern the way in which a terminal interacts with a PAD. CCITT Recommendation X.29 governs the control of a PAD, over an X.25 PSDN, by a host computer. The PAD that is described by these three recommendations is also known as Triple-X PAD (X.3, X.28, X.29).

    The IBM X.25 Co-Processor Support Program provides Triple-X PAD support in two modes:

    1. X.28 mode. In this mode the IBM X.25 Co-Processor Support Program emulates a PAD connected to the network through the X.25 link. Your application can control the operation of the PAD by sending X.3/X.28 control text through the X28DataSend verb.

    2. X.29 mode. In this mode the IBM X.25 Co-Processor Support Program acts as a host system. It transfers data to and from a remote PAD, and sends control information to the remote PAD. Verbs are provided to allow you to easily send control packets to the PAD.
    You load the support for X.28 and X.29 modes only if you need it. Parameters in the X.25 parameter file control this support (see IBM X.25 Co-Processor Support Program: User's Guide). X.29 mode support requires that all the X.25 API is made available but X.28 mode support can operate independently of much of the X.25 API.

    Triple-X PAD operation to a character-mode terminal, using PAD supplied by the PTT and to the IBM X.25 Co-Processor Support Program operating in X.28 mode, is shown in Figure 9.

    Figure 9. Triple-X PAD modes.

    |          X.25 and X.29 Commands                             X.28
    +-------------------------------------------------| <--------------------
    |
                                                                   +-----------+
                                -----------    X.25   +-----+ V.24 | Character |
                               /           \----------+ PAD +------+ Mode      |
                       -------/             \         +-----+      | Terminal  |
     +--------+      /                      -----                  +-----------+
     |        | X.25 /           PSDN            /
     |  HOST  +------\                           \
     |        |       \              -------------\ + = = = = = =+   +-------------
     +--------+        \            /               = +-----+    |   |
                        \          /----------------=-+ PAD |    | A |
                         \--------/       X.25      = +-----+    | P | User
                                                    =            | I | Application
                                                    = X.25       |   |
                                                    = Subsystem  |   |
                                                    + = = = = = =+   +-------------
    
    Note: The X.28 and the X.29 mode support is based on the IBM X.25 Co-Processor Support Program architecture described in "Using the X.25 application programming interfaces". Refer to that topic for more details.

    Description of the X.28 API

    General

    X.28 Verbs

    The X.28 API provides the verbs you need to let an application operate in character-mode, as opposed to packet-mode.

    You must still initialize the application task as either a manager or nonmanager task. In the former case, the task has to control link connection. The task may also want to obtain system and link status information, setup and clear routing information, and obtain directory information.

    Verbs that are common to X.25 and X.28

    The X.25 verbs that do these functions are also available to the X.28 API. For uniformity, X.28 names are defined for these verbs and control blocks. They are, however, identical to their X.25 counterparts (only the prefix is different). The verbs are summarized here and full descriptions are contained in "X.25 application programming verbs".

    X28AppInit
    Initializes a nonmanagement task.

    X28AppTerm
    Terminates a nonmanagement task.

    X28Deafen
    Disassociates a Routing table entry name from a task.

    X28Event
    Notifies a task of API termination or reinitialization.

    X28Init
    Initializes a management task.

    X28LinkAuto
    Places a link in Autoconnect mode.

    X28LinkConnect
    Connects a link.

    X28LinkDisconnect
    Disconnects a link.

    X28LinkStatus
    Obtains the status of all or specified links.

    X28Listen
    Associates a Routing table entry name with a task.

    X28Name
    Queries an entry in the nicknames directory.

    X28SemClear
    Terminates all outstanding verbs on a virtual circuit.

    X28SemWait
    Suspends a task until any verb completes.

    X28Status
    Obtains the status of all or specified links.

    X28Term
    Terminates a management task.

    X28Trace
    Traces specified frames and packets to and from the network.
    Verbs that are unique to X.28

    Some verbs have no X.25 counterparts - they are unique to X.28. They are summarized here and descriptions of the verbs begin in topic reference #15. (Ref #13.)

    X28CallReceive
    Receive a call via a PAD.

    X28Close
    Close a connection to a PAD.

    X28DataSend
    Send data to a PAD.

    X28DataReceive
    Receive data from a PAD.

    X28Open
    Open a connection to a PAD.

    X28SendBreak
    Send a "break" to a PAD.

    PAD states

    The PAD may be in one of two states:

    1. Command state. In this state any data that a task sends to the PAD, using the X28DataSend verb, is treated as a PAD command.

    2. Data transfer state. In this state any data that a task sends to the PAD, using the X28DataSend verb, is treated as data for transmission.
    The PAD is in command state when no virtual call is established. It enters data-transfer state after a call is set up and enters command state when it receives the PAD escape character (DLE - 10h) within a data stream. The PAD automatically returns to the data-transfer state on completion of the command.

    Communicating with the API PAD

    The way in which communication is established with the API PAD depends on whether the application task wants to originate or receive calls.

    Making a call through the API PAD

    When an application wants to make a call, it must first open a connection to the API PAD. The X28Open verb is used for this, the output from which is a connection ID. On completion of X28Open, the application task is in the command state and uses the X28DataSend verb to communicate with the API PAD.

    When the API PAD has been opened, a call is established by passing the appropriate PAD command string in an X28DataSend verb. The API PAD tries to establish the connection. A text message, generated by the API PAD and received through an X28DataReceive verb, shows whether the call was successful.

    After the call is cleared, the connection with the API PAD is still available. You must use an X28Close verb to break the connection.

    Receiving a call through the API PAD

    Your application does not open an initial connection when it wants to receive a call through the API PAD; it issues the X28Listen and the X28CallReceive verbs instead. The X28CallReceive verb completes when an incoming call is received that matches the routing details supplied with the X28Listen verb. The API PAD automatically accepts the call; there is, therefore, no X.28 equivalent to the X25CallAccept verb.

    The connection with the PAD is not broken when the call is cleared. You must use an X28Close verb to break the connection.

    Sending and receiving data through the API PAD

    Application tasks send and receive characters to and from the API PAD. Depending on the PAD state, these may be messages to or from remote systems, commands to the API PAD, or responses or status indications from the API PAD. The way in which the API PAD responds depends on the setting of various PAD profile parameters. For example:

    Notes:
    1. A full list of parameters is in topic reference #16.

    2. Some of the parameters (for example, line speed between terminal and the PAD) have no meaning for the IBM X.25 Co-Processor Support Program PAD.
    Characters are sent to the API PAD by issuing the X28DataSend verb. Any characters that are sent to the API PAD while it is transferring data are assembled into packets. When a character that forces the packet to be sent is received, usually a line control character or one that fills the packet, the data is sent over the X.25 link.

    The X28DataReceive verb passes characters from Data packets, received by the API PAD, to the application task. Responses from the API PAD to PAD commands, and status message from the PAD are also returned through the X28DataReceive verb. Status messages might indicate that the call has been cleared or an interrupt has been received. See also the note in topic reference #18.

    (Ref #14.) The X28DataReceive verb completes as soon as any data is available from the API PAD. This does not have to be a single, complete line of data; it can be a single character, or characters from multiple packets. The maximum length of returned data is 128 bytes.


    Descriptions of the X.28 API verbs

    (Ref #15.)

    This section provides descriptions of each of the X.28 API verbs. Each description is accompanied by a table to show the contents of the XVRB and, where appropriate, a table to show the contents of the data buffer.

    See "Contents of the verb request block" and "Data buffers" for details of the fields in the tables.

    X28CallReceive

    Purpose

    A task uses X28CallReceive to receive any incoming call that matches the active routing information for the application. The call must have its Call User Data (CUD) set to indicate that it is a call to a PAD. (A call is automatically accepted by the PAD so a task does not need to use a special verb to show that the call was accepted.)

    The incoming call information is returned in the Call Data Buffer. A text message, describing the call is also generated by the API PAD and is received by way of an X28DataReceive verb. The connection ID is returned in the XVRB.

    Verb request block for X28CallReceive

    Table 33. X28CallReceive verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28CallReceive                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | addr_opt    | 1   | I   | Convert address option                           |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | O   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | lcn         | 2   | O   | Logical channel number                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Call buffer pointer                              |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Call buffer length                               |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28CallReceive

    These codes have the same meanings as for X.25. See topic  reference #12.

    X28Close

    Purpose

    A task uses X28Close to terminate X.28 communication for a connection ID. The connection may have been established by a successful X28Open or an X28CallReceive.

    Any verbs using this connection ID are terminated, if they have not completed.

    Verb request block for X28Close

    Table 34. X28Close verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28Close                                         |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28Close

    These codes have the same meanings as for X.25. See topic  reference #12.

    X28DataReceive

    Purpose

    A task uses X28DataReceive to receive character data from a specific connection ID.

    The data returned to the task from this verb may be data received from a virtual circuit or may be a message generated by the PAD. PAD messages can be either the response to a PAD command sent using a previous X28DataSend verb or an indication of an event on the virtual circuit. (For example, indication of an Interrupt or a Reset Indication packet.)

    The maximum number of characters returned is 128. The parity bit is cleared on all returned characters.

    Verb request block for X28DataReceive

    Table 35. X28DataReceive verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28DataReceive                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Size of data buffer                              |
    +-------------+-----+-----+--------------------------------------------------+
    | data_len    | 2   | O   | Size of data in buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28DataReceive

    These codes have the same meanings as for X.25. See topic  reference #12.

    X28DataSend

    Purpose

    A task uses X28DataSend to send data to an API PAD or on an opened virtual circuit. The data sent may be either forwarded by the API PAD (after being assembled into packets) or may be processed as commands by the API PAD.

    The API performs requests to send data on a connection ID in the sequence it receives them. Subsequent sends for the same connection ID wait until all previous sends are complete.

    The API PAD clears the parity bit on any characters that it transmits the over the network. The parity bit is ignored on any characters that are sent to the API PAD as PAD commands.

    The X28DataSend verb completes as soon as the character data is passed to the API PAD. It does not wait until the data is sent on the virtual circuit. The maximum allowable length of data is 128 characters.

    Verb request block for X28DataSend

    Table 36. X28DataSend verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28DataSend                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Size of data buffer                              |
    +-------------+-----+-----+--------------------------------------------------+
    | data_len    | 2   | I   | Size of data in buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28DataSend

    These codes have the same meanings as for X.25. See topic  reference #12.

    X28Open

    Purpose

    A task uses X28Open to create a connection to an API PAD. When this verb completes, the application can send characters to the connection ID (even though a virtual circuit does not yet exist). These characters can be control commands to the API PAD; for example, to request the setup of a virtual circuit.

    Note: The X28CallReceive verb should be used to set up a PAD to receive an incoming call. X28Open is not required in this case.

    Verb request block for X28Open

    Table 37. X28Open verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28Open                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task indicator                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 4   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28Open

    These codes have the same meanings as for X.25. See topic  reference #12.

    X28SendBreak

    Purpose

    A task uses X28SendBreak to send a "break" to a PAD on an opened connection.

    The action taken by the PAD on receipt of a "break" depends on the current value of the PAD parameters.

    Verb request block for X28SendBreak

    Table 38. X28SendBreak verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X28SendBreak                                     |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | I   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X28SendBreak

    These codes have the same meanings as for X.25. See topic  reference #12.


    X.28 String commands

    Status

    Returns the current line status:

    Format: STAT

    Return values

    Clear

    Requests clearing of the Virtual Circuit.

    Format: CLR

    Read

    Returns the value of one or more of the PAD parameters.

    Format: PAR?param,param,...param

    Where param,param,...param is an optional list of the PAD parameters to be returned. If this list is omitted, the values of all the PAD parameters are returned.

    The parameter values are returned in a text message in the form:

    PAR.par:val,:val,...par:val
    
    If any of the parameter numbers are invalid, the value is set as "INV", for example:
    PAR 2:1,3:2,45:INV,6:1
    

    Set


    Sets the value of one or more of the PAD parameters.

    Format:

    SET par:val,par:val,...par:val
    Where par:val,par:val,...par:val is a list of the PAD parameters to be updated together with their new values.

    Read and set


    This is identical to SET followed by a READ command

    Format: SET? par:val,par:val,...par:val

    Profile selection

    Selects a profile (predefined set of PAD parameter settings).

    Format: PROF num

    Where num is the number of the selected profile.

    Reset

    Requests a reset of the Virtual Call.

    Format: RESET

    Interrupt

    Requests the transmission of an interrupt packet on the Virtual Call.

    Format: INT

    Select

    Requests the establishment of a Virtual Call.

    Format: CALL

    G<nn>,R,T<rpoa>,C,N<nui>-<address><cud>

    Where:


    PAD parameters

    (Ref #16.)

    The following table shows the PAD parameters that are defined in X.25.

    Table 39. PAD parameters

    +===========+================================+================================+
    | Parameter | Meaning                        | Value                          |
    | Number    |                                |                                |
    +===========+================================+================================+
    | 1         | Escape to PAD command state on | 0=Disabled                     |
    |           | receipt of DLE                 | 1=Escape possible              |
    +-----------+--------------------------------+--------------------------------+
    | 2         | Character echo                 | 0=Do not echo typed characters |
    |           |                                | to display                     |
    |           |                                | 1=Echo characters typed to     |
    |           |                                | display                        |
    +-----------+--------------------------------+--------------------------------+
    | 3         | Data forwarding characters     | 00=No data forwarding          |
    |           |                                | characters. Data is forwarded  |
    |           |                                | only after the 128th character |
    |           |                                | of input.                      |
    |           |                                | 01=A-Z, a-z, 0-9               |
    |           |                                | 02=CR                          |
    |           |                                | 04=ESC, BEL, ENQ, ACK          |
    |           |                                | 08=DEL, CAN, DC2               |
    |           |                                | 16=ETX, EOT                    |
    |           |                                | 32=HT, LF, VT, FF              |
    |           |                                | Note: Other values can be      |
    |           |                                | achieved by combining the      |
    |           |                                | above values.                  |
    +-----------+--------------------------------+--------------------------------+
    | 4         | Data forwarding on time out    | 0=Disabled                     |
    |           |                                | 1-255=Time out period in       |
    |           |                                | 0.05-second units              |
    +-----------+--------------------------------+--------------------------------+
    | 5         | Flow control of terminal by    | 0=Disable                      |
    |           | PAD                            | 1=Use X-ON and X-OFF           |
    +-----------+--------------------------------+--------------------------------+
    | 6         | Suppression of service signals | 0=Suppress messages            |
    |           | from the PAD                   | 1=Relay messages to terminal   |
    +-----------+--------------------------------+--------------------------------+
    | 7         | Action on receipt of a Break   | 0=No action on receipt of      |
    |           | from the terminal              | Break                          |
    |           |                                | 1=PAD transmits X.25 Interrupt |
    |           |                                | Packet to Host                 |
    |           |                                | 2=PAD transmits X.25 Reset     |
    |           |                                | Packet to Host                 |
    |           |                                | 5=PAD transmits X.25 Interrupt |
    |           |                                | Packet and an indication of    |
    |           |                                | Break                          |
    |           |                                | 8=The PAD leaves the Data      |
    |           |                                | Transfer State and waits for a |
    |           |                                | command                        |
    |           |                                | 21=As for 5 but parameter 5 is |
    |           |                                | set to 1                       |
    +-----------+--------------------------------+--------------------------------+
    | 8         | Data delivery to terminal      | 0=Normal delivery to terminal  |
    |           |                                | 1=Discard data destined for    |
    |           |                                | terminal                       |
    |           |                                | Note: Receipt of a Reset       |
    |           |                                | Indication or confirmation     |
    |           |                                | sets this parameter to 0.      |
    +-----------+--------------------------------+--------------------------------+
    | 9         | Padding after Carriage Return  | 0=No padding characters after  |
    |           |                                | CR                             |
    |           |                                | 1-7=1 Number of padding        |
    |           |                                | characters after CR            |
    +-----------+--------------------------------+--------------------------------+
    | 10        | Line folding                   | 0=No line folding              |
    |           |                                | 1-255=Value at which to fold   |
    |           |                                | terminal line                  |
    +-----------+--------------------------------+--------------------------------+
    | 11        | Terminal speed                 | Not applicable                 |
    +-----------+--------------------------------+--------------------------------+
    | 12        | Flow control of the PAD by the | 0=No use of X-ON and X-OFF     |
    |           | terminal                       | 1=Use X-ON and X-OFF           |
    +-----------+--------------------------------+--------------------------------+
    | 13        | Line feed insertion after      | 0=No LF insertion              |
    |           | carriage return                | 1=LF inserted after every CR   |
    |           |                                | transmitted                    |
    |           |                                | 4=LF is echoed after every     |
    |           |                                | local CR is echoed             |
    |           |                                | 5=Combined effect of 1 and 4   |
    |           |                                | 6=LF is inserted after every   |
    |           |                                | CR echoed to the terminal and  |
    |           |                                | sent to the host               |
    |           |                                | 7=Combined effect of 1 and 6   |
    +-----------+--------------------------------+--------------------------------+
    | 14        | Padding characters inserted    | This is the same parameter as  |
    |           | after line feed                | 9, except that the effect is   |
    |           |                                | to cause the PAD to send       |
    |           |                                | padding characters whenever an |
    |           |                                | LF is sent to the terminal     |
    +-----------+--------------------------------+--------------------------------+
    | 15        | Editing                        | 0=No editing                   |
    |           |                                | 1=Editing allowed using        |
    |           |                                | parameters 16, 17, and 18      |
    +-----------+--------------------------------+--------------------------------+
    | 16        | Character delete character     | 0 through 127                  |
    +-----------+--------------------------------+--------------------------------+
    | 17        | Buffer delete character        | 0 through 127                  |
    +-----------+--------------------------------+--------------------------------+
    | 18        | Buffer display character       | 0 through 127                  |
    +-----------+--------------------------------+--------------------------------+
    | 19        | Editing PAD service signals    | 0=No editing                   |
    |           |                                | 1=Editing allowed using        |
    |           |                                | parameters 16, 17, and 18      |
    +-----------+--------------------------------+--------------------------------+
    | 20        | Echo mask                      | 0=Echo all characters (Other   |
    |           |                                | values are country dependent)  |
    |           |                                | Note: This parameter does not  |
    |           |                                | apply if parameter 2 is set to |
    |           |                                | 0                              |
    +-----------+--------------------------------+--------------------------------+
    | 21        | Parity treatment               | 0=No parity detection or       |
    |           |                                | generation (Other values are   |
    |           |                                | country dependent)             |
    +-----------+--------------------------------+--------------------------------+
    | 22        | Page wait                      | 0=Disabled (Other values are   |
    |           |                                | country dependent)             |
    +-----------+--------------------------------+--------------------------------+
    

    Standard PAD profiles

    The following values define parameter settings for the standard profiles.

    Profile 0 (default)

    Profile 1

    Profile 90 (CCITT simple standard profile)

    Profile 91 (CCITT transparent standard profile)


    Description of the X.29 API

    The X.29 API is an extension of the X.25 API. It provides facilities that let an application function as an X.29 host system connected to one or more remote PADs. An application uses a combination of X.25 verbs and X.29 verbs.

    Note: X.29 operates in packet-mode, unlike X.28 which is a character-mode interface.

    Except for X25Call and X25CallReceive, an X.29 application can use any of the X.25 verbs (see "X.25 application programming verbs" for details of X.25 verbs). The application uses X29Call and X29CallReceive to establish a virtual circuit with a PAD. The remaining X.29 API verbs allow the application to exchange control information with the PAD.

    Note: An application is not restricted only to X.25 or X.29 virtual circuits; it can use a combination of these. It is not allowed to use X.29 control verbs on circuits that you set up to use an X25Call verb or an X25CallReceive verb.

    A task that operates as an X.29 host may call X.25 and X.29 verbs in the following order (any X25SemWait verbs are not shown):

    Summary of the unique X.29 verbs

    X29Call
    Establish a virtual call to a PAD.

    X29CallReceive
    Receive a call from a PAD.

    X29ReadParam
    Send an X.29 read PAD parameter message to the remote PAD.

    X29SendBreakInd
    Send an X.29 Indication of Break PAD message to the remote PAD.

    X29SendInvitationToClear
    Send an X.29 Invitation to Clear PAD message to the remote PAD.

    X29SendReselectInvn
    Send an X.29 Invitation to Reselect PAD message to the remote PAD.

    X29SetAndReadParam
    Send an X.29 set and read PAD parameter message to the remote PAD.

    X29SetParam
    Send an X.29 set PAD parameter message to the remote PAD.

    Descriptions of the X.29 API verbs

    This section provides descriptions of each of the X.29 API verbs. Each description is accompanied by a table to show the contents of the XVRB and, where appropriate, a table to show the contents of the data buffer.

    See "Contents of the verb request block" and "Data buffers" for details of the fields in the tables.

    X29Call

    Purpose

    A task uses X29Call to set up a virtual circuit with a PAD. The use of this verb indicates that the virtual call is to be in X.29 mode.

    The X.29 call identifier "0100 0000" is placed in the first four bytes of the Call User Data. Any other Call User Data (up to a maximum of 12 bytes) supplied in the Call Data Buffer is appended to this identifier.

    D-bit acknowledgment is not allowed on X.29 virtual circuits. You cannot set up the circuit in SNA mode. Apart from these differences, the X29Call verb operates in the same way as its X.25 counterpart.

    The contents of the verb request block are shown in Table 40. The Data Buffer is the same as the CallData buffer for X25Call, described in "X.25 application programming verbs".

    Verb request block for X29Call

    Table 40. X29Call verb request block

    +----------------------------------------------------------------------------+
    | Name        | Lth | I/O | Description                                      |
    +-------------+-----+-----+--------------------------------------------------+
    | verb_id     | 1   | I   | X29Call                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | I/O | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | lcn         | 2   | O   | Logical channel number                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Data buffer pointer                              |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    | ccode       | 1   | O   | Cause code                                       |
    +-------------+-----+-----+--------------------------------------------------+
    | dcode       | 1   | O   | Diagnostic code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X29Call

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29CallReceive

    Purpose

    A task uses X29CallReceive to receive a call from a PAD. The use of this verb indicates that the API should check that the call is identified as an X.29 call.

    X29CallReceive checks that the received call request is for an X.29 call. (The correct call routing is still the user's responsibility.) You must set up an active incoming call routing entry to route the call from the PAD to the task. This routing must accept incoming calls with "0100 0000" in the first four bytes of the Call User Data. It should, therefore, set this field of the routing entry to "0100 0000".

    D-bit processing is not available on virtual circuits used for X.29 communication. Apart from these differences, the X29CallReceive verb operates in the same way as an X25CallReceive verb. You should accept the incoming call with an X25CallAccept verb.

    Verb request block for X29CallReceive

    Table 41. X29CallReceive verb request block

    +=============+=====+=====+==================================================+
    | Name        | Lth | I/O | Description                                      |
    +=============+=====+=====+==================================================+
    | verb_id     | 1   | I   | X29CallReceive                                   |
    +-------------+-----+-----+--------------------------------------------------+
    | ver         | 1   | I   | Version identifier                               |
    +-------------+-----+-----+--------------------------------------------------+
    | task_id     | 2   | I   | Task ID                                          |
    +-------------+-----+-----+--------------------------------------------------+
    | sem         | 2   | I/O | Semaphore                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | com_code    | 2   | O   | Completion code                                  |
    +-------------+-----+-----+--------------------------------------------------+
    | addr_opt    | 1   | I   | Convert address option                           |
    +-------------+-----+-----+--------------------------------------------------+
    | link_name   | 8   | O   | Link name                                        |
    +-------------+-----+-----+--------------------------------------------------+
    | conn_id     | 2   | O   | Connection ID                                    |
    +-------------+-----+-----+--------------------------------------------------+
    | lcn         | 2   | O   | Logical channel number                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff        | 4   | I   | Pointer to data buffer                           |
    +-------------+-----+-----+--------------------------------------------------+
    | buff_len    | 2   | I   | Length of data buffer                            |
    +-------------+-----+-----+--------------------------------------------------+
    

    Return and completion codes for X29CallReceive

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29ReadParam

    Purpose

    A task uses X29ReadParam to send an X.29 "Read PAD parameter" message. The parameter values are returned in a data packet that can be obtained using the X29DataReceive verb.

    The contents of the verb request block are shown in Table 42.

    Verb request block for X29ReadParam

    Table 42. X29ReadParam verb request block

    +==============+=====+=====+=================================================+
    | Name         | Lth | I/O | Description                                     |
    +==============+=====+=====+=================================================+
    | verb_id      | 1   | I   | X29ReadParam                                    |
    +--------------+-----+-----+-------------------------------------------------+
    | ver          | 1   | I   | Version identifier                              |
    +--------------+-----+-----+-------------------------------------------------+
    | task_id      | 2   | I   | Task ID                                         |
    +--------------+-----+-----+-------------------------------------------------+
    | sem          | 2   | I/O | Semaphore                                       |
    +--------------+-----+-----+-------------------------------------------------+
    | com_code     | 2   | O   | Completion code                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | conn_id      | 2   | I   | Connection ID                                   |
    +--------------+-----+-----+-------------------------------------------------+
    | param_buff   | 4   | I   | Pointer to data buffer                          |
    +--------------+-----+-----+-------------------------------------------------+
    | num_of&#     | 2   | I   | Number of entries in parameter list             |
    | 95;entries   |     |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    

    Data Buffer for X29ReadParam

    Table 43. Data buffer

    +===============+=====+=====+================================================+
    | Name          | Lth | I/O | Description                                    |
    +===============+=====+=====+================================================+
    | parameter     |     |     | The Data Buffer should contain an entry for    |
    | entries       |     |     | each parameter that the task wants to read.    |
    +---------------+-----+-----+------------------------------------------------+
    | param_ref_num | 1   | I   | Parameter reference number                     |
    +---------------+-----+-----+------------------------------------------------+
    | param_value   | 1   | I   | Parameter value                                |
    +---------------+-----+-----+------------------------------------------------+
    
    (Ref #17.)

    Return and completion codes for X29ReadParam

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29SendBreakInd

    Purpose

    A task uses X29SendBreakInd to send an "Indication of Break" PAD message to a PAD on a virtual call. A task can request that the PAD discards any data it has for the terminal. It does this by setting the output_discard field in the XVRB to X29_OUT_DISC_YES.

    Note: (Ref #18.) The X.28 API hides the Break signal below the user interface, therefore users of the X.28 API cannot see that the PAD has issued a Break signal.

    Verb request block for X29SendBreakInd

    Table 44. X29SendBreakInd verb request block

    +==============+=====+=====+=================================================+
    | Name         | Lth | I/O | Description                                     |
    +==============+=====+=====+=================================================+
    | verb_id      | 1   | I   | X29SendBreakInd                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | ver          | 1   | I   | Version identifier                              |
    +--------------+-----+-----+-------------------------------------------------+
    | task_id      | 2   | I   | Task ID                                         |
    +--------------+-----+-----+-------------------------------------------------+
    | sem          | 2   | I/O | Semaphore                                       |
    +--------------+-----+-----+-------------------------------------------------+
    | com_code     | 2   | O   | Completion code                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | conn_id      | 2   | I   | Connection ID                                   |
    +--------------+-----+-----+-------------------------------------------------+
    | output_d     | 1   | I   | Output discard                                  |
    | iscard       |     |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    

    Return and completion codes for X29SendBreakInd

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29SendInvitationToClear

    Purpose

    A task uses X29SendInvitationToClear to send an "Invitation to Clear" PAD message to a PAD on a virtual call.

    Verb request block for X29SendInvitationToClear

    Table 45. X29SendInvitationToClear verb request block

    +===============+=====+=====+================================================+
    | Name          | Lth | I/O | Description                                    |
    +===============+=====+=====+================================================+
    | verb_id       | 1   | I   | X29SendInvitationToClear                       |
    +---------------+-----+-----+------------------------------------------------+
    | ver           | 1   | I   | Version identifier                             |
    +---------------+-----+-----+------------------------------------------------+
    | task_id       | 2   | I   | Task ID                                        |
    +---------------+-----+-----+------------------------------------------------+
    | sem           | 2   | I   | Semaphore                                      |
    +---------------+-----+-----+------------------------------------------------+
    | com_code      | 2   | O   | Completion code                                |
    +---------------+-----+-----+------------------------------------------------+
    | conn_id       | 2   | I   | Connection ID                                  |
    +---------------+-----+-----+------------------------------------------------+
    

    Return and completion codes for X29SendInvitationToClear

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29SendReselectInvn

    Purpose

    A task uses X29SendReselectInvn to send an "Invitation to Reselect PAD" message to a PAD on a virtual call.

    X.25 facilities can be supplied in the Facilities field in the Call Buffer, and are sent in the reselection PAD message.

    The task can supply up to 12 bytes of Call User Data in the CUD field of the Call Buffer to be sent in the Reselection PAD message.

    On receipt of the "Invitation to reselect PAD" message the remote PAD should clear the virtual call and establish a new virtual call to the reselected DTE using the address, CUD and facilities given in the Invitation to Reselect PAD message.

    The contents of the verb request block are shown in x29sdir page=no..

    The Data Buffer is the same as the Call Data buffer for X25Call described in "X.25 application programming verbs".

    Verb request block for X29SendReselectInvn

    Table 46. X29SendReselectInvn verb request block

    +===============+=====+=====+================================================+
    | Name          | Lth | I/O | Description                                    |
    +===============+=====+=====+================================================+
    | verb_id       | 1   | I   | X29SendReselectInvn                            |
    +---------------+-----+-----+------------------------------------------------+
    | ver           | 1   | I   | Version identifier                             |
    +---------------+-----+-----+------------------------------------------------+
    | task_id       | 2   | I   | Task ID                                        |
    +---------------+-----+-----+------------------------------------------------+
    | sem           | 2   | I/O | Semaphore                                      |
    +---------------+-----+-----+------------------------------------------------+
    | com_code      | 2   | O   | Completion code                                |
    +---------------+-----+-----+------------------------------------------------+
    | conn_id       | 2   | I   | Connection ID                                  |
    +---------------+-----+-----+------------------------------------------------+
    | buff          | 4   | I   | Pointer to data buffer                         |
    +---------------+-----+-----+------------------------------------------------+
    | buff_len      | 2   | I   | Size of data buffer                            |
    +---------------+-----+-----+------------------------------------------------+
    

    Return and completion codes for X29SendReselectInvn

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29SetAndReadParam

    Purpose

    A task uses X29SetAndReadParam to send an X.29 "set and read PAD parameter" message.

    The contents of the verb request block are shown in Table 47. The parameter data buffer is the same as for X29ReadParam and is described in topic reference #17.

    Verb request block for X29SetAndReadParam

    Table 47. X29SetAndReadParam verb request block

    +===============+=====+=====+================================================+
    | Name          | Lth | I/O | Description                                    |
    +===============+=====+=====+================================================+
    | verb_id       | 1   | I   | X29SetAndReadParam                             |
    +---------------+-----+-----+------------------------------------------------+
    | ver           | 1   | I   | Version identifier                             |
    +---------------+-----+-----+------------------------------------------------+
    | task_id       | 2   | I   | Task ID                                        |
    +---------------+-----+-----+------------------------------------------------+
    | sem           | 2   | I/O | Semaphore                                      |
    +---------------+-----+-----+------------------------------------------------+
    | com_code      | 2   | O   | Completion code                                |
    +---------------+-----+-----+------------------------------------------------+
    | conn_id       | 2   | I   | Connection ID                                  |
    +---------------+-----+-----+------------------------------------------------+
    | param_buff    | 4   | I   | Pointer to data buffer                         |
    +---------------+-----+-----+------------------------------------------------+
    | num_of	        | 2   | I   | Number of entries in parameter list            |
    | 5;entries     |     |     |                                                |
    +---------------+-----+-----+------------------------------------------------+
    

    Return and completion codes for X29SetAndReadParam

    These codes have the same meanings as for X.25. See topic  reference #12.

    X29SetParam

    Purpose

    A task uses X29SetParam to send an X.29 "set PAD" message.

    The contents of the verb request block are shown in Table 48. The parameter data buffer is the same as for X29ReadParam and is described in topic reference #17.

    Verb request block for X29SetParam

    Table 48. X29SetParam verb request block

    +==============+=====+=====+=================================================+
    | Name         | Lth | I/O | Description                                     |
    +==============+=====+=====+=================================================+
    | verb_id      | 1   | I   | X29SetParam                                     |
    +--------------+-----+-----+-------------------------------------------------+
    | ver          | 1   | I   | Version identifier                              |
    +--------------+-----+-----+-------------------------------------------------+
    | task_id      | 2   | I   | Task ID                                         |
    +--------------+-----+-----+-------------------------------------------------+
    | sem          | 2   | I/O | Semaphore                                       |
    +--------------+-----+-----+-------------------------------------------------+
    | com_code     | 2   | O   | Completion code                                 |
    +--------------+-----+-----+-------------------------------------------------+
    | conn_id      | 2   | I   | Connection ID                                   |
    +--------------+-----+-----+-------------------------------------------------+
    | param_buff   | 4   | I   | Pointer to data buffer                          |
    +--------------+-----+-----+-------------------------------------------------+
    | num_of&#     | 2   | I   | Number of entries in parameter list             |
    | 95;entries   |     |     |                                                 |
    +--------------+-----+-----+-------------------------------------------------+
    

    Return and completion codes for X29SetParam

    These codes have the same meanings as for X.25. See topic  reference #12.


    Developing and executing application programs


    X.25 API programming language support

    For a list of trademarks, see topic reference #1. Trademark. For a list of trademarks, see topic reference #1.

    The X.25 API supports the Assembler, C, and Pascal programming languages. The diskette that contains the IBM X.25 Co-Processor Support Program also provides language bindings that define:

    The following translators are supported:

    Assembler support

    The Assembler include files are:

    The include file x2xa.i contains definitions common to all the APIs. The other files are API-specific. The entry point is x25a.

    C language support

    The C include files are:

    The include file x2xc.h contains definitions common to all the APIs. The other files are API-specific. The entry point is x25c.

    Pascal language support

    The Pascal include files are:

    The x2xp files contain definitions common to all the APIs. The other files are API-specific. The entry point is x25p.

    Linking X.25 applications

    The procedure for the IBM X.25 Co-Processor Support Program API entry point must be included when you link application programs.

    The entry-point routines are contained in the link library GQK.LIB, which is included on the distribution diskette. This library should be specified when your application is linked (see your DOS manuals for details of how to specify link libraries).

    Note: Turbo Pascal cannot link with link libraries. The object module GQK.OBJ should be linked with Turbo Pascal applications.


    The example application

    This section describes a simple X.25 application program written to listen for and receive Incoming Calls from remote users. When an Incoming Call is received, the application saves the incoming call data in a file. The call is then cleared and the application waits for another call.

    The example program is intended to run as a background application and could be used to record all incoming calls when no other applications are active.

    A listing of the example program begins in topic reference #19.

    General points

    An application communicates with the X.25 API by passing the address of a verb request block (XVRB) as a parameter to the API entry point. This XVRB contains an identifier (verb_id) that tells the API which verb is requested. These identifiers are provided in the X.25 include files.

    The example is intended to show how API verb calls are incorporated in an application. It does not test all possible error conditions.

    The application initializes a task ready to use the X.25 API. The API is assumed to have already been loaded. There is only one task in the application, a management task, which is initialized by the X25Init verb. The task is a background task so that other DOS applications can be run at the same time.

    Note: You must have set the HOTkey parameter (in the parameter file passed to the X25 command when loading the API) to NULL. This ensures that the resident event- and link-manager tasks are not started.

    Task initialization

    The task is initialized using the X25Init verb. You set the parameters in the XVRB to indicate that it is a background task and that it is the last task to be initialized from the application:

    Once the parameters have been validated, the X25Init verb is queued for further processing and a task identifier is placed in the XVRB. The API, recognizing that this is the last task in the application, terminates it, leaving it resident, and returns to DOS.

    The value returned in the task_id field of the X25Init XVRB must be used in all subsequent calls to the API.

    If there is an error in the validation of the verb, the API returns to the application, passing a return code that indicates the cause of the failure. The application then displays the return code on the screen.

      xInit.verb_id     = X25Init;
      xInit.ver         = X25_API_VERSION;
      xInit.resume_addr = Task;
      xInit.stack_size  = 1024;
      xInit.last_task   = X25_LAST_TASK_YES;
    
      rc = x25c ((XVRB far *)&xInit;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    

    The task

    Waiting for events

    A task waits for events using X25SemWait. The API returns control to a task when a verb completes or when a time out value expires.

      xSemWait.verb_id  = X25SemWait;
      xSemWait.ver      = X25_API_VERSION;
      xSemWait.task_id  = xInit.task_id;
      xSemWait.time_out = 100;
    
      rc = x25c ((XVRB far *)&xSemWait;);
      if (X25_OK != rc)
      {
    
      /*  Process the error processing X25SemWait by examining the immediate      */
      /*  return code and immediate completion code.                              */
    
      };
    
      if (X25_OK != (xSemWait.xvrb_ptr) -> com_code)
      {
    
      /* Process the delayed completion code of the verb that has completed by    */
      /* examining the verb identifier in the XVRB pointed to by the xvrb_ptr     */
      /* field of the X25SemWait XVRB, and the completion code in that XVRB.      */
    
      };
    
    In the example application, the task first calls X25SemWait to wait for completion of X25Init. When the task is again given control, and no errors are reported, it can issue other X.25 verbs.

    Unexpected events

    The task uses two management verbs to enable it to be informed when specific unexpected events occur.

    X25Status, when called with the stat_opt parameter set to X25_STATUS_DELAYED, notifies the task of any change in the status of the link. For example, if it becomes disconnected.

      xStatus.verb_id   = X25Status;
      xStatus.ver       = X25_API_VERSION;
      xStatus.task_id   = xInit.task_id;
      xStatus.stat_opt  = X25_STATUS_DELAYED;
      xStatus.buff      = Status_buff;
      xStatus.buff_len  = sizeof (Status_buff);
    
      strncpy (xStatus.link_name, "X25LINK1", 8);
    
      rc = x25c ((XVRB far *)&xStatus;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    
    X25Event notifies the task if the API is terminated. For example, if a user issues the command X25 Term at the DOS prompt.
      xEvent.verb_id    = X25Event;
      xEvent.ver        = X25_API_VERSION;
      xEvent.task_id    = xInit.task_id;
    
      rc = x25c ((XVRB far *)&xEvent;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    
    These two verbs may never complete because the events they are waiting for may not occur.

    Because more than one verb is now outstanding, subsequent returns from X25SemWait may indicate completion of these or other verbs. The ProcessX procedure looks specifically for the completion of X25Status and X25Event.

    Link management

    In order to receive incoming calls an X.25 link must be established. Using the IBM X.25 Co-Processor Support Program configuration utility, a user should have configured a link with the name X25LINK1. The task then calls X25LinkConnect to connect the link, and calls X25SemWait to wait for its completion.

      xLinkC.verb_id    = X25LinkConnect;
      xLinkC.ver        = X25_API_VERSION;
      xLinkC.task_id    = xInit.task_id;
    
      strncpy (xLinkC.link_name, "X25LINK1", 8);
    
      rc = x25c ((XVRB far *)&xLinkC;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    

    Processing calls

    Specify calls to be received

    To receive incoming calls, the task must specify which calls it is prepared to receive. Using the IBM X.25 Co-Processor Support Program configuration utility, a user should have configured a routing entry with the name X25BKGND to receive all incoming calls. This is done by placing an asterisk (*) in each of the relevant routing entry fields. The task then calls X25Listen, specifying "X25BKGND" as a routing entry name, and waits for it to complete.

      xListen.verb_id   = X25Listen;
      xListen.ver       = X25_API_VERSION;
      xListen.task_id   = xInit.task_id;
      xListen.buff      = Listen_buff;
      xListen.buff_len  = sizeof (Listen_buff);
    
      Listen_info_ptr   =
        (X25Listen_INFO far *) (((X25Listen_BUFF far *) Listen_buff) -> route_data);
    
      ((X25Listen_BUFF far *) Listen_buff) -> num_route_names = 1;
    
      strncpy (listen_info_ptr -> route_name, "X25BKGND", 8);
    
      rc = x25c ((XVRB far *)&xListen;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    

    Receiving calls

    To receive a call the task issues an X25CallReceive and waits for it to complete. X25CallReceive completes when the fields in an incoming field match the fields in a routing entry that was specified with the use of X25Listen. In this task, it completes for all calls.

    When X25SemWait returns, indicating that X25CallReceive has completed, data from the incoming call is available in the buffer pointed to by the buff field in the X25CallReceive XVRB. This data is saved by the ProcessCall and the LogCall procedures.

      xCallR.verb_id    = X25CallReceive;
      xCallR.ver        = X25_API_VERSION;
      xCallR.task_id    = xInit.task_id;
      xCallR.addr_opt   = X25_CONVERT_ADDR_NO;
      xCallR.buff       = CallR_buff;
      xCallR.buff_len   = sizeof (CallR_buff);
    
      rc = x25c ((XVRB far *)&xCallR;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    

    Clearing the call

    A more sophisticated program would now go into a X25CallAccept/X25DataReceive sequence. However, for simplicity, this example logs data associated with incoming calls only and clears the call with X25CallClear.

      xCallC.verb_id    = X25CallClear;
      xCallC.ver        = X25_API_VERSION;
      xCallC.task_id    = xInit.task_id;
      xCallC.conn_id    = xCallR.conn_id;
      xCallC.buff       = 0;
      xCallC.buff_len   = 0;
    
    
      rc = x25c ((XVRB far *)&xCallC;);
      if (X25_OK != rc)
      {
    
      /*  Process the error by examining the immediate return code and immediate  */
      /*  completion code.                                                        */
    
      };
    

    The example application program

    (Ref #19.)
    /*****************************************************************************/
    /*  File                           X25BACK.C                                 */
    /*****************************************************************************/
    /*  Description   : Example background application                           */
    /*  Note          : Background Task configured as Subsystem manager          */
    /*                                                                           */
    /*  Language      : IBM C/2 1.0                                              */
    /*                                                                           */
    /*  Dependencies  : X2XC.H and X25C.H                                        */
    /*                                                                           */
    /*  Compiler opts : Large Model (/AL)                                        */
    /*  Link opts     : /STACK:4096                                              */
    /*                                                                           */
    /*****************************************************************************/
    /*****************************************************************************/
    /*                         Define Header Files used                          */
    /*****************************************************************************/
    
    /*****************************************************************************/
    /*                         General purpose includes                          */
    /*****************************************************************************/
    
    #include 
    #include 
    
    /*****************************************************************************/
    /*                         The X25 API Header files                          */
    /*****************************************************************************/
    
    #include "X2XC.H"                    /* Global X25/28/29 Header information  */
    #include "X25C.H"                    /* X25 Specific Header File             */
    
    /*****************************************************************************/
    /*                         Structures for Application                        */
    /*****************************************************************************/
    
    typedef struct
    {
      UINT             num_ext_names;                /* Number of entries in list */
      X25Listen_INFO   ListenInfo �1�;               /* One listen - can be array */
    } ListenList;
    
    typedef struct
    {
      USHORT           links_conf;                   /* No. of configured links   */
      USHORT           link_status_len;              /* Length link status entry  */
      USHORT           num_link_entries;             /* Number of actual entries  */
      X25Link_INFO     LinkInfo �1�;                 /* One link - can be array   */
    } StatusStruct;
    
    /*****************************************************************************/
    /*                         Define Global Constants                           */
    /*****************************************************************************/
    
    #define     MAX_STR_LEN   8                    /* Used for strncpy functions */
    
    #define     DEF_STACK     1024                 /* Default Stack Size         */
    #define     TIME_OUT      -1                   /* SemWait timeout value      */
    #define     DEF_SEM       0xFF                 /* Default Start up Semaphore */
    #define     LINK_NAME     "LINK1   "           /* Link Name - 8 chars long   */
    #define     ROUTE_NAME    "MYMATE1 "           /* Route Name - 8 chars long  */
    #define     CALL_FNAME    "EXAMPLE.CAL"        /* Call Processing Filename   */
    #define     LOG_FNAME     "EXAMPLE.LOG"        /* Log  Processing Filename   */
    
    /*****************************************************************************/
    /*                         Format Strings for Errors                         */
    /*****************************************************************************/
    
    #define     ERROR_1       "\nError *** Completion Code: %d"
    #define     ERROR_2       "\nError *** Immediate Code: %d Completion Code: %d"
    #define     FATAL_ERR     "\nFatal Error: %d *** Initialization Failure"
    #define     LOG_MSG       "\nOne Call cycle completed"
    
    /*****************************************************************************/
    /*                         Define Call Buffer                                */
    /*****************************************************************************/
    
    #define     CALL_BUFF_LEN 400
    
    typedef struct
    {
      char Buffer �CALL_BUFF_LEN�;
    } CallBuff;
    
    /*****************************************************************************/
    /*                         Define Global Variables                           */
    /*****************************************************************************/
    
    BOOL    DiskIO    = X25_TRUE;                  /* Disk IO Control variable   */
    FILE    *OutFile;                              /* Output File                */
    BOOL    LogIO     = X25_TRUE;                  /* Log IO Control variable    */
    FILE    *LogFile;                              /* Log File                   */
    
    /*****************************************************************************/
    /*                         Define XVRB Global Variables                      */
    /* See Header Files for the complete XVRB structure listing                  */
    /*****************************************************************************/
    
    /*****************************************************************************/
    /* Init - used to initialize the subsystem manager and a Task                */
    /*****************************************************************************/
    
    X25Init_XVRB             xInit = {0};
    
    /*****************************************************************************/
    /* Link Connect - used to connect and return the status of the Link          */
    /*****************************************************************************/
    
    X25LinkConnect_XVRB      xLinkConnect = {0};
    X25LinkStatus_BUFF       xLinkStatBuf = {0};
    
    /*****************************************************************************/
    /* Status - used to read the status/change of status of the link             */
    /*****************************************************************************/
    
    X25Status_XVRB           xStatus = {0};
    StatusStruct             xStatBuf = {0};
    
    /*****************************************************************************/
    /* Event - used to return an Event signal                                    */
    /*****************************************************************************/
    
    X25Event_XVRB            xEvent = {0};
    
    /*****************************************************************************/
    /* Listen - used to make the X25 API route incoming calls to the application */
    /*****************************************************************************/
    
    X25Listen_XVRB           xListen = {0};
    X25Listen_BUFF           xListenBuf = {0};
    ListenList               xList = {0};
    
    /*****************************************************************************/
    /* Call Receive/Clear - used to receive/establish calls                      */
    /*****************************************************************************/
    
    X25CallReceive_XVRB      xCallRx = {0};
    CallBuff                 xCallBuf = {0};
    X25CallClear_XVRB        xCallClr = {0};
    
    /*****************************************************************************/
    /* Sem Wait - used to wait for completion/time out of a verb                 */
    /*****************************************************************************/
    
    X25SemWait_XVRB          xSemWait = {0};
    
    /*****************************************************************************/
    /* Term - used to terminate the system and application                       */
    /*****************************************************************************/
    
    X25Term_XVRB             xTerm = {0};
    
    /*****************************************************************************/
    /* Local XVRB                                                                */
    /*****************************************************************************/
    
    XVRB                     far * x;
    
    /*****************************************************************************/
    /* Procedures used by the application.                                       */
    /*****************************************************************************/
    
    /*****************************************************************************/
    /* PROCEDURE Terminate - No Parameters                                       */
    /* This procedure is used to terminate the application. All                  */
    /* files that are still open are closed, the Terminate XVRB is loaded with   */
    /* the appropriate parameters and a call to the X25 function is made.        */
    /* Then the SemWait function is setup and called.                            */
    /* The X25 API will only  return after this call if there is an error.       */
    /*****************************************************************************/
    
    void Terminate (void)
    {
      int rc;
    
      rc = fcloseall(); /* Close all the files in the system; use rc as dummy */
    
      xTerm.verb_id   = X25Term;
      xTerm.ver       = X25_API_VERSION;
      xTerm.task_id   = xInit.task_id;
      xTerm.sem       = DEF_SEM;
      xTerm.term_opt  = X25_TERM_IMMED;
    
      rc = x25c ((XVRB *) &xTerm;);
    
    /*****************************************************************************/
    /* Now wait for the verb to complete                                         */
    /*****************************************************************************/
    
      xSemWait.verb_id  = X25SemWait;           /* The verb ID - See Headers    */
      xSemWait.ver      = X25_API_VERSION;
      xSemWait.task_id  = xInit.task_id;        /* The Task ID from X25Init      */
      xSemWait.sem      = DEF_SEM;              /* Put semaphore                 */
      xSemWait.time_out = TIME_OUT;             /* Specify Time Out              */
    
    /*****************************************************************************/
    /* Call the X25 API function storing the immediate return code in rc         */
    /*****************************************************************************/
    
      rc = (x25c ((XVRB *) &xSemWait;));         /* Call the API function         */
    
    /*****************************************************************************/
    /* The API should not return control after this call. A return indicates an  */
    /* unrecoverable API error. EXIT used to abort task.                         */
    /*****************************************************************************/
    
      exit (rc);
    
    }
    
    /*****************************************************************************/
    /* PROCEDURE ProcessImmediate - PARAMETERs ReturnCode (integer)              */
    /* This procedure will examine the supplied parameter ReturnCode, and if not */
    /* X25_OK will print the completion code, then issue a call to Terminate (). */
    /* Thereby terminating the application  and the system.                      */
    /*****************************************************************************/
    
    void ProcessImmediate (ReturnCode,CompCode)
    
    int   ReturnCode;
    short CompCode;
    
    {
      if (ReturnCode != X25_OK)
      {
        printf (ERROR_2,ReturnCode,CompCode);
        Terminate ();
      } /* if */
    }
    
    /*****************************************************************************/
    /* PROCEDURE ProcessX     - PARAMETERs none                                  */
    /* This procedure will examine the XVRBs returned by SemWait. It checks the  */
    /* verb in verb_id and if it is X25Event or X25Status then the application   */
    /* and system terminate. In this example program, X25Event returns if the    */
    /* user enters X25 term from the keyboard, and X25Status returns if there is */
    /* a change in the link status. Since the application runs if the link is    */
    /* correctly connected, a change implies that the link is down.              */
    /*****************************************************************************/
    
    void ProcessX (void)
    {
    
      if ((x->verb_id == X25Status) || (x->verb_id == X25Event))
        Terminate ();
    
    } /* ProcessX */
    
    /*****************************************************************************/
    /* PROCEDURE ProcessCompletion - PARAMETERs CompCode (integer)               */
    /* This procedure checks the completion code parameter and if an Error will  */
    /* Terminate  the application.                                               */
    /*****************************************************************************/
    
    void ProcessCompletion (CompCode)
    
    int CompCode;
    
    {
      if (CompCode != X25_OK)
      {
        printf (ERROR_1,CompCode);
        Terminate ();
      } /* if */
    }
    
    /*****************************************************************************/
    /* PROCEDURE Wait         - PARAMETERs none                                  */
    /* This procedure will Wait until a Verb completes.                          */
    /* If the immediate return or completion code is an error then the           */
    /* application terminates. The time waited is set in the time_out field of   */
    /* the XVRB. In this example it is set to -1 wait indefinitely until         */
    /* something happens.                                                        */
    /*****************************************************************************/
    
    void Wait (void)
    {
    
      int           rc;                       /* The return code of any X25 call */
    
    /*****************************************************************************/
    /* First set up the parameters of the SemWait XVRB. The structure of the     */
    /* XVRB can be found in the headers file.                                    */
    /*****************************************************************************/
    
      xSemWait.verb_id  = X25SemWait;           /* The verb ID - See Headers    */
      xSemWait.ver      = X25_API_VERSION;
      xSemWait.task_id  = xInit.task_id;        /* The Task ID from X25Init      */
      xSemWait.sem      = DEF_SEM;              /* Put semaphore                 */
      xSemWait.time_out = TIME_OUT;             /* Specify Time Out              */
    
    /*****************************************************************************/
    /* Call the X25 API function storing the immediate return code in rc         */
    /*****************************************************************************/
    
      rc = (x25c ((XVRB *) &xSemWait;));         /* Call the API function         */
    
    /*****************************************************************************/
    /* Now process the return information. See ProcessImmediate/Completion for   */
    /* more information on how those errors are handled.                         */
    /*****************************************************************************/
    
      ProcessImmediate (rc,xSemWait.com_code);
    
    /*****************************************************************************/
    /* The function has returned, therefore copy the xvrb_ptr in the SemWait     */
    /* XVRB into x and process it. See ProcessX for more information on how      */
    /* the asynchronous verbs X25Event and X25Status are handled.                */
    /*****************************************************************************/
    
      x = ((XVRB *) xSemWait.xvrb_ptr);
    
    /*****************************************************************************/
    /* Now handle the completion code of the verb that has returned              */
    /*****************************************************************************/
    
      ProcessCompletion (x->com_code);      /* Check the Completion code         */
      ProcessX ();                 /* Check completion of event monitoring verbs */
    
    } /* Wait */
    
    /*****************************************************************************/
    /* PROCEDURE Listen       - PARAMETERs none                                  */
    /* This procedure informs the X25 API that the issuing application wishes    */
    /* to receive calls for a given route name. The route name in this program   */
    /* is .                                                             */
    /*****************************************************************************/
    
    void Listen (void)
    {
    
      int rc;
    
    
      strncpy(xList.ListenInfo �0�.route_name, ROUTE_NAME ,MAX_STR_LEN);
      xList.num_ext_names = 1;
    
      xListen.verb_id    = X25Listen;
      xListen.ver        = X25_API_VERSION;
      xListen.task_id    = xInit.task_id;
      xListen.sem        = DEF_SEM;
      xListen.buff       = (char far *) &xList;
      xListen.buff_len   = sizeof (xList);
    
      rc = (x25c ((XVRB *) &xListen;));
    
      ProcessImmediate (rc,xListen.com_code);
    
    } /* Listen */
    
    /*****************************************************************************/
    /* PROCEDURE ReceiveCall - PARAMETERs none                                   */
    /* This procedure informs the X25 API that the issuing application is in     */
    /* receive mode ready to receive calls.                                      */
    /*****************************************************************************/
    
    void ReceiveCall (void)
    {
    
      int rc;
    
      xCallRx.verb_id  = X25CallReceive;
      xCallRx.ver      = X25_API_VERSION;
      xCallRx.task_id  = xInit.task_id;
      xCallRx.addr_opt = X25_NAME_CONVERT_NO
      xCallRx.sem      = DEF_SEM;
      xCallRx.buff     = (char far *) &xCallBuf;
      xCallRx.buff_len = sizeof (xCallBuf);
    
      rc = (x25c ((XVRB *) &xCallRx;));
    
      ProcessImmediate (rc,xCallRx.com_code);
    
    } /* ReceiveCall  */
    
    /*****************************************************************************/
    /* PROCEDURE ClearCall - PARAMETERs none                                     */
    /* This procedure informs the X25 API that the issuing application is        */
    /* clearing the established call on the current connection ID                */
    /*****************************************************************************/
    
    void ClearCall (void)
    {
    
      int rc;
    
      xCallClr.verb_id  = X25CallClear;
      xCallClr.ver      = X25_API_VERSION;
      xCallClr.task_id  = xInit.task_id;
      xCallClr.sem      = DEF_SEM;
      xCallClr.conn_id  = xCallRx.conn_id;
      xCallClr.buff     = NULL;
      xCallClr.buff_len = 0;
      rc = x25c ((XVRB *)&xCallClr;);
    
      ProcessImmediate (rc,xCallClr.com_code);
    
    } /* ClearCall */
    
    /*****************************************************************************/
    /* PROCEDURE ConnectLink - PARAMETERs none                                   */
    /* This procedure will cause the X25 API to connect a link to the Network    */
    /* DCE. For this application the link name is set to .                */
    /*****************************************************************************/
    
    void ConnectLink (void)
    {
    
      int rc;
    
      xLinkConnect.verb_id = X25LinkConnect;
      xLinkConnect.ver     = X25_API_VERSION;
      xLinkConnect.task_id = xInit.task_id;
      xLinkConnect.sem     = DEF_SEM;
      strncpy(xLinkConnect.link_name,LINK_NAME ,MAX_STR_LEN);
    
      rc = (x25c ((XVRB *) &xLinkConnect;));
    
      ProcessImmediate (rc,xLinkConnect.com_code);
    
    } /* ConnectLink */
    
    /*****************************************************************************/
    /* PROCEDURE MonitorStatus - PARAMETERs none                                 */
    /* This procedure will monitor the change of status of a Link. Since the     */
    /* link is up when this procedure is called, a change in status implies      */
    /* that the link has gone down.                                              */
    /*****************************************************************************/
    
    void MonitorStatus (void)
    {
    
      int rc;
    
      xStatus.verb_id       = X25Status;
      xStatus.ver           = X25_API_VERSION;
      xStatus.task_id       = xInit.task_id;
      xStatus.sem           = DEF_SEM;
      xStatus.stat_opt      = X25_STATUS_DELAYED;
    
      strncpy (xStatus.link_name, LINK_NAME ,MAX_STR_LEN);
      xStatus.buff          = (char far *) &xStatBuf;
      xStatus.buff_len      = sizeof (xStatBuf);
      rc = (x25c ((XVRB *) &xStatus;));
    
      ProcessImmediate (rc,xStatus.com_code);
    
    } /* MonitorStatus */
    
    /*****************************************************************************/
    /* PROCEDURE MonitorEvent - PARAMETERs  none                                 */
    /* This procedure monitors a change in Event. A request to terminate the     */
    /* operation of the X25 API                                                  */
    /*****************************************************************************/
    
    void MonitorEvent (void)
    {
    
      int rc;
    
      xEvent.verb_id       = X25Event;
      xEvent.ver           = X25_API_VERSION;
      xEvent.task_id       = xInit.task_id;
      xEvent.sem           = DEF_SEM;
    
      rc = (x25c ((XVRB *) &xEvent;));
    
      ProcessImmediate (rc,xEvent.com_code);
    
    } /* MonitorEvent */
    
    /*****************************************************************************/
    /* PROCEDURE ProcessCall - PARAMETERs none                                   */
    /* This procedure will append the user data in the call request packet       */
    /* to a disk file. Any disk IO problems will have the effect of disabling    */
    /* the disk access mechanism by setting the global variable DiskIO to FALSE. */
    /* Subsequent calls are not processed                                        */
    /*                                                                           */
    /*****************************************************************************/
    
    void ProcessCall (void)
    {
    
      if (DiskIO && X25_TRUE)
      {
        DiskIO = ((sizeof (X25Call_BUFF) == fwrite ((char *)&xCallBuf;,
                  sizeof (X25Call_BUFF), 1, OutFile))
                  ? X25_TRUE : X25_FALSE);
        fflush (OutFile);
      } /* if */
    }
    
    /*****************************************************************************/
    /* PROCEDURE LogCall - PARAMETERs none                                       */
    /* This procedure logs the receipt of a call. At the moment it only prints   */
    /* the fact that it has received a call. The user may change it to do        */
    /* something more elaborate                                                  */
    /*****************************************************************************/
    
    void LogCall (void)
    {
      if (LogIO && X25_TRUE)
      {
        LogIO = ((fprintf (LogFile, LOG_MSG ) != 0)
                 ? X25_TRUE : X25_FALSE);
        fflush (LogFile);
      } /* if */
    }
    
    /*****************************************************************************/
    /* PROCEDURE  Task        - PARAMETERs None                                  */
    /* The program Task. This task is installed in the background and operates   */
    /* continuously until a verb fails or until an Event or Link Disconnect      */
    /* is detected.                                                              */
    /*****************************************************************************/
    
    int far Task (void)
    /* This is the main task installed by main.*/
    {
      Wait ();                    /* For the X25Init call to complete            */
    
      MonitorEvent ();            /* Monitor Event - X25 TERM from Keyboard      */
    
      ConnectLink ();             /* Connect Link                                */
      Wait ();                    /* Wait for Verb to complete                   */
    
      MonitorStatus ();           /* Monitor Link Status - delayed return option */
    
      Listen ();                  /* Listen for call                             */
      while (X25_TRUE)
      {
         Wait ();                 /* Wait for Verb to complete                   */
         ReceiveCall ();          /* Receive the Call                            */
         Wait ();                 /* Wait for Verb to complete                   */
    
        /*************************************************************************/
        /* The Virtual Circuit is now established. The User Procedure could make */
        /* X25DataSend and X25DataReceive API calls to send and receive data.    */
        /*************************************************************************/
    
         ProcessCall ();          /* Execute the User Proc                       */
         LogCall ();              /* Log the Call Receipt                        */
    
         ClearCall ();            /* Clear Call                                  */
    
      } /* while */
    
    } /* Task body */
    
    /*****************************************************************************/
    /* PROCEDURE InitDevices - PARAMETERs none                                   */
    /* This procedure prepares the applications' files for output                */
    /*****************************************************************************/
    
    void InitDevices (void)
    /* This procedure prepares the applications' files for output */
    {
      DiskIO = ((OutFile = fopen (CALL_FNAME ,"wb+")) != NULL)
                ? X25_TRUE : X25_FALSE;
    
      LogIO  = ((LogFile = fopen (LOG_FNAME ,"w")) != NULL)
                ? X25_TRUE : X25_FALSE;
    
    } /* InitDevices */
    
    /*****************************************************************************/
    /* PROGRAM X25B - main   - PARAMETERs  none                                  */
    /* The main program initializes the applications' output files, loads the    */
    /* X25INIT XVRB with the X25 subsystem initialization parameters and calls   */
    /* the X25 function x25c. This function will NOT return and the installed    */
    /* task Task will run under the supervisor control. If the X25 API was not   */
    /* accessible then the call will return and the program then prints an error */
    /* message and finishes.                                                     */
    /*****************************************************************************/
    
    main()
    {
    
      int rc;
    
      InitDevices ();                                 /* Open  output files      */
    
      xInit.verb_id     = X25Init;                    /* Load XVRB Verb          */
      xInit.ver         = X25_API_VERSION;
      xInit.resume_addr = Task;                       /* Load XVRB Resume Addr   */
      xInit.stack_size  = DEF_STACK;                  /* Allocate Task Stack     */
      xInit.sem         = DEF_SEM;
      xInit.last_task   = X25_LAST_TASK_YES;          /* Only one task           */
    
      rc = x25c ((XVRB *) &xInit;);                /* Call X25 Function           */
    
      printf (FATAL_ERR ,rc);
    
    } /* main */
    

    Glossary

    This glossary includes definitions from:

    A

    adapter
    See communication adapter.

    API
    Application program interface.

    application program interface (API)
    The formally-defined programming language interface which is between an IBM system control program or a licensed program and the user of the program.

    asynchronous data transfer
    A physical transfer of data to or from a device that occurs without a regular or predictable time relationship following the execution of an I/O request.

    B

    bis
    Describes a secondary recommendation that is an alternative to a primary recommendation.

    C

    call-accepted packet
    A call supervision packet that a called data terminal equipment (DTE) transmits to indicate to the data circuit-terminating equipment (DCE) that it accepts the incoming call.

    call connected packet
    A call supervision packet that a data circuit-terminating equipment (DCE) transmits to indicate to a calling data terminal equipment (DTE) that the connection for the call has been completely established.

    call request packet
    A call supervision packet that a data terminal equipment (DTE) transmits to ask that a connection for a call be established throughout the network.

    call supervision packet
    A packet used to establish or clear a call at the interface between the data terminal equipment (DTE) and the data circuit-terminating equipment (DCE).

    CCITT
    Comite Consultatif International Telegraphique et Telephonique. The International Telegraph and Telephone Consultative Committee. An organization of common carriers and PTTs that recommends standards for the interconnection of communications equipment.

    clear confirmation packet
    A call supervision packet that a data circuit-terminating equipment (DCE) transmits to confirm that a call has been cleared.

    clear indication packet
    A call supervision packet that a data circuit-terminating equipment (DCE) transmits to inform a data terminal equipment (DTE) that a call has been cleared.

    clear request packet
    A call supervision packet transmitted by a data terminal equipment (DTE) to ask that a call be cleared.

    closed user group
    A group of network subscribers that can communicate with one another, but whose access is normally barred to and from all other subscribers of the service. Many networks offer closed user groups with incoming and outgoing access allowed.

    communication adapter
    A circuit card with associated software that enables a processor, controller, or other device to be connected to a network.

    communications co-processor
    A microprocessor on an expansion board that supplements the operations of the processor in the system unit, enabling a computer to use communication services in parallel with other operations.

    configure
    To describe to a system the nature, number, and chief characteristics of its functional units, either hardware or software.

    D

    data circuit-terminating equipment (DCE)
    In a data station, the equipment that provides the signal conversion and coding between the data terminal equipment (DTE) and the line. (I)

    data link
    The assembly of parts of two data terminal equipment that are controlled by a link protocol, and the interconnecting data circuit, that enable data to be transferred from a data source to a data sink. (I)
    The interconnecting data circuit and the link protocol between two or more equipments; it does not include the data source or the data sink.

    data packet
    At the interface between a data terminal equipment (DTE) and a data circuit-terminating equipment (DCE), a packet used to transmit user data over a virtual circuit.

    data terminal equipment (DTE)
    That part of a data station that serves as a data source, data sink, or both. (I)

    DCE
    Data circuit-terminating equipment

    DCE clear confirmation packet
    A call supervision packet that a data circuit-terminating equipment (DCE) transmits to confirm that a call has been cleared.

    delivery confirmation bit (D-bit)
    A bit in the data-packet header that instructs the network to wait until delivery to the remote DTE has been confirmed before confirming delivery to the sending DTE. Usually, confirmation is returned to the sending DTE when its packets have been transmitted to the network.

    DTE
    Data terminal equipment.

    duplex
    Pertaining to communication in which data can be sent and received at the same time. Contrast with half-duplex.

    F

    frame
    The contiguous sequence of eight-bit bytes delimited by beginning and ending flags. Frames are used to perform control functions, data transfers, and transmission checking on the link.

    frame level
    See link level.

    H

    half-duplex
    In data communication, pertaining to transmission in only one direction at a time. Contrast with duplex.

    I

    incoming call packet
    A call supervision packet transmitted by a data circuit-terminating equipment (DCE) to inform a called data terminal equipment (DTE) that another DTE has requested a call.

    International Organization for Standardization (ISO)
    An organization of national standards bodies from various countries established to promote development of standards to facilitate international exchange of goods and services, and develop cooperation in intellectual, scientific, technological, and economic activity.

    ISO
    International Organization for Standardization.

    L

    LAP
    Link access procedures.

    LAPB
    Link access protocol-balanced

    link
    In data communications, the combination of the physical medium of transmission, the protocol, and associated devices and programming; it is both logical and physical.

    link access procedures (LAP)
    The link level elements used for data interchange between data circuit-terminating equipment (DCE) and data terminal equipment (DTE) operating in user classes of service 8 to 11, as specified in CCITT Recommendation X.1.

    link access protocol-balanced
    A protocol used for accessing an X.25 network at the link level. LAPB is a duplex, asynchronous, symmetric protocol, used in point-to-point communication. It supersedes the earlier LAP protocol.

    link level
    A part of Recommendation X.25 that defines the link protocol used to get data into and out of the network across the full-duplex link connecting the subscriber's machine to the network node. LAP and LAPB are the link access protocols recommended by the CCITT.

    logical channel
    In packet mode operation, a sending channel, a receiving channel, or both used at the same time, established on a data link. Several logical channels can be established on the same data link by interleaving the transmission of packets.

    M

    modem (modulator/demodulator)
    See data circuit-terminating equipment.

    more data bit (M-bit)
    A bit in a data packet header that indicates the following packet contains logically related data.

    N

    network user address (NUA)
    Up to 15 decimal digits that serve to identify a data terminal equipment (DTE). The first four digits (digits 0 to 3) of an NUA are known as the data network identification code (DNIC); they identify the country and the service within the country. Digits 4 to 12 indicate the national number. The final two digits may be used for a subaddress.

    NUA
    Network user address.

    O

    octet
    A byte composed of eight binary elements. (I)

    optional network facilities
    Facilities a network user may request when establishing a virtual circuit.

    P

    packet
    In data communication, a sequence of binary digits, including data and control signals, that is transmitted and switched as a composite whole. (I)

    packet assembler/disassembler (PAD)
    An equipment used for connecting asynchronous (start/stop) devices to an X.25 network.

    packet level
    A part of CCITT Recommendation X.25 that defines the protocol for establishing logical connections between two DTEs and for transferring data on these connections.

    packet switching
    The process of routing and transferring data by means of addressed packets so that a channel is occupied only during the transmission of a packet. On completion of the transmission, the channel is made available for the transfer of other packets. (I)

    packet switching data network (PSDN)
    A communications network that uses packet switching as a means of transmitting data.

    PAD
    Packet assembler/disassembler.

    PAD parameters
    A set of values that define the behavior of the PAD. They can be changed either by the remote DTE (using X.29 commands) or by the local asynchronous device (using X.28 commands).

    permanent virtual circuit (PVC)
    A virtual circuit that has a logical channel permanently assigned to it at each data terminal equipment (DTE). A call establishment protocol is not required. A permanent virtual circuit is the packet network equivalent of a leased line.

    physical level
    A standard that defines the electrical, physical, functional, and procedural methods used to control the physical link running between the DTE and the DCE.

    program segment prefix (PSP)
    A block of 256 bytes that DOS places before the beginning of every application.

    protocol
    A set of semantic and syntactic rules that determines the behavior of functional units in achieving communication. (I)

    PSDN
    packet switching data network.

    PTT
    Post Telephone and Telegraph Administration.

    PVC
    permanent virtual circuit.

    Q

    qualifier-bit (Q-bit)
    A bit in a data packet header indicating the type of information contained in the packet. A 0-bit indicates control information, and a 1-bit indicates data.

    R

    RCM
    Realtime control microcode.

    realtime control microcode
    Firmware supplied with the IBM X.25 Interface Co-Processor/2 adapter.

    reset procedure
    On a virtual circuit, reinitialization of data flow control. At reset, all data in transit are eliminated, but the connectivity of the logical channel is maintained.

    restart procedure
    A procedure used by a DTE or DCE to clear all virtual calls and reset all permanent virtual circuits.

    RIC
    Realtime Interface Co-processor. The generic name given to a family of IBM communication adapters.

    S

    SNA
    Systems Network Architecture.

    SVC
    Switched virtual circuit.

    switched virtual circuit (SVC)
    A virtual circuit that is requested by a virtual call. It is released when the virtual circuit is cleared.

    synchronous data transfer
    A physical transfer of data to or from a device that has a predictable time relationship with the execution of an I/O request.

    T

    TSR
    Terminate-and-stay-resident program.

    V

    virtual call
    See virtual call facility.

    virtual call facility
    In data communication, a user facility in which a call setup procedure and a call clearing procedure determine a period of communication between two data terminal equipments (DTEs) in which user data is transferred in the network in the packet mode of operation. All user data is delivered from the network in the order it is received by the network. It is the packet network equivalent of a dialled line.

    virtual circuit
    In packet switching, the facilities provided by a network that give the appearance to the user of an actual connection. (T)
    A logical connection established between two data terminal equipments (DTEs).

    W

    window
    In data communication, the number of data packets a DTE or DCE can send across a logical channel before waiting for authorization to send another data packet. The window is the main mechanism of pacing, or flow control, of packets.

    X

    X.21
    In data communication, a recommendation of the CCITT that defines the interface between data terminal equipment and public data networks for digital leased and circuit switched synchronous services.

    X.21 bis
    An interim standard that allows existing V-series equipment to be connected to public data networks.

    X.25
    In data communication, a recommendation of the CCITT that defines the interface between data terminal equipment and packet switching networks. Recommendations X.25 (1976), X.25 (Geneva 1980), and X.25 (Malaga-Torremolinos 1984) have been published.

    X.25 network
    A service providing packet-switched data transmission that conforms to Recommendation X.25 adopted by the CCITT.

    X.25 verb
    In IBM X.25 Co-Processor Support Program, a library routine provided for the management, control, or use of an X.25 network. An external verb can be issued by an application; an internal verb is provided for management or for data link control and is not available to applications.

    XVRB
    X.25 verb request control block.

    X.3
    The CCITT recommendation that specifies the service provided to an asynchronous (start/stop) device by a packet assembler/disassembler (PAD).

    X.25 verb request control block (XVRB)
    A block passed to IBM X.25 Co-Processor Support Program that contains data about a verb being issued.

    X.28
    The CCITT recommendation that specifies the user interface between an asynchronous (stop start) device and a packet assembler/disassembler (PAD).

    X.28 command string
    A character string sent to the PAD by the asynchronous device to control it.

    X.28 control verb
    One of a series of verbs used by the application to control the PAD.

    X.28 PAD message
    A message exchanged between the PAD and the remote DTE using the X.29 protocol.

    X.28 PAD signal
    A character string sent by the PAD to the asynchronous device which informs it of an asynchronous event (for example, the call has been cleared).

    X.28 response string
    A character string sent by the PAD to the asynchronous device which responds to a previous X.28 command string.

    X.29
    The CCITT recommendation that specifies the user interface between a DTE and a remote packet assembler/disassembler (PAD).
     

    Last modified: March 25, 1999