Measure Reference Manual

Reading in the Declaration Files
Use the TAL compiler ?SOURCE command to read these declaration files into the source code
global declarations:
• $SYSTEM.SYSTEM.EXTDECS0 contains the external declarations for the Measure procedures.
Each Measure procedure used in your program must be specified in the ?SOURCE command.
• $SYSTEM.SYSnn.MEASDECS contains the template structures for the Measure control block,
configuration table, and entity descriptors. It also declares literal identifiers for the error
message codes returned by the procedures and for constants used in the configuration table
and entity descriptors.
Allocating Space for the Measure Control Block
Unless you use only the MEASCLOSE, MEASOPEN, MEASREAD, and MEASREADCONF procedures
in a program, you must allocate space in the program’s global data area for the Measure control
block. You need only one Measure control block per process, regardless of the number of
measurements the process makes.
MEASCB^DEF in the MEASDECS file is the template structure for the control block. This referral
structure allocates space for the control block:
STRUCT .MEASCB(MEASCB^DEF)
The Measure subsystem uses the control block to store data for procedure calls. Do not modify the
contents of the block after you pass it to a procedure.
Before you call the first procedure that uses the control block, you must initialize each element in
the block to -1:
$FILL16(MEASCB, $LEN(MEASCB)/2, -1);
Specifying Entity Descriptors
Like the entity specifications used in the command interface, entity descriptors describe an entity
or set of entities. Use entity descriptors to define the entities to measure and to specify the counter
records to maintain for each entity. Entity descriptors are part of the configuration table that you
pass to the MEASCONFIGURE procedure before starting a measurement.
The MEASDECS file declares template structures for the entity descriptors. For example, the
CPU^DESC template contains the fields you use to define a CPU entity. Each entity descriptor
contains:
• Type. A numeric identifier or a literal that identifies the type of entity being defined. The
MEASDECS file declares the literal for each entity type. See Table 6: Entity Descriptors and
Type Values (page 452)
• Len. The length, in bytes, of the descriptor.
• Cpu^number. The number of the CPU where the entity resides. (A few descriptors use a
different name for this field.)
The remaining fields in a descriptor identify the entity or entities to be measured.
For detailed descriptions of entity descriptors, see Chapter 5: Entity Descriptors (page 451).
Measuring a Set of Entities
In many descriptor fields, you can use wild-card values to indicate all entities of a particular type.
For example:
• In a CPU entity descriptor, the literal -1 in the cpu^number field specifies all CPUs on the
system.
• In a field representing a PIN, channel, ctl, unit, or system number, the literal -1 specifies all.
376 Measure Callable Procedures