Close_PIPE

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 be closed 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 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 Return area and function call EQUATE copybooks 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.