Implementing the CX10GVID API
(BMC.AMIOPS.SPE2207)
The answer area contains an SMF type 79 record.
When you implement the CMF CX10GVID API, it calculates the values appearing on the SDSF DA screen. The API prepares either a type 79-1 or a type 79-2 SMF record image, (whichever type 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 module name CX10GVID.
You can also use the CMF CX10GVID API with application programs written to use the RMF ERBSMFI API. To do this, you must make the hilevel.BBLINK library available to the application by including it in a //STEPLIB or Link List data set. CX10GVID is normally loaded into ECSA during CMF initialization and is called from the CMF API Stub, CX10APIS, via its alias of ERBSMFI. If RMF is also present on your system, make sure that the intended API routine (either ERBSMFI distributed with RMF or CX10APIS/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. All samplers must be active in CPM mode.
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 |
Calling CX10GVID
When you implement the CMF CX10GVID API, an application program calls the CX10GVID program by 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. Otherwise, the subtype 2 record images returned are incomplete. If BBXS is not active, the following events 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. Otherwise, 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 64,000 devices requested; only 64,000 devices returned |
100 | Invalid input record type or subtype |
104 | Record buffer too short; no data returned |
108 | Request type not known |