The EXCI CALL interface commands

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_User

Function

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.

Note:
A user is a program that has issued an Initialize_user request (or for which an Initialize_User request has been issued), with a unique name per TCB. For example:
  • A simple client program running under MVS™ can be a single user of the external CICS interface.
  • A client program running under MVS can open several pipes and issue external CICS interface calls over them sequentially, on behalf of different vendor packages. In this case, from the viewpoint of the client program, each of the packages is a user, identified by a unique user name. Thus a single client program can operate on behalf of multiple users.
  • A program running under MVS can attach several TCBs. Under each TCB, a vendor package issues external CICS interface calls on its own behalf. Each package is a client program in its own right, and runs under its own TCB. Each is also a user, with a unique user name.

Syntax

CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              user_name),VL,MF=(E,(1))

Parameters

version_number
A fullword binary input area indicating the version of the external CICS interface parameter list being used. It must be set to 1 in the client program.

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.

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 output area containing a 32-bit token supplied by the CICS external interface to represent the client program.

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.

call_type
A 1-word input area indicating the function of the command. It must be set to 1 in the client program to indicate that this is an Initialize_User command.

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.

user_name
An input area holding a name that identifies the user of the external CICS interface. Generally, this is the client program. If this user is to use a specific pipe, then the value in user_name must match that of the NETNAME attribute of the CONNECTION definition for the specific pipe.

Responses and reason codes

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

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Initialize_User call:

Response OK
Command executed successfully (RC 0). Reason code:
0
Normal response
Response WARNING
The command executed successfully, but with an error (RC 4). Reason codes:
3
VERIFY_BLOCK_FM_ERROR
4
WS_FREEMAIN_ERROR
Response RETRYABLE
The command failed because of setup errors but can be reissued (RC 8). Reason code:
201
NO_CICS_IRC_STARTED
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
403
INVALID_USER_NAME
410
DFHMEBM_LOAD_FAILED
411
DFHMET4E_LOAD_FAILED
412
DFHXCURM_LOAD_FAILED
413
DFHXCTRA_LOAD_FAILED
419
CICS_AFCB_PRESENT
420
DFHXCOPT_LOAD_FAILED
421
RUNNING_UNDER_AN_IRB
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
601
WS_GETMAIN_ERROR
602
XCGLOBAL_GETMAIN_ERROR
603
XCUSER_GETMAIN_ERROR
605
VERIFY_BLOCK_GM_ERROR
606
SSI_VERIFY_FAILED
607
CICS_SVC_CALL_FAILURE
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED
627
INCORRECT_SVC_LEVEL

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_Pipe

Function

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.

Start of changeYou 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.End of change

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

Syntax

CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              pipe_token,CICS applid,allocate_opts),VL,MF=(E,(1))

Parameters

version_number
A fullword binary input area indicating the version of the external CICS interface parameter list being used. It must be set to 1 in the client program.

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.

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
The 1-word token returned on the Initialize_User command.
call_type
A 1-word input area indicating the function of the command. It must be set to 2 in the client program to indicate that this is an Allocate_Pipe command.

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.

pipe_token
A 1-word output area. CICS returns a 32-bit token in this area to represent the allocated session. This token must be used on any subsequent command that uses this session.
CICS_applid (or null_ptr)
An 8-byte input area containing the generic applid of the CICS system to which the allocated session is to be connected.

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.

allocate_opts
A 1-byte input area to represent options specified on this command. The options specify which type of session is to be used--specific or generic. X'00' represents a specific session. X'80' represents a generic session.

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.

Responses and reason codes

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

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Allocate_Pipe call:

Response OK
Command executed successfully (RC 0). Reason code:
0
Normal response
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
404
INVALID_USER_TOKEN
421
RUNNING_UNDER_AN_IRB
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
604
XCPIPE_GETMAIN_ERROR
608
IRC_LOGON_FAILURE
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED
628
IRP_LEVEL_CHECK_FAILURE

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.

Open_Pipe

Function

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:

