Implementation of the CX10GVID API
CX10GVID returns control to your program after the service is completed successfully.
The answer area contains an SMF type 79 record.
When the CMF CX10GVID API is implemented, the values appearing on the SDSF DA screen are calculated by the API. The API prepares either a type 79-1 or a type 79-2 SMF record image, whichever type value is requested, and returns it to the caller--in this case, SDSF.
To support CX10XDGS, as well as other MVS performance tools, CX10GVID can also return record images for all other SMF type 79 subtypes. The CMFMON write facility (CX10GV79), not the CMF Extractor, writes the type 79 records to SMF or CMF data sets.
The CMF type 79 API is distributed in hilevel.BBLINK with the module name of CX10GVID and an alias name of ERBSMFI assigned to it. ERBSMFI is the name of the RMF type 79 API.
Application programs written to use the RMF ERBSMFI API can also use the CMF CX10GVID API. To do this, you must make the hilevel.BBLINK library available to the application by including it in a //STEPLIB or system linklist data set. Alternatively, you can copy or link edit CX10GVID to a library that is accessible to the desired application. If RMF is also present on your system, you must make sure that the intended API routine (either ERBSMFI distributed with RMF or ERBSMFI distributed with CMF) is available to the applications requesting it. If both modules are accessible, the MVS control program selects the first ERBSMFI found according to the MVS rules of load module search. For more information, see Additional-CMF-API-considerations.
Customization of the Extractor to get data
Some data is available only when the MVS PAS is running with CXEN=Y and the appropriate sampler is active in CPM mode.
For example, in a PR/SM environment, the CPU sampler must be active in CPM mode for the API to return the system CPU utilization. When the CPU sampler is not active (in CPM mode) in a PR/SM environment, the API returns a value of -1 (x’FFFFFFFF) instead of the CPU utilization value.
The following table lists the Extractor samplers that are required for SMF 79 record subtypes:
Subtype | Data description | Required CMF Extractor control statement |
|---|---|---|
8 | Transaction Activity | WORKLOAD |
9 | Device Activity | DEVICE |
11 | Paging Activity | ASMDATA |
13 | I/O Queuing Activity for 438x and 308x processors | IOQ |
14 | I/O Queuing Activity for ES/9000 and 3090 processors | IOQ |
All samplers must be active in CPM mode. | ||
Calling CX10GVID
When the CMF CX10GVID API is implemented, an application program calls program CX10GVID using standard MVS linkage conventions and passing the parameter list.
The invoking program must provide a buffer into which the API returns the requested data.
CX10GVID must be called in 31-bit addressing mode. It can be invoked by unauthorized programs, but the fields in the following table are returned only when the caller is running in Supervisor state or is APF-authorized:
Subtype | Field | Description |
|---|---|---|
9 | R799CUB R799DVB R799DPB | control unit busy delay time device busy delay time director port busy delay time |
11 | R79BDEVN R79BCU | page data set device name page data set control unit name |
When a caller requests subtype 2 record images, the BBX subsystem (BBXS) must be active or the subtype 2 record images returned are incomplete. If BBXS is not active, the following occurs:
- The real storage utilization fields of subtype 2 (listed below) contain null data.
- Bit R792RSM of byte R792FLG is on, signifying that the fields are invalid.
Subtype 2 real storage utilization fields affected by BBXS are shown in the following table.
Field | Description |
|---|---|
R792PRFX | total fixed frames |
R792FXBL | fixed frames below the 16-MB line |
R792NLQF | non-LSQA fixed frames |
R792LSQA | LSQA fixed frames |
R792SLQR | LSQA real storage pages |
R792LSQE | LSQA expanded storage pages |
When a caller requests subtype 3 record images, BBXS must be active or the subtype 3 record cannot be returned.
General-purpose registers
At entry to CX10GVID, the following general-purpose registers must contain the values described in the following table.
Register | Value |
|---|---|
1 | address of the parameter list |
13 | address of a standard, 72-byte save area |
14 | return address |
15 | entry-point address of CX10GVID |
Return codes for CX10GVID
Return codes for CX10GVID are different from those of the XDS APIs. After return from CX10GVID, register 15 contains one of the following return codes:
Return code | Description |
|---|---|
0 | all requested data in the buffer was returned |
4 | invalid syntax, no buffer address |
8 | operating system not supported |
16 | no data currently available |
20 | ESTAE macro failed |
24 | API abend, or GETMAIN failure |
28 | data would not all fit in buffer; partial data returned |
32 | data not available; CMF sampler not active |
36 | data not available; sampler is recording |
40 | channel measurement not active |
44 | requested subtype is not applicable in goal mode |
64 | more than 64K devices requested; only 64K devices returned |
100 | invalid input record type or subtype |
104 | record buffer too short; no data returned |
108 | request type not known |