smf_record (BPX1SMF, BPX4SMF) — Write an SMF record

Function

The smf_record callable service writes an SMF record to the SMF data set. The caller must be permitted to the BPX.SMF resource profile in the FACILITY class or be APF-authorized.

The service can also be used to determine whether a particular type or subtype of SMF record is being recorded. Determining whether the type or subtype is being recorded avoids the overhead of data collection if the SMF record is not going to be recorded.

Requirements

Operation Environment
Authorization Supervisor state or problem state, any PSW key
Dispatchable unit mode Task
Cross memory mode PASN = HASN
AMODE (BPX1SMF) 31-bit
AMODE (BPX4SMF) 64-bit
ASC mode Primary mode
Interrupt status Enabled for interrupts
Locks Unlocked
Control parameters All parameters must be addressable by the caller and in the primary address space.

Format

The syntax format is as follows:
CALL BPX1SMF,(Smf_record_type,
              Smf_record_subtype,
              Smf_record_length,
              Smf_record_address,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SMF with the same parameters. The Smf_record_address parameter is a doubleword.

Parameters

Smf_record_type
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the SMF record type. See z/OS MVS System Management Facilities (SMF) for information on SMF record type and SMF record layout.

Smf_record_subtype
Supplied parameter.
Type:
Integer
Length:
Fullword

The name of a field that contains the SMF record subtype. See z/OS MVS System Management Facilities (SMF) for information about SMF record type and SMF record layout.

Smf_record_length
Supplied parameter.
Type:
Integer
Length:
Fullword

The name of a field that contains the SMF record length.

Smf_record_address
Supplied parameter.
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) that contains the starting address of the SMF record to be written, or 0. If it contains 0, SMF is tested to determine if a particular record type or subtype is being recorded.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the smf_record service returns 0 if the request is successful, or -1 if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the smf_record service stores the return code. The smf_record service returns Return_code only if Return_value is -1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The smf_record service can return one of the following values in the Return_code parameter:
Return_code Explanation
EINVAL The value that was specified for an operand was incorrect. The following reason code can accompany the return code: JRSMFBadRecordLength, JrSMFTypeSubtypeMismatch, or JrSMFRecordLenMismatch.
ENOMEM Not enough storage is available. The following reason code can accompany the return code: JRNoStorage.
EPERM The calling process is not permitted to the BPX.SMF resource in the FACILITY class and the calling processes are not APF-authorized, or the calling process is permitted to the BPX.SMF.xxx.yyy FACILITY class resource but the environment is dirty. The following reason code can accompany the return code: JRSMFNotAuthorized, JREnvDirty.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the smf_record service stores the reason code. The smf_record service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes

  1. To determine whether a particular type or subtype is being recorded, specify the record address as zero.
    • If the return value is zero, the type or subtype is being recorded.
    • If the return value is -1 and the return code is EMVSERR with a reason code of JRSMFNotAccepting, SMF is not recording this type or subtype.
  2. When writing the SMF record, user exit IEFU84 is called if the exit is enabled. If the caller wants user exit IEFU83 to be called instead, set ThliEP_FunctionCode to ThliEP_SMFFlagSet and set the ThliEP_SMFIEFU83 bit to on. These fields are mapped in the THLI control block as described in BPXYTHLI — Thread-level information. z/OS® UNIX callable services cannot be issued by these user exits because they are running under this syscall and nested syscalls are not allowed.
  3. Because the THLIEP_FUNCTIONCODE and the THLIEP_MRSMFFLAGS fields may be cleared by any syscall, the values in these fields should not be expected to be retained across syscalls.
  4. Start of changeThe smf_record callable service supports the use of standard and extended SMF record headers. End of change

Related services

There are no related services.

Characteristics and restrictions

  • In order to use the smf_record callable service, the caller must be APF-authorized or be permitted to either the BPX.SMF or the BPX.SMF.type.subtype resource profile in the FACILITY class where type is the SMF record type to be written and subtype is the SMF record subtype to be written.

    To allow users to generate all SMF records, use the BPX.SMF profile. If the user is permitted to BPX.SMF, the BPX.SMF.type.subtype profiles are not checked. If the user is not permitted to generate SMF records, the exception is generated against the BPX.SMF profile.

  • When you use the BPX.SMF.type.subtype resource profile, the process must be program-controlled and the environment marked MUST_STAY_CLEAN. After the MUST_STAY_CLEAN state is set, any loads or execs are prevented to files that reside in uncontrolled libraries. The MUST_STAY_CLEAN state prevents user-written programs from writing SMF records.
  • The program-controlled attribute is not required when using the BPX.SMF resource profile.
  • If you are using the BPX.SMF.type.subtype FACILITY class authorization, the type and subtype sections in the FACILITY class name do not have leading zeros. BPX.SMF.type.subtype profiles must be discrete.
    Some examples:
    • BPX.SMF.7.0
    • BPX.SMF.119.94
    • BPX.SMF.0.0

Examples

See BPX1SMF (smf_record) example.

MVS-related information

  1. See z/OS MVS System Management Facilities (SMF) for a list of valid SMF record types and subtypes. It also has information about SMF record layout.
  2. See Setting up the UNIX-related FACILITY and SURROGAT class profiles in z/OS UNIX System Services Planning for a description of the BPX.SMF FACILITY class profile and how it is created.