Note:
This command should be used only when there is a DPL call ready to be issued to the CICS server region. When not in use, EXCI sessions should not be left open.

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.

Syntax

CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              pipe_token),VL,MF=(E,(1))

Parameters

version_number
A fullword binary input area indicating the version of the external CICS interface parameter list being used. It must be set to 1 in the client program.

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.

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
The 1-word token returned on the Initialize_User command.
call_type
A 1-word input area indicating the function of the command. This must be set to 3 in the client program to indicate that this is an Open_pipe command.

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.

pipe_token
A 1-word output area containing the token passed by CICS on the Allocate_Pipe command. It represents the pipe being opened on this command.

Responses and reason codes

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

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Open_Pipe call:

Response OK
Command executed successfully (RC 0). Reason code:
0
NORMAL
Response WARNING
The command executed successfully, but with an error (RC 4). Reason codes:
1
PIPE_ALREADY_OPEN
Response RETRYABLE
The command failed because of setup errors but can be reissued (RC 8). Reason codes:
202
NO_PIPE
203
NO_CICS
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
404
INVALID_USER_TOKEN
418
INVALID_PIPE_TOKEN
421
RUNNING_UNDER_AN_IRB
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
609
IRC_CONNECT_FAILURE
621
PIPE_RECOVERY_FAILURE
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED

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.

DPL_Request

Function

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.

Syntax

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))

Parameters

version_number
A fullword binary input area indicating 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 topic Table 18 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 specifying the user token returned to the client program on the Initialize_User command.
call_type
A 1-word input area indicating 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 topic Table 18 for copybook details.

pipe_token
A 1-word input area specifying 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 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.

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.

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 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 don't specify a COMMAREA, this parameter is ignored.

transid (or null_ptr)
A 4-character input area containing 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. Furthermore, 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 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.

uowid (or null_ptr)
An input area containing 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 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:

  • A 1-byte length field containing the overall length of the UOWID (excluding this field).
  • A 1-byte length field containing 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 containing a period (.)
    • A 4-byte field containing the MVS system identifier (SYSID), in characters, under which the client is running.
    • A 4-byte field containing the address space id (ASID) in which the MVS client program is running. The field contains the four character EBCDIC representation of the two-byte hex address space id.
  • The clock value--the middle 6 bytes of an 8-byte store clock (STCK) value
  • A two--byte sequence number set to X'0001'.
userid (or null_ptr)
An 8-character input area containing 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 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.

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, or
  • 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 containing 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 may 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 the CICS Application Programming Reference 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 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 may 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 indicating options to be used on the DPL_Request call.

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:

X'00'
Indicates that Start of changeyou specified NOSYNCONRETURN, becauseEnd of change 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 topic Table 18 for copybook details.

transid2 (or null_ptr) VERSION_2 only
A 4-character input area containing 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 16. 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®, 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.

ccsid (or null_ptr) VERSION_2 only
A fullword binary input area indicating 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 indicating 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), then conversion of binary data will depend on what has been specified in the DFHCNV conversion template installed in the server. The parameter can take the following values:
16909060 ( X'01020304')
indicates that binary data is held in big endian format .
67305985 (X'04030201')
indicates that 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.

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the DPL call:

