/PURGE command

The /PURGE command stops input for a particular communication line, terminal, or logical link path, or stops input messages destined for a particular transaction code.

Messages can be sent to the specified communication line or terminal, and transactions can still be scheduled.

Any APPC requests that are queued in 64-bit storage as a result of APPC/IMS flood control are rejected with sense code TP_Not_Available_No_Retry.

Subsections:

Environment
Syntax
Keywords
Usage notes
Equivalent IMS type-2 commands
Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the commands and keywords.

Table 1. Valid environments for the /PURGE command and keywords
Command / Keywords	DB/DC	DCCTL
/PURGE	X	X
APPC	X	X
CLASS	X	X
FPPROG	X	X
FPRGN	X	X
LINE	X	X
LTERM	X	X
MSNAME	X	X
PTERM	X	X
TRAN	X	X

Syntax

Keywords

The following keywords are valid for the /PURGE command:

APPC

Is used to purge incoming transactions. All new requests by APPC/z/OS to schedule a transaction in IMS are rejected with TP_Not_Available_No_Retry. Transactions that IMS has already received are processed normally. Sending of output to LU 6.2 devices proceeds normally. Because /PURGE APPC does not call to APPC/z/OS, the rejection of transaction scheduling is done by the schedule exit of IMS only.

Note: The sense code returned to the LU 6.2 remote device for an incoming ATTACH to a purged APPC/IMS system is determined by APPC/z/OS, and it might differ from release to release. In general, the remote LU 6.2 application should wait for a period of time after rejection before any attempts to reestablish a session with IMS.

The /PURGE APPC command sets the PURGING status and resets conditions previously set by the /START APPC command. The command is rejected if the APPC is already in DISABLED, FAILED, STOPPED, or CANCEL state.

FPPROG

Specifies the PSB name of the message-driven program to be terminated.

/PURGE takes message-driven programs out of wait-for-input mode and terminates them as soon as their load balancing group message queue is empty.

Use the FPPROG keyword with caution, because all Fast Path message-driven programs that are using a PSB with the same name will be terminated.

FPRGN

Specifies the region identifier of the message-driven program to be terminated.

LINE

Specifies the communication line for which input is to be stopped.

LTERM

Specifies the logical terminal for which input is to be stopped.

The /PURGE LTERM command is rejected for LTERMs in QLOCK state. (QLOCK indicates that the LTERM is locked from sending any further output or from receiving input that can create additional output for the same LTERM until the state is reset by a specific request received on the session.) /PURGE LTERM is also rejected for remote logical terminals. The LTERM supports generic parameters where the generic parameter specifies LTERMs that already exist.

The /PURGE LTERM command is valid only for LTERMs that belong to nodes that are logged on.

MSNAME

Specifies the logical link path in a multiple systems configuration for which input is to be stopped. The MSNAME keyword supports generic parameters.

TRAN

Specifies the transaction code for which input messages are to be stopped.

The TRAN parameter can be generic where the generic parameter specifies transactions that already exist.

The /PURGE TRAN command is not allowed for a transaction that is marked bad with the NOTINIT-15-REPOCHGLIST reason code because the IMS change list processing is not complete for the transaction or the change list processing failed.

Usage notes

The /PURGE command validity checks all parameters entered by the terminal operator. If an error is detected on parameters that are independent of one another, only the invalid parameters are indicated as being in error and the /PURGE command processes the rest of the parameters.

The /PURGE command can be used to reset conditions previously set by the /START, /RSTART, /STOP, /PSTOP, or /MONITOR command.

This command can be issued to an IMSplex using the Batch SPOC utility.

Equivalent IMS type-2 commands

The following table shows variations of the /PURGE command and the IMS type-2 commands that perform similar functions.

Table 2. Type-2 equivalents for the /PURGE command
Task	/PURGE command	Similar IMS type-2 command
Stops input messages for a particular transaction code.	/PURGE TRAN `tranname`	UPDATE TRAN NAME(`tranname`) START(SCHD) STOP(Q)

Examples

The following are examples of the /PURGE command:

Example 1 for /PURGE command

Entry ET:

  /PURGE FPPROG ALL

Response ET:

  DFS058I  PURGE COMMAND COMPLETED

Explanation: All message-driven programs are taken out of wait-for-input mode and terminated by PSB name as soon as their load balancing group message queue is empty.

Example 2 for /PURGE command

Entry ET:

  /PURGE FPRGN ALL

Response ET:

  DFS058I  PURGE COMMAND COMPLETED

Explanation: All message-driven programs are taken out of wait-for-input mode and terminated by region identifier as soon as their load balancing group message queue is empty.

Example 3 for /PURGE command

Entry ET:

  /PURGE LINE 4

Response ET:

  DFS058I PURGE COMMAND COMPLETED

Response RT:

  DFS059I  TERMINAL PURGING

Explanation: All physical terminals associated with line 4 can receive output sent to them but are not allowed to enter input.

Example 4 for /PURGE command

Entry ET:

  /PURGE LINE 5 7 400

Response ET:

  DFS058I  PURGE COMMAND COMPLETED EXCEPT LINE 400

Explanation: All physical terminals associated with line 5 and line 7 can receive output but are not allowed to enter input. Line 400 is an invalid line number.

Example 5 for /PURGE command

Entry ET:

  /PURGE MSNAME BOSTON

Response ET:

  DFS058I  PURGE COMMAND COMPLETED

Explanation: All messages from a terminal (primary requests), except messages continuing a conversation, will not be queued for the destinations represented by MSNAME BOSTON. This includes all messages destined for remote transactions with the SYSID of the MSNAME, and for remote logical terminals associated with this MSNAME.

Example 6 for /PURGE command

Entry ET:

  /PURGE TRAN PIT, SEED

Response ET:

  DFS058I  PURGE COMMAND COMPLETED

Explanation: Transactions PIT and SEED can still be scheduled but input for these transactions cannot be queued unless the input originates as output from an application program.

Example 7 for /PURGE command

Entry ET:

  /PURGE TRAN ALL CLASS 2

Response ET:

  DFS058I  PURGE COMMAND COMPLETED

Explanation: All transactions associated with class 2 are marked as purged. No further transactions are queued from terminals.