Open_Pipe

Cause IRC to connect an allocated pipe to a receive session.

Open_Pipe causes 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:

The EXCI connection with a NETNAME value equal to the user_name parameter on the Initialize_User command (that is, you are using a specific connection, dedicated to this client program)
The EXCI connection defined as generic.

In an XCF environment, the Open_Pipe command causes the interregion communication program, DFHIRP, to connect to the LPAR that receives the request. This request is asynchronous, so although the Open_Pipe command can receive a good return code, the subsequent DPL_Request call might fail.

If you shut down CICS without the support of the supplied shutdown-assist transaction (CESD) or an equivalent, and sessions remain open, CICS might 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:

The netname of the session if it is on a specific connection
The word GENERIC if the open sessions are on a generic connection.

If you use the 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 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. 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 1 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:

608: IRC_LOGON_FAILURE
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.