Using the Eicon X.25 Development Tools

---

This section introduces the Eicon X.25 Development Tools. It presents an overview of the Eicon Network Service Provider and the Eicon X.25 Development Tools, and describes how they function in the Linux environment.

For more information, refer to the following:

	X.25 User-Facility Support and Code References
	X.25 Development Tools Error Messages
	X.25 Development Tools Constants and Structures
	X.29 Call User Data Format
	Key Packet Formats

For additional information on using Eicon X.25 Development Tools commands, see the HTML pages located in the usr/lib/eicon/docs directory.

 
Eicon X.25 Development Tools

---

The X.25 Development Tools is one in a series of Application Development Tools available from Eicon Networks. Application Development Tools allow programmers to write user applications that can communicate over the X.25 protocol that resides in the Eiconcard.

The X.25 Development Tools provides a high-level interface that consists of a set of C functions used to perform X.25 network-level requests. This allows you to write your own custom applications that use the full facilities of the Eiconcard and the applicable protocol software.

The X.25 Development Tools allows user-developed programs to communicate with an X.25 network through a set of high-level-language functions via the Eiconcard communications adapter. The X.25 Development Tools supports Permanent Virtual Circuits (PVCs) and Switched Virtual Circuits (SVCs). It can control up to 254 virtual circuits per adapter. It also supports optional user facilities such as Network User Identification (NUI), Reverse Charging, Call User Data, Closed User Groups (CUGs), throughput class negotiation, and window size negotiation.

 
Using the X.25 Development Tools

The Appendices contain descriptions of all constants, data structures and error codes that are used in the X.25 Development Tools. It is strongly recommended that you use these predefined constants and data structures in your programs. This practice will isolate your programs from any changes that may occur to values used in the X.25 Development Tools.

Pointers to various data structures are required in many of the library functions. Due to the asynchronous operating nature of the library in No-wait mode, it is important that the data structures referred to by the library functions remain active. This may not be the case when using an automatic variable allocated upon a function entry (see Variable Allocation). The application must also ensure that such variables are referenced by at most one function at a time.

The order of the library names is important: libEx25.a must be specified before libEec.a.

The application should include the x25.h file. To compile and link an application program, the option -lEx25 -lEec must be given as linker options on the compiler command line.

	-lEx25 refers to the libEx25.a library found in the /usr/lib directory.
	-lEec refers to the libEec.a. A library found in the /usr/lib directory, which must be installed for the X.25 library to work properly. This library is provided with Eicon Networks' gateway products for Linux.

Note: The include files for the X.25 Development Tools are located in /usr/include/eicon.

Note: The x25.h file automatically includes two other definition files: x25err.h and x25proto.h.

Sample Programs

The following sample application programs are included in the /usr/include/eicon/sample/x25toolkit directory:

Buffers

A user application must dynamically allocate the required buffer space before sending or receiving data. This is done using the x25alloc() function. This function returns a pointer to a buffer. Both the x25send() and x25recv() functions require a buffer allocated by x25alloc() to work properly. The specified buffer size may not be more than 65524 bytes. This is determined by the length of a buffer being stored in a two-byte word (65535 bytes) of which the X.25 Development Tools uses 11 bytes to store internal information.

The use of buffers is controlled by the X.25 library to ensure a buffer is not freed while in use (x25free() would return -1 with x25error() returning EX25BUFUSED), or that a buffer is not re-used when already in use (x25send() or x25recv() fail with x25error(), again returning EX25BUFUSED).

All buffers allocated by the x25alloc() function must also be freed by the x25free() function. Buffers that are not allocated by x25alloc() must not be freed by x25free().

Addresses

All local_dte and remote_dte strings (X.25 addresses) should be declared as variables of length X25_ADDRLEN+X25_ADDREXT+2 bytes, as in:

char local_dte[X25_ADDRLEN+X25_ADDREXT+2];

char remote_dte[X25_ADDRLEN+X25_ADDREXT+2];

X.25 addresses cannot contain more than 15 characters (the value of X25_ADDRLEN) unless you specify them as extended addresses. However, since these strings must be NULL terminated, provisions should be made for the additional 2 characters ("\0").

For the x25xcall() and x25xlisten() functions, the local_dte and remote_dte parameters are null-terminated, non-empty strings of digits "0" to "9" inclusive (ASCII 30h to 39h). For the x25xlisten() function, the local_dte and remote_dte parameters will also accept the "*" and "?" meta-characters, as well as the empty string. The two addresses, remote_dte and local_dte, are optional for call or listen requests and may be replaced by NULL pointers.

