DPL_Request

Parameters

version_number

A fullword binary input area that indicates the version of the external CICS interface parameter list being used. This can be set to 1 or 2 in the client program.

The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is either VERSION_1 or VERSION_2. See Return area and function call EQUATE copybooks for copybook details.

return_area

A 5-word output area to receive response and reason codes, and a message pointer field. For more details, see Return area for the EXCI CALL interface.

user_token

A 1-word input area that specifies the user token returned to the client program on the Initialize_User command.

call_type

A 1-word input area that indicates the function of the command. This must be set to 6 in the client program to indicate that the pipe is now being used for the DPL_Request call.

The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is DPL_REQUEST. See Return area and function call EQUATE copybooks for copybook details.

pipe_token

A 1-word input area that specifies the token returned by EXCI on the Allocate_Pipe command. It represents the pipe being used for the DPL_Request call.

pgmname

The 8-character name of the CICS application program being called as the server program.

This is either the name as specified on a predefined PROGRAM resource definition installed in the CICS server region, or as it is known to a user-written autoinstall program if the program is to be autoinstalled. The program can be defined in the CICS server region as a local program, or it can be defined as remote. Programs defined as remote enable daisy-chaining, where EXCI-CICS DPL calls become EXCI-CICS-CICS DPL calls.

COMMAREA (or null_ptr)

A variable length input area for the communications area (COMMAREA) between the client and server programs. The length is defined by COMMAREA_len.

This is the storage area that contains the data to be sent to the CICS application program. This area is also used to receive the updated COMMAREA from the CICS application program (the server program).

This parameter is optional. If it is not required, you must ensure that the CALL parameter list contains a null address for this parameter. How you do this depends on the language you are using for the non-CICS client program. For an example of a call that omits an optional parameter, see Example of EXCI CALLs with null parameters.

COMMAREA_len

A fullword binary input area. This parameter specifies the length of the COMMAREA. It is also the length of the server program's COMMAREA (EIBCALEN).

If you specify a COMMAREA, you must also specify this parameter to define the length.

This value should not exceed 24 KB if the COMMAREA is to be passed between any two CICS servers (for any combination of product/version/release). Otherwise, if you are confident that the COMMAREA will not be passed on a further LINK request, you can use a COMMAREA up to 32 KB in length.

If you do not specify a COMMAREA, this parameter is ignored.

data_len

A fullword binary input area. This parameter specifies the length of contiguous storage, from the start of the COMMAREA, to be sent to the server program.

This parameter restricts the amount of data sent to the server program, and should be used to optimize performance if, for example, the COMMAREA is large but the amount of data being passed is small.

On return from the server program, the EXCI data transformer program ensures that the COMMAREA in the non-CICS client program is the same as that of the server program. This caters for the following conditions:

• The data returned is more than the data passed in the original COMMAREA.
• The data returned is less than the data passed in the original COMMAREA.
• There is no data returned because it is unchanged.
• The server is returning null data.

The value of data_len must not be greater than the value of COMMAREA_len. A value of zero is valid and results in no data being sent to the server program.

If you do not specify a COMMAREA, this parameter is ignored.

transid (or null_ptr)

A 4-character input area that contains the id of the CICS mirror transaction under which the server program is to run. This transaction must be defined to the CICS server region, and its definition must specify:

PROGRAM(DFHMIRS)

The initial program must be the CICS supplied mirror program DFHMIRS.

Failure to specify DFHMIRS as the initial program means that a COMMAREA passed from the client application program is not passed to the CICS server program. Also, the DPL request fails and the client application program receives a response of SYSTEM_ERROR and reason SERVER_PROTOCOL_ERROR.

PROFILE(DFHCICSA)

The DFHCICSA profile specifies the correct value for the INBFMH parameter, which must be specified as INBFMH(ALL) for a mirror transaction.

When the CICS server region receives a DPL request, it attaches the mirror transaction and invokes DFHMIRS. The mirror program then passes control to the requested server program, passing the COMMAREA supplied by the client program. The COMMAREA passed to the server program is primed with the data only, the remainder of the COMMAREA being set to nulls.

The purpose of the transid parameter is to distinguish between different invocations of the server program. This enables you to run different invocations of the server program under transactions that specify different attributes. For example, you can vary the transaction priorities, or the security requirements.

A transid is optional. By default, the CICS server region uses the CICS-supplied mirror transaction, CSMI. If you do not want to specify transid, you must ensure that the CALL parameter list contains a null address for this parameter. How you do this depends on the language you are using for the non-CICS client program. For an example of a call that omits an optional parameter, see Example of EXCI CALLs with null parameters.

If you issue multiple requests in the same MVS™ unit-of-recovery, the same transid must be used in all of them.

uowid (or null_ptr)

An input area that contains a unit-of-work identifier, using the APPC architected format, that is passed on the DPL_Request for correlation purposes.

For DPL requests that are committed when the CICS program returns control to the MVS application, this parameter is optional.

