Fourth Edition, June 1996
Introducing X.25 communications
Using the X.25 application programming interfaces
X.25 application programming verbs
Developing and executing application programs
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.
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/2The 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.
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.
The book contains the following:
A glossary is provided at the back of the book.
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.
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 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. (*)
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.
The IBM X.25 Co-Processor Support Program consists of these components:
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".)
The IBM X.25 Co-Processor Support Program provides support for:
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.
Packet switching has its own terminology; you need to be familiar with the following terms:
This is a computer, or other terminal, which uses the network for communication.
This is the device at the point of access to the network through which the DTE is connected to the PSDN.
This is a virtual circuit that is established by a virtual call request. It is released when the virtual call is cleared.
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.
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".
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.
The X.25 recommendation concerns itself with three levels of DTE to DCE connection:
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.
Packets of different types fulfill different functions. Typical uses of packets are:
Note: Most packets have two different names: one applies to a packet being sent to the network, the other to the same packet when it is transmitted from the network to the receiving DTE.
For example, a Call Request packet is sent by a computer that wants to make a call. This becomes an Incoming Call packet when the network passes it to the receiving computer or terminal.
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.
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.
The use of different packets in a "conversation" between two computers on a switched virtual circuit is described in the following sections.
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.
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.)
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.
+--------+------------+--------+ | 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.
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:
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 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.
(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.
You can create applications, the tasks of which run either in foreground mode or background mode.
Foreground tasks are suitable for interactive X.25 applications.
Background tasks are useful when more than one X.25 application is loaded at the same time, or when the PS/2 is needed for other applications while the X.25 application is running.
You start the application that contains the foreground task by typing its name at the DOS prompt. For example:
C:> EXAMPLEF parameter1, parameter2loads 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:
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, parameter2loads 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:
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.)
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.
DOS function calls may be used within a background task with the following exceptions:
The following stack sizes must be calculated when background tasks are being used:
The stack required for each background task can be calculated as the sum of the following values:
Note: The space required to service normal DOS interrupts has been included in the API requirements.
The stack required for the application must be allocated at link time. It is calculated as the sum of the following values:
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:
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 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.
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.
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:
There are three modes you can specify for a link:
At any time the link is in one of seven states, which are controlled by the above three verbs. These are:
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.
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.
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.
Note: The X25Status and X25LinkStatus verbs are identical; the management task can request X25Status, other tasks must request X25LinkStatus.
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.
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:
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.
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.
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:
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.
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.
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.
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.
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:
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.
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:
The first step is performed by the application, the rest are performed inside 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:
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.
You must use a termination verb to end a task. The X25Term verb ends a management task, and X25AppTerm ends a nonmanagement task.
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:
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.
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.
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.
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.
The API assigns a unique connection ID to each virtual circuit that a task establishes. Virtual circuits are established when:
or
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.
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.
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:
The connection ID allocated on the immediate completion of X25CallReceive then becomes valid.
An SVC is cleared when a task:
or
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.
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.
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.
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 (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.
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.
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.
A task can use an established SVC or an allocated PVC to send and receive Data packets across the network.
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.
The task calling X25DataSend can request, by setting an indicator in the verb request block, that the M-bit is set on all packets created by one X25DataSend request. The M-bit in a packet shows that more packets of related data are to follow the current one. The task sends later data by requesting another X25DataSend.
Note: The M-bit option is only valid with X25DataSend if the data length in the buffer is equal to an integral number of packets.
Note: A task must set the Q-bit to the same value for all data within an M-bit sequence. For example, if a task sets both the Q-bit and M-bit on with the first X25DataSend verb, then it must also set the Q-bit on with the next X25DataSend.
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.
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:
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.
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:
Note: A Q-bit change refers to any packet in a sequence with a setting that is different from the first setting. If a Q-bit change is detected, the Q-bit returned is as in the first packet. Because the &Delta.Q-bit; is set, the actual Q-bit that was received can be determined.
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.
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:
or
When the Reset Request packet is sent, no further data can be sent on the virtual circuit until:
or
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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:
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.
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:
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.
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:
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:
The API clears an incoming call if it cannot find a routing list entry match for the call.
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:
If a task specifies higher values than those configured for the link, the API reduces the values to the maximum values configured for the link. A task can query the values negotiated when a call was established by using the X25VCStatus verb.
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.
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.
The following restrictions apply to applications that use the IBM X.25 Co-Processor Support Program:
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:
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.)
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.
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].
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:
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.
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.
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:
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:
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:
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.
These are set by the API to indicate the packet header flags for this data [X25DataReceive]. The defined values are bit settings:
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].
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:
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:
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].
Set by the task, this is the number of bytes of data to be sent (the maximum is 64K -16) [X25Interrupt X25DataSend, X25DataReceive].
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.
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.
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:
The API places the semaphore value from the completed verb in this field of the XVRB of the X25SemWait verb.
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.
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].
A pointer is set by the API in the X25SemWait XVRB. It points to the XVRB of the verb that has completed.
A number identifying a PVC, as described in the IBM X.25 Co-Processor Support Program: User's Guide [X25PVCAlloc].
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.
This field shows the type of traffic to be carried over the virtual circuit. [X25Call, X25CallAccept]. Values are:
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.
This field indicates that current statistics are to be stored [X25Trace]. It can have one of the following values:
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:
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].
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].
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:
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:
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:
When X25Trace completes, this parameter indicates the end of the most recent trace or statistics record in the buffer.
This indicates the length of the trace buffer in bytes. It is set by the task.
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.
This can be set to one of these values:
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].
This field is set by the API to show the type of data it has passed to the task [X25DataReceive]. Values are:
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.
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].
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.
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.
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.
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).
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).
Minimum size is zero, maximum:
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.
Minimum 0, maximum 15 bytes. The field must be large enough to hold the NUA even if a nickname is used.
Minimum 0, maximum 109 bytes. Standard CCITT meaning.
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.
This is the local DTE being called. A task can set up an NUA or a nickname in the directory.
This is the remote DTE that is making the call. It can be an NUA or a nickname.
If present, this field contains the Call User Data that the API writes into the Call Accept packet.
When present, this field contains the Facilities information that the API writes into in the Call Accept packet that it creates.
The remaining fields have the same meaning as for X25Call.
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.
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.
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.
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.
The remaining fields have the same meaning as for X25Call.
This is the local DTE being called, as set by the remote DTE.
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.
This field contains the Call User Data (if present) from the received Call Request packet.
This field contains Facilities information (if present) from the Call Request packet.
The remaining fields have the same meaning as for X25Call.
Data that the task wants to send. Minimum 1 byte, maximum 64K -16.
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.
These contain the following fields:
Each contains two fields:
Data that the task wants to send in the Interrupt packet. Minimum 1 byte, maximum 32 bytes.
This is required by the X25Status and X25LinkStatus verbs. It contains the fields:
Each entry contains the following fields:
This is used by X25Name. It contains the following fields:
Each entry contains five fields:
This is a free-format ASCII buffer that contains trace information and statistics. It is a "circular" buffer.
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:
The following field is present only for supervisory frames:
The remaining fields are present only for information frames:
The trace format of a packet-level packet is:
PX VC NAME packet_data
The remaining fields depend on the packet type and, if applicable, include:
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=2which 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=17This 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.
This contains the following fields:
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.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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:
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 | +-------------+-----+-----+--------------------------------------------------+
+====================+=====+=====+===========================================+ | 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 | +--------------------+-----+-----+-------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
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 | +--------------------+-----+-----+-------------------------------------------+
This data buffer is optional. It has the same layout as that for X25Call as shown in topic reference #9.
See topic reference #12 for the meanings of these codes.
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
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 | +-------------+-----+-----+--------------------------------------------------+
This data buffer is optional. It has the same layout as that for X25Call reference #9.
See topic reference #12 for the meanings of these codes.
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
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 | +-------------+-----+-----+--------------------------------------------------+
This data buffer has the same layout as that for X25Call as shown in topic reference #9.
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.)
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 | +-------------+-----+-----+--------------------------------------------------+
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 | +--------------------+-----+-----+-------------------------------------------+
See topic reference #12 for the meanings of these codes.
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:
or
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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:
or
PVCs are not applicable to X25LinkAuto. X25LinkAuto puts the link into autoconnect mode. The link is connected by X25Call and disconnected by X25CallClear.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
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 | +--------------------+-----+-----+-------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
This is the same as for X25Deafen, see topic reference #10.
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
+====================+=====+=====+===========================================+ | 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 | +--------------------+-----+-----+-------------------------------------------+
See topic reference #12 for the meanings of these codes.
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).
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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".
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 | | | | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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.
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 | +-------------+-----+-----+--------------------------------------------------+
This data buffer is the same as for X25LinkStatus, see topic reference #11.
See topic reference #12 for the meanings of these codes.
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".)
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 | +-------------+-----+-----+--------------------------------------------------+
See topic reference #12 for the meanings of these codes.
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
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.
Table 30. X25Trace verb request block
See topic
reference #12 for the meanings of these codes.
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.
Table 31. X25VCStatus verb request block
Table 32. X25VCStatus data buffer
See topic
reference #12 for the meanings of these codes.
X.25 processing has ended abnormally.
The API detected a DOS error. The DOS error code is contained in the
completion code field of the XVRB.
The API detected an X.25 error. The X.25 error code is contained
in the completion field of the XVRB.
The IBM X.25 Co-Processor Support Program has not been loaded.
An X25SemWait request was made with a time-out value of zero
and no verbs had just completed.
The verb has been accepted and is being processed.
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.
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.
X.25 processing has ended abnormally.
The X.25 subsystem has already been initialized.
The adapter for this link is not installed, or cannot be accessed.
The adapter is managing D-bit acknowledgment for this virtual
circuit.
An error has occurred on the adapter. The specific error code has
been logged.
The task has already initialized X.25 communications.
The task is not initialized for X.25 communications.
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.
The verb was terminated by an X25SemClear verb.
The task has requested termination of X.25 processing.
The specified length of the buffer was insufficient to hold all the
data to be returned.
The call with this connection ID is already accepted.
The call has been cleared. No more data can be exchanged.
The call is in the process of being cleared. No more data can be
exchanged.
The length must be less than or equal to 15 bytes.
The name specified was not found in the directory.
An invalid character was specified in the called address. Addresses
must be specified in Binary Coded Decimal (BCD).
Length must be less than or equal to 15 bytes.
The name specified was not found in the directory.
An invalid character was specified in the calling address. Addresses
must be specified in Binary Coded Decimal (BCD).
The call associated with this connection ID has not been accepted.
This verb cannot be processed until the call is accepted.
An attempt was made to access a connection ID that is still waiting
for an incoming call.
A Clear Indication packet arrived while a Clear Request packet was
being processed.
An X25CallAccept verb was issued with a connection ID set up
by an X25Call verb.
The value of the parameter that specified D-bit usage was not valid.
The X25Ack verb was issued on a virtual circuit that was
not set up to use D-Bit acknowledgment.
Some data was discarded when the verb was terminated by an
X25SemClear verb.
Unexpected DOS error stopped X.25 processing. See error log.
There is already an X25Event request outstanding for this
task.
The X.25 subsystem detected error in Facilities field coding.
Length must be less than or equal to 109.
The X.25 subsystem is not initialized.
There must be at least one byte of interrupt data. (There may be up to
16 bytes of data using CCITT 1984.)
An Interrupt packet has been sent on this virtual circuit and not yet
been confirmed.
The specified buffer length is too small to contain the minimum amount
of data that is returned.
The call buffer that has been specified contains invalid information.
The cause code must be 0 or, if CCITT 1984, the most significant bit
must be set to 1.
The specified connection identifier is not associated with a virtual
circuit.
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.
An invalid parameter value was used to specify the conversion of an
incoming call to a nickname.
The specified link name is invalid.
Connect mode is invalid for the specified link (for example,
Transpac VX32 DCE).
An invalid task initialization parameter has been specified.
The PVC number is not configured for the specified link.
An invalid processing state has been detected.
The option for immediate or delayed termination specified for the
X25LinkStatus or the X25Status verb was invalid.
The task identifier is not valid for a user task.
The option for immediate or delayed termination specified for the
X25Term verb was invalid.
The parameter value used to specify the destination of the trace data
is not valid.
Specified trace name not found.
The parameter value used to specify the required statistics information
is invalid.
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.
The version identifier did not match that expected by the API.
Specified link is already in Autoconnect mode.
Specified link is already in Connect mode.
Specified link is already in Disconnect mode.
Specified link is in Disconnect mode; it must be put in Connect mode
or Autoconnect mode before it can be used.
There is an error on the link at the physical level.
There is an error on the link at the frame level.
There is an error on the link at the packet level.
M-bit was specified but the data length was not an integral number of
packets.
The value of the parameter specifying M-bit usage was not valid.
An attempt was made to access a connection ID that had not yet been
allocated by the API.
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.
A data length of zero was specified where at least one byte of data is
needed. For example, X25DataSend.
No D-bit acknowledgment is outstanding on this virtual circuit.
No directory entries match the supplied fields.
There is more than one link in the system and no link name was
specified.
The memory pool became exhausted while processing the verb.
An X25ResetConfirm verb was issued for a virtual circuit that
had not received a Reset Indicator packet.
No semaphores were cleared, because no active verbs were found that
matched the request.
There is no virtual circuit available on the required link. No
further call can be made until an existing call is cleared.
The verb completed successfully.
The PVC has been freed, no more data may be exchanged.
The PVC is already allocated.
The value of the parameter specifying Q-bit usage was not valid.
A Reset Indication packet arrived while this Reset Request packet
was being processed.
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.
The value of the parameter to specify an SNA or native X.25
connection was invalid.
One or more errors occurred during termination. Specific error(s)
(freeing virtual circuits, disconnecting links, and so on) have been
logged.
The X.25 subsystem is already in delayed termination.
The X.25 subsystem is already in immediate termination.
A trace is already running for the specified link.
Length must be less than or equal to 16 bytes (or less than or equal
to 128 bytes for Fast Select).
One or more active PVCs or SVCs were freed or cleared to service this
verb.
One or more errors were detected while freeing PVCs or clearing SVCs.
The virtual circuit has received a remote Reset Indication packet.
The virtual circuit is being reset, no further data exchange is
possible until the reset is complete.
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:
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.
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.
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".
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.)
The PAD may be in one of two states:
The way in which communication is established with the API PAD depends
on whether the application task wants to originate or receive calls.
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.
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.
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:
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.
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.
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.
Table 33. X28CallReceive verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 34. X28Close verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 35. X28DataReceive verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 36. X28DataSend verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 37. X28Open verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 38. X28SendBreak verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
Returns the current line status:
The parameter values are returned in a text message in the form:
Where:
The following table shows the PAD parameters that are defined in X.25.
The following values define parameter settings for the standard
profiles.
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):
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.
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".
Table 40. X29Call verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 41. X29CallReceive verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 42. X29ReadParam verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 44. X29SendBreakInd verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
A task uses X29SendInvitationToClear to
send an "Invitation to Clear" PAD message to a PAD on a virtual call.
Table 45. X29SendInvitationToClear verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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".
Table 46. X29SendReselectInvn verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 47. X29SetAndReadParam verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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.
Table 48. X29SetParam verb request block
These codes have the same meanings as for X.25.
See topic
reference #12.
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 Assembler include files are:
The C include files are:
The Pascal include files are:
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
This glossary includes definitions from:
B C D F H I L M N O P Q R S T V W X
Last modified: March 25, 1999
Verb request block for X25Trace
+==============+=====+=====+=================================================+
| 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
X25VCStatus
Purpose
Verb request block for X25VCStatus
+=============+=====+=====+==================================================+
| 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
+====================+=====+=====+===========================================+
| 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
Summary of API return and completion codes
Return codes
X25_ABEND
X25_DOS_ERROR
X25_ERROR
X25_NO_SUBSYSTEM
X25_NO_VERB_COMPLETE
X25_OK
X25_SYS_ERROR
X25_TIME_OUT
Completion codes
(Ref #12.)
X25_ABEND
X25_ACTIVE
X25_ADAPTER_ACCESS_ERROR
X25_ADAPTER_ACK_SELECTED
X25_ADAPTER_ERROR
X25_APP_ACTIVE
X25_APP_INACTIVE
X25_APP_LIMIT_EXCEEDED
X25_APP_REQ_CLEAR_SEM
X25_APP_TERMINATING
X25_BUFFER_TOO_SHORT
X25_CALL_ALREADY_ACCEPTED
X25_CALL_CLEARED
X25_CALL_CLEARING
X25_CALLED_ADDRESS_LEN_ERROR
X25_CALLED_ADDRESS_NAME_ERROR
X25_CALLED_ADDRESS_VALUE_ERROR
X25_CALLING_ADDRESS_LEN_ERROR
X25_CALLING_ADDRESS_NAME_ERROR
X25_CALLING_ADDRESS_VALUE_ERROR
X25_CALL_NOT_YET_ACCEPTED
X25_CALL_NOT_YET_RECEIVED
X25_CLEAR_COLLISION
X25_CONNECTION_OUTGOING
X25_DBIT_INDICATOR_ERROR
X25_DBIT_NOT_SELECTED
X25_DISCARD_APP_REQ_CLEAR_SEM
X25_DOS_ERROR
X25_EVENT_ALREADY_REQUESTED
X25_FACILITIES_ERROR
X25_FACILITIES_LEN_ERROR
X25_INACTIVE
X25_INTERRUPT_DATA_LEN_ERROR
X25_INTERRUPT_IN_PROGRESS
X25_INVALID_BUFFER_LEN
X25_INVALID_CALL_DATA
X25_INVALID_CAUSE_CODE
X25_INVALID_CONNECTION_ID
X25_INVALID_CONNECTION_MODE
X25_INVALID_CONVERT_ADDR_OPT
X25_INVALID_LINK_NAME
X25_INVALID_LINK_TYPE
X25_INVALID_PARAMETER
X25_INVALID_PVC_NUMBER
X25_INVALID_STATE
X25_INVALID_STATUS_OPTION
X25_INVALID_TASK_ID
X25_INVALID_TERM_OPTION
X25_INVALID_TRACE_DEST_OPTION
X25_INVALID_TRACE_NAME
X25_INVALID_TRACE_STATS_OPTION
X25_INVALID_VERB_ID
X25_INVALID_VERSION_ID
X25_LINK_ALREADY_AUTOCONNECT
X25_LINK_ALREADY_CONNECT
X25_LINK_ALREADY_DISCONNECT
X25_LINK_CLOSED
X25_LINK_ERROR_LEVEL_1
X25_LINK_ERROR_LEVEL_2
X25_LINK_ERROR_LEVEL_3
X25_MBIT_AND_INCOMPLETE_ERROR
X25_MBIT_INDICATOR_ERROR
X25_NO_CONNECTION_ALLOCATED
X25_NO_CONNECTION_AVAILABLE
X25_NO_DATA
X25_NO_DATA_TO_ACK
X25_NO_DIRECTORY_MATCH
X25_NO_LINK_NAME
X25_NO_MEMORY
X25_NO_RESET_TO_CONFIRM
X25_NO_SEMAPHORES_CLEARED
X25_NO_VC_AVAILABLE
X25_OK
X25_PVC_FREED
X25_PVC_IN_USE
X25_QBIT_INDICATOR_ERROR
X25_RESET_COLLISION
X25_SEM_CLEARING
X25_SNA_INDICATOR_ERROR
X25_TERM_ERROR
X25_TERMINATING_DELAYED
X25_TERMINATING_IMMEDIATE
X25_TRACE_ACTIVE_ON_LINK
X25_USER_DATA_LEN_ERROR
X25_VC_FREED
X25_VC_FREE_ERROR
X25_VC_RESET
X25_VC_RESETTING
X.3, X.28, and X.29 support
Introducing X.3, X.28, and X.29 support
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.
| 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
Verbs that are common to X.25 and X.28
Verbs that are unique to X.28
PAD states
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
Making a call through the API PAD
Receiving a call through the API PAD
Sending and receiving data through the API PAD
Notes:
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.
Descriptions of the X.28 API verbs
(Ref #15.)
X28CallReceive
Purpose
Verb request block for X28CallReceive
+=============+=====+=====+==================================================+
| 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
X28Close
Purpose
Verb request block for X28Close
+=============+=====+=====+==================================================+
| 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
X28DataReceive
Purpose
Verb request block for X28DataReceive
+=============+=====+=====+==================================================+
| 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
X28DataSend
Purpose
Verb request block for X28DataSend
+=============+=====+=====+==================================================+
| 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
X28Open
Purpose
Verb request block for X28Open
+=============+=====+=====+==================================================+
| 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
X28SendBreak
Purpose
Verb request block for X28SendBreak
+=============+=====+=====+==================================================+
| 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
X.28 String commands
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.
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>
PAD parameters
(Ref #16.)
+===========+================================+================================+
| 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
Profile 0 (default)
Profile 1
Profile 90 (CCITT simple standard profile)
Profile 91 (CCITT transparent standard profile)
Description of the X.29 API
.
.
Summary of the unique X.29 verbs
Descriptions of the X.29 API verbs
X29Call
Purpose
Verb request block for X29Call
+----------------------------------------------------------------------------+
| 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
X29CallReceive
Purpose
Verb request block for X29CallReceive
+=============+=====+=====+==================================================+
| 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
X29ReadParam
Purpose
Verb request block for X29ReadParam
+==============+=====+=====+=================================================+
| 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
+===============+=====+=====+================================================+
| 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
X29SendBreakInd
Purpose
Verb request block for X29SendBreakInd
+==============+=====+=====+=================================================+
| 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
X29SendInvitationToClear
Purpose
Verb request block for X29SendInvitationToClear
+===============+=====+=====+================================================+
| 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
X29SendReselectInvn
Purpose
Verb request block for X29SendReselectInvn
+===============+=====+=====+================================================+
| 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
X29SetAndReadParam
Purpose
Verb request block for X29SetAndReadParam
+===============+=====+=====+================================================+
| 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
X29SetParam
Purpose
Verb request block for X29SetParam
+==============+=====+=====+=================================================+
| 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
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 following translators are supported:
Assembler support
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 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 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 example application
General points
Task initialization
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.
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
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
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.
Link management
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
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
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
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
Glossary
A