Upon return of the x25xlisten() function, the remote_dte parameter may be overwritten (if it is not a NULL pointer) with the address of the matching call request. This is why the X.25 address variables must be buffers of X25_ADDRLEN + X25_ADDREXT + 2 bytes.

If extended addresses are used they must be specified in the following format:

XXX.YYY

where XXX is a string of 0 to 15 digits representing a standard address and YYY is an extension string of 0 to 40 digits. A period separates the two parts. For the x25xlisten() function, the extension string may also contain the "*" and "?" meta-characters.

Port Numbers

The port parameter used by call or listen functions specifies a logical number mapping to a physical port on an Eiconcard. Each physical port on the Eiconcard is uniquely identified. You can have many applications running concurrently, each of which can be dedicated to a specific port.

On an Eicon gateway, more than one port may be active at a time. The ports are numbered as 1 to 48 or FFh to D0h. The logical port mapping is defined during configuration and is stored in the configuration file (ec.cfg). A copy of the mapping is kept in the Eiconcard driver.

Call Matching

When a CALL-INDICATION packet is received from the network, the X.25 software tries to match the call with the list of pending LISTEN requests.

Each LISTEN request is tested against six criteria for matching or rejecting a call. The six criteria are as follows, in order of priority:

Every LISTEN request waiting for a Call is checked against the CALL-INDICATION using all six criteria. If a match occurs then this match is stored and a check is made to see if a better match can be reached with another LISTEN request. This is done by comparing the lengths of the matching strings of each of the six criteria in the order of priority. A precise match has a higher priority than a match with wildcards.

Each digit of the local address in the LISTEN request is compared with the corresponding digit in the Called DTE address of the CALL-INDICATION packet.

If the specified digit is "?" then any address digit is accepted and the next digit is checked. If the specified digit is "*" then the check is immediately considered a success. If the digit is a value 0 to 9 then the address digit in the CALL-INDICATION packet must be exactly that value. If this address match fails then the next LISTEN request is tried. The same check is repeated for the local extension, the remote address and the remote extension.

Call facility codes are then verified as follows:

0x01

If the facility code 0x01 (reverse charging) is included in the LISTEN request then incoming calls will be accepted if Bit 0 of the incoming call value matches Bit 0 of the parameter value. If not used then any incoming call will be accepted.

Fast select acceptance may be specified by setting Bit 6 and 7 of the parameter value accordingly. These bits are not matched for call acceptance against incoming call values.

0x42

If the facility code 0x42 is included in the LISTEN request then the packet size is downward negotiated to the two-byte value associated with this code. The two bytes specifying the packet size should be the same.

0x43

If the facility code 0x43 is included in the LISTEN request then the window size is downward negotiated to the two-byte value associated with this code. The two bytes specifying the window size should be the same.

In the end, the "best fit" LISTEN request is selected. If no match is found, the call is rejected and diagnostics are returned. These could be one of the following:

Call Rejection Diagnostics

If the test of facilities fail, the Rejection Code is set to 0x42 (Facility parameter not allowed). If all the above tests succeed, the Rejection code is set to 0x00 (No additional information) and the LISTEN request is marked as a possible successful match.

If the User data fields are of equal length then the call is accepted, the matching process is terminated, and the LISTEN request is completed.

Otherwise, the next LISTEN is tried for a better fit. The best match is that with the largest data length. In the end if no better match is found the marked request is completed.

Qualified Listen Handling

Qualified Listen allows the user to perform an additional level of type checking to all incoming calls. This feature provides added security whenever it is required. Qualified Listen is available only with the x25xlisten() function by setting the Qualifier Bit (see Bit Field Manipulation).

The application must respond to the incoming call by either accepting it (with x25accept()) or rejecting it (with x25xhangup()). No automatic handling of the call is performed by the X.25 software on the Eiconcard.

Packet Handling

Some packets are automatically generated by the Eiconcard if the connection is not in End-to-End Confirmation mode. These include the following:

Request Cancelling

Any x25recv(), x25send(), x25sendexp(), x25sendconfirm(), x25xcall(), or x25xlisten() request may be cancelled if it is submitted to the Eiconcard and it is still pending. Once a request is successfully cancelled, it completes with ENETCMDCANC and the x25cancel() function completes with 0. The x25done() function must be called for the cancelled request, but it is not necessary for the x25cancel() function itself. The Eiconcard will generate a CLEAR packet when cancelling any send request.

Connection ID

