Allocate_Pipe

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 increase this using the LOGONLIM parameter when you define CICS as an MVS subsystem. See EXCI pipe allocation.

This limit is set to prevent EXCI clients from monopolizing 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 LOGON requests.

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 DFHXCPL x (where x indicates the language) is VERSION_1. See Table 1 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 DFHXCPL x (where x indicates the language) is ALLOCATE_PIPE. See Table 1 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 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 specify the applid either on this parameter to the Allocate_Pipe call, or on the URMCICS parameter in the user-replaceable module, DFHXCURM (DFHXCURM is always invoked during Allocate_Pipe processing). You can also use the URMCICS parameter in DFHXCURM to override an applid specified on the Allocate_Pipe call. See The EXCI user-replaceable module for information about the URMCICS 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 CALL 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 DFHXCPL x (where x indicates the language) are SPECIFIC_PIPE and GENERIC_PIPE. See Table 1 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.