/PSTOP command

Use the /PSTOP command to stop the sending and receiving of messages to a particular communication line, terminal, or logical link.

You can also use this command to stop scheduling messages that contain specific transaction codes, to allow the queuing of output messages and input messages to continue, to halt a stalled synchronous program switch request, and to perform validity checks of all parameters entered by the terminal operator.

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 /PSTOP command and keywords
Command / Keywords	DB/DC	DBCTL	DCCTL
/PSTOP	X	X	X
AOITOKEN	X	X	X
CLASS	X		X
FORCE	X		X
JOBNAME	X	X	X
LINE	X		X
LINK	X		X
LTERM	X		X
MSPLINK	X		X
PTERM	X		X
PURGE	X		X
REGION	X	X	X
SYNC	X		X
TRAN	X		X

Syntax

Keywords

The following keywords are valid for the /PSTOP command:

LINE

Specifies the IMS communication line to stop.

LINK

Specifies the link to be stopped; the partner link in another IMS system stops itself and notifies the master terminal operator of that system..

PURGE

PURGE can be used only for one logical link whose physical link is channel-to-channel. PURGE must be used when the partner link is in a system that failed. Otherwise, the link will not become idle after it is stopped.

FORCE

The FORCE keyword is for TCP/IP and VTAM® links and is intended for use when a link does not clean up and assume a PSTOPPED IDLE status during normal PSTOP processing, even though the session is terminated.

After /PSTOP processing is completed on one side of the link, the other side is displayed. If the other side is not in a PSTOPPED IDLE state, the operation must be repeated in the partner IMS system. When both sides are in the PSTOPPED IDLE state, the /RSTART LINK command can be issued to restart the link.

For TCP/IP links, the FORCE option is useful for shutting down an MSC TCP/IP link that does not shut down normally after the link was shut down in the partner IMS system. A link that does not shut down normally might have a NOTIDLE-C status or might otherwise fail to assume a PSTOPPED, IDLE status.

For TCP/IP links, you can issue /PSTOP with the FORCE option at any time. You are not required to shut down a link normally before using the FORCE option.

IMS performs the following actions when processing the FORCE option for a TCP/IP link:

Shuts down the link in the IMS where the command is issued
Notifies the local IMS Connect instance to clean up the send socket
Issues error message DFS3177E MSC DETECTED AN ERROR RETCODE = 00000000, RSNCODE = 00000070, LOSTSESS = FORCESTO
Issues informational message DFS2169I DISCONNECTION COMPLETED ON LINK
Places the link in PSTOPPED ERE IDLE status

Note: To determine if a TCP/IP link session is still active in IMS Connect, issue the WTOR command VIEWMSC lclplkid on the local IMS Connect instance. You can also use the z/OS® MODIFY command QUERY MSC or the IMS type-2 command QUERY IMSCON TYPE(MSC).

For VTAM links, the FORCE option can be used with some VTAM commands to idle and clean up the VTAM link within IMS.

IMS performs the following actions when processing the FORCE option for VTAM links:

Determines if the link started PSTOP processing. If PSTOP processing started, the link displays as PSTOPPED NOTIDLE.
Tests if the hang condition is due to an outstanding VTAM request. If so, IMS issues an inquire request to VTAM to determine if the session is inactive. In that case, IMS simulates the completion of the VTAM request to enable the link to complete PSTOP processing.

You can determine if a session is still active to VTAM by issuing the command DISPLAY NET,SESSIONS,LU1=applid1,LU2=applid2,SCOPE=ALL,LIST=ALL. If it is active, note the SID of the session.

If the VTAM session is not active and it has a PSTOPPED NOTIDLE status to IMS, then issue /PSTOP LINK x FORCE.

If the session is still active to VTAM, then issue VARY NET,TERM,SID=x,NOTIFY=YES,SCOPE=ALL,TYPE=FORCE to VTAM to terminate the session.

Under normal conditions, the VTAM VARY NET,TERM command terminates the session in VTAM and cause IMS to PSTOP and IDLE the link associated with the VTAM session. If the VTAM VARY command does terminate the VTAM session but does not PSTOP and IDLE the link, then the IMS /PSTOP LINK FORCE command can be used to complete the PSTOP and cleanup processing within IMS.

IMS replies with DFS058 /PSTOP LINK COMPLETED EXCEPT LINK x, if the /PSTOP LINK x FORCE command cannot be executed because:

The session is still active to VTAM.
Normal PSTOP processing is not started (issue /PSTOP without the FORCE keyword in this case).
PSTOP processing is not completing because of some reason other than an incomplete VTAM request.

LTERM

