Operator commands, messages and SMF records - syncsort_simulate_2000

The DEFCMD, DEFMSG and DEFSMF statements are used to build operator commands, user messages and SMF records. Other rules statements actually request that these statements be performed. For example, the DEFRULE statement can use the WRITEMSG parameter to send a message.

The OPERCMD, WRITEMSG and WRITESMF parameters must specify the name of the associated DEFCMD, DEFMSG and DEFSMF statements. Therefore, unique names must be specified on the commands, messages and SMF records.

For example, the following rule will use the WRITEMSG(TSOACT01) parameter to write a message informing a TSO user that SIMULATE 2000 is active for the session.


DEFRULE TSOTEST CONTINUE(NEXTRULE) IF &JOBNAME EQ (TSOTEST1,TSOTEST2)
THEN SET RESCAN = YES WRITEMSG(TSOACT01)
DEFMSG TSOACT01 "** SIMULATE 2000 ACTIVE FOR &JOBNAME **"

While the DEFSMF statement can only be used to produce an SMF record, the DEFMSG statement has the ability to write the text field as an SMF record, as well as a message. The SMFRID parameter on DEFMSG specifies the record identifier of the SMF record. If an SMFRID parameter is coded, all messages are both written to the job and copied to the SMF files.

Building Commands, Messages and SMF records

