API provider data from SMF type 123 subtype 1 version 2 records

The SMF type 123 subtype 1 version 2 record is used to capture enhanced data for individual API provider requests.

To configure IBM® 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

The SMF type 123 subtype 1 version 2 record contains the following sections:
  1. Standard SMF header.
  2. SMF type 123 header extension.
  3. Server and Request data triplets section.
  4. Server section (one instance).
  5. Request data section (multiple instances).
Important: SMF 123 subtype 1 version 2 and SMF 123 subtype 2 version 2 together are known as version 2 of the SMF 123 records. Version 2 records contain data for multiple requests in a single SMF record. Therefore, the record is only written when one of the following conditions are met:
  • The server processes the required number of requests to fill a record. Currently, this is 20.
  • The apiProviderMaxDelay or apiRequesterMaxDelay attributes are 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. From V3.0.74.0, value is 2; prior to this value is 1.
1 SMF123_SERVER_FEATURE_MAJOR 1 CHAR From V3.0.74.0, z/OS Connect feature major version.

For SMF123_SERVER_SECT_VERSION=1, field is reserved. See Note.
2 SMF123_SERVER_FEATURE_MINOR 1 CHAR From V3.0.74.0, z/OS Connect feature minor version. See Note

For SMF123_SERVER_SECT_VERSION=1, field is reserved.
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 that the server is running. A server with the zosConnect-2.0 feature configured can run only OpenAPI 2 APIs. A server with the zosConnect-3.0 feature configured can run only OpenAPI 3 APIs. A server cannot be run with both the zosConnect-2.0 feature and the zosConnect-3.0 feature configured. For a server with the zosConnect-2.0 feature configured, SMF123_SERVER_FEATURE_MAJOR is set to the value 2 and SMF123_SERVER_FEATURE_MINOR is set to the value 0.
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:
0 = Unknown
1 = API
2 = Service
3 = Admin
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 Service name.
264 SMF123S1_SERVICE_VERSION 8 CHAR Service 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 IBM 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. See Note 2.
720 SMF123S1_TIME_SOR_RECV 16 STCKE Time the response was received from the system of record. See Note 2.
736 SMF123S1_SP_NAME 16 CHAR Service provider name. 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. See Note 2.
784 SMF123S1_SOR_IDENTIFIER 64 CHAR System of record identifier. Value of com.ibm.zosconnect.spi.Data.SOR_IDENTIFIER. See Note 2.
848 SMF123S1_SOR_RESOURCE 128 CHAR System of record resource. Value of com.ibm.zosconnect.spi.Data.SOR_RESOURCE. See Note 2.
976 SMF123S1_REQ_ID 8 BINARY Request identifier that is unique within a IBM 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 3.
1048 SMF123S1_REQ_HDR1 64 CHAR Request header.

<header1name>:<header1value>
1112 SMF123S1_REQ_HDR2 64 CHAR Request header.

<header2name>:<header2value>
1176 SMF123S1_REQ_HDR3 64 CHAR Request header.

<header3name>:<header3value>
1240 SMF123S1_REQ_HDR4 64 CHAR Request header.

<header4name>:<header4value>
1304 SMF123S1_RESP_HDR1 64 CHAR Mapped response header.

<header1name>:<header1value>
1368 SMF123S1_RESP_HDR2 64 CHAR Mapped response header.

<header2name>:<header2value>
1432 SMF123S1_RESP_HDR3 64 CHAR Mapped response header.

<header3name>:<header3value>
1496 SMF123S1_RESP_HDR4 64 CHAR Mapped response header.

<header4name>:<header4value>
Note:
  1. The value is one of the following:
    • The authenticated username.
    • From V3.0.58.0, when apiProviderEarlyFailure="true" is configured:
      • For a request that fails basic authentication with the 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 z/OS Connect server, with a 401 response code, the value of the "sub" claim in the JWS.
      • The unauthenticated username.
  2. SMF 123 SOR data is not available for IMS DB.
  3. Tracking tokens are currently supported by the CICS®, IMS and REST client service providers.
    • For CICS, up to IBM z/OS Connect V3.0.29.0, the tracking token is available in the user correlation data field USERCORRDATA of the task association data.

      From V3.0.30.0, the tracking token is available in the adapter data field ODADPTRDATA1 of the task association data, and the adapter field ODADPTRID contains the IBM z/OS Connect product identifier in the format IBM_zOS_Connect_CICS_SP <product_version><product_buildlevel>.

      CICS makes this data available to applications through the INQUIRE ASSOCIATION system command. CICS also records this information in the OADID and OADATA1 fields 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_OFF field 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 REST endpoints, 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-ID HTTP header on each request.
    • 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-ID HTTP header on each request.

      Db2 takes the value in the X-Correlation-ID header and assigns it to the Db2 CURRENT CLIENT_CORR_TOKEN special register for access by application processes.

      Db2 also records the value of X-Correlation-ID as the client correlation token in the accounting correlation header record of Db2 trace. The full length correlation token value is reported in the QWHCCTKN_D field of the trace record which is located using fields QWHCCTKN_OFF, QWHCCTKN_LEN, and QWHCCTKN_VAR. These trace records can be written to SMF 101 records or GTF.

    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 2 for CICS and IMS, and in Table 3 for REST endpoints.

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.