Specifies the logical terminal that is to be stopped from sending and receiving messages.

The /PSTOP LTERM command has no effect on an LTERM that is in QLOCK state, or is a remote logical terminal. The LTERM parameter can be generic, where the generic parameter specifies existing LTERMs.

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

If time-controlled operations (TCO) is active, the /PSTOP LTERM command is valid for the DFSTCF TCO LTERM, even if the DFSTCF LTERM is not allocated to a node.

MSPLINK

Stops logons to an MSC TCP/IP or VTAM physical link and enables the operator to issue the /MSASSIGN command to reassign logical links to the physical link. Any links in sessions that were not stopped by the /PSTOP command are not affected by an /MSASSIGN command.

After the /PSTOP command is issued, the status of the link is either PSTOPPED or, for links in a TCP/IP generic resource group, PSTOPGEN.

After the logical link assignments are complete, issue the /RSTART command to permit logons to the physical link.

The /PSTOP MSPLINK command does not apply to CTC or MTM links.

REGION

If the TRAN keyword is specified, the message region is not stopped. A QC status (no more messages) is returned to the application program currently active in the specified region. The scheduler continues to schedule available transactions in the referenced region.

The /PSTOP REGION command is ignored unless both of the following occur:

An active transaction type is specified.
The referenced message region is processing transactions with the wait-for-input option, or the region is an MPP.

If the AOITOKEN keyword is specified, the AO application in wait AOI token state is posted and receives AIB return code X'00000004' and reason code X'0000004C'.