For DPL requests that are part of an RRMS unit-of-recovery, null_ptr must be specified. The unit-of-work identifier that is already associated with the RRMS unit-of-recovery is used, if there is one; if not, CICS (or another RRMS resource manager) generates a unique unit-of-work identifier and associates it with the RRMS unit-of-recovery.

If you do not want to specify a uowid parameter , you must ensure that the CALL parameter list contains a null address for this parameter. How you do this depends on the language you are using for the non-CICS client program. For an example of a call that omits an optional parameter, see Example of EXCI CALLs with null parameters.

The uowid parameter is passed to the CICS server region, which uses it as the UOWID for the first unit of work executed by the CICS server program. If the server program issues intermediate sync points before returning to the client program, CICS uses the supplied uowid for the subsequent units of work, but with the two-byte sequence number incremented for each new logical unit of work. If the CICS server program updates remote resources, the client-supplied UOWID is distributed to the remote systems that own the resources.

The uowid parameter is supplied on the EXCI CALL interface for correlation purposes only, to allow units of work that originated from a particular client program to be identified in CICS. The uowid is not provided for recovery purposes between CICS and the client program.

The uowid can be a maximum of 27 bytes long and has the following format:

• A 1-byte length field that contains the overall length of the UOWID (excluding this field).
• A 1-byte length field that contains the length of the logical unit name (excluding this field).
• A logical unit name field of variable length up to a maximum of 17 bytes.
  To conform to APPC architecture rules, the LUNAME must be of the form AAAAAAAA.BBBBBBBB, where AAAAAAAA is optional and:

  • AAAAAAAA and BBBBBBBB are 8-byte names separated by a period
  • If AAAAAAAA is omitted, the period must also be omitted
  • AAAAAAAA and BBBBBBBB must be type-1134 symbol strings (that is, character strings consisting of one or more EBCDIC uppercase letters A - Z and 0 - 9, the first character of which must be an uppercase letter).
• The clock value; the middle 6 bytes of an 8-byte store clock (STCK) value.
• A 2-byte sequence number.

If you omit a unit-of-work identifier (by specifying a null pointer), and the DPL request is not part of an RRMS unit-of-recovery, the external CICS interface generates one for you, consisting of the following:

• A 1-byte length field set to X'1A'.
• A 1-byte LU length field set to X'11'.
• A 17-byte LU name consisting of:
  • An 8-byte eyecatcher set to DFHEXCIU.
  • A 1-byte field that contains a period (.)
  • A 4-byte field that contains the MVS system identifier (SYSID), in characters, under which the client is running.
  • A 4-byte field that contains the address space id (ASID) in which the MVS client program is running. The field contains the four character EBCDIC representation of the 2-byte hex address space id.
• The clock value; the middle 6 bytes of an 8-byte store clock (STCK) value
• A 2-byte sequence number set to X'0001'.

userid (or null_ptr)

An 8-character input area that contains the RACF® userid for user security checking in the CICS region. The external CICS interface passes this userid to the CICS server region for user resource and command security checking in the server application program.

A userid is required only if the MRO connection specifies the ATTACHSEC(IDENTIFY) attribute. If the connection specifies ATTACHSEC(LOCAL), the CICS server region applies link security checking. See Intercommunication security for information about link security on MRO connections.

See also Security for EXCI for information about external CICS interface security considerations.

This parameter is optional. However, if you do not specify a userid, the external CICS interface passes the security userid under which the client program is running. For example, if the client program is running as an MVS batch job, the external CICS interface obtains and passes the userid specified on the USER parameter of the JOB statement.

If you specify a userid, the userid under which the EXCI job is running is subject to a surrogate user check. This check is performed by the external CICS interface to ensure that the client job userid is authorized to use the userid specified on the DPL call. For more information about surrogate user security checking, see Security for EXCI.

If you want to let userid default, you must ensure that the CALL parameter list contains a null address for this parameter. How you do this depends on the language you are using for the non-CICS client program. For an example of a call that omits an optional parameter, see Example of EXCI CALLs with null parameters.

If you issue multiple requests in the same MVS unit-of-recovery, the same userid must be used in all of them. If the unit-of-recovery also includes EXEC CICS calls, you should allow the userid on all DPL_requests to default to the security userid under which the client program is running.

dpl_retarea

A 12-byte output area into which the DPL_Request processor places responses to the DPL request. Generally, these responses are from CICS, but in some cases the error detection occurs in the external CICS interface, which returns exception conditions that are the equivalent of those returned by an EXEC CICS LINK command.

This field is only meaningful in the following circumstances:

• The response field of the EXCI return-area has a zero value
• The EXCI return-area indicates that the server program has abended (response=USER_ERROR and reason=SERVER_ABENDED).

The 12 bytes form three fields, providing the following information:

Field 1 (fullword value)

This field is a fullword that contains a RESP value from the DPL_Request call. See Error codes for the RESP values that can be returned on a DPL_Request call.

If the DPL_Request call reaches CICS, this field contains the EIBRESP value, otherwise it contains an equivalent response set by the external CICS interface. If this field is set by the external CICS interface, RESP is further qualified by a RESP2 value in the second field.

