Exception conditions for LINK command

There are error conditions introduced in support of DPL which are returned to the client and server programs.

Exception conditions returned to the client program

Condition codes returned to a client program describe such events as remote system not known or failure to commit in the server program. There are different reasons, identified by EIBRESP2 values, for raising the INVREQ and LENGERR conditions on a LINK command. The ROLLEDBACK, SYSIDERR, and TERMERR conditions can also be raised. See CICS API commands for programming information about these commands.

If the mirror transaction in the remote region fails, the application program that issued the DPL request can handle the abend of the mirror, and commit its own local resources, only if both the following are true :
  1. The application program explicitly handles the abend caused by the failure of the mirror, and either:
    • Takes an implicit sync point by normal transaction termination
    • or Issues an explicit sync point request.
  2. The remote mirror transaction performed no recoverable work within the scope of the unit of work of the application program. That is, the mirror was invoked only for a distributed program link (DPL) request with SYNCONRETURN.

In all other cases—that is, if the application program does not handle the abend, or the mirror does any recoverable work (for example, a file update, even to an unrecoverable file) CICS® forces the transaction to be backed out.

The PGMIDERR condition is raised on the HANDLE ABEND PROGRAM, LOAD, RELEASE, and XCTL commands if the local program definition specifies that the program is remote. This exception is qualified by an EIBRESP2 value of 9.

Exception conditions returned to the server program

INVREQ is returned, qualified by an EIBRESP2 value of 200, to a server program if it issues one of the prohibited commands summarized in Table 1 . If the server program does not handle the INVREQ condition, the default action is to abend the mirror transaction under which the server program is running with abend code ADPL.

If you attempt to use any of the EXEC CICS WEB commands as a server, those commands fail with INVREQ and a RESP2 value of 1. The following three commands fail with INVREQ and a RESP2 value of 5: EXEC CICS WEB EXTRACT, EXTRACT TCPIP and EXTRACT CERTIFICATE. There is no issue with using these commands where CICS is acting as a client.

For programming information about the DPL-related exception conditions, see LINK.

Table 1. API commands prohibited in programs invoked by DPL
Command Options
ASSIGN ALTSCRNHT ALTSCRNWD APLKYBD APLTEXT BTRANS COLOR DEFSCRNHT DEFSCRNWD DELIMITER DESTCOUNT DESTID DESTIDLENG DS3270 DSSCS EWASUPP EXTDS FACILITY FCI GCHARS GCODES GMMI HILIGHT INPARTN KATAKANA LDCMNEM LDCNUM MAPCOLUMN MAPHEIGHT MAPLINE MAPWIDTH MSRCONTROL NATLANGINUSE NEXTTRANSID NUMTAB OPCLASS OPSECURITY OUTLINE PAGENUM PARTNPAGE PARTNS PARTNSET PS QNAME SCRNHT SCRNWD SIGDATA SOSI STATIONID TCTUALENG TELLERID TERMCODE TERMPRIORITY TEXTKYBD TEXTPRINT UNATTEND USERNAME USERPRIORITY VALIDATION
CONNECT PROCESS all
CONVERSE all
EXTRACT ATTRIBUTES all
EXTRACT PROCESS all
FREE all
HANDLE AID all
ISSUE ABEND CONFIRMATION ERROR PREPARE SIGNAL PRINT ABORT ADD END ERASE NOTE QUERY RECEIVE REPLACE SEND WAIT
LINK INPUTMSG INPUTMSGLEN
PURGE MESSAGE all
RECEIVE all
RETURN INPUTMSG INPUTMSGLEN
ROUTE all
SEND CONTROL MAP PARTNSET TEXT TEXT(MAPPED) TEXT(NOEDIT) PAGE
SIGNOFF all
SIGNON all
START TERMID, where its value is the ID of the intersystem session. (That is, where the issuing task's principal facility is a session rather than a terminal.)
START CHANNEL TERMID, where its value is the ID of the intersystem session. (That is, where the issuing task's principal facility is a session rather than a terminal.)
SYNCPOINT Can be issued in server region if SYNCONRETURN specified on LINK
SYNCPOINT ROLLBACK Can be issued in server region if SYNCONRETURN specified on LINK
WAIT TERMINAL all
XCTL INPUTMSG INPUTMSGLEN
The following commands are also restricted but can be used in the server region if SYNCONRETURN is specified on the LINK:
  • CPIRR COMMIT
  • CPIRR BACK
  • EXEC DLI TERM
  • CALL DLI TERM

Where only certain options are prohibited on the command, they are shown. All the APPC commands listed are prohibited only when they refer to the principal facility. One of these, the CONNECT PROCESS command, causes an error even if it refers to the principal facility in a non-DPL environment. It is included here because, if a CONNECT PROCESS command refers to its principal facility in a server program, the exception condition raised indicates a DPL error.