Response OK
Command executed successfully (RC 0). Reason code:
0
NORMAL
Response WARNING
The command executed successfully, but with an error (RC 4). Reason codes:
6
IRP_IOAREA_FM_FAILURE
7
SERVER_TERMINATED
Response RETRYABLE
The command failed because of setup errors but can be reissued (RC 8). Reason codes:
203
NO_CICS
204
WRONG_MVS_FOR_RRMS
205
RRMS_NOT_AVAILABLE
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
404
INVALID_USER_TOKEN
406
PIPE_NOT_OPEN
407
INVALID_USERID
408
INVALID_UOWID
409
INVALID_TRANSID
414
IRP_ABORT_RECEIVED
415
INVALID_CONNECTION_DEFN
416
INVALID_CICS_RELEASE
417
PIPE_MUST_CLOSE
418
INVALID_PIPE_TOKEN
421
RUNNING_UNDER_AN_IRB
422
SERVER_ABENDED
423
SURROGATE_CHECK_FAILED
425
UOWID_NOT_ALLOWED
426
INVALID_TRANSID2
427
INVALID_CCSID
428
INVALID_ENDIAN
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
612
TRANSFORM_1_ERROR
613
TRANSFORM_4_ERROR
614
IRP_NULL_DATA_RECEIVED
615
IRP_NEGATIVE_RESPONSE
616
IRP_SWITCH_PULL_FAILURE
617
IRP_IOAREA_GM_FAILURE
619
IRP_BAD_IOAREA
620
IRP_PROTOCOL_ERROR
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED
624
SERVER_TIMEDOUT
625
STIMER_SETUP_FAILURE
626
STIMER_CANCEL_FAILURE
629
SERVER_PROTOCOL_ERROR
630
RRMS_ERROR
631
RRMS_SEVERE_ERROR
632
XCGUR_GETMAIN_ERROR

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.

Close_PIPE

Function

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.

Syntax

CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              pipe_token),VL,MF=(E,(1))

Parameters

version_number
A fullword binary input area indicating the version of the external CICS interface parameter list being used. It must be set to 1 in the client program.

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.

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
The 1-word input area specifying the token, returned to the client program by EXCI on the Initialize_User command, that represents the user of the pipe being closed.
call_type
A 1-word input area indicating the function of the command. This must be set to 4 in the client program to indicate that this is a Close_Pipe command.

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.

pipe_token
A 1-word input area specifying the token, returned to the client program by EXCI on the original Allocate_Pipe command, that represents the pipe being closed.

Responses and reason codes

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

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Close_Pipe call:

Response OK
Command executed successfully (RC 0). Reason code:
0
NORMAL
Response WARNING
The command executed successfully, but with an error (RC 4). Reason codes:
2
PIPE_ALREADY_CLOSED
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
404
INVALID_USER_TOKEN
418
INVALID_PIPE_TOKEN
421
RUNNING_UNDER_AN_IRB
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
610
IRC_DISCONNECT_FAILURE
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED

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_Pipe

Function

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.

Syntax

CALL DFHXCIS,(version_number,return_area,user_token,call_type,
              pipe_token),VL,MF=(E,(1))

Parameters

version_number
A fullword binary input area indicating the version of the external CICS interface parameter list being used. It must be set to 1 in the client program.

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.

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 containing the token returned on the Initialize_User command.
call_type
A 1-word input area indicating the function of the command. This must be set to 5 in the client program to indicate that this is a Deallocate_Pipe command.

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.

pipe_token
A 1-word input area containing the token passed back on the original Allocate_Pipe command, that represents the pipe now being deallocated.

Responses and reason codes

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

Note:
All numeric response and reason code values are in decimal.

The following is a summary of the response and reason codes that the external CICS interface can return on the Deallocate_Pipe call:

Response OK
Command executed successfully (RC 0). Reason code:
0
NORMAL
Response WARNING
The command succeeded successfully, but with an error (RC 4). Reason codes:
5
XCPIPE_FREEMAIN_ERROR
6
IRP_IOAREA_FM_FAILURE
Response USER_ERROR
The command failed because of an error in either the client or the server (RC 12). Reason codes:
401
INVALID_CALL_TYPE
402
INVALID_VERSION_NUMBER
404
INVALID_USER_TOKEN
405
PIPE_NOT_CLOSED
418
INVALID_PIPE_TOKEN
421
RUNNING_UNDER_AN_IRB
Response SYSTEM_ERROR
The command failed (RC 16). Reason codes:
611
IRC_LOGOFF_FAILURE
622
ESTAE_SETUP_FAILURE
623
ESTAE_INVOKED

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.

Related concepts
Introduction to the external CICS interface
The EXCI programming interfaces
Related tasks
The EXCI CALL interface
EXCI call response code values
Return area for the EXCI CALL interface
Example of EXCI CALLs with null parameters
The EXCI EXEC CICS interface
[[ Contents Previous Page | Next Page Index ]]