8.3 Diagnosing Errors with C$PING

ACUCOBOL-GT includes a library routine, C$PING, that provides diagnostic information for debugging network performance with AcuServer. If you write a small COBOL program that calls C$PING, you will obtain information such as whether or not the client is AcuServer-enabled, whether or not the parameter passed from the COBOL program is valid, whether the connection was refused or accepted by the server, and whether or not a socket error occurred.

A compiled COBOL program called acuping is included in the \AcuGT\bin directory where you installed ACUCOBOL-GT. This program contains a call to the C$PING library routine along with a graphical screen that runs well on Windows and UNIX platforms. If desired, you can run this program to diagnose AcuServer errors, or you can modify the source code for the program as required. You'll notice that AcuPing has four entry fields: log file name, server to ping, number of pings, and ping delay (1/10th second). The program shows results for Message ID, Time at Client, Time at Server, and Round Trip Time.

If you choose to write your own COBOL program, use the following calling sequence for C$PING:

call "C$PING" using server-to-ping, server-time [, client-data].

server-to-ping is a PIC X(64) data item that should be filled in by the COBOL program before calling C$PING. This is the server that will be pinged.

server-time is a pic 9(8) data item that is filled in by C$PING, and that designates the time the server got and returned the request. Note that if this is a group item, the time is left-justified instead of right-justified (as is done via a COBOL MOVE statement). For this reason, a PIC 9(8) elementary data item is highly recommended.

client-data is a PIC X(n) data item that is passed verbatim to the server. The server displays this data in the trace file (if tracing is enabled) and returns it verbatim to the client. The result is that the data in this data item is unchanged, even though it came from the server. This argument is optional.

When the library routine finishes, it sets the external variable return-code to the status of the ping, as follows: (these values are defined in acucobol.def.)

       78  CPING-OK                         VALUE 0. 
       78  CPING-NO-CLIENT                  VALUE 1. 
       78  CPING-PARAM-ERROR                VALUE 2. 
       78  CPING-CONN-REFUSED               VALUE 3. 
       78  CPING-VERSION-ERROR              VALUE 4. 
       78  CPING-SOCKET-ERROR               VALUE 5.

CPING-OK means that everything worked, and time-at-server has a valid time from the server.

CPING-CONN-REFUSED means that the server refused the connection, possibly because it is not running or is running on a different port than the one for which the client is configured.

CPING-VERSION-ERROR means that the version of the server is not compatible with this version of the runtime.

If the server has tracing enabled, the ping request is logged in the trace file.