A zero value is the normal response, which equates to EXEC_NORMAL in the return codes copybooks.

Field 2 (fullword value)

This field is a fullword that can contain a RESP2 value from the link request, further qualifying the RESP value in field 1.

If the DPL_Request call reaches CICS, the RESP2 field generally is null (CICS does not return RESP2 values across MRO links). However, if the RESP field indicates SYSIDERR (value 53), this field provides a reason code. SeeDpl_retarea return codes for more information.

If the RESP field is set by the external CICS interface, it is further qualified by a RESP2 value in this second field. For example, if the data_len parameter specifies a value greater than the COMMAREA_len parameter, the external CICS interface returns the RESP value 22 (which equates to EXEC_LENGERR in the return codes copybooks), and a RESP2 value of 13.

See the LINK conditions in LINK for full details of the possible RESP and RESP2 values.

Note: The data transformer program makes special use of the RESP2 field. If any error occurs in the transformer, the error is returned in RESP2.

Field 3 (fullword value)

The third field, a 4-character field, contains the following information:

• The abend code if the server program abended
• Four blanks if the server program did not abend.

If a server program abends, it is backed out to its last syncpoint, which can be the start of the task, or an intermediate syncpoint. The server program can issue intermediate syncpoints because SYNCONRETURN is forced.

DPL_opts (or null_ptr)

A 1-byte input area that indicates options to be used on the DPL_Request call.

If you omit this parameter, it defaults to the value X'00'. If you want to omit DPL_opts and let it default, ensure that the CALL parameter list contains a null address for this parameter. How you do this depends on the language you are using for the non-CICS program. For an example of a call that omits an optional parameter, see Example of EXCI CALLs with null parameters.

Currently, the DPL_opts parameter applies only to resource recovery, using the following values:

X'00'

Indicates that you specified NOSYNCONRETURN, because you want the client batch program to control resource recovery, using 2-phase commit protocols supported by MVS RRS. With this option, the CICS server region does not perform a syncpoint when the server program returns control to CICS. Furthermore, the CICS server application program must not take any explicit syncpoints, otherwise it is abended by CICS. For more information, see Resource recovery.

X'80'

indicates that SYNCONRETURN is required in the CICS server region.

SYNCONRETURN specifies that the server region is to take a syncpoint on successful completion of the server program, independently of the client program. This option does not prevent a server program from taking its own explicit syncpoints.

The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is SYNCONRETURN. See Return area and function call EQUATE copybooks for copybook details.

transid2 (or null_ptr) VERSION_2 only

A 4-character input area that contains a CICS transaction id.

The server program runs under a CICS supplied mirror transaction, CSMI or CPMI. However the transaction id made available to the server program through the EIBTRNID field in the Exec Interface Block is the one specified by the transid2 parameter. The transid2 parameter is ignored if the transid parameter is specified. The following table gives an example of different combinations of transid and transid2:

Table 1. Use of transid2

transid	transid2	program executes under	EIBTRNID seen by program
UTRN	omitted	UTRN	UTRN
UTRN	UEIB	UTRN	UTRN
omitted	omitted	CSMI	CSMI
omitted	UEIB	CSMI	UEIB

The transid2 parameter is useful for server programs that access DB2®, because EIBTRNID is used to determine which DB2ENTRY definition to use. Previously, EIBTRNID could only be set by using transid, which then required you to define a mirror transaction to CICS. Using transid2, EIBTRNID is set, but the mirror program executes under the CICS provided definition CSMI.

ccsid (or null_ptr)VERSION_2 only

A fullword binary input area that indicates the Coded Character Set Identifier (CCSID) of the character data contained in the COMMAREA. The ccsid parameter must be specified if character data has to be converted when the COMMAREA is passed to, or returned from, the server program. The parameter can take the following values:

-1 (X'FFFFFFFF')

Indicates that conversion of character data is required and that the source CCSID is defined in the conversion template installed in the server.

1 <= ccsid <= 65535

Indicates that conversion of character data is required and that the value specified overrides the source CCSID defined in the conversion template installed in the server.

endian (or null_ptr) VERSION_2 only

A fullword binary input area that indicates the format, big endian or little endian, for binary data contained in the COMMAREA. Big endian indicates that the leftmost byte contains the most significant digits, as used, for example, in System 390 architecture. Little endian indicates that the rightmost byte contains the most significant digits, as used, for example, in Intel architecture. The endian parameter should be specified if binary data has to be converted when the COMMAREA is passed to, or returned from, the server program. If the ccsid parameter indicates that conversion is required, but endian is not specified (defaults to null), conversion of binary data depends on what is specified in the DFHCNV conversion template installed in the server. The parameter can take the following values:

16909060 ( X'01020304')

Binary data is held in big endian format.

67305985 (X'04030201')

Binary data is held in little endian format.

Responses and reason codes

For all non-zero response codes, a unique reason code value identifies the reason for the response.

For information about response codes, see EXCI call response code values.

For information about the reason codes, see Response and reason codes returned on EXCI calls.