LISTSTAT – List Status of Current Plan Objects

Use LISTSTAT to LIST items and set a return code based on their status.

LISTSTAT <resource> <arguments> [POLICY(<RC-expression>)]

LISTSTAT performs a LIST request to find the relevant elements within HCL Workload Automation for Z. If the LIST request returns multiple records, the command ends with RC=8.

The arguments for LISTSTAT are the same as the arguments for the related LIST request for the same resource with the exception of POLICY which is used to set the return code policy for the request.

If you want to set your own Return Code policy you can add the POLICY keyword to the LISTSTAT command. The POLICY keyword allows you to set specific return codes for groups of status values, and set a return code for anything that does not match any of your listed statuses:
POLICY(<status_list1>=<rc1>,<status_list2>=<rc2>,...,
        <status_listn>=<rcn>,<catch_all>)

If you omit to supply a catch all return code then you will get RC=99 when no match occurs. The return code must be a non-negative whole number.

There is a special status of ? that occurs if the LISTSTAT statement does not find an operation. This allows you to decide what return code to set for an operation not found.

For example, the following command:
LISTSTAT CPOPCOM ADID(TWSCDAILYPLAN) OPNO(010) IA(0805281200)
         POLICY(AR*=10,SW=20,C=30,?=90,40)
would return 10 if the status was A, R or *, it would return 20 if the status was S or W, it would return 30 if the status was C and return 40 if any other status was encountered. If the operation was not found in the current plan then 90 would be returned.
Another use of POLICY is to separate acceptable from unacceptable conditions, as in the following example:
LISTSTAT CPOPCOM ADID(TWSCDAILYPLAN) OPNO(010) IA(0805281200)
         POLICY(C=0,?=0,20)

This command ends with return code zero if the operation is complete or it is not in the current plan, but returns 20 if it is in any other state.

Note:
  • Workload Automation Programming Language will return 4 if the item being listed is not found, 8 if more than one item is found, 12 if you have made a syntax error and 16 if an initialization error occurs. It is recommended, that you avoid using these return codes in your POLICY if you need to distinguish those errors from your return codes.
  • If you run multiple LISTSTAT commands in one session, the highest return code is returned.
  • If any command other than LISTSTAT breaches the OPTIONS STOPRC setting, the LISTSTAT return code is not returned.
  • The LISTSTAT command itself will only ever complete with return codes 0, 4, 8 or 12. The actual return code for the status is returned as Workload Automation Programming Language terminates.
  • The SETMAX command has no impact on the return code set by LISTSTAT.
  • If the LISTSTAT command does not find an operation, a return code of 4 is set. However if you have a POLICY keyword and you have not added a specific entry for the special status of ?, then the “catch all” return code will be returned which may override the 4 if it is higher. This allows you to treat “not found” as a undesired status along with any others in the scope of the “catch all”.
The following list shows the supported resources for LISTSTAT:
CPOC
Occurrences in the Current Plan
CPOPCOM
Operations in the Current Plan
CPWSCOM
Workstations in the Current Plan
CSRCOM
Special Resources in the Current Plan
The following list shows the standard return codes are:
8
More than one record identified
12
Workload Automation Programming Language error
99
Unexpected status returned or no match in POLICY
The following list shows the return codes that are set when POLICY is not specified:
4
Resource not found or user ID has no RACF authorization to read the resource
31
Occurrence status C (completed)
32
Occurrence status D (deleted)
33
Occurrence status E (ended in error)
34
Occurrence status P (processor pending)
35
Occurrence status S (started)
36
Occurrence status U (undecided)
37
Occurrence status W (no started operations)
40
Operation status *
41
Operation status A (waiting for input to arrive)
42
Operation status R (ready)
43
Operation status S (started)
44
Operation status C (completed)
45
Operation status D (deleted)
46
Operation status I (interrupted)
47
Operation status E (ended in error)
48
Operation status W (waiting for a predecessor)
49
Operation status U (undecided)
50
Operations status X (excluded)
60
Workstation status A (active)
61
Workstation status O (offline)
62
Workstation status F (failed)
70
Special resource available
71
Special resource unavailable