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 must be APF-authorized.
The service can also be used to determine if 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
|
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 zero. If it contains zero, 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 complete list of possible return code values, see 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. 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
codes 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 the reason codes, see z/OS UNIX System Services Messages and Codes.
Usage notes
- 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.
- 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.
- The THLIEP_FUNCTIONCODE and the THLIEP_MRSMFFLAGS fields may be cleared by any syscall and therefore values in these fields should not be expected to be retained across syscalls.
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.
- When using 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.
- When using the BPX.SMF.type.subtype FACILITY
class authorization, the type and subtype sections
in the FACILITY class name do not have leading zeros. Some examples:
- BPX.SMF.7.0
- BPX.SMF.119.94
- BPX.SMF.0.0
Examples
For an example that uses this callable service, see BPX1SMF (smf_record) example.
MVS-related information
- 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.
- See Setting up the BPX.* FACILITY class profiles in z/OS UNIX System Services Planning for a description of the BPX.SMF FACILITY class profile and how it is created.