X.25 communications can be used to provide a network service for higher-level protocols, such as SNA, or directly with commands or the API. The X.25 commands can be used as soon as you have set up X.25 communications. The application programming interface (API) can be used to write applications tailored to specific needs. The following sections discuss portions of the X.25 API:
Before you can use the COMIO emulation X.25 API, the X.25 Licensed Program must be installed and configured, and emulation ports added as required. You also need access to a C compiler.
The X.25 API includes a library of C subroutines that use the services of the X.25 adapter and adapter code. Application programs call these subroutines to access X.25 functions. The subroutines use a number of structures to pass information between the X.25 functions and the application programs. Further information can be found in:
The X.25 API provides the following types of identifiers for use in programs:
In addition to the subroutine library and the header files for the structures, there are example programs that demonstrate the use of the subroutines. Further information can be found in "X.25 Example Programs".
Background information for using the subroutines is included in "Processing Calls with the X.25 API".
For many of the subroutines, parameters are placed in a structure, and the subroutine is passed a pointer to this structure. Definitions of these structures are supplied as a header file, /usr/include/x25sdefs.h. Include the following line in programs:
#include <x25sdefs.h>
"x25sdefs.h File for X.25" in AIX Files Reference lists all the structures included in the /usr/include/x25sdefs.h file.
Each of the fields in a structure has an associated flag. This flag tells the API whether the associated field has been used. If the corresponding flag has not been set, the field is ignored by the API. To use the flag, which is a constant, OR it with the unsigned long flags in the structure. This sets the appropriate bit in the flags field.
Before invoking a subroutine, the appropriate flags field must be set to 0 or to a particular flag constant. For example, to set the flags field to 0 before invoking the x25_call subroutine, use the following:
cb_call.flags = 0
To indicate that the link_name field is being used, before invoking the x25_call subroutine, use the following:
cb_call.flags = X25FLG_LINK_NAME
Some flags, for instance, X25FLG_D_BIT, do not correspond to structure elements.
The /dev/x25sn special file is provided through the COMIO emulation migration.
The emulator supports the /dev/x25sn special file as a character-multiplex special file. The special file must be opened for both reading and writing (O_RDWR). There are no particular considerations for closing the special file. The special file name used in an open call differs depending on how the device is to be opened. Types of special file names are:
| /dev/x25sn | Starts the device handler on the next available port. |
| /dev/x25sn/R | Starts the device handler for updating the routing table. |
The X.25 subroutines set the x25_errno and errno flags to indicate error conditions.
If an error condition results from an X.25 API subroutine call, it is indicated in one of the following ways:
In a production program, check for each condition that is likely to occur, giving the end user a message telling what action to take. The code example for the x25_link_statistics subroutine shows how to do this. All the other subroutines can be handled in a similar way.
"API Error Codes" lists the error codes that may be returned by X.25 subroutines.
To improve performance, applications should be divided into multiple processes. For instance, you can start a separate process for sending or receiving data. Or, you can have one process to listen for calls and one process to make calls.
Child processes should not be created while a call is being established or after an incoming call has been received. However, you can start a process:
After an incoming call is successfully received, an open file is created in the current process that is used by the API library functions for subsequent communication on this connection. The file is closed when the call is cleared. Creating child processes after the call is received may leave the file open indefinitely, leading to an error due to reaching the limit on open files (errno 23).
A connection identifier can be used by the process that made or received the call, or by the process' children. It cannot be used by other processes.
A child process can use a virtual circuit established by its parent, but a parent process cannot use a virtual circuit established by its child.