Deallocate_Pipe

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.

Note: After a successful Open_Pipe request, when your client program finishes using the pipe, you must first issue a Close_Pipe command and then a Deallocate_Pipe command to free the pipe. If you issue a Deallocate_Pipe command without first closing an open pipe with Close_Pipe, your request fails.

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 DFHXCPL x (where x indicates the language) is VERSION_1. See Return area and function call EQUATE copybooks 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 DFHXCPL x (where x indicates the language) is DEALLOCATE_PIPE. See Return area and function call EQUATE copybooks 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.