If JOBNAME keyword is specified, the job name for the dependent region must be 1-8 alphanumeric or national ($,#,@) characters. The first character of the job name must be either alphabetic or national.

If the SYNC keyword is specified, the user application in wait synchronous callout state is posted and receives AIB return code X'00000100' with reason code X'0000010C'.

The X'00000100' return code with the X'0000010C' reason code is also returned if the SYNC keyword is used while a user application is waiting for a reply to a synchronous program switch request.

TRAN

Stops the scheduling of transactions; however, the transactions will continue to be processed until the limit count is reached. If the limit count is large, the processing interval will be long. The /DISPLAY command ascertains the status of the transaction; the /ASSIGN command alters the status of the transaction.

If a region is scheduled against a process stopped transaction and there are no more messages available for that transaction, the region does not wait for the next message (wait-for-input-mode). Instead, a QC status (no more messages) is returned to the application. If the region is scheduled and waiting for the next message when the command is entered, the region is notified and a QC status is returned to the application.

A batch message processing region (BMP) scheduled against wait-for-input (WFI) transactions returns a QC status code (no more messages) for /PSTOP REGION, /DBD, /DBR, or /STA commands only.

The /PSTOP command cannot stop the scheduling of Fast Path exclusive transactions but can be used to stop Fast Path potential transactions.

The /PSTOP TRAN command cannot be used for Fast Path exclusive transactions or CPI Communications driven transaction programs.

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

In a shared-queues environment, the /PSTOP TRAN command will result in IMS deregistering interest for the transaction, which indicates that the transaction cannot be scheduled at that IMS.

The /PSTOP 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

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 /PSTOP command processes the rest of the parameters.

The /PSTOP command can be used to reset conditions previously established with the /START, /RSTART, /PURGE, or /MONITOR command.

In a single IMS system, or in the local system in a multiple system configuration, IMS system messages such as broadcast text and terminal status messages (DFS059 TERMINAL STARTED) are not affected by the /PSTOP command. In a multiple system configuration, broadcast messages are queued but not sent across stopped links.

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

If a synchronous program switch request (a DL/I ICAL request to an IMS transaction) stalls for a long period of time, you can use the /DISPLAY ACTIVE REGION command to determine which region contains the stalled application. Then, issue /PSTOP to stop the application and halt the request.

Equivalent IMS type-2 commands

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

Table 2. Type-2 equivalents for the /PSTOP command
Task	/PSTOP command	Similar IMS type-2 command
Stops the scheduling of transactions.	/PSTOP TRAN `tranname`	UPDATE TRAN(`tranname`) START(Q) STOP(SCHD)
Stops logons to the physical link (only for MSC VTAM links).	/PSTOP MSPLINK `mplinkname` \| ALL	UPDATE MSPLINK NAME(`msplinkname` \| *) STOP(LOGON)
Posts the regions in which the program is scheduled so that a new refreshed copy of the program can be obtained on the next schedule of the program.	/PSTOP REGION TRAN `tranname`	UPDATE PGM START(REFRESH)

Examples

The following are examples of the /PSTOP command:

Example 1 for /PSTOP command

Entry ET:

  /PSTOP LINE 4 PTERM 1

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Response RT:

  DFS059I  TERMINAL PSTOPPED

Explanation: LINE 4 PTERM 1 is not sent application program or message switch output and is not allowed to send input. Output messages for the terminal continue to be queued.

Example 2 for /PSTOP command

Entry ET:

  /PSTOP LINE 4 6 200

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED EXCEPT LINE 200

Explanation: LINE 4 and LINE 6 are not allowed to send or receive messages. Message queuing continues. Line 200 is an invalid line number.

Example 3 for /PSTOP command

Entry ET:

  /PSTOP LINK 2 3 4

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Response ET:

  DFS2169I  DISCONNECTION COMPLETED ON LINK 2

Explanation: Logical link 2 is disconnected. This message is received for each logical link that is disconnected.

Response Remote MT:

  DFS2161I  LINK 2 STOPPED BY PARTNER
  DFS2161I  LINK 3 STOPPED BY PARTNER
  DFS2161I  LINK 4 STOPPED BY PARTNER

Explanation: Logical links 2, 3, and 4 stop processing messages. Output queuing continues.

Response ET:

  DFS2169I  DISCONNECTION COMPLETED ON LINK 3

Explanation: Logical link 3 is disconnected. This message is also received when logical link 4 disconnects.

Example 4 for /PSTOP command

Entry ET:

  /PSTOP LINK ALL

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Response Remote MT:

  A DFS2161 LINK n STOPPED BY PARTNER message
  is received for each logical link that was
  operational when /PSTOP was entered.

Explanation: Output to all logical links stops. Output queuing continues. Input is not allowed.

Response ET:

  DFS2169I  DISCONNECTION COMPLETED ON LINK XXX

Explanation: As each logical link is disconnected, this message is received.

Example 5 for /PSTOP command

Entry ET:

  /PSTOP LINK 1 2 3 PURGE

Response ET:

  DFS2272I PURGE KEYWORD INVALID, ONLY ONE
  CTC LINK ALLOWED

Explanation: Only one link can be specified with the PURGE keyword.

Example 6 for /PSTOP command

Entry ET:

  /PSTOP LINK 2 PURGE

Response ET:

  DFS2273I PURGE KEYWORD REJECTED, CURRENT STATUS
  OF LINK IS NORMAL

Explanation: The partner system has not failed and the link appears to be working.

Example 7 for /PSTOP command

Entry ET:

  /PSTOP LTERM APPLE, TREE

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Response RT:

  DFS059I  TERMINAL PSTOPPED

Explanation: The physical terminals associated with logical terminals APPLE and TREE are not sent output that is destined for logical terminals APPLE or TREE, or allowed to enter input. Output queuing continues.

Example 8 for /PSTOP command

Entry ET:

  /PSTOP MSPLINK ALL

Response ET:

  DFS058I  COMMAND COMPLETED

Explanation: All the VTAM physical links are stopped from receiving logons. Any links in session are not affected.

Example 9 for /PSTOP command

Entry ET:

  /PSTOP TRAN SEED

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Explanation: Transaction code SEED can no longer be scheduled. Queuing of the transaction continues.

Example 10 for /PSTOP command

Entry ET:

  /PSTOP TRAN ALL CLASS 3

Response ET:

  DFS058I  PSTOP COMMAND COMPLETED

Explanation: All transactions associated with class 3 can no longer be scheduled. Queuing of the transactions continues.

Example 11 for /PSTOP command

Entry ET:

  /PSTOP REGION 1 TRAN XYZ

Response ET:

  DFS058I  PSTOP COMMAND IN PROGRESS

Response ET:

  DFS0569I PSTOP COMPLETE FOR REGION 1 TRAN XYZ
  DFS0566I PSTOP NOT VALID FOR TRAN XYZ

Explanation: If the DFS0569I message prints, processing of the transaction type, xyz, is stopped in message region 1. If the DFS0566I message prints, the command was ignored because the two required conditions were not satisfied.

Example 12 for /PSTOP command

Entry ET:

  /PSTOP REGION 2 AOITOKEN AOITOK2

Response ET:

  DFS058I PSTOP COMMAND IN PROGRESS

Response MT:

  DFS0569I PSTOP OR STOP COMPLETE FOR REGION 2 AOIT AOITOK2.

Explanation: If the DFS0569I message prints, the AO application in region 2 waiting for a message for AOI token AOITOK2 is posted; the application receives AIB return code X'00000004' and reason code X'0000004C'.

Example 13 for /PSTOP command

Entry ET:

  /PSTOP REGION 2 AOITOKEN  AOITOK2

Response ET:

   DFS058I PSTOP COMMAND IN PROGRESS

Response MTO:

   DFS1190I REGION 2 NOT WAITING ON AOITOKEN AOITOK2

Explanation: If the DFS1190I message prints, the command is ignored because region 2 was not waiting on AOI token AOITOK2.

Example 14 for /PSTOP command

Entry ET:

  /DIS ACTIVE REG

Response ET:

  REGID JOBNAME   TYPE  TRAN/STEP PROGRAM  STATUS         CLASS
      1 MPP610C   TP    NQF1      PMVAPZ12 ACTIVE           1,  2,  3,  4
        BATCHREG  BMP   NONE
        FPRGN     FP    NONE
        DBTRGN    DBT   NONE
        DBRECTA9  DBRC
        DLIECTA9  DLS
        *96081/150611*

Explanation: Message processing program PMVAPZ12 is processing transaction NQF1. The job name of the region is MPP610C

Entry ET:

  /PSTOP REGION JOBNAME MPP610C TRAN NQF1

Response ET:

  DFS058I PSTOP COMMAND IN PROGRESS
  DFS0569I PSTOP OR STOP COMPLETE FOR REGION 00001 TRAN NQF1

Response ET:

  DFS058I PSTOP COMMAND IN PROGRESS
  DFS0566I PSTOP NOT VALID FOR TRAN NQF1

Explanation: If the DFS0569I message is displayed, processing if the transaction type, NQF1, is stopped in message region 1. If the DFS0566I message is displayed, the command was ignored because the two required conditions were not satisfied.

Example 15 for /PSTOP command

Entry ET:

  /DIS ACTIVE REG

Response ET:

  REGID JOBNAME   TYPE  TRAN/STEP PROGRAM  STATUS           CLASS
      1 MPP1A     TP    APOL11    APOL1    WAIT-CALLOUT     1
                  TMEM:   HWS1             TPIPE:  TPIPE1
        JMPRGN    JMP   NONE
        JBPRGN    JBP   NONE
        BATCHREG  BMP   NONE
        FPRGN     FP    NONE
        DBTRGN    DBT   NONE
        DBRZCSAJ  DBRC
        DLIZCSAJ  DLS
  *08235/173441*

Explanation: Message processing program APOL1 is processing transaction APOL11, which is waiting for a response to a synchronous callout request (WAIT-CALLOUT) from transaction pipe TPIPE1.

Entry ET:

  /PSTOP REGION 1 SYNC TPIPE1

Response ET:

  DFS058I PSTOP COMMAND IN PROGRESS
  DFS0569I PSTOP OR STOP COMPLETE FOR REGION 00001 SYNC TPIPE1

Response ET:

  DFS058I PSTOP COMMAND IN PROGRESS
  DFS1190I REGION 00001 NOT WAITING ON SYNTPIPE TPIPE1

Explanation: If the DFS0569I message prints, the user application in wait synchronous callout state is posted; the application receives AIB return code X'00000100' and reason code X'0000010C'. If the DFS1190I message prints, the command is ignored because region 1 was not waiting for a response to a synchronous callout request from transaction pipe TPIPE1.

Example 16 for /PSTOP command

This example demonstrates a scenario for using PSTOP to halt a stalled synchronous program switch request. The following command is issued to determine the status of a waiting program:

/DIS ACTIVE REG

The following response is returned:

REGID JOBNAME  TYPE TRAN/STEP PROGRAM STATUS       CLASS
    1 MPP1A    TP   APOL11    APOL1   WAIT-CALLOUT 1
               TRAN:SKS1              END TIME: 2010.172 12:45:04	
      JMPRGN   JMP  NONE
      JBPRGN   JBP  NONE
      BATCHREG BMP  NONE
      FPRGN    FP   NONE
      DBTRGN   DBT  NONE
      DBRZCSAJ DBRC
      DLIZCSAJ DLS
*10172/120101*
*

The message processing program APOL1 is processing transaction APOL12. The transaction is waiting for a synchronous program switch response from transaction SKS2. The following command is issued to end the wait state:

/PSTOP REGION 1 SYNC SKS2

The command will receive one of the two possible responses. The following response indicates that the PSTOP command successfully ended the wait state:

DFS058I PSTOP COMMAND IN PROGRESS
DFS0569I PSTOP OR STOP COMPLETE FOR REGION 00001 SYNC SKS2

You will receive a different response if the PSTOP command executes successfully but the specified region is not waiting for the specified transaction to respond:

DFS058I PSTOP COMMAND IN PROGRESS
DFS1190I REGION 00001 NOT WAITING ON TRAN SKS2