In the description of each command that follows, the syntax box illustrates the assembler form of the command. The syntax shows VL,MF=(E,(1)) for each command, indicating the execute form of the CALL macro, with the parameter list storage area addressed by Register 1.
The commands are also supported by C, COBOL, and PL/I programming languages, using the CALL conventions appropriate for these languages.
There are examples of these CALLs, in all the supported languages, in the sample client programs provided by CICS®. See Using EXCI sample application programs for information about these.
Initialize the user environment. This includes obtaining authority to use IRC facilities. The environment is created for the lifetime of the TCB, so the command needs to be issued only once per user per TCB. Further commands from this user must be issued under the same TCB.
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
user_name),VL,MF=(E,(1))
The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is VERSION_1. See topic Table 18 for copybook details.
The user token corresponds to the user-name parameter. The client program must pass this token on all subsequent external CICS interface commands made for the user defined on the user_name parameter.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is INIT_USER. See topic Table 18 for copybook details.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the Initialize_User call:
For more 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.
Allocate a single session, or pipe, to a CICS region. This command does not connect the client program to a CICS region; this happens on the Open_Pipe command.
You can allocate up to 250 pipes
in an EXCI address space. The default limit is 100 pipes. However, you can
use the CICS system initialization parameter, LOGONLIM, to change the limit when MVS is
IPLed.
This limit is set to prevent EXCI clients from monopolising MRO resources, which could prevent CICS systems from using MRO. The limit is applied in both MRO and cross system MRO (XCF/MRO) environments. An ALLOCATE_PIPE request results in an MRO LOGON request being issued and there is a limit on the total number of MRO LOGON requests allowed from all address spaces. This is particularly critical when using XCF/MRO, where the limit on the number of members in a XCF group also limits the total number of MRO LOGONs
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token,CICS applid,allocate_opts),VL,MF=(E,(1))
The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is VERSION_1. See topic Table 18 for copybook details.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is ALLOCATE_PIPE. See topic Table 18 for copybook details.
Although an applid is required to complete the Allocate_Pipe function, this parameter is optional on the Allocate_Pipe call. You can either specify the applid on this parameter to the Allocate_Pipe call, or in the user-replaceable module, DFHXCURM, using the URMAPPL parameter (DFHXCURM is always invoked during Allocate_Pipe processing). You can also use the URMAPPL parameter in DFHXCURM to override an applid specified on the Allocate_Pipe call. See The EXCI user-replaceable module for information about the URMAPPL parameter.
If you omit the applid from the call, you must ensure that the CALL parameter list contains a null address for CICS_applid. 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 equated value for these options in the CICS-supplied copybook DFHXCPLx (where x indicates the language) are SPECIFIC_PIPE and GENERIC_PIPE. See topic Table 18 for copybook details.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the Allocate_Pipe call:
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.
Cause IRC to connect an allocated pipe to a receive session of the appropriate connection defined in the CICS region named either on the Allocate_Pipe command, or in DFHXCURM. The appropriate connection is either:
If you shut down CICS without the support of the CICS-supplied shutdown-assist transaction (CESD) or an equivalent, and sessions are left open, CICS may not be able to shut its IRC facility in an orderly manner. A normal shutdown of CICS without the support of the shutdown assist transaction waits if any EXCI sessions are not closed. CICS issues message DFHIR2321 indicating the following information:
If you use the CICS-supplied shutdown-assist transaction, CESD, sessions left open do not present a problem to normal shutdown, because CESD issues an immediate close of IRC.
Provided that at least one DPL_Request call has been issued on the session, message DFHIR2321 also shows the job name, step name, and procedure name of the client job that is using the session, and the MVS ID of the MVS image on which the client program is running.
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token),VL,MF=(E,(1))
The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is VERSION_1. See topic Table 18 for copybook details.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is OPEN_PIPE. See topic Table 18 for copybook details.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the Open_Pipe call:
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.
Issue a distributed program link request across an open pipe connected to the CICS system on which the server (or target) application program resides. The command is synchronous, and the TCB waits for a response from CICS. Once a pipe is opened, any number of DPL requests can be issued before the pipe is closed. To the server program, the link request appears just like a standard EXEC CICS LINK request from another CICS region, and it is not aware that it is sent from a non-CICS client program using EXCI.
The syntax of the call is shown in two forms: the parameters that can be used when version_number is set to VERSION_1, and the parameters that can be used when version_number is set to VERSION_2.
VERSION_1
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token,pgmname,COMMAREA,COMMAREA_len,data_len,
transid,uowid,userid,dpl_retarea,DPL_opts),
VL,MF=(E,(1))
VERSION_2
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token,pgmname,COMMAREA,COMMAREA_len,data_len,
transid,uowid,userid,dpl_retarea,DPL_opts,
transid2,ccsid,endian),
VL,MF=(E,(1))
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 topic Table 18 for copybook details.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is DPL_REQUEST. See topic Table 18 for copybook details.
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.
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.
If you specify a COMMAREA, you must also specify this parameter to define the length.
This value may not exceed 32 500 bytes 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 32k in length.
If you don't specify a COMMAREA, this parameter is ignored.
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.
Note that 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 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 don't specify a COMMAREA, this parameter is ignored.
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. Furthermore, the DPL request fails and the client application program receives a response of SYSTEM_ERROR and reason SERVER_PROTOCOL_ERROR.
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 don't 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.
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 don't want to specify uowid, 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 syncpoints 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:
To conform to APPC architecture rules, the LUNAME must be of the form AAAAAAAA.BBBBBBBB, where AAAAAAAA is optional and:
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 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 the CICS RACF Security Guide for information about link security on MRO connections.
See also EXCI security for information about external CICS interface security considerations.
This parameter is optional. However, if you don't 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 and SURROGCHK=YES is specified in the EXCI options table DFHXCOPT, 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 EXCI security.
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.
This field is only meaningful in the following circumstances:
The 12 bytes form three fields, providing the following information:
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.
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 the CICS Application Programming Reference for full details of the possible RESP and RESP2 values.
If a server program abends, it is backed out to its last syncpoint which may be the start of the task, or an intermediate syncpoint. The server program can issue intermediate syncpoints because SYNCONRETURN is forced.
If you omit this parameter, it defaults to the value X'00' (see below). 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:
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 topic Table 18 for copybook details.
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:
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®, as 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.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the DPL call:
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.
Disconnect an open pipe from CICS. The pipe remains in an allocated state, and its tokens remain valid for use by the same user. To reuse a closed pipe, the client program must first reissue an Open_Pipe command using the pipe token returned on the Allocate_Pipe command for the pipe. Pipes should not be left open when not in use because this prevents CICS from shutting down its IRC facility in an orderly manner. Therefore, the Close_Pipe command should be issued as soon as possible after all DPL_Request calls have completed.
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token),VL,MF=(E,(1))
The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is VERSION_1. See topic Deallocate_Pipe for copybook details.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is CLOSE_PIPE. See topic Table 18 for copybook details.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the Close_Pipe call:
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.
Deallocate a pipe from CICS. On completion of this command, the pipe can no longer be used, and its associated tokens are invalid. This command should be issued for pipes that are no longer required. This command frees storage associated with the pipe.
CALL DFHXCIS,(version_number,return_area,user_token,call_type,
pipe_token),VL,MF=(E,(1))
The equated value for this parameter in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is VERSION_1. See topic Table 18 for copybook details.
The equated value for this call in the CICS-supplied copybook DFHXCPLx (where x indicates the language) is DEALLOCATE_PIPE. See topic Table 18 for copybook details.
For all non-zero response codes, a unique reason code value identifies the reason for the response.
The following is a summary of the response and reason codes that the external CICS interface can return on the Deallocate_Pipe call:
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.