Readme Notes 211-143-03 September 2007 Eiconcard X.25 Development Tools for Linux Introduction ========================================================================== These Readme Notes provide the latest information for developers wishing to use Eiconcard(r) products and the X.25 protocol, on the Linux(r) operating system. These Readme Notes are organized as follows: o Installation o Compiler support o Specific to Linux o Added features o Samples Installation ========================================================================== The installation of Eiconcard X.25 Development Tools for Linux requires that Eiconcard Connections for Linux software package be already installed on the system. The X25/Linux directory contains a tar file (x25linux.tar) that will expand files into the following directories: Target directory Files /usr/include/eicon/ Include files /usr/lib/ libEx25.a /opt/dialogic/c4l/dev_tools/x25/samples programming code samples The tar file x25linux.tar contains only relative paths. Extract the files from the root directory to obtain the file layout above. Note that the tar can also be extracted in any subdirectory if you prefer not to have files extracted into system directories. In this case you will have to modify the sample code makefiles to reflect the new location of the include files and libraries. The Readme.txt file from the X25/Linux directory can be copied in the following directory: /opt/dialogic/c4l/dev_tools/x25 Compiler support ========================================================================== The C compiler native to your Linux system is supported. Consult the documentation that accompanies Eiconcard Connections for Linux, for specific details about supported Linux distributions. Specific to Linux ======================================================================== A reference guide, for function description and other specific development information, can be found in the X25\Help\Html directory on the Eiconcard Development Suite CD. It is an HTML help file (index.htm), with reference to the Eiconcard X.25 Development Tools and its usage. It is also strongly recommended for new developers to refer to the Getting Started section of this reference guide. This part of the Readme Notes has some specific information for Linux development that may not be found in the above mentioned documentation. This information is very important and should be read. This section is organized as follows: -Library files -Include files -Compiling Options Library file ------------ The library file containing functions to be used for Linux application programs are included in the /usr/lib/eicon directory. File Description: libEx25.a Archived C function library for the X.25 library PLEASE NOTE: If you are using this library on versions of Eiconcard Connections for Linux older than V5R6, please contact devsup@dialogic.com to obtain an updated libEec.a Include files ------------- Include files are contained in the /usr/include/eicon/ directory. File Description: x25.h Include file defining the variable structures x25err.h Include file defining X.25 error messages x25proto.h Include file defining prototype for each function neterr.h Include file defining network error messages Compiling Options ---------------- When compiling an application, the -DEC_UNIX and -DSCO options must be specified. This will activate the appropriate #defines for the Linux environment. Even though a Linux environment is being used, the -DEC_UNIX and -DSCO options must be specified. Added features ========================================================================== The reference pointer is a new parameter added in all asynchronous APIs. The reference pointer is a parameter designed to help simplify application design and implementation. The reference parameter can be used for all asynchronous functions. Asynchronous functions return immediately, but the processing for the request continues internally. The application can identify the completing request by examining the doneinfo structure at fields such as the xi_cmd, xi_cid, and xi_buf. These fields respectively indicate the command, the connection, and the associated data that completes. The reference parameter is a additional field for identifying the completing request. The ref parameter is fully controlled by your application. When submitting the X.25 request the application can initialize the ref parameter to any useful value. Upon completion of that request the xi_ref field from the doneinfo structure returns the same value. As an example, the application can set the ref parameter to the address of a structure pertaining to the connection. Upon completion of the request, the xi_ref value allows the application to directly access the correct structure without having to search for it. The ref parameter is new. In order to keep backward compatibility in compilation with applications developed with previous X.25 libraries, the ref parameter is optional. To access the ref parameter functionality, the application must define the variable EC_REF. It is suggested that the project pre-define the EC_REF value. Example 1: Without the reference pointer. OSEXTERN OSINT OSFNDEF x25xcall ( OSINT OSDTPTR cid, OSINT waitmode, OSINT port, OSINT info, struct x25data OSDTPTR facility, struct x25data OSDTPTR udata, char OSDTPTR remote, char OSDTPTR local, void (OSFNPTR post)(struct x25doneinfo *)); Example 2: With the reference pointer, the variable EC_REF has to be defined in order to activate those APIs. OSEXTERN OSINT OSFNDEF x25xcall ( OSINT OSDTPTR cid, OSINT waitmode, OSINT port, OSINT info, struct x25data OSDTPTR facility, struct x25data OSDTPTR udata, char OSDTPTR remote, char OSDTPTR local, void (OSFNPTR post)(struct x25doneinfo *), void *ref); The file "x25proto.h" contains all function prototypes. Example 3: Pseudo code showing the usage of the reference pointer. /* User define structure */ typedef struct _MyStruct { int myfield; } MyStruct, *pMystruct; MyStruct SomeVar; pMyStruct pSomeVar; main () { . . //Passing the address of the structure in the ref ref= (void *) &SomeVar; //***** if ( x25send(cid, buf, len, info, X25NULLFN, ref) < 0 ) { /* Cannot submit the x25send. Call x25error to get the error message. */ } //The x25send() request has been successfully submitted to the driver. //Now poll for completion. //Set the timeout to XD_NOTO, XD_TONOW, or a user application value. timeout = XD_TONOW; while ( x25done(cid, timeout, &done_info) < 0 ) { /* X25done() failed. If the error is ENETPEND, then the request hasn't completed keep polling. Otherwise, we have a less recoverable error - exit. */ } //The request has completed (not necessarily without errors) and // the done_info structure has been updated. //Get the address of the structure that was passed in the ref of //the x25send pSomeVar = (pMyStruct)done_info.xi_ref; //*** // Process the doneinfo structure . . . . } Samples ========================================================================== After the toolkit has been installed, included in the /opt/dialogic/c4l/dev_tools/x25/samples directory, are some sample applications that show the usage of the toolkit for the Linux platform. Each corresponding sample directory has a set of the sample source code and their correponding makefile. These sample applications are for testing purposes only and should not be used in a production environment. -- It is strongly recommended to look at the sample source code and read the comments before using them. -- File Description ../xft/ xft.c Shows usage of WAIT mode makxft Make file for xft.c sample ../xct/ xct.c Shows usage of NOWAIT mode using polling and signals makxct Make file for xct.c sample ../xterm/ xterm.c Shows usage of WAIT mode and NOWAIT mode using polling makxterm Make file for xterm.c sample ../ft_poll/ ft_poll.c Shows usage of NOWAIT mode using polling makftpol Make file for ft_poll.c sample X.25 function application tool (EXE file only) ---------------------------------------------- ..\X25utils Demonstrates the usage of some of the more important functions of the X.25 library. All request that are submitted to the EiconCard are in NOWAIT mode using polling (the polling with x25done() is manually done by the user). This application can be used to reproduce scenarios/situations that can be encountered during the development of an application. Eiconcard Tester application ---------------------------- ..\ECTester Checks if your Eiconcard is correctly installed and configured, by allowing the user to perform 3 different tests. - Test the connection to an X.25 network - Test a back-to-back X.25 connection - Test the HDLC link level for a specific port ############## End of 211-143-03 ######################################### Copyright (c) 1998-2007 Dialogic Corporation