To establish a dialog between your application and an application on a remote machine, a call or listen function must be used to establish a virtual connection. These include one of the following functions: x25xcall(), x25pvccall(), or x25xlisten().

These functions contain a parameter called the connection identifier (cid). Upon return of any call or listen function, the connection identifier is set to a unique number that identifies a connection to which a process may refer.

Every connection established using the X.25 Development Tools is independent of all others. The process that created the connection can provide other processes with the parameters necessary to use the same logical session with their own connection identifier (see Connections Across Processes).

The cid numbers start from 0, and for each new connection the smallest unused number is affected. If the application uses a maximum number of m connections at any given time, the cid will always be smaller than m. The cids are de-allocated upon completion of x25xhangup() or x25hangupconfirm().

Using PVCs

The following describes the suggested protocol for two applications using Permanent Virtual Circuits (PVCs):

If application "A" wants to inform a remote application, application "B", that it is ready to set up the connection, it should issue the x25pvccall() function. The x25pvccall() function returns immediately and application "A" should issue the x25recv() function to receive information from either application "B" or from the network.

Application "B" should follow the same sequence whenever it is ready to exchange data.

When the x25pvccall() function is called, a RESET REQUEST packet (with cause and diagnostic values equal to 0x00) is generated by the Eiconcard. If the Eiconcard receives a RESET INDICATION, the x25recv() function will complete with the error ENETSRESET (depending on whether the connection mode is set to XI_ENDEND or not, the info or doneinfo.xi_info parameter will be initialized to XC_RRESETIND or XC_ACKRRESETIND). This indicates that the remote application is ready for the data exchange.

It is possible that the network itself (for example, DATAPAC) will generate a RESET to inform the application of network congestion or temporary failure. In this case the cause will have one of the values defined in the X.25 recommendation (see CCITT X.25 Recommendations (1988) 4.2.).

If the Eiconcard receives data for a PVC and the application is not active (no x25pvccall() has been issued), then it will generate the RESET REQUEST packet with cause equal to 0x00 and diagnostic equal to 0x40 (call setup problem).

If application "A" wants to inform application "B" that it will no longer exchange data, it should call the x25xhangup() function. The Eiconcard will generate a RESET REQUEST packet with diagnostic equal to 0x40.

Modes

The X.25 Development Tools supports two modes of operation: Wait mode, and No-wait mode. No-wait mode is commonly implemented with polling or with a post routine mechanism.

The mode of operation is defined individually for each connection and may only be specified by setting the waitmode parameter on a function that creates a connection (any call or listen function).

If the application is not using No-wait mode with the post routine mechanism, then the post parameter in all applicable X.25 Development Tools functions must be set to X25NULLFN.

Wait Mode

The Wait mode should be used when it is desired that the program wait until the command completes.

The Wait mode is sometimes referred to as "synchronous" mode.

While in Wait mode, any library function referring to a connection will return only when the actual requests have completed. In addition, the x25error() function may return any code from the neterr.h file or the x25err.h file.

No-wait Mode

An application program will normally use a No-wait mode connection. No-wait mode is sometimes referred to as "asynchronous" mode. An application using the No-wait mode can poll for request completion.

Polling

While in No-wait mode with polling, any library function will return as soon as the actual request is submitted to the driver software.

A user application may poll for completion of the requests by calling the x25done() function.

The x25done Library Function

The x25done() function is used for completion of X.25 requests only in No-wait mode. You cannot call x25done() in Wait mode.

When you call the x25done() function, you specify the connection id (cid) as the only selection criterion. If successful and unless XD_NOTO or a timeout value was specified, x25done() will either return immediately with the oldest completed request, or block the process until completion of the least-recently submitted request of the connection. It may happen that the completed request was not submitted by the thread issuing x25done().

 
Signal Handling

The X.25 Development Tools software internally uses signal number 14 (SIGALRM) when the x25done() function is used with a timeout value, other than XD_TONOW (no Wait for completion) or XD_NOTO (wait forever until completion). User applications should avoid using this signal.

Application programs should also not use the alarm() system call when using x25done() with a timeout value other than XD-TONOW or XD-NOTO, since the x25done() function already uses it.

The signo parameter of x25init() may be used by an application program. The process will be interrupted (signalled) with signal number signo when a request is completed and is ready to be received. This feature can be used when a lot of processing must be done and a call to x25done() for polling connections is unnecessary and undesirable. The application program must properly handle the interrupt for this feature to be useful.

The interrupt handler should never call x25done() or any X.25 functions. It should return normally, and not by the longjmp() function. The interrupt handler should only set a global flag and then return. The application program main loop should check the global flag to be set, and call x25done() only when required. This will ensure maximum program throughput.

