INGSTX

Purpose

INGSTX controls user-defined status items. Status items can be defined, updated, queried, and deleted. They are stored in the status item repository within the SA z/OS automation manager.

Each status item has the following attributes that are either set or modified through INGSTX:

• STIORIGN — Status item originator. This field contains the name of the system that the status item is collected from. This field cannot be updated.
• STISTGRP — Status item group. If the status item was defined in the form of two subfields separated by a period, this is the first subfield. Otherwise, the field is empty (null string). This field cannot be updated.
• STISTNAM — Status item name. If the status item was defined in the form of two subfields separated by a period, this is the second subfield. Otherwise, this is the complete name that was specified when the status item was created. This field cannot be updated.
• STIVALUE — Status item’s current value. An arbitrary positive or 0 integer value expressing the status item’s current condition. This field can be updated.
• STIDESCR — Status item description. A textual description of the status. This field can be updated.
• STITRTXT — Status item transient user text. This field can be used to store transient user data. This field can be updated.
• STITCHNG — Status item change time. The format of this field is: CYYMMDDHHMMSSmmm. This field is updated by SA z/OS® when a status time was set the last time. Format = GMT.
• STIPERST — Status item persistency. This field is set upon first mention of this status item. A value of 1 means it is persistent; 0 means it is non-persistent.

Parameters

SET/SETL

This is the function code to define or update a status item. A status item is defined implicitly upon the first mention of the item name. At definition time, you can determine whether the status item should be persistent across SA z/OS sessions or even across IPLs. The PERSISTENT keyword is ignored on subsequent updates of the same status item.

With function code SET the change time in the STITCHNG field is in GMT. If you want to use the local time, use the alternate function code SETL.

QUERY

This is the function code to query one or more status items that match the pattern denoted by namespec. The status item attribute values are positional and are returned in the following format (all on one line):

STIORIGN<del>STISTGRP<del>STISTNAM<del>STIVALUE<del>STIDESCR
<del>STITRTXT<del>STITCHNG<del>STEPERST<del>

where <del> is a non-ambiguous delimiter character. For an attribute that has not been specified, a null string is returned, that is, <del><del>. STISTGRP is the first substring, if any, of the status item name, and STISTNAM is the remainder, if any, excluding the period.

<del> is the character ☐, which represents X'FF'.

DELETE

This is the function code to delete one or more status items that match the pattern denoted by namespec.

namespec

This is either the complete specification of a status item or a specification pattern using the asterisk (*) wildcard character.

Each status item has a system scope. To enable grouping of status items, the name can be divided into two substrings separated by a period (.). For each substring, only alphanumeric characters and the national characters $, &, and # are allowed. The second substring can contain additional periods for readability purposes. The first character must not be a period or a numeric character. Its maximum length cannot exceed 32 characters.

When a wildcard is used, it can be specified at the beginning or at the end of each substring. The following are examples of valid namespecs:

• CICSREGA.MAXTASKS
• CICS*.MAX*
• *.MAX*
• JOB*

Status item names are case-sensitive.

Avoiding the '.' for Status Items with Group names: If a Take Action command on the Tivoli Enterprise Portal (TEP) refers to a namespec of type Group.Name, it is difficult to generate a one word argument with a dot as a separator. You can therefore use a colon (:) as a separator instead, resulting in a namespec of type Group:Name. The corresponding notation in the Take Action command is therefore:

&Status_Items.Group:&Status_Items.Name

attributes

Each status item has a set of optional attributes. They are specified in attribute=value pairs. If the value is a string that contains blanks, or you want to preserve the case of the characters, enclose value in single or double quotation marks.

Valid attributes are:

STIDESCR=description

A textual description of the status item. The maximum length is 32 characters. Basically, all readable characters are allowed.

STITRTXT=transientText

User-specific text that provides further details about the status item’s value. The maximum length is 128 characters. Basically, all readable characters are allowed.

STIVALUE=value

An arbitrary 4-byte positive or 0 (zero) integer value of the status item, up to 2,147,483,647. If not specified, the default is set to 0.

SCOPE

This keyword indicates whether the request that is specified addresses status items from the local system only or from all systems in the sysplex (more specifically, all systems connected to the automation manager’s XCF group).

SCOPE=LOCAL

Only status items bound to the local system are addressed. This is the default.

SCOPE=SYSPLEX

Status items from all systems in the same sysplex are addressed. This scope is not allowed for SET requests.

WAIT

This keyword indicates whether the request is executed synchronously or asynchronously and, if synchronously, how long the caller is willing to wait for an answer. A request will be discarded if the default or user-specified wait time expires.

Note: This parameter is always either YES or a time period for QUERY requests.

WAIT=YES

The request is executed synchronously, that is, the caller regains control only when the request has been processed by the automation manager, either completely or after waiting for more than 30 seconds. If the request could not be processed within this time, it is discarded. This is the default option.

WAIT=NO

The request is executed asynchronously, that is, the caller regains control immediately after the request was accepted by the automation manager. The automation manager executes the request in the background.

WAIT=nnn

This option is similar to WAIT=YES with the difference that the maximum time the caller waits for the request to complete is specified as nnn seconds. Specify any value between 1 and 999 seconds.

PERSISTENT

A status item can be defined as persistent to live across SA z/OS sessions or IPLs. Non-persistent status items are implicitly removed from the status item repository in the SA z/OS automation manager upon disconnecting a system from the sysplex XCF group.

PERSISTENT=NO

Status item is non-persistent. This is the default.

PERSISTENT=YES

Status item is persistent.

Return Codes