Verbs and Built-in Functions › &SMFWRITE

&SMFWRITE

(z/OS systems only) Writes a record to the SMF data set.

&SMFWRITE   [ TEST ] [ RECID=nnn ] 
            hexadecimal-string

NCL processes executing in z/OS regions could need to record SMF information for later analysis and off line processing. You can write a procedure that creates an SMF record, holding the information that you wish to record, then use &SMFWRITE to write the record to the SMF data set.

Operands:

TEST

Specifies that all formatting of the SMF record is to be performed but the record will not be written to SMF. Instead the data provided is dumped to the activity log with an SMFWRITE eye catcher.

RECID=nnn

Specifies the (decimal) SMF record type to be generated. Range is 0 to 255. Default is as set by the SYSPARMS SMFID operand.

If RECID is not specified, the following occurs:

• The default as set by the SMF Customizer Parameter Group (/PARMS) is used.
• The SMF Record Identifier field is set to the desired default value. To Display this value, use the /SYSPARM shortcut to display the SMFID sysparm.

hexadecimal-string

The data to be written as an SMF record. This is provided in expanded hexadecimal form, that is, if the record is to contain the characters AB, the hexadecimal string will express them as C1C2.

Example1:

The following &SMFWRITE call uses the default SMF Record Identifier value and generates the SMF data set record containing the string set in the &MYDATA variable.

&MYDATA = &STR THIS DATA WILL BE WRITTEN TO SMF
&SMFREC = &HEXEXP &MYDATA
&SMFWRITE &SMFREC

Example 2:

The following code extract only sends the output to the product region’s activity logs as TEST output.

&MYDATA = &STR THIS TEST SMF DATA IS SENT TO LOG ONLY
&SMFREC = &HEXEXP &MYDATA
&SMFWRITE TEST RECID=132 &SMFREC

This produces the following output in the activity log:

SMFWRITE +0000 00380000 3E840003 79630107 024FC3C1  .... .d.. `... .|CA
SMFWRITE +0010 F3F1E3C8 C9E240E3 C5E2E340 E2D4C640  31TH IS T EST SMF
SMFWRITE +0020 C4C1E3C1 40C9E240 E2C5D5E3 40E3D640  DATA IS SENT TO
SMFWRITE +0030 D3D6C740 D6D5D3E8                    LOG ONLY

Notes:

• The header of the SMF record is created by the &SMFWRITE verb.
• hexadecimal-string is compressed by the &SMFWRITE verb. The use of the &HEXEXP built-in function assists in the formatting of hexadecimal data strings prepared for &SMFWRITE.
• Enter /SYSPARM to access the SMFTRACE system parameter.
• The SMFTRACE system parameter (/SYSPARM at the command prompt), when set to YES, can be used to dynamically request the writing of the SMF record to the activity log. It is done regardless of the TEST operand specification. When the TEST operand is specified on the &SMFWRITE verb, the SMF record is written to the activity log only, regardless of the SMFTRACE system parameter setting. Normally, only background users can write data to SMF using &SMFWRITE verb. The SMF record is written to the activity log regardless of the authorization. Message N25B02 is logged if authorization fails.
• The use of &SMFWRITE is authorized by the NCL file ID access authorization exit. For more information about using &SMFWRITE, see the Security Guide. By default, &SMFWRITE is always authorized if executed by a system level procedure and always denied if executed by a process executing on behalf a real user. You must implement an NCL File ID Access Authorization exit to authorize use of &SMFWRITE by ordinary users.
• &SMFWRITE operates only if your product region is running as an authorized task.

Return Codes:

On completion, &RETCODE is set to one of the following values:

0

Operation was successful. &ZFDBK = SMF return code.

4

SMF inactive. &ZFDBK = SMF return code.

8

SMF operation failed. &ZFDBK = SMF return code.

12

Invalid system for request or not APF authorized.

16

User is not authorized for request.

More information:

&HEXEXP