Passing data to other programs

You can pass data to another program when control is passed to that other program by means of a program control command.

The COMMAREA option of the LINK and XCTL commands specifies the name of a data area (known as a communication area) in which data is passed to the program being invoked. In the receiving program you must give this data area the name DFHCOMMAREA.

In a similar manner, the COMMAREA option of the RETURN command specifies the name of a communication area in which data is passed to the transaction identified in the TRANSID option.(The TRANSID option specifies a transaction that will be initiated when input is received from the terminal associated with the task.) The length of the communication area is specified in the LENGTH option; PL/I programs need not specify the length.

The invoked program receives the data as a parameter. The program must contain a definition of a data area to allow access to the passed data.

In an assembler language program, the data area should be a DSECT. The register used to address this DSECT must be loaded from DFHEICAP, which is in the DFHEISTG DSECT.

In a COBOL program, if a program passes a COMMAREA as part of a LINK, XCTL, or RETURN command, the data area can be in either working storage or the linkage section. A program receiving a COMMAREA should have the data specified in the linkage section. This applies whether the program is the receiving program during a LINK or XCTL command where a COMMAREA is passed or the initial program where a COMMAREA and TRANSID have been specified on the RETURN command of a previously called task.

In a PL/I program, the data area can have any name, but it must be declared as a based variable, based on the parameter passed to the program. The pointer to this based variable should be declared explicitly as a pointer rather than contextually by its appearance in the declaration for the area. This will prevent the generation of a PL/I error message. No ALLOCATE statement can be executed within the receiving program for any variable based on this pointer. This pointer must not be updated by the application program.

The receiving data area need not be of the same length as the original communication area; if access is required only to the first part of the data, the new data area can be shorter. It must not be longer than the length of the communication area being passed, because the results in this situation are unpredictable.

The invoked program can determine the length of any communication area that has been passed to it by accessing the EIBCALEN field in the EIB of the task. If no communication area has been passed, the value of EIBCALEN will be zero; otherwise, EIBCALEN will always contain the value specified in the LENGTH option of the LINK, XCTL, or RETURN command, regardless of the size of the data area in the invoked program.

When a communication area is passed by means of a LINK command, the invoked program is passed a pointer to the communication area itself. Any changes made to the contents of the data area in the invoked program are available to the invoking program, when control returns to it; to access any such changes, the program names the data area specified in the original COMMAREA option.

When a communication area is passed by means of an XCTL command, a copy of that area is made unless the area to be passed has the same address and length as the area that was passed to the program issuing the command. For example, if program A issues a LINK command to program B which, in turn, issues an
XCTL command to program C, and if B passes to C the same communication area that A passed to B, program C will be passed addressability to the communication area that belongs to A (not a copy of it) and any changes made by C will be available to A when control returns to it.

A communication area can be passed by means of a RETURN command issued at the highest logical level when control returns to CICS; in this case, a copy of the communication area is made, and addressability to the copy is passed to the first program of the next transaction.

The invoked program can access field EIBFN in the EIB to determine which type of command invoked the program. The field must be tested before CICS commands are issued. If a LINK or XCTL invoked the program, the appropriate code will be found in the field; if RETURN is used, no CICS commands will have been issued in the task, and the field will contain zeros.