API requester data from SMF type 123 subtype 2 version 2 records

The SMF type 123 subtype 2 version 2 record is used to capture enhanced data for individual API requester 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 2 version 2 record structure

The SMF type 123 subtype 2 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 2 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 2 version 2 header extension
Table 2. SMF 123 subtype 2 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/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.
2 SMF123_SERVER_FEATURE_MINOR 1 CHAR From V3.0.74.0, z/OS Connect feature minor version.

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 server.xml for the server is located, this includes the server name.
172 SMF123_SERVER_VERSION 16 CHAR Version of the server <v.r.m.f>.
Request data section
Table 5. Request data section
Offset Name Length Data type Data
0 SMF123S2_REQ_DATA_VERSION 1 BINARY Version of request data record. Set to 1.
1 SMF123S2_REQ_APP_TYPE 1 BINARY Request application type:

1 = CICS®
2 = IMS
3 = ZOS
2 SMF123S2_HTTP_RESP_CODE 2 BINARY HTTP response code returned from the API endpoint.
4 SMF123S2_REQ_STATUS_CODE 2 BINARY HTTP status code returned to the z/OS application.
6 SMF123S2_RESP_FLAGS 1 BINARY Response flags.
  (BIT 0): SMF123S2_REQ_RETRIED   BIT Set if the request to the API endpoint was retried after a 401 authentication failure.
  (BITS 1- 7): SMF123S2_RESERVED_03   - Reserved.
7 SMF123S2_RESERVED_04 5 - Reserved.
12 SMF123S2_REQ_PAYLOAD_LEN 4 BINARY Length of the request payload sent to the API endpoint, in bytes.
16 SMF123S2_RESP_PAYLOAD_LEN 4 BINARY Length of the response payload received from the API endpoint, in bytes.
20 SMF123S2_USER_NAME 64 CHAR See Note 1.
84 SMF123S2_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.
92 SMF123S2_USER_NAME_ASSERTED 8 CHAR z/OS application asserted user ID.
100 SMF123S2_API_REQ_NAME 64 CHAR API requester name.
164 SMF123S2_API_REQ_VERSION 8 CHAR API requester version.
172 SMF123S2_ENDPOINT_REFERENCE 32 CHAR Reference to the element in server.xml that identifies the connection to the API endpoint.
204 SMF123S2_ENDPOINT_HOST 128 CHAR The value of the host property of the API endpoint.
332 SMF123S2_ENDPOINT_PORT 2 BINARY The value of the port property of the API endpoint.
334 SMF123S2_ENDPOINT_FULL_PATH 256 CHAR The full path invoked on the API endpoint.
590 SMF123S2_ENDPOINT_METHOD 8 CHAR The HTTP method used for the API endpoint request, GET/POST/PUT/DELETE/OPTIONS.
598 SMF123S2_ENDPOINT_QUERY_STRING 128 CHAR The query string that is passed to the API endpoint.
726 SMF123S2_TIME_STUB_SENT 16 STCKE Time the request left the calling application.
742 SMF123S2_TIME_ZC_ENTRY 16 STCKE Time of IBM z/OS Connect Entry.
758 SMF123S2_TIME_ZC_EXIT 16 STCKE Time of IBM z/OS Connect Exit.
774 SMF123S2_TIME_TOKEN_GET_START 16 STCKE Time IBM z/OS Connect started to obtain one or more access tokens.
790 SMF123S2_TIME_TOKEN_GET_FINISH 16 STCKE Time IBM z/OS Connect completed obtaining the access token(s).
806 SMF123S2_TIME_ENDPOINT_SENT 16 STCKE Time IBM z/OS Connect sent the request to the endpoint.
822 SMF123S2_TIME_ENDPOINT_RECEIVED 16 STCKE Time IBM z/OS Connect received a response from the endpoint.
838 SMF123S2_MVS_JOBNAME 8 CHAR MVS Job Name of the calling application (JSAB -> JSABJBNM).
846 SMF123S2_MVS_JOBID 8 CHAR MVS Job ID of the calling application (JSAB -> JSABJBID).
854 SMF123S2_MVS_SYSNAME 8 CHAR MVS System Name of the calling application (CVT -> CVTSNAME).
862 SMF123S2_MVS_ASID 2 BINARY MVS ASID of the calling application (ASCB -> ASCBASID).
864 SMF123S2_MVS_SID 4 CHAR MVS SID of the calling application (SMCA -> SMCASID).
868 SMF123S2_CICS_APPLID 8 CHAR The APPLID of the CICS region.
876 SMF123S2_CICS_TASK_NUMBER 4 BINARY The CICS task number of the calling application.
880 SMF123S2_CICS_TRANSID 4 CHAR The CICS transaction ID of the calling application.
884 SMF123S2_CICS_RMUOWID 8 BINARY The CICS Recovery Manager UOW ID of the calling application. For correlation with CICS see Note 2.
892 SMF123S2_CICS_NETUOW_PX 20 BINARY CICS Network UOW Prefix of the calling application. For correlation with CICS see Note 2.
912 SMF123S2_CICS_NETUOW_SX 8 BINARY CICS Network UOW Suffix of the calling application. For correlation with CICS see Note 2.
920 SMF123S2_RESERVED_05 4 - Reserved.
924 SMF123S2_IMS_IDENTIFIER 8 CHAR The identifier from the execution parameters of the calling application.
932 SMF123S2_IMS_REGION_ID 4 BINARY The region identifier of the calling application.
936 SMF123S2_IMS_TRANSNAME 8 CHAR The transaction name of the calling application.
944 SMF123S2_IMS_APPNAME 8 CHAR The name of the application.
952 SMF123S2_IMS_PSBNAME 8 CHAR The name of the PSB.
960 SMF123S2_IMS_RECOVERY_TOKEN 16 BINARY The recovery token for the UOW of the calling application. For correlation with IMS see Note 2.
976 SMF123S2_REQ_ID 8 BINARY Request identifier that is unique within a IBM z/OS Connect server instance.
984 SMF123S2_TRACKING_TOKEN 64 BINARY Tracking token.
1048 SMF123S2_REQ_HDR1 64 CHAR Request header.

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

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

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

<header4name>:<header4value>
1304 SMF123S2_RESP_HDR1 64 CHAR Response header.

<header1name>:<header1value>
1368 SMF123S2_RESP_HDR2 64 CHAR Response header.

<header2name>:<header2value>
1432 SMF123S2_RESP_HDR3 64 CHAR Response header.

<header3name>:<header3value>
1496 SMF123S2_RESP_HDR4 64 CHAR Response header.

<header4name>:<header4value>
Note:
  1. The value is one of the following:
    • The authenticated username.
    • From V3.0.58.0, when apiRequesterEarlyFailure="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.
      • The authenticated username.
  2. It is possible to correlate the SMF 123 subtype 2 record with data from CICS and IMS systems.
    • For CICS, the data run time that is required for correlation can be obtained by using the CEMT INQUIRE TASK system command. CICS also records this information in the RMUOWID, NETUOWPX, and NETUOWSX fields of the DFHTASK group in the PERFORMANCE class of SMF 110 SubType 1 records.
    • For IMS, the recovery token represents the work performed within a commit interval and is available in the IMS log records written to the IMS log.

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.