AOCUPDT

Purpose

AOCUPDT performs several status update functions, including:

  • Updating the automation agent status for the resource
  • Identifying any messages associated with the automation agent status change and processing options performed for these messages:
    • Whether a message is issued and logged in the NetView log
    • Which message is issued
    • Whether the message is sent as a notification message to notification operators on a local system (distinct from forwarding to a focal-point system)
    • Whether the message is forwarded to a focal-point system

    AOCUPDT calls the AOCMSG command to handle processing of log and notification messages.

  • Updating SDF status displays with the resource status change
  • Updating the automation manager OBSERVED status

Syntax

Read syntax diagramSkip visual syntax diagramAOCUPDTresourceSTATUS= statusRESTYPE=SUBSYSTEMRESTYPE= typeMSG=571MSG=message_id( message_id, msgtext)NONE(NONE, msgtext)LOG=YESLOG=NOSDF_Options
SDF_Options
Read syntax diagramSkip visual syntax diagram,FPFWD=YES,FPFWD=NO,SDFUPDT=YES,SDFUPDT=NOINFO= textRV= ref_dataFROM= userid( domain)USER=(1..240, "userdata")

Parameters

resource
The name of the resource that status or information updates specified by other AOCUPDT parameters are performed for. This value is required and must be specified first on an AOCUPDT call. You can use the following formats for resource.
Format Example
system_name.resource PROD.TSO or PROD.VTAM
system_name.resource/component PROD.TSO/SUBSYS
system_name.resource
/major_component.component		 SYSPLEX.SYSTEM/SAPLEX.CONFIG
resource TSO or VTAM

The system_name variable defaults to AOFSYSNAME.

The component needs to be specified if the resource name is not defined in the tree. This occurs when using BODY/CELL statements in an SDF panel. In case the component itself is not uniquely defined in a tree major_component must be specified for identifying the desired component. Refer to Status Display Facility Definitions for more details about component and major_component.

STATUS
Specifies the new value of the automation agent status for the resource.

When you use this parameter to change status, some other AOCUPDT parameters perform default actions, unless otherwise coded. These parameters include:

  • MSG
  • FPFWD
  • SDFUPDT

If you specify STATUS to change status, but do not specify any of the parameters listed above (thereby using parameter defaults), the following occurs:

  • SA z/OS issues the message AOF571I resource_name SUBSYSTEM STATUS FOR JOB jobname IS status - text and also logs the message in the NetView log.
  • The specified status change is reflected in SDF status panels.

To change the values or actions performed by the MSG, FPFWD, and SDFUPDT parameters, or to preclude their use, you must specify those parameters and desired values.

If a status value that has a length greater than eight characters is used, the status value is truncated to a length of eight characters.

RESTYPE
Identifies the type of resource for the resource parameter. You can specify a resource type of your own choice, with the exception of SYSTEM, which is reserved for internal use only. The default is SUBSYSTEM.
type
A resource type of your own choice.
SUBSYSTEM
A resource type of SUBSYSTEM.
FPFWD
Determines whether the specified status is sent from a local system (the system that AOCUPDT is issued on) to a focal-point system.
YES
The status is sent. This is the default.
NO
The status is not sent.
Note: For status forwarding to a focal-point system to occur, you must already have configured an automation network and defined the automation network to SA z/OS. Refer to IBM Z® System Automation User's Guide for details.
SDFUPDT
Determines whether the specified status change is also reflected in SDF status displays.
YES
The status change is reflected in SDF status displays. This is the default if STATUS is specified.
NO
The status change is not reflected in SDF status displays. This is the default if STATUS is not specified.
MSG
This parameter identifies the message associated with the status change specified with the STATUS parameter. This message is issued to make a note of when the status change occurs. This parameter is applicable only if the STATUS parameter is also specified.

The default is 571, the message ID for SA z/OS status change message AOF571I, resource_name SUBSYSTEM STATUS FOR JOB jobname IS status—text.

This parameter value can be specified using the following formats:
message_id
Identifies the numeric part of a message ID. For example, 571 specifies SA z/OS message AOF571I.
(message_id)
The complete message ID, including message prefix and message number, enclosed in parentheses, for example, (AOF123).
(message_id,msgtext)
The complete message ID, including message prefix and message number, plus message text to be substituted for message variables in the message text. This entire specification is enclosed in parentheses, for example, (123,AA,BB,CC). Quotation marks are not allowed in the message text.

