DPL exceptional conditions

LINK requests that are shipped to a remote system can raise any of the exceptional conditions for the command that can occur if the server program is local. In addition, there are some conditions that apply only when the server program is remote.

Remote system not available

When the remote system is unavailable, the SYSIDERR condition can be raised in the client program for exactly the same reasons as described for function shipping in topic Remote system not available.

The default action for the SYSIDERR condition is to terminate the task abnormally.

Server’s work backed out

If the client program issues the LINK command with the SYNCONRETURN option, the mirror program issues a syncpoint as soon as the server program terminates successfully. It is possible for this syncpoint to fail. If this happens, the ROLLEDBACK condition is returned to the client program. The work done by the server program will also be backed out, unless the server program has already committed the work by issuing its own syncpoint request.

Multiple links to the same server region

When a client program issues a LINK command with the SYNCONRETURN option, the mirror transaction terminates as soon as control is returned to the client program. It is therefore possible for the client program to issue a subsequent LINK command to the same server region.

However, when a client program issues a LINK command without the SYNCONRETURN option, the mirror transaction is suspended pending a syncpoint request from the client region. The client program can issue subsequent LINK commands to the same server region as long as the SYNCONRETURN option is omitted and the TRANSID value is not changed. A subsequent LINK command with the SYNCONRETURN option or with a different TRANSID value will be unsuccessful unless it is preceded by a SYNCPOINT command.

Note:
Similar considerations apply if the client program sends function shipping requests to the server region, and the mirror for the function shipping request is suspended. For example:
EXEC CICS LINK PROGRAM('PGA') SYSID(SERV)
EXEC CICS SYNCPOINT
EXEC CICS READQ TS QUEUE('RQUEUE') SYSID(SERV)
EXEC CICS LINK PROGRAM('PGB') SYSID(SERV) TRANSID(TRN1)

The last LINK command fails if, for example, MROLRM=YES is specified in the CICS® server region (SERV). This is because the mirror used for the READQ TS command is still around. For the above sequence of commands to work, the client program must issue a SYNCPOINT after the READQ TS command; alternatively, you could set the MROLRM system initialization parameter to 'NO' in the server region. For detailed information about using DPL and function shipping requests in the same program, see the CICS Application Programming Guide.

These errors are indicated by the INVREQ and PGMIDERR conditions.

On the INVREQ condition, an accompanying RESP2 value of 14 indicates that a syncpoint is necessary before the failed LINK command can be successfully attempted. A RESP2 value of 15 indicates that the TRANSID value is different from that of the linked mirror transaction. A RESP2 value of 16 indicates that a TRANSID value of spaces (blanks) was specified on the LINK command. A RESP2 value of 17 indicates that a TRANSID value of spaces (blanks) was supplied by the dynamic routing program.

On the PGMIDERR condition, an accompanying RESP2 value of 25 indicates that the dynamic routing program rejected the link request.

Mirror transaction abend

If the mirror program (as opposed to the server program) abends or the session with the server region fails, the TERMERR condition is returned to the client program.

Multiple updates to a recoverable resource by the same distributed UOW

In a non-DPL environment, it is possible for multiple programs within one unit of work (UOW) to update the same recoverable resource. For instance, program1 might update Record1 in a recoverable file, then link to program2, which could update the same record, Record1, in the same file. This is not necessarily good programming practice but it does work, because CICS considers the owner of the resource to be the task, not the program.

However, in a DPL environment, where the programs involved are running in different CICS regions, it is not possible for multiple programs to update the same recoverable resource within the same UOW. Using the same example as above, program1 updates Record1 in a recoverable file, then links to program2, which runs under a mirror task in another region. If program2 function-ships a file control request to update Record1 in the same file, the request hangs. It hangs because the mirror task processing program2’s file control request cannot get the record lock for Record1. The lock is owned by the task under which program1 is running. Even though the file control mirror task and the task under which program1 is running are part of the same distributed UOW, CICS does not allow the update. This is because CICS uses the task, not the distributed UOW, as the basis for locking recoverable resources.

Related concepts
Introduction to DPL programming
The client program
The server program
Related tasks
Defining remote resources for DPL
Defining local resources for DPL
[[ Contents Previous Page | Next Page Index ]]