The SM2GDAT macro (SM2 Get Data) supplies all the monitoring data for the most recently completed monitoring cycles; this data is also output in the SM2 report screens. There is an SM2 data buffer for each area (e.g. TIME-IO, DAB, MEMORY). The caller uses a macro call to request all SM2 data buffers or a freely selectable subset of all SM2 data buffers.
The macro copies the requested SM2 data buffers to an output area made available by the caller; the size and address of the output area are passed as parameters to the macro when it is called.
-----------------------------------------------------------------------------
#include "FHDR.H"
#include "SM2GDAT.H"
#include "SM2RC.H"
SM2GDAT( struct SM2GDAT_get_data_mdl SM2_DATA, long length_buffer,
void *buffer_ptr, unsigned long buffer_flags, char *host_name );
-----------------------------------------------------------------------------
struct SM2GDAT_get_data_mdl SM2_DATA
This structure of the type SM2GDAT_get_data_mdl must be defined before the macro is called. After the call, the return code and the actually required size of the output area can be queried. There is a description of the structure in section "Structures of theSM2GMS macro".
long length_buffer
Size of the output area to which the macro is to copy the SM2 data buffer, specified in multiples of 4 Kb.
void *buffer_ptr
Address of the output area to which the macro is to copy the SM2 data buffer.
unsigned long buffer_flags
Integer variable whose binary value specifies the SM2 data buffers to be copied by the macro to the output area. Symbolic constants are available for specifying the SM2 data buffers; if several SM2 data buffers are to be copied to the output area, the corresponding symbolic constants of the SM2 data buffers must be added (section "Example").
Caution
The same symbolic constant cannot be re-added multiple times. If this were to happen, then the required SM2 data buffers would not be supplied. In particular, no symbolic constants may be added to SM2GDAT_BUFFER_ALL.
The following applies to programs which were generated using an earlier version of the macro:
The programs remain executable and do not have to be recompiled.
If they are recompiled than the logical OR operator must be replaced by an addition for the logical constants as otherwise compilation errors will occur.
char *host_name
This parameter, which supports a host network, can be used to call the SM2 data of those hosts to which a connection exists through the MSCF subsystem.
However, this is dependent on the following conditions:
the MSCF connection type must be CCS and the MSCF partner type must be CCS or XCS
the SM2 subsystem must be loaded on the remote host
the SM2 version must be higher than or the same as that of the SM2GDAT version of the local host.
The parameter specifies the address of the field which contains the name of the host.If the SM2 data of a remote host is to be called, the host name of that host must be specified in the field in 8 characters (see the “HIPLEX MSCF” manual [8 (Related publications)]).
If the SM2 data of the local host is to be called, the 8-byte field is to be initialized with zero (binary) or a blank.
Names of the symbolic constants
Constant | Meaning |
SM2GDAT_BUFFER_ACF | Requests the ACF data buffer |
SM2GDAT_BUFFER_ALL | Requests all the SM2 data buffers |
SM2GDAT_BUFFER_BASIC | Requests the BASIC data buffer |
SM2GDAT_BUFFER_BCAM | Requests the BCAM-CONNECTION data buffer |
SM2GDAT_BUFFER_CATEGORY | Requests the CATEGORY data buffer |
SM2GDAT_BUFFER_CHANNEL_IO | Requests then CHANNEL-IO data buffer |
SM2GDAT_BUFFER_CMS | Requests the CMS data buffer |
SM2GDAT_BUFFER_DAB | Requests the DAB data buffer |
SM2GDAT_BUFFER_DISK_FILE | Requests the DISK-FILE data buffer |
SM2GDAT_BUFFER_DLM | Requests the DLM data buffer |
SM2GDAT_BUFFER_FILE | Requests the FILE data buffer |
SM2GDAT_BUFFER_HSMS | Requests the HSMS data buffer |
SM2GDAT_BUFFER_ISAM | Requests the ISAM data buffer |
SM2GDAT_BUFFER_ISAM_FILE | Requests the ISAM-FILE data buffer |
SM2GDAT_BUFFER_MEMORY | Requests the MEMORY data buffer |
SM2GDAT_BUFFER_MSCF | Requests the MSCF data buffer |
SM2GDAT_BUFFER_NSM | Requests the NSM data buffer |
SM2GDAT_BUFFER_OPENFT | Requests the OPENFT data buffer |
SM2GDAT_BUFFER_PERTASK | Requests the PERIODIC-TASK data buffer |
SM2GDAT_BUFFER_PFA | Requests the PFA data buffer |
SM2GDAT_BUFFER_POSIX | Requests the POSIX data buffer |
SM2GDAT_BUFFER_PUBSET | Requests the PUBSET data buffer |
SM2GDAT_BUFFER_RTIME | Requests the RESPONSETIME data buffer |
SM2GDAT_BUFFER_SCHANNEL | Requests the SCHANNEL data buffer |
SM2GDAT_BUFFER_SDEVICE | Requests the SDEVICE data buffer |
SM2GDAT_BUFFER_SESAM_SQL | Requests the SESAM-SQL data buffer |
SM2GDAT_BUFFER_SVC | Requests the SVC data buffer |
SM2GDAT_BUFFER_SYSTEM | Requests the SYSTEM data buffer |
SM2GDAT_BUFFER_TCP_IP | Requests the TCP_IP data buffer |
SM2GDAT_BUFFER_TIME_IO | Requests the TIME_IO data buffer |
SM2GDAT_BUFFER_TLM | Requests the TLM data buffer |
SM2GDAT_BUFFER_USERFILE | Requests the USERFILE data buffer |
SM2GDAT_BUFFER_USERISAM | Requests the USERISAM data buffer |
SM2GDAT_BUFFER_UDS_SQL | Requests the UDS-SQL data buffer |
SM2GDAT_BUFFER_UTM | Requests the UTM data buffer |
SM2GDAT_BUFFER_VM | Requests the VM data buffer |
SM2GDAT_BUFFER_VM_CPU_POOL | Requests the VM cpu pool data buffer |
SM2GDAT_BUFFER_VM_GROUP | Requests the VM-GROUP data buffer |
Return code
The return codes are stored in the standard header.
The standard header is a structure of the type ESMFHDR. It can be addressed by means of the “hdr” structure element of the SM2_DATA structure. The evaluation of the return codes is described in section "Evaluating the return codes".
Notes
SM2GDAT is implemented as a macro.
When the macro is used, the ISM2CALL module from the SYSLIB.SM2.<ver> library must be linked to the program(for native code on x86 servers: SKULIB.SM2.<ver>).
SM2GDAT.H is in the SYSLIB.SM2.<ver> library and can be printed out with the following command:
/PRINT-DOCUMENT FROM-FILE=*LIBRARY-ELEMENT( LIBRARY=SYSLIB.SM2.<ver>, ELEMENT=SM2GDAT.H,TYPE=S)“length_buffer”
SM2 checks whether the size specified in the “length_buffer” parameter for the output area is large enough for the requested SM2 data buffer (but not whether the caller has really made available an output area – e.g. using “malloc” – of the size specified in “length-buffer”).Size of the output area
The size of some data buffers (e.g. the PERIODIC-TASK data buffer) can change dynamically (the number of tasks is not constant). If the output area is not large enough, a corresponding return code is set, and the actually required size is stored in the “length_buffer” structure element of the SM2_DATA structure. In this case, the “length_buffer” parameter must be supplied with the value of the “length_buffer” structure element, enough space must be made available, and the macro call must be repeated with the new “length_buffer” value. The caller can use this to determine the required size for the output area by calling the macro initially with a value of 0 for the “length_buffer” parameter.Making the output area available
The output area for the requested SM2 data buffer must be made available by the caller before calling the macro.Before the macro is called with a sufficiently high value in the “length_buffer” parameter, an output area must always be made available that is at least as large as the value specified in the “length_buffer” parameter. When the macro is called in order to determine how large the output area has to be, a value of 0 should always be specified for the “length_buffer” parameter to prevent a situation in which the size specified in the “length_buffer” parameter happens to be large enough but the actually available output area is not.Validity of the SM2 data buffers
The data buffers BASIC, TIME_IO, MEMORY, CATEGORY, ACF and SCHANNEL can always be supplied. For all other data buffers, the corresponding monitoring program must be active; whether a monitoring program is active can be checked using the SM2GMS macro. For all requested data buffers, after SM2GDAT has been called and before the data buffer has been evaluated, the “valid” bit should be checked. This is because there are situations in which SM2 supplies the data buffer but it does not contain any valid data. The “valid” bit can be checked with the “state” structure element in the BUFFER HEADER of the data buffer. The BUFFER HEADER is described in section "Structures of the SM2GDAT macro", and section "Example" contains an example of the checking of the “valid” bit.Monitoring data of the data buffers
The chapter "SM2 screen output" contains a detailed description of the monitored data supplied in the data buffers. The screen outputs use the same interface. The monitored data supplied in the data buffers is “raw data” that first has to be converted to units such as percent, accesses per second, and so on. For example, the CPU idle, TU, TPR and SIH times are supplied in units of “0.1 milliseconds”; to convert them to a percentage, they must be divided by the duration of the monitoring cycle (“elapsed_time”) (unit “1/300 seconds”!).The section "Example" contains an example of the use of the macro.
Structure of the output area
In the output area, the caller receives copies of the requested SM2 data buffers. These copies are obtained from the central data buffer to which the SM2 monitoring task writes the monitoring data at the end of each online cycle (or offline cycle, when no online cycle is defined).
The structure of the output area is shown in the following figure.
The output area begins with a global header that contains pointers to the individual data buffers. The “SM2GDAT_global_header_mdl” structure describes the global header.
The pointers to unrequested data buffers are supplied with NULL.
All data buffers have a standard BUFFER HEADER and a data area. The “SM2GDAT_buffer_header_mdl” structure describes the BUFFER HEADER, which contains information on the validity and position of the monitoring data in the data buffer. The structure of the data area depends on the type of the data buffer.
There are four different types of data buffer (see figure above), which are described briefly below; positioning on the data area with the information from the BUFFER HEADER is also explained for the individual types.
In section "Structures of the SM2GDAT macro" you will find detailed descriptions of the different data buffers.
Type 1 | The data area has a fixed length (referred to as “single” in the diagram). In the case of this type, the “fixed_part_dsp” element of the BUFFER HEADER supplies the displacement of the data area from the beginning of the BUFFER HEADER. Data buffers: ACF, BASIC, DLM, HSMS, MEMORY, MSCF, NSM, POSIX |
Type 2 | The data area consists of a number of repeat groups (referred to as “multiple” in the diagram), which all have the same structure; each repeat group contains the monitoring data for a specific monitored object. In the case of this type, the “first_group_dsp” element of the BUFFER HEADER supplies the displacement of the first repeat group from the beginning of the BUFFER HEADER. The other repeat groups come after the first repeat group. The “length_group” element supplies the length of a repeat group, and the “number_groups” element supplies the number of repeat groups in the data area. Data buffers: SCHANNEL, SDEVICE, SVC, UTM |
Type 3 | The data area consists of an area of fixed length (“single”) and a number of repeat groups (“multiple”), which all have the same structure. The area of fixed length contains data that does not refer to a specific object, whereas each repeat group contains the monitoring data for a specific object. In the case of this type, the “fixed_part_dsp” element of the BUFFER HEADER supplies the displacement of the fixed-length data area from the beginning of the BUFFER HEADER, and the “first_group_dsp” element supplies the displacement of the first repeat group from the beginning of the BUFFER HEADER. The other repeat groups come after the first repeat group. The “length_group” element supplies the length of a repeat group. In the case of the BCAM-CONNECTION and CMS data buffers, the number of repeat groups is supplied by the “number_groups” element of the BUFFER HEADER and, in the case of the CATEGORY, CHANNEL-IO, DISK-FILE, FILE, ISAM, PERIODIC-TASK, PUBSET, SESAM-SQL, TCP-IP, TIME-IO, TLM, UDS-SQL, USERFILE, USERISAM, VM, VM-CPU-POOL and VM-GROUP data buffers, by the “used_groups” element in the fixed-length data area. In the case of the PFA data buffer, the number_bcb_groups element supplies the number of repeat groups and the first_bcb_group_dsp element the displacement from the first repeat group. The number of “used_groups” repeat groups that are actually filled may be smaller than the number of “number_groups” present. Data buffers: BCAM-CONNECTION, CATEGORY, CHANNEL-IO, CMS, DISK-FILE, FILE, ISAM, PERIODIC-TASK, PFA, PUBSET, SESAM-SQL, TCP-IP, TIME-IO, TLM, UDS-SQL, USERFILE, USERISAM, VM, VM-CPU-POOL, VM-GROUP |
Type 4 | The data area has a “special” structure. This structure is described in section"Structures of the SM2GDAT macro" In the case of this type, the “fixed_part_dsp” element of the BUFFER HEADER supplies the displacement of the data area from the beginning of the BUFFER HEADER. Data buffers: DAB, RESPONSETIME |
The following table provides an overview of all the data buffers and the structures that describe the data area of the data buffer:
Data buffer | Type | Symbolic constant for selecting the data buffer in “buffer_flags” | Structures |
ACF | 1 | SM2GDAT_BUFFER_ACF | SM2GDAT_acf_single_mdl |
BASIC | 1 | SM2GDAT_BUFFER_BASIC | SM2GDAT_basic_single_mdl |
BCAM-CONNECTION | 3 | SM2GDAT_BUFFER_BCAM | SM2GDAT_bcam_single_mdl |
CATEGORY | 3 | SM2GDAT_BUFFER_CATEGORY | SM2GDAT_category_single_mdl |
CHANNEL-IO | 3 | SM2GDAT_BUFFER_CHANNEL_IO | SM2GDAT_chio_single_mdl |
CMS | 3 | SM2GDAT_BUFFER_CMS | SM2GDAT_cms_single_mdl |
DAB | 4 | SM2GDAT_BUFFER_DAB | SM2GDAT_dab_single_mdl |
DISK-FILE | 3 | SM2GDAT_BUFFER_DISK_FILE | SM2GDAT_disk_file_single_mdl |
DLM | 1 | SM2GDAT_BUFFER_DLM | SM2GDAT_dlm_single_mdl |
FILE | 3 | SM2GDAT_BUFFER_FILE | SM2GDAT_file_single_mdl |
HSMS | 1 | SM2GDAT_BUFFER_HSMS | SM2GDAT_hsms_single_mdl |
ISAM | 3 | SM2GDAT_BUFFER_ISAM | SM2GDAT_isam_single_mdl |
ISAM-FILE | 3 | SM2GDAT_BUFFER_ISAM_FILE | SM2GDAT_isam_file_single_mdl |
MEMORY | 1 | SM2GDAT_BUFFER_MEMORY | SM2GDAT_memory_single_mdl |
MSCF | 1 | SM2GDAT_BUFFER_MSCF | SM2GDAT_mscf_single_mdl |
NSM | 1 | SM2GDAT_BUFFER_NSM | SM2GDAT_nsm_single_mdl |
OPENFT | 3 | SM2GDAT_BUFFER_OPENFT | SM2GDAT_openft_multiple_mdl |
PERIODIC-TASK | 3 | SM2GDAT_BUFFER_PERTASK | SM2GDAT_pertask_single_mdl |
PFA | 3 | SM2GDAT_BUFFER_PFA | SM2GDAT_pfa_single_mdl |
POSIX | 1 | SM2GDAT_BUFFER_POSIX | SM2GDAT_posix_single_mdl |
PUBSET | 3 | SM2GDAT_BUFFER_PUBSET | SM2GDAT_pubset_single_mdl |
RESPONSE-TIME | 4 | SM2GDAT_BUFFER_RTIME | SM2GDAT_rtime_single_mdl |
SCHANNEL | 2 | SM2GDAT_BUFFER_SCHANNEL | SM2GDAT_schannel_multiple_mdl |
SDEVICE | 2 | SM2GDAT_BUFFER_SDEVICE | SM2GDAT_sdevice_multiple_mdl |
SESAM-SQL | 3 | SM2GDAT_BUFFER_SESAM_SQL | SM2GDAT_sesam_sql_single_mdl |
STORAGE-SYSTEM | 4 | SM2GDAT_BUFFER_ST_SYSTEM | SM2GDAT_sts_single_mdl |
SVC | 2 | SM2GDAT_BUFFER_SVC | SM2GDAT_svc_multiple_mdl |
SYSTEM | 3 | SM2GDAT_BUFFER_SYSTEM | SM2GDAT_system_single_mdl |
TCP-IP | 3 | SM2GDAT_BUFFER_TCP_IP | SM2GDAT_tcp_ip_single_mdl |
TIME-IO | 3 | SM2GDAT_BUFFER_TIME_IO | SM2GDAT_time_io_single_mdl |
TLM | 3 | SM2GDAT_BUFFER_TLM | SM2GDAT_tlm_single_mdl |
UDS-SQL | 3 | SM2GDAT_BUFFER_UDS_SQL | SM2GDAT_uds_sql_single_mdl |
USERFILE | 3 | SM2GDAT_BUFFER_USERFILE | SM2GDAT_userfile_single_mdl |
USERISAM | 3 | SM2GDAT_BUFFER_USERISAM | SM2GDAT_userisam_single_mdl |
UTM | 2 | SM2GDAT_BUFFER_UTM | SM2GDAT_utm_multiple_mdl |
VM | 3 | SM2GDAT_BUFFER_VM | SM2GDAT_vm_single_mdl |
VM-CPU-POOL | 3 | SM2GDAT_BUFFER_VM_CPU_POOL | SM2GDAT_vm_cpupool_single_mdl |
VM-GROUP | 3 | SM2GDAT_BUFFER_VM_GROUP | SM2GDAT_vm_group_single_mdl |