STATUS — Start and stop a subtask

Description

Use the STATUS macro to change the dispatchability status of one or all of a program's subtasks. For example, the STATUS macro can be used to restart subtasks that were stopped when an attention exit routine was entered.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE: 31-bit
ASC mode: Primary or access register (AR)
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks held.
Control parameters: No requirements.

Programming requirements

None.

Restrictions

The caller cannot have an EUT FRR established.

Input register information

Before issuing the STATUS macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

Using STATUS will degrade performance of the calling program's address space while STATUS runs.

Syntax

The STATUS macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede STATUS.
   
STATUS  
   
␢ One or more blanks must follow STATUS.
   

START
STOP

  
   
   ,TCB=tcb addr tcb addr: RX-type address or address in register (2) - (12).
   
   ,RELATED=value value: Any valid macro keyword specification.
   

Parameters

The parameters are explained as follows:

START
STOP
Specifies that the task identified on the TCB parameter is to be stopped (STOP) or started (START). If you omit the TCB parameter, all subtasks of the originating task are stopped or started.
Note: This parameter does not ensure that the subtask is stopped when control is returned to the issuer. A subtask can have a “stop deferred” condition that would cause that particular subtask to remain dispatchable until stops are no longer deferred. In a multiprogramming environment, it would be possible to have a task issue the STATUS macro with the STOP parameter and resume processing while the subtask (for which the STOP was issued) is redispatched to another processor.
,TCB=tcb addr
Specifies the address of a fullword on a fullword boundary containing the address of the task control block that is to have its START/STOP count adjusted. (If a register is specified, however, the address is of the TCB itself.) If this parameter is not coded, the count is adjusted in the task control blocks for all the subtasks of the originating task.
Note: TCB must reside in 24-bit addressable storage.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.

The RELATED parameter is available on macros that provide opposite services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).

The RELATED parameter may be used, for example, as follows: 
STAT1   STATUS    STOP,TCB=YOURTCB,RELATED=(STAT2,
                  'STOP A SUBTASK')
  .
  .
  .
STAT2   STATUS    START,TCB=YOURTCB,RELATED=(STAT1,
                  'START A SUBTASK')
Note: Each of these macros will fit on one line when coded, so there is no need for a continuation indicator.

Return codes

Return codes from execution of STATUS are as follows:

Table 1. Return Codes for the STATUS Macro
Hexadecimal Return Code Meaning and Action
00 Meaning: Processing completed successfully.

Action: No action necessary.
04 Meaning: Program error. START/STOP request failed. The task you specified is not a subtask of the calling program's task.

Action: Ensure that you specify a task on the TCB parameter that is a subtask of the calling program.

Example 1

Stop all subtasks. 
STATUS   STOP

Example 2

Create a subtask. Stop the subtask, then restart it. 
         PRINT NOGEN
STATUS   CSECT
STATUS   AMODE 31
STATUS   RMODE ANY
*********************************************************************
*  The following code performs the following functions:             *
*      1.  Creates a subtask by issuing the ATTACH macro.           *
*      2.  Stops the subtask by issuing the STATUS macro with the   *
*          STOP parameter.                                          *
*      3.  Starts the stopped subtask by issuing the STATUS macro   *
*          with the START parameter.                                *
*                                                                   *
*********************************************************************
         SPACE 3
***************************************
* Entry linkage                       *
***************************************
         SPACE 3
         STM   R14,R12,12(R13)
         BALR  R12,0
         USING BEGN,R12
BEGN     DS    0H
         ST    R13,SAVE+4
         LA    R15,SAVE
         ST    R15,8(0,R13)
         LR    R13,R15
         EJECT
**********************************************************************
* Attach a subtask and request that it be notified by an ECB when    *
* the subtask completes.                                             *
*                                                                    *
**********************************************************************
         SPACE 3
ATTCH1   ATTACH EP=SUBTASK,ECB=AMYECB
         SPACE 3
         ST     R1,TCBADDR         SAVE SUBTASK TCB ADDRESS
         EJECT
******************************************************************
*  Stop the subtask by issuing STATUS STOP, then restart it by   *
*  issuing STATUS START.                                         *
*                                                                *
******************************************************************
         SPACE 3
         STATUS STOP,TCB=TCBADDR
         SPACE 3
         .
****************************************************
* Processing of other subtasks continues.         *
****************************************************
         .
         STATUS START,TCB=TCBADDR
         SPACE 3
         EJECT
*****************************************************
* Wait until subtask completes, then detach it.     *
*****************************************************
         SPACE 3
         WAIT  1,ECB=AMYECB        WAIT ON E-O-T ECB
         SPACE 3
         DETACH TCBADDR           DETACH SUBTASK
         SPACE 3
         EJECT
***************************************
* End of job                          *
***************************************
         SPACE 3
FINI     DS    0H
         L     R13,SAVE+4
         DROP  R12
         LM    R14,R12,12(R13)
         XR    R15,R15
         BR    R14
         EJECT
***********************************
*   Define constants              *
***********************************
SAVE     DC    18F'0'
*
TCBADDR  DC    F'0'        ADDRESS OF SUBTASK TCB
AMYECB   DC    F'0'        END-OF-SUBTASK ECB
         EJECT
***********************************************
*   Register equates                          *
***********************************************
         SPACE 3
R1       EQU   1
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
         LTORG
         END