API provider data from SMF type 123 subtype 1 version 2 records
To configure z/OS® Connect to capture SMF 123 records, see Configuring the audit interceptor.
You should consider using SMF log streams with compression enabled. For more information, see Setting up and managing SMF recording to logstreams and the COMPRESS parameter in Statements and parameters for SMFPRMxx.
SMF type 123 subtype 1 version 2 record structure
- Standard SMF header.
- SMF type 123 header extension.
- Server and Request data triplets section.
- Server section (one instance).
- Request data section (multiple instances).
- The server processes the required number of requests to fill a record. Currently, this is 20.
apiProviderMaxDelayattribute is set and the maximum delay has expired before 20 requests have been processed.
- The server is shut down.
SMF type 123 subtype 1 version 2 section descriptions
- Standard SMF header
Table 1. Standard SMF 123 header fields. Offset Name Length Data type Data 0 SMF123_LEN 2 BINARY Record length. Maximum size is 32,756. 2 SMF123_SEG 2 BINARY Segment descriptor. 4 SMF123_FLAG 1 BINARY System indicator (0x01011110). 5 SMF123_REC_TYPE 1 BINARY Record type (123 -0x7B). 6 SMF123_TIME 4 TIME (1/100s) Time when record was moved into the SMF buffer, in hundredths of a second since midnight. 10 SMF123_DATE 4 DATE (01YYDDDF) Date when record was moved into the SMF buffer, YY is the current year (0 -99), DDD is the current day (1 -366), and F is the sign. 14 SMF123_SID 4 CHAR System ID from the SID parameter. 18 SMF123_SSI 4 CHAR Subsystem ID. Set to "ZCON". 22 SMF123_SUBTYPE 2 BINARY Record subtype (0x0001 for API provider and 0x0002 for API requester).Note: The first 4 bytes of the standard SMF header, the record descriptor word (RDW), contains the fields SMFxLEN and SMFxSEG. The SMF offload utility, IFASMFDP, strips the RDW from each record, so offsets for the subsequent header fields must be adjusted.
- SMF type 123 subtype 1 version 2 header extension
Table 2. SMF 123 subtype 1 header extension. Offset Name Length Data type Data 0 SMF123_SUBTYPE_VERSION 4 BINARY Record subtype version. Set to 2. 4 SMF123_TRIPLET_COUNT 1 BINARY Number of triplets in this record. Default is x0002. 5 SMF123_TRIPLET_OFFSET 1 BINARY Triplet section offset. 6 SMF123_RESERVED_01 2 - Reserved. 8 SMF123_DATETIME_OFFSET 8 BINARY Local date and time offset (CVTLDTO).
- Triplet section
Table 3. Triplet section Offset Name Length Data type Data 0 SMF123_SERVER_OFFSET 4 BINARY Server ID section offset. 4 SMF123_SERVER_LEN 2 BINARY Server ID section length. 6 SMF123_SERVER_COUNT 2 BINARY Server ID section count. 8 SMF123_REQ_DATA_OFFSET 4 BINARY Request data section offset. 12 SMF123_REQ_DATA_LEN 2 BINARY Request data section length. 14 SMF123_REQ_DATA_COUNT 2 BINARY Request data section count.
- Server section
Table 4. Server section Offset Name Length Data type Data 0 SMF123_SERVER_SECT_VERSION 1 BINARY Version of the server section. Value is 2. 1 SMF123_SERVER_FEATURE_MAJOR 1 CHAR z/OS Connect feature major version. See Note 1. 2 SMF123_SERVER_FEATURE_MINOR 1 CHAR z/OS Connect feature minor version. See Note 1. 3 SMF123_RESERVED_02 1 - Reserved. 4 SMF123_SERVER_SYSTEM 8 CHAR System name (CVTSNAME). 12 SMF123_SERVER_SYSPLEX 8 CHAR Sysplex name (ECVTSPLX). 20 SMF123_SERVER_JOBID 8 CHAR Job ID of the server (JSABJBID). 28 SMF123_SERVER_JOBNAME 8 CHAR Job name of the server (JSABJBNM). 36 SMF123_SERVER_STOKEN 8 BINARY SToken of the server (ASS-BSTKN). 44 SMF123_SERVER_CONFIG_DIR 128 CHAR The path to where the server.xml file for the server is located. This includes the server name. 172 SMF123_SERVER_VERSION 16 CHAR Version of the server in the form v.r.m.f.Note:
- The SMF123_SERVER_FEATURE_MAJOR and SMF123_SERVER_FEATURE_MINOR
together indicate the version of the IBM z/OS Connect
feature the server is running. A server with the zosConnect-3.0 feature
configured can run only OpenAPI 3 APIs. A server with the zosConnect-2.0 feature
configured can run only OpenAPI 2 APIs. A server can’t be run with both the
zosConnect-3.0 feature and zosConnect-2.0 features configured.
For a server with the zosConnect-3.0 feature configured,
SMF123_SERVER_FEATURE_MAJOR is set to the value
3and SMF123_SERVER_FEATURE_MINOR is set to the value
- The SMF123_SERVER_FEATURE_MAJOR and SMF123_SERVER_FEATURE_MINOR together indicate the version of the IBM z/OS Connect feature the server is running. A server with the zosConnect-3.0 feature configured can run only OpenAPI 3 APIs. A server with the zosConnect-2.0 feature configured can run only OpenAPI 2 APIs. A server can’t be run with both the zosConnect-3.0 feature and zosConnect-2.0 features configured. For a server with the zosConnect-3.0 feature configured, SMF123_SERVER_FEATURE_MAJOR is set to the value
- Request data section
Table 5. Request data section Offset Name Length Data type Data 0 SMF123S1_REQ_DATA_VERSION 1 BINARY Version of request data record. Set to 1. 1 SMF123S1_REQ_TYPE 1 BINARY Request type:1 = API
2 SMF123S1_HTTP_RESP_CODE 2 BINARY HTTP response code. 4 SMF123S1_RESP_FLAGS 1 BINARY Response flags. (BIT 0): SMF123S1_REQ_TIMED_OUT BIT Request timed out indicator. (BITS 1- 7): SMF123S1_RESERVED_03 - Reserved. 5 SMF123S1_RESERVED_04 3 - Reserved. 8 SMF123S1_USER_NAME 64 CHAR See Note 1. 72 SMF123S1_USER_NAME_MAPPED 8 CHAR If a distributed ID was sent on the request and is mapped to a SAF username, then this value is the authenticated SAF username. Otherwise, this value is blank. 80 SMF123S1_CLIENT_IP_ADDR 48 CHAR Client IP address. 128 SMF123S1_API_NAME 64 CHAR API name. 192 SMF123S1_API_VERSION 8 CHAR API version. 200 SMF123S1_SERVICE_NAME 64 CHAR z/OS asset name. 264 SMF123S1_SERVICE_VERSION 8 CHAR z/OS asset version. 272 SMF123S1_REQ_METHOD 8 CHAR Method GET/POST/PUT/DELETE. 280 SMF123S1_REQ_QUERY_STR 128 CHAR Query string. 408 SMF123S1_REQ_TARGET_URI 256 CHAR Target URI. 664 SMF123S1_REQ_PAYLOAD_LEN 4 BINARY Request payload length in bytes. 668 SMF123S1_RESP_PAYLOAD_LEN 4 BINARY Response payload length in bytes. 672 SMF123S1_TIME_ZC_ENTRY 16 STCKE Time the request was received by the z/OS Connect server. 688 SMF123S1_TIME_ZC_EXIT 16 STCKE Time the response was ready to be sent to the HTTP client. 704 SMF123S1_TIME_SOR_SENT 16 STCKE Time the request was sent to the system of record. 720 SMF123S1_TIME_SOR_RECV 16 STCKE Time the response was received from the system of record. 736 SMF123S1_SP_NAME 16 CHAR Type of the z/OS asset. Value of com.ibm.zosconnect.spi.Data.SERVICE_PROVIDER_NAME. 752 SMF123S1_SOR_REFERENCE 32 CHAR Reference to the element in server.xml that identifies the connection to the system of record. Value of com.ibm.zosconnect.spi.Data.SOR_REFERENCE. 784 SMF123S1_SOR_IDENTIFIER 64 CHAR System of record identifier. Value of com.ibm.zosconnect.spi.Data.SOR_IDENTIFIER. 848 SMF123S1_SOR_RESOURCE 128 CHAR System of record resource. Value of com.ibm.zosconnect.spi.Data.SOR_RESOURCE. 976 SMF123S1_REQ_ID 8 BINARY Request identifier that is unique within a z/OS Connect server instance. 984 SMF123S1_TRACKING_TOKEN 64 BINARY Tracking token that is padded with spaces (0x40) since V3.0.45 and nulls (0x00) previously. See Note 2. 1048 SMF123S1_REQ_HDR1 64 CHAR Request header.
1112 SMF123S1_REQ_HDR2 64 CHAR Request header.
1176 SMF123S1_REQ_HDR3 64 CHAR Request header.
1240 SMF123S1_REQ_HDR4 64 CHAR Request header.
1304 SMF123S1_RESP_HDR1 64 CHAR Mapped response header.
1368 SMF123S1_RESP_HDR2 64 CHAR Mapped response header.
1432 SMF123S1_RESP_HDR3 64 CHAR Mapped response header.
1496 SMF123S1_RESP_HDR4 64 CHAR Mapped response header.
- The value is one of the following:
- The authenticated username.
- For a request that fails basic authentication with the IBM z/OS Connect server, with a 401 response code due to invalid credentials, the username from the credentials in the Authorization header.
- For a request that fails JWS authentication with the IBM z/OS Connect server, with a 401 response code, the value of the "sub" claim in the JWS.
- The authenticated username.
- Tracking token support.
For information about how to access the information in those fields, see the applicable system of record documentation. The format of tracking tokens is shown in Table 6 for CICS and IMS, and in Table 7 for Db2.
- For CICS®, the tracking token is available in the adapter
ODADPTRDATA1of the task association data, and the adapter field ODADPTRID contains the z/OS Connect product identifier in the format
CICS makes this data available to applications through the INQUIRE ASSOCIATION system command. CICS also records this information in the
OADATA1fields of the DFHCICS group in the PERFORMANCE class of SMF 110 SubType 1 records.
- For IMS, the tracking token is available
in the user data fields in the OTMA header. The
OMUSR_TRCKID_OFFfield in the OTMA user data provides the offset to the tracking token. The tracking token is then recorded by IMS in the X'01' type log record under the MVS APPC message prefix segment.
- For Db2®, the first 4 bytes of the tracking token are
converted to ASCII and the remaining bytes are Base64 encoded. The result is sent in the
X-Correlation-IDHTTP header on each request.
Db2 takes the value in the
X-Correlation-IDheader and assigns it to the Db2
CURRENT CLIENT_CORR_TOKENspecial register for access by application processes.
Db2 also records the value of
X-Correlation-IDas the client correlation token in the accounting correlation header record of Db2 trace. The full-length correlation token value is reported in the
QWHCCTKN_Dfield of the trace record which is located using fields
QWHCCTKN_VAR. These trace records can be written to SMF 101 records or GTF.
Table 6. Format of a tracking token passed to CICS and IMS. Bytes Field Type Description 0-2 Product Identifier Character z/OS product identifier, 'BAQ' in EBCDIC. 3 Version Integer Version of tracking token. 4-5 Correlator length Integer Length of the correlator, in big-endian format. 6-n Correlator Byte array System-wide unique correlator. n+1 Stakeholder token count Integer Number of stakeholder tokens. n+2 Stakeholder token length Integer Length of stakeholder tokens. Present only if the number of stakeholder tokens is not zero. (Use this length to traverse the list of stakeholder tokens to allow for a future increase in the length of stakeholder tokens.) n+3 Stakeholder token list Stakeholder token array List of stakeholder tokens. Present only if the number of stakeholder tokens is not zero. Table 7. Format of a tracking token passed to Db2. Characters Field Type Description 0-2 Product Identifier Character z/OS product identifier, 'BAQ' in ASCII. 3 Version Character Version of tracking token in ASCII. 4-n Encoded tracking information Character Base64 encoded bytes 4-(n+3) of the tracking token in Table 6.
- For CICS®, the tracking token is available in the adapter data field
- The value is one of the following:
Sample JCL to format SMF 123 records
To format the SMF 123 records, use the sample JCL provided. For more information, see Sample JCL to format SMF records.