Behavior in the event of errors

This section describes the effects on a communication partner when a UTM application or a CPI-C client application terminates. It also explains how to re-establish a basic state for successful program-to-program communication in the event of an error.

Termination of a UTM application

If the UTM application terminates, this is detected by the CPI-C program with the next call at the communication interface. The following two cases can be distinguished:

• a connection shutdown may be detected with a Receive call or

• the termination of the application may be detected with a call at the communication interface, which also caused the conversation to terminate automatically.

In both cases, CM_DEALLOCATED_ABEND is returned as the result.

Abnormal termination of a CPI-C program

The UTM application is generally informed of the program termination by means of a connection shutdown. In this case, no further actions are required.

If the UTM application does not detect a connection shutdown, the connection still exists as far as openUTM is concerned. Two cases can be distinguished:

• On the UTM side a PTERM or an LTERM pool with TPOOL ...,CONNECT-MODE=SINGLE is configured for the client application. In this case, openUTM can distinguish between the connected clients. As soon as a client attempts (after a loss of connection) to open another connection under the same name, openUTM shuts down the old connection and rejects the connection setup request. Any subsequent connection setup request from the client is then accepted.

• On the UTM side an LTERM pool with TPOOL ..., CONNECT-MODE=MULTI is configured for the client application. In this case, several clients can connect to the UTM application from the same system and with the same name. The UTM application can then no longer recognize whether a client is connecting from scratch or after loss of a connection. A lost connection for which the UTM application was not shown a connection shutdown must in this case be shut down explicitly by the administration, i.e. openUTM does not shut down the “lost” connection itself the next time the client attempts to set up a connection.

UPIC local (Unix, Linux and Windows systems only):

The following can occur:

The UTM application has not recognized the termination of the CPI-C process. As soon as the CPI-C program signs on to openUTM again with the same program name, openUTM shuts down the old connection and accepts the new one.

Serious error in the CPI-C program

If a serious error occurs while the UPIC program is running, and this error effectively prevents the program from continuing, the process is abnormally terminated (with FatalAppExit in WIndows systems; with abort in Unix and Linux systems). The following error message is also written to the UPIC log file:

UPIC: internal error <reason>

The error messages that may occur on the CPI-C side are described in the table below.

<reason>	Meaning
1	When sending the rest of the data, the value of data length is negative
9	The SIGTRAP signal has occurred
10	Error when establishing the connection
11	Error when receiving confirmation for connection setup
12	Message other than connection setup received
13	Error when sending data
14	Error when receiving data
15	Invalid message received
16	Error when shutting down connection

For error diagnosis see also section “Diagnostics”.

UPIC local (Unix, Linux and Windows systems only):

With local communication via UPIC local, moreover, error messages beginning with the letters “IPC” can occur. These come from openUTM and are described in the openUTM manual “Messages, Debugging and Diagnostics on Unix, Linux and Windows Systems” under the dump error codes.

For error diagnosis you require the dump (e.g. core dump in Unix and Linux systems) together with the linked program as well as the contents of the UPIC trace file and the UPIC log file.

Message exchange with a programmed PEND ER/FR

If a programmed PEND ER/FR was carried out while a UTM program unit was running, the message segments sent with MPUT prior to the PEND ER/FR can be received. The Receive or Receive_Mapped_Data call is used for this purpose (until the return code is CM_DEALLOCATED_ABEND).

Message exchange with SYSTEM PEND ER

If, in the event of an error, the UTM service ends with PEND ER, the result CM_DEALLOCATED_ABEND is returned when Receive() or Receive_Mapped_Data() is called. In addition, an error message is written to the log file (see also section “UPIC log file”).

A separate error message for a UPIC-Client can be created in a dialog program unit using the MPUT ES (error system) call (see also openUTM manual „Programming Applications with KDCS”, MPUT ES call), which the UPIC client can read with he call Receive() or Receive_Mapped_Data(). In this case, no error message is written to the log file.

Problems with connection setup

Problems in setting up a connection to the UTM application can be detected by the fact that the Allocate call does not terminate with the result CM_OK. In this case you should check the following:

On BS2000 systemen invoke the ping command as follows

/&* for IPV4 connections
/START-PING4 <hostname>

/&* for IPV6 connetions
/START-PING6 <hostname>

• Use a ping command to check whether it is possible at all to establish a network connection between the client and server.

  On Unix, Linux and Windows systems, call the ping command using:

  ping <internetaddress> or ping <hostname>

  ping must be in your path, i.e. the PATH variable must be suitably set.

  On BS2000 systems, call ping as follows:

  
  

  Check the TCP/IP protocol using one of the standard applications telnet or ftp.

• On Unix, Linux and Windows systems, call these commands as follows:

  telnet internetaddress or telnet hostname
  ftp internetaddress or ftp hostname

  The applications must be in your path, i.e. the PATH variable must be suitably set.

  On BS2000 systems, the applications are called with:

  START-TELNET
  START-FTP

• Check whether the necessary resources are available in the UTM partner application. For example, the LTERM pool or the LTERM partner via which the client wants to sign on must not be locked. See also the openUTM manual “Generating Applications”.

• Check whether all the necessary resources are available on the local system. You should always check the local configuration (side information if necessary) and the partner configuration (openUTM if necessary).

BS2000 systems:

In a configuration which requires BCMAP entries in the BS2000 system, you must make sure that the BCMAP command does not perform any update function, i.e. that BCMAP entries must first be deleted and then entered again. For more information on the BCMAP command, refer to the BCAM manuals.