The AOCMSG command substitutes the message text values into message variables &1 through &9 in the fixed message text that is located in the NetView message library. See AOCMSG for details of how this command works. Some message variables are preset to certain values depending on the message ID and message text that are specified on the AOCUPDT call:

  • Variable &1 is always set to AOFRUPDT, which is the name of the automation procedure that the AOCUPDT command processor resides in.
  • If the message text is omitted, the following message variables are preset:
    Var
    Setting
    &1
    AOFRUPDT
    &2
    Time
    &3
    system_name.resource
    &4
    Resource type
    &5
    Subsystem name
    &6
    Subsystem job name
    &7
    Status
  • If the message text is provided and the message_id number is 571, the following message variables are preset:
    Var
    Setting
    &1
    AOFRUPDT
    &2
    Time
    &3
    system_name.resource
    &4
    Resource type
    &5
    Subsystem name
    &6
    Subsystem job name
    &7
    Status

    Variables &8 and &9 can be assigned values from the msgtext portion of this parameter.

  • If the message text is provided and the message_id number is not 571, the following message variables are preset:
    Var
    Setting
    &1
    AOFRUPDT
    &2
    Time
    &3
    system_name.resource
    &4
    Resource type

    Variables &5 through &9 can be assigned values from the msgtext portion of this parameter.

NONE
The operator is not notified that the update has taken place. The text string RESOURCE resource_name STATUS UPDATED TO status_value is written to SDF.
(NONE,msgtext)
The operator is not notified that the update has taken place. The text string msgtext is written to SDF.
LOG
Specifies whether a trace message is written to the NetView log. The message has the following format: AOFRUPDT: system_name resource_name resource_type, STATUS=status. This specification can be overruled by the global variable AOF_AAO_AOCUPDT_LOGGING. A default can be specified by the same global variable. If nothing specified the default is YES. For more information, see the appendix "Global Variables" in IBM Z System Automation Customizing and Programming.
INFO
The SDF INFO attribute shown in the detail panel of an SDF status descriptor. Can be any alphanumeric character up to a length of 80 characters.
RV
The reference value of the SDF status descriptor. The maximum length is 40 characters.
FROM
The user id (operator task) and optionally the domain id of the originator of the status update. The default is the issuing task and local domain id.
USER
The user data that is associated with the resource. The data is stored in a 240-byte area initialized with blanks. The parameter accepts two values:
  1. The offset which defaults to 1 specifies the location in the area where the subsequent data is stored.
  2. The user data enclosed by delimiters. The delimiter can be any printable character greater than x'40' that does not occur in the data.
SDF truncates the data when the offset plus the length of the data exceed the maximum size.

Restrictions and Limitations

AOCUPDT has the following restrictions and limitations:

  • AOCUPDT should only be issued from an automation procedure.
  • Parentheses appearing within message text must be properly paired and balanced.
  • Using AOCUPDT to change a resource status only changes the status. It does not initiate any associated status change processing that occurs if the status change is processed through a command such as ACTIVMSG or TERMMSG. Also, the automation status remains unchanged. For example, if the resource is involved in a STARTUP, and the resource's status is changed to UP via AOCUPDT, this process will not be affected because the automation status will not be changed to IDLE.
  • AOCUPDT captures the status change message with a default severity based on the new status:
    • CRITICAL if the status is BREAKING, BROKEN, or STOPPED
    • IMPORTANT if the status is ABENDING, HALTED, or INACTIVE
    • UNUSUAL if the status is STARTED2, CTLDOWN, or MOVED
    • NORMAL in all other cases

    The default severity can be overridden using the code definitions under pseudo-message ID CAPMSGS. Under CODE2, specify MVSESA for messages with SYSTEMMSG=YES, or otherwise, the subsystem's jobname. The severity used is the content of Value Returned of the first row that matches in the code definitions table. CODE3 is not considered. To avoid message capturing, set Value Returned to *IGNORE*.

Return Codes

0
AOCUPDT processed normally.
4
All requested actions were performed. However, the system detected that some of the data to be changed was the same as the modified data specified on the AOCUPDT call.
8
Incorrect keyword specifications were detected and ignored. All other keywords processed normally.
12
No function keyword was specified on the AOCUPDT call. A resource was identified, but no action to perform on the resource was specified.
16
The specified resource was not found, when the specified resource type (RESTYPE value) is SUBSYSTEM and the system name is the system that AOCUPDT is running on.
20
The resource name length was longer than allowed. When the specified RESTYPE value is SUBSYSTEM, the resource name cannot be longer than 11 characters.
99
A timeout or another error occurred.

Usage

When you use AOCUPDT to change resource status, the status change message is sent to notification operators defined to receive the message. Notification of a status change occurs whether automation flags for the resource are enabled or disabled (set to Yes or No). To suppress sending a message when a status change occurs, specify MSG=NONE along with the STATUS parameter.