The DEFREC statement can be used to define a
record used in the rules language, or map an existing symbolic field. During
rules and procedure processing, the SET and
ISSUE action statements use the WRITEREC
parameter to actually write the record.
When rules are processed in environments that do not allow file I/O,
records are scheduled to be written to DD statements allocated in the
DIF started task, or written to an
MQSERIES message queue for network delivery. For
non-authorized environments, records can be written to DD statements in
the current job step.
Building records — The DEFREC
statement builds a record using FIELD substatements. The
FIELD substatements can use symbolic fields or literal
values. The LENGTH parameter on the
DEFREC defines the logical record size. If not
specified, the record length will be established using the last field
definition in the record.
Fields can be placed at specific offsets within the record with the
POSITION parameter. If no position is specified, the
field is added immediately after the previous field. By default, field
lengths are obtained from the symbolic field or the length of a literal
string. The length can be specified on the field definition with the
LENGTH parameter.
The records can contain both character fields and numeric fields. Numeric
fields can be specified as binary or packed. If
TRANSLATE(ASCII) has been specified, the character
fields in the record are translated to ASCII before the record is
written.
The following example illustrates the use of the DEFREC
and FIELD statements. The @ACTREC record
length is fixed at 245 bytes and will be initialized to blanks. The fields
that define the record use implicit offsets and lengths — the compiler
calculates the position and length of each field. During program
execution, when a rule definition requests
WRITEREC(@ACTREC), the record is built and written to
the SCCACT DD statement.
DEFREC @ACTREC INIT(BLANKS) DDNAME(SCCACT) LEN(245) FIELD &SYSID
FIELD &CURLDATE FIELD &CURDAY FIELD &CURTIME FIELD &JOBNAME FIELD "ACTION " FIELD &VOLSER FIELD &DSNAME FIELD &ENV
FIELD &ENVS FIELD &DADSM_RC FIELD &RUSER
POSITION and LENGTH parameters
on FIELD when explicit control is required.
Mapping user-defined input records — Much like the
DEFEQU statement, DEFREC with the
MAPFIELD parameter can be used to equate
installation-defined symbolic names with segments of another symbolic
field.
For example, the EXTERNALRECORDS statement in
SCC Monitor allows the product to read user-defined
input records into the EXTRECORD symbolic field. However,
to allow access to fields within those records, fields must be defined
using DEFREC with MAPFIELD.
DEFREC must be placed in the
rules language before any fields defined by the DEFREC
are used in rules logic.Example of DEFREC with MAPFIELD:
DEFREC USERREC LENGTH(100) MAPFIELD(EXTRECORD)
FIELD &DSNAME POS(1) LENGTH(44)
FIELD &VOLID POS(45) LENGTH(6)
FIELD &TYPE POS(51) LENGTH(4)
Symbolic field names that match existing variable names are allowed. If
rules need to access data set or volume information obtained from the user
record (for example, DSNAME and VOLID),
you must signal internal Monitor routines that mapped fields are connected
to Monitor symbolic fields. For example, to allow Monitor to access data
set size information using the DSNAME and VOLID obtained from the user
record, add the following statements before any logic that accesses dsname
or volume information:
SET SET_DSNAME = &DSNAME
SET SET_VOLSER = &VOLID
RECORD(NAME(<defrec_name>)) must be specified to
indicate which record layout the report utility should use. This parameter
is required when FORMAT and/or SORT
statements are used to format user records.
Remapping existing fields — Other symbolic fields can
also be mapped by DEFREC using MAPFIELD.
For example, instead of using DEFEQU statements, the
following DEFREC remaps the JOBNAME
symbolic field:
DEFREC JOBNMAP LENGTH(8) MAPFIELD(JOBNAME)
FIELD &JBTYPE POS(1) LENGTH(2)
FIELD &JBGRP POS(3) LENGTH(2)
Syntax summary for DEFREC (shown as code for
clarity):
DEFREC name
DDNAME(ddname) FILTERRULE(rulename) INITIALIZE(option) LENGTH(num)
MAPFIELD(symbolic_name) REQUIRED(option) SMFRID(num)
TRANSLATE(option)
field_statement_1
field_statement_2
...
field_statement_n
Parameters
name — Function: This is a required parameter.
The name parameter is used by the
WRITEREC parameter on other rule statements
(DEFDMYU, DEFDMYV,
DEFPROC, and DEFRULE). The
name defines the link between the statement that
wants a record written and the DEFREC statement.
The DEFREC statement can use a special statement name
to establish parameter defaults. When $DEFAULT is
specified, the rule compiler uses the specified parameters to modify the
parameter defaults for later DEFREC statements. For
more information, examine “Using $DEFAULT on Statement
Definitions” in the referenced documentation.
Default: None
Format: Specify a name 1 to 20 characters long.
DDNAME(ddname) — Function: This is a required
parameter. When a product uses WRITEREC to produce a
record, the DDNAME parameter defines which file
receives the record.
In environments where file I/O is not allowed, the record is passed to
the DIF started task and written by DIF to the DD
statement allocated in the DIF address space. If the DD statement name
starts with a dollar sign ($), the record is broadcast
via APPC.
For rules executed in non-authorized environments, records can be written to DD statements in the current job step.
Default: None
Format: Any valid DD name.
FILTERRULE(rulename) — Function: Optional. The
FILTERRULE keyword determines whether the current
statement is honored by the rule processor. If the rule member requested
by FILTERRULE sets the symbolic field RULE_SKIP
= YES, then the current rule statement is skipped. For more
information, examine “Filter Rules for Rule Statements” in the
referenced documentation.
Default: None
Format: Specify the name of a rule member found in the SCC rule
library (for example: DTS.R71.RULELIB).
INITIALIZE(option) — Function: The
INITIALIZE parameter is used during record
initialization.
When rule execution builds a record, the record can be initialized to one of the following options:
-
BLANKS -
NULLS
Default:
INITIALIZE(BLANKS)
LENGTH(num) — Function: Specify the record
length with the LENGTH parameter. This length is used
as the LRECL when the record is written to the output file. If the
LENGTH parameter is not specified, the
FIELD subparameters are analyzed to calculate the
record length.
Default: None
Format:
LENGTH(num) where num is a numeric
value between 1 and 255.
MAPFIELD(symbolic_name) — Function: The
MAPFIELD parameter equates installation-defined
symbolic names with segments of another symbolic field.
Default: None
Format: The name of an existing symbolic field.
REQUIRED(option) — Function: The
REQUIRED parameter on the DEFREC
statement establishes the default for the REQUIRED
parameter on associated FIELD statements. If a record
contains required fields, the record is written only when all required
fields are available for substitution.
If a field is not specified as required and the field is not available for substitution, the field is initialized to blanks for character fields and 0 for numeric fields.
Default:
REQUIRED(NO)
Format:
YES or NO
SMFRID(num) — Function: The
SMFRID parameter sets the SMF record identifier. If
set, an SMF record is created by adding an SMF header to the record and
writing it using the specified SMF record number.
Default: None
Format: Specify a numeric value between 128 and 255.
Trace and Translate
TRACE — Function: The TRACE parameter produces
additional debugging messages for records that contain symbolic fields
that cannot be resolved when the product builds the message. This
parameter is normally used with the product’s trace DD statement:
PTLTRACE.
Default: None
Format:
TRACE
TRANSLATE(option) — Function: The
TRANSLATE parameter is used for records headed
outside the mainframe environment. If TRANSLATE(ASCII)
is specified, character fields in the record are translated to ASCII
before the record is written.
Default:
EBCDIC
Format:
EBCDIC or ASCII