The DEFCMD, DEFMSG and DEFSMF statements build the command, message or record text with the use of literal strings and symbolic substitution. The text field must start with a single (') or double quote ("), and stop with the same type of quote. Both character and numeric symbolic fields can be placed in the message.

When symbolic fields are used in quoted text, the symbolic name can be ended with a blank, another ampersand, or a period (.). When the period is used as a separator, the rules compiler will remove the period during the substitution process. For example, the following statement produces a message that includes the job and step names separated by a single period.

DEFMSG PTLMSG01 '&JOBNAME..&STEPNAME IS OKAY'

The message and SMF text fields cannot be continued onto the next line. These fields must start and end on the same control card. To produce a long message or SMF record, multiple text fields can be specified. To continue the text field, add a plus (+) sign after the end of the field, and start another quoted text field on the next control card.

DEFMSG PTLMSG02 'THIS IS A VERY LONG MESSAGE ' +

'THAT CAN ONLY BE HANDLED BY ' + 'MULTIPLE TEXT ENTRIES'

Note: Message and command text fields are limited to 125 bytes after substitution is performed. SMF record text is limited to 1024 bytes after substitution.

The MSG parameter on the DEFPROD and DEFMSG statements determine whether rules processing will automatically add the message name specified on the DEFMSG statement to the message text. If MSG(GENID) was requested, the first DEFMSG example might produce the following message:

PTLMSG01 DON.STEP1 IS OKAY

Your messages can be assigned levels of Information, Warning, Action, Error, or Catastrophic. Related parameters can use an assigned level to determine whether your message or SMF record is written. If no LEVEL is specified on a DEFMSG or DEFSMF statement, the product will bypass level processing and the message or record will always be written.

If a level is assigned, any message using an eight character message identifier will have the level displayed after the message identifier. The MSG(NOLEVEL) parameter can disable the level display. To disable the entire message identifier, the MSG(NOGENID) can be specified.

Message and SMF Record Levels

Internal messages that are produced by SIMULATE 2000 have default message levels. The defaults can be changed with the DIF MESSAGE console command. Messages and SMF records produced through the rules language can have an installation assigned level. One of the following levels can be associated with every user created message and SMF record. The levels are displayed in order of importance: least to most.

I Information - This is the lowest level of a message or SMF record, and includes any message that simply displays additional information about an allocation request. By default, Information messages are not displayed.
W Warning - The product encountered an unexpected condition. This condition will not cause problems, but may be worth examination. By default, Warning messages are not displayed.
A Action - The product has taken an expected action. This message is used to inform the user that the action has occurred. By default, Action messages are displayed.
E Error - The product has encountered an unexpected situation. The situation is judged to be an error, but does not affect the overall performance of the product. This message is used to inform your installation that the error occurred. By default, Error messages are displayed.
C Catastrophic - The product has encountered an unexpected situation. The situation is judged to be an error, and may affect the overall performance of the product. By default, Catastrophic messages are displayed.

Controlling Messages and SMF Records

Internal messages that are produced by SIMULATE 2000 have default message levels. Messages and SMF records produced by the rules language can have an installation assigned level. The MSG LEVEL, SMF LEVEL, LOG LEVEL and USERID LEVEL subparameters on the DEFPROD and DEFENV statements define the minimum level required for the product to write a message or SMF record.

For example, since DEFPROD and DEFENV statements have a default of MSG(LEVEL(A)), only messages that have a level of Action, Error, or Catastrophic will be displayed.

The MSG LEVEL, SMF LEVEL, LOG LEVEL and USERID LEVEL parameters on the DEFPROD statement simply establish the defaults for the same parameters on the DEFENV statements.

Note:

If no LEVEL is specified on a DEFMSG or DEFSMF statement, the product will bypass level processing and the message or record will always be written.

The MSG LEVEL subparameter on the appropriate DEFENV statement controls message processing.

Note:

The MSG LEVEL subparameter on the DEFPROD statement simply establishes the default for the MSG LEVEL on the DEFENV statements.

Note:

If the PTLTRACE tracing facility has been enabled, or a PTLMSG DD DUMMY statement is allocated in the step, all message level processing will be ignored. All messages will be written to the user.

For all internal messages and any installation defined messages using eight character message identifiers, the message level associated with the message will be displayed. If your installation requires that the level not be displayed, use the MSG(NOLEVEL) parameter on the DEFPROD statement to disable level display. To disable the entire message identifier, the MSG(NOGENID) can be specified on the DEFPROD statement.

Using SMF LEVEL to Limit SMF Records

When SIMULATE 2000 is determining whether to write an SMF record, the product uses the SMF LEVEL subparameters found on the DEFPROD and DEFENV statements. The SMF LEVEL subparameters work in the same manner as MSG LEVEL. SMF LEVEL has been provided to allow different level settings when writing SMF records.

For example, your installation may want to echo all messages as SMF records using the SMFRID parameter on the DEFMSG statement. The SMF LEVEL allows the rules to establish different limits for SMF record processing. Message processing might still limit messages to MSG LEVEL(A), but SMF LEVEL(I) could be used to write all messages as SMF records.

The LOG parameter on the DEFMSG, DEFENV and DEFPROD statements allow your rules language to route copies of messages to log data sets allocated to the DIF started task. For internal messages, the LOG parameter on the DIF MESSAGE command can be used to route copies of internal messages.

If the LOG parameter is specified, the product uses the LOG LEVEL subparameters found on the DEFPROD and DEFENV statements. The LOG LEVEL subparameters determine whether a message is displayed.

For example, your installation may want to log a message using the LOG parameter on a DEFMSG statement. The LEVEL parameter on DEFMSG allows the rules to establish different limits for LOG processing. Message processing might still limit messages to MSG LEVEL(A), but LOG LEVEL(I) could be used to log the message.

Using USERID LEVEL to Limit Messages to TSO Users

The USERID parameter on the DEFMSG, DEFENV and DEFPROD statements allow your rules language to route copies of messages to TSO users. For internal messages, the USERID parameter on the DIF MESSAGE command can be used to route copies of internal messages.

If the USERID parameter is specified on DEFMSG, the product uses the USERID LEVEL parameters found on the DEFPROD and DEFENV statements. The USERID LEVEL parameters determine whether a message is displayed.

For example, your installation may want to route a message using the USERID parameter on a DEFMSG statement. The USERID LEVEL allows the rules to establish different limits for userid processing. Message processing might still limit messages to MSG LEVEL(A), but USERID LEVEL(I) could be used when routing the message.

Using Messages for Auditing

Writing information to SMF records for event logging can be helpful in monitoring events in your installation. Unfortunately, the additional SMF processing requirements can complicate this form of monitoring. DIF provides two other facilities that can be used to monitor events that occur during SIMULATE 2000 processing:

The LOG parameter allows the product to make copies of messages, and write them to files allocated in the DIF started task.
The USERID parameter can be used to send a copy of a message to a specific TSO userid.

The USERID parameter on the DEFMSG, DEFENV and DEFPROD statements can be used to forward a copy of a message to a specific userid. Since the product uses the WTO write-to-programmer SVC interface, the TSO userid must allow delivery of the message with a PROFILE INTERCOM command.

By default, the LOG and USERID parameters forward copies of messages to a log data set or userid. If the ONLY subparameter is specified on LOG or USERID, the original message is routed to the log data set or userid, and the message will not appear on the user's job log.

The Message Facility Print Program - DIFMFPRT

The rules language is capable of routing messages and/or records to SMF data sets or the system logger. DIF provides a simple print facility to format the records: DIFMFPRT. When extracting messages from SMF data, DIFMFPRT processes the SMF records after they have been moved from the SYS1.MANn data sets to a sequential file.

SMF EXTRACT - The following JCL can be used to run the DIFMFPRT program to extract messages from the SMF data sets. The program itself can be found in the DTS.R71.LOADLIB library.


 //SMFPRT EXEC PGM=DIFMFPRT,PARM='SMFRID=nnn,LINES=nn'
 //STEPLIB  DD DSN=DTS.R71.LOAD,DISP=SHR
 //SMFFILE  DD DSN=smf.library,DISP=SHR
 //SYSPRINT DD SYSOUT=*

SYSTEM LOGGER EXTRACT - The following JCL can be used to run the DIFMFPRT program to extract messages and/or records from the system logger. The program itself can be found in the DTS.R71.LOADLIB library.


 //SMFPRT EXEC PGM=DIFMFPRT,
 // PARM='DDNAME=ddname,SYSID=id,TYPE=type'
 //STEPLIB  DD DSN=DTS.R71.LOAD,DISP=SHR
 //SYSPRINT DD SYSOUT=*
 //SMFFILE  DD DSN=logger.stream.name,SUBSYS=(LOGR),DCB=(LRECL=32000,BLKSIZE=32000)

	//	DCB=(LRECL=32000,BLKSIZE=32000)
DDNAME		Function: When records are to be extracted from the system logger, a DDNAME parameter can be used to filter the data for the records that were originally directed to a specific log file. If the DDNAME parameter is not specified, no filtering will occur.
		Default: None
		Format: Any valid DD name.
LINES		Function: The LINES parameter can be used to specify the number of lines per page to be used by the report program.
		Default: LINES=55
		Format: Specify a numeric value between 20-99.
SMFRID		Function: The SMFRID parameter can be used to specify the SMF record identifier that was used by the product's rules language to write the record.
		Default: None
		Format: Specify a numeric value between 128-255.

SYSID	Function:	When records are to be extracted from the system logger, a SYSID parameter can be used to filter the data for the records originating from a specific system. If the SYSID parameter is not specified, no filtering will occur.
	Default:	None
	Format:	A valid SMF System Identifier
TYPE	Function:	When records are to be extracted from the system logger, a TYPE parameter can be used to filter the data for the requested record type: MESSAGE or RECORD. If the TYPE parameter is not specified, no filtering will occur.
	Default:	None
	Format:	MESSAGE or RECORD

Operator commands, messages and SMF records - syncsort_simulate_2000 - Latest

Syncsort™ Storage Management Portal 2000 Rules Language Guide

Using SMF LEVEL to Limit SMF Records

Using USERID LEVEL to Limit Messages to TSO Users