You should be aware that by using the signal() function a process is subject to termination. Refer to your Linux documentation for complete information on signals.

It is strongly recommended that your X.25 Development Tools applications use the Linux sigaction() signal-handling mechanism. (The sigaction() routine supersedes the signal() routine. The signal() routine is not considered to be completely reliable for some applications.) This is particularly important in high-traffic situations, or when the x25cancel() or x25xhangup() functions are used, because many signals can be received in a short period of time.

Handling Multiple Completed Requests

In some configurations, there can be more than one completed request per signal received. Therefore, when a signal is received, the application should issue x25done() for each completed request received, as illustrated in the following code sequence:

struct   sigaction   isas;

void sig_handler (int sig)

{

	 	 completed_request_flag = TRUE;

}

Supported Signals

Signals that can be used with Eicon Networks drivers are as follows:

	SIGUSR1
	SIGUSR2

Intercepted Signals

If the application program intercepts any signals (for example, SIGTERM), it must ensure that the signal handler function returns normally to where the application was executing. This is important since a bad return may cause the internal data structure to be corrupted. The signal handler should either exit right away using exit() (without doing x25cancel(), x25xhangup(), or x25exit()) or return normally.

 
Security

A process that does an X.25 request is the only process that can receive the results upon completion of the request. The Eiconcard device driver enforces this. For example, a parent process can spawn a child process, but when the parent process submits a request to the library, the child will not receive the results of the completed request.

 
Connections Across Processes

It is possible for a connection to be handled by a process other than its creator. This feature is particularly useful in multi-tasking environments.

Consider the following scenario. A main process may issue one or more calls and listens. When a call or listen completes, the main process may spawn a child process depending on the remote caller/listener, and a different process may be required for different connections. This permits modularity in program development, and makes better use of the system.

The functions used to move connections across processes are x25delconn(), x25getconn(), and x25mkconn().

When a call or a listen completes, x25getconn() is called to obtain relevant connection information, the child process is spawned, and the connection information is given to it.

The child process calls x25mkconn() with the relevant connection information. After the child is spawned and its own connection identifier is created, the main process may call x25delconn() to abandon the connection, since this connection is now handled by another process.

Note: A process that submits requests (makes calls to any X.25 library functions that submit a request to the Eiconcard) is the only process eligible to receive the results when the request completes.

Example: Using Multiple Processes

An application opens a connection in No-Wait mode. It uses x25getconn(), x25delconn(), and x25mkconn() functions and forks two child processes: One to handle sending and one to handle receiving operations.

/* Parent Process */

	 	 x25init(0);

	 	 x25xlisten(&cid,... X25NOWAIT ...);

	 	 while (TRUE)

	 	 {

	 	 ....

	       x25done(cid,XD_NOTO,...);

	 	 ....

	 	 }

	 	 x25getconn(cid, &port, &lsn);

/* Fork Send Child Process */

	 	 pid_1 = fork();

	 	 switch (pid_1)

	 	 {

	    case 0:

	       SendChild();

	       exit(0);

	    case -1:  /* unable to fork */

	       x25xhangup(cid, ..., XH_IMM, X25NULLFN);

	    default:

	       ...

	 	 }

/* Fork Receive Child Process */

	 	 pid_2 = fork();

	 	 switch (pid_2)

	 	 {

	    case 0:

	       ReceiveChild();

	       exit(0);

	    case -1:  /* unable to fork */

	       x25xhangup(cid, ..., XH_IMM, X25NULLFN);

	    default:

	       ...

	 	 }

	 	 ....

	 	 x25xhangup(cid, ...);

	 	 x25exit();

SendChild()

   x25mkconn(&cid1, port, lsn, NOWAIT);

   while (TRUE)

   {

      ...

      x25send(cid1, ...);

      x25done(cid1,XD_NOTO, ...);

      ...

   }

   x25delconn(cid1);

ReceiveChild()

   x25mkconn(&cid2, port, lsn, NOWAIT);

   while (TRUE)

   {

      ...

      x25recv(cid2, ...);

      x25done(cid2,XD_NOTO, ...);

      ...

   }

   x25delconn(cid2);

 
Variable Allocation

The application developer must ensure that all variables referred to by an X.25 library function remain allocated until the actual request completes -- even after the particular function returns. This is important for No-wait mode connections. The following example illustrates this point:

int Do_listen( )

