ViewPoint Manual

Customizing ViewPoint
ViewPoint Manual—426801-001
6-37
Message Structures for Status
Commands and Responses
busy. This value is a snapshot of the busy timer; successive snapshots are used to
compute a percentage. Counters are scalar values that are used directly. They are a
count of the number of objects up, or throughput counts.
Counter values can be fractions; a Z-SCALE field is included in the ZVPT-STATUS-
ITEM structure. Its value (0, 1, or 2) indicates the number of decimal positions assumed
in the count. Z-SCALE is a static property; it cannot be changed by configuration.
The Z-MAXIMUM-VALUE field is optionally set to contain the maximum value a
counter can attain. This field is used to compute a percentage for the status display if
the item was configured to use the maximum. Some counts, such as throughput counts,
have no definite maximum values. A field called Z-USE-MAXIMUM in ZVPT-
STATUS-ITEM is set during configuration to specify whether the Z-MAXIMUM-
VALUE field is used. The server checks the value of this field in the CHECK-ITEM
command, and chooses to reject the configured value of this field by returning
ZERR-STAT-CNFG-INCOMPATIBLE. If the server accepts a TRUE value (“Y”) in
this field, it should always set Z-MAXIMUM-VALUE in response to the SAMPLE-
ITEM command. Counts of objects up are items for which Z-MAXIMUM-VALUE is
useful. The Z-MAXIMUM-VALUE field can be ignored for busy-timer items.
A timestamp is supplied with each sample. This timestamp is the four-word, Julian-
date-based, microsecond-resolution timestamp at the time of the sample (or as soon as
possible after the sample), as returned by the JULIANTIMESTAMP system procedure
call.
The SAMPLE-LIST command is the equivalent of one or more SAMPLE-ITEM
commands. SAMPLE-LIST improves performance because it retrieves all the
samples—up to a maximum of 16—from a given server with one command. A return
code must be set for each of the 16 requested items. The return code is used in the same
way that the Z-IPC-RETN-CODE is used in SAMPLE-ITEM; that is, 0 (zero) indicates
no error. (Note that Z-IPC-RETN-CODE is still used in the SAMPLE-ITEM
command.) If the value is nonzero, all samples received by the request are in error; the
particular error is determined by the value of Z-IPC-RETN-CODE. If Z-IPC-RETN-
CODE is 0 (zero), return codes for each status item determine the success or failure of
the particular sample.
The SAMPLE-LIST command is sent to servers that implement version C20 of
ViewPoint, as determined by the version value returned in the Z-VERSION-CODE
field. A version value of C20 (or later) indicates that ViewPoint recognizes SAMPLE-
LIST. The ViewPoint status server (ZVPT-STAT-COLL) recognizes SAMPLE-LIST.
Message Structures for Status Commands and Responses
The message structures shown in Figure 6-11 refer to definitions in previous figures: the
message-header definitions (Figure 6-8) and the status-server structure definitions
(Figure 6-10).
Note. Be sure to initialize to 0 (zero) all variables in the reply; this is particularly important for
variables that are otherwise ignored such as Z-OBJECT-INDEX. Variables that are not
initialized can cause unpredictable errors.