SMFEWTM — Writing SMF records

The SMFEWTM macro can be used to write records to the SMF data set. You can use this macro in any exit routine that is in supervisor state except IEFU83, IEFU84, IEFU85, IEFU86, and IEFU29 and in any application program that has APF authorization. The SMFEWTM macro verifies that SMF recording is active and allows the issuer to branch directly to SMF.

When you invoke the SMFEWTM macro, you must include the IEESMCA mapping macro, which maps the SMCA.

Note that you can also write SMF records without using a macro. See smf_record (BPX1SMF, BPX4SMF) — Write an SMF record in z/OS UNIX System Services Programming: Assembler Callable Services Reference.

For records of all types, you must complete the record descriptor word (RDW), and the record type must be provided in the standard or extended header, in accordance with record type requirements described in the Standard and Extended SMF record headers section.

Record types 0 - 127, and 1152 - 2047, which are SMF-formatted records are reserved for IBM® products. For these record types SMF supplies the date and time and system ID in the standard header, and the extended TOD clock and time zone offset in the extended header, if used.

Record types 128 - 255 are available for user-written records. When writing these record types, you must provide all of the information in the standard header, including the date, time, and system identifier. While the system identifier can be any four character identifier, specifying the value of the SID parameter is consistent with the system records SMF produces. For user-written records, SMF supplies the extended TOD clock and time zone offset in the extended header, if used.

If properly defined to the system, all SMF records are given to installation exit IEFU86 and then to installation exit IEFU84 or IEFU85 before they are written to the SMF data set or log stream.

Syntax

[label] SMFEWTM {record address}{,BRANCH=NO }[{,SUBSYS=name}{,WRKAREA=addr }[,MODE=XMEM]]
              {(r)} {,BRANCH=YES}[{,SUBSYS=(reg)}{,WRKAREA=(reg)}]

Parameters

record address

The symbolic address of the record to be written.

(r)

The register number (2 - 12), that contains the address of the record to be written.

Note: SMF does not preserve register 0 when processing SMFEWTM.

BRANCH=NO

BRANCH=YES

Specifies a branch entry (YES) or an SVC entry (NO) to the requested SMF writer routine. The default is BRANCH=NO.

If you specify BRANCH=NO, before SMF writes the record to the SMF data set, the SMF record is given to installation exit IEFU83.

If you specify BRANCH=YES, before SMF writes the record to the SMF data set, the SMF record is given to installation exit IEFU84, or IEFU85 if MODE=XMEM. To use BRANCH=YES, the caller must be in supervisor state, have a protection key of zero, and set register 13 to point to a standard 72-byte save area.

You should note therefore that if you change from using the SMFWTM macro to write SMF records and use the SMFEWTM macro, BRANCH=YES, then the SMF records are given to installation exit IEFU84 (rather than installation exit IEFU83) or IEFU85 if MODE=XMEM.

SUBSYS=name

SUBSYS=(reg)

Specifies the name (or address in register 2 - 12) of the 4-byte field containing the subsystem name. The macro looks for the subsystem name in SMFPRMxx and uses the options for that subsystem to determine if the record is written. The subsystem name must be left-justified and padded with blanks. If you use a register, it must be enclosed in parentheses. If the subsystem name is not found, then the macro uses the options specified for the entire system on the SYS option in SMFPRMxx to determine if the record is written.

If you do not specify SUBSYS, the macro will use the subsystem name for the current address space, for example, TSO for TSO/E users, STC for started tasks, ASCH for APPC/MVS transactions programs, or the name of the job entry subsystem (JES2 or JES3) for batch jobs. If the defaulted subsystem name is not found, then the macro uses the options specified for the entire system on the SYS option to determine if the record is written.

WRKAREA=addr

WRKAREA=(reg)

Specifies the address (addr) or a register (reg, 2 - 12) that contains the address of a five-word work area that you must supply for SMF to use. If you specify a register, it must be enclosed in parentheses. You must specify WRKAREA when you specify MODE=XMEM.

MODE=XMEM

Specifies that the caller is entered in cross-memory mode (the primary address space is not the home address space). The caller must be in primary ASC mode. If you specify MODE=XMEM, you must specify BRANCH=YES and WRKAREA.

Return codes

When the SMFEWTM macro returns control, register 15 contains one of the following return codes.

Code dec (hex): Meaning
00 (00): The record was written without error.
08 (08): The record was not written because the length specified in the RDW was less than 18 bytes, or an SMF record exit changed the length in the RDW to be less than 18 bytes.
16 (10): The record was not written because SMF is not active or has ended abnormally.
20 (14): The record was not written because the installation-written IEFU83, IEFU84, or IEFU85, IEFU86 exit routine suppressed the record.
24 (18): The record was not written because the data was lost.
36 (24): The record was not written because the record type specified is not currently being recorded.
40 (28): The record was not written because a buffer shortage caused the data to be lost.
44 (2C): The record was not written because SMF could not establish recovery.
48 (30): The caller was not in primary ASC mode or an incorrect ASID was encountered.
52 (34): SMF cannot write this record because of an SMF record flooding filter.
56 (38): Record not written because the record contains a malformed record header for an extended record type. See the Generating records with Extended headers section for the rules for generating a record with an extended header.
60 (3C): Record not written because the record was modified by an installation exit (IEFU83, IEFU84, IEFU85, or IEFU86) to contain a malformed record header for an extended record type. See the Generating records with Extended headers section for the rules for generating a record with an extended header.