{

	 	 	 struct x25data parm;

	 	 	 parm.xd_len = 0;

	 	 	 if (x25xlisten(&cid, X25NOWAIT, port, info, facility,\
	 	 	 	  &parm, remote, local, post) < 0)

	 	 	 	 return -1;

	 	 	 else

	 	 	 	 return 0;

}

In the above example, the x25xlisten() function will save the address of the parm structure, which is currently allocated on the stack frame of the Do_listen() function. If the call to x25xlisten() is queued correctly, it will immediately return 0. At this point, the actual listen request that has been submitted to the Eiconcard may not have completed yet.

The Do_Listen() function returns, deactivating the stack frame, and hence the parm data structure. Upon completion of the LISTEN request, the X.25 software will attempt to write, in parm, the length of the user data as well as the user data itself.

Since the parm data structure has already been deactivated, another stack frame might have been allocated at that address. The application may fault, making the program behave strangely. This problem can be avoided with the use of static or global variables.

 
Bit Field Manipulation

The info parameter is a bit field used to set certain options such as end-to-end support, delivery confirmation, more data, and the qualifier bit. Any of these bit values can be "ORed" together to set the info parameter. See X-Bit Info Field Values.

End-to-End Support

End-to-end support is available at connection establishment for applications that require full control for handling reset, interrupt, and clear confirmations. If the info parameter in the listen or call request is set with XI_ENDEND then the user application is required to generate interrupt/reset/clear confirms (the X.25 software will not generate this automatically).

If the info parameter is not set to XI_ENDEND then the Eiconcard will automatically generate interrupt/reset/clear confirms. XI_ENDEND may only be specified in the x25xcall(), x25xlisten(), and x25pvccall().

Delivery Confirmation

The Delivery Confirmation Bit (D-Bit) is used to indicate whether or not end-to-end acknowledgment of received data is to be used. Both local and remote DTEs must have the info parameter set with XI_DBIT for delivery confirmation to be in effect. This feature can only be selected by x25xcall(), x25xlisten(), and x25pvccall().

Qualifier Bit

The Qualifier Bit (Q-Bit) is generally used to indicate control information to the remote DTE as defined by the application program. For example, the Q-Bit is set when using the X.29 protocol. The info parameter of an x25send() function must be set with XI_QBIT to indicate control information. Both remote and local DTEs can use the Q-Bit when required. The Q-Bit is also used to indicate Qualified Listen for the x25xlisten() function.

More Data

The More Data Bit (M-Bit) is used to indicate that more data for the same sequence will be coming in the next packet. The info parameter must be set with XI_MBIT to do this. XI_MBIT can only be specified for the x25send() function.

The table below illustrates the use of the More Data Bit in conjunction with the Delivery Confirmation Bit. In the case of a packet sent with incomplete data and where the D-bit is 0, the M-bit will be forced to 0 by the Eiconcard. In any case, the network will not combine data packets with subsequent data packets.

A full data packet received from the source DTE with M-Bit set to 1 and D-Bit set to 0, will be combined with subsequent packets by the Eiconcard. If the data packet is combined with other subsequent data packets, the M-Bit and D-Bit settings received by the destination DTE will be that of the last data packet sent of this sequence. The receive request will complete when the receive buffer is full or when the packet is received with M-Bit = 0.

Clear/Reset Handling

If upon completion of a request the x25error() function returns ENETCALLCLR, the application should issue an x25xhangup() request to release the internal structure allocated by the X.25 Development Tools for that connection, and find the clear cause and diagnostic.

If upon completion of a request the x25error() function returns ENETSRESET, the application should issue an x25recv() request to find the reset cause and diagnostic.

If upon completion of an x25recv() function the x25error() returns ENETSRESET the application should check the info parameter (or the xi_info field of the x25doneinfo structure). If the first two bits are set to 0 (normal data in buffer), then an x25recv() request must be issued to obtain the cause and diagnostics. If the info parameter is set to 0x02 or 0x82 then the cause and diagnostics are already in the buffer.

When a circuit is locally cleared, either by the Eiconcard or a CLEAR REQUEST issued by an application (x25xhangup()), all pending requests on that circuit will return with ENETCALLCLR before the x25xhangup() request completes.

Note: For PVCs, a restart_ind packet is interpreted by the Development Kit as a reset_ind. Four bytes will be placed into the x25doneinfo buffer: 0xFB to 0x00 cc dd. The cc represents the cause, and the dd represents a diagnostic code.

 
Reserved Words

The table below contains the function and variable names that are defined by the X.25 Development Tools. These names must never be used or redefined by an application program, otherwise unpredictable results may occur.