Macro invocation syntax for EQQLSENT

Purpose

EQQLSENT produces an entry in the data set triggering selection table, EQQDSLST. EQQDSLST is used in SMF exit IEFU83 by the data set triggering function to decide which SMF records to process. When an SMF 14, 15, or 64 record matches a condition in EQQDSLST, a special resource availability event is created and broadcast to all HCL Workload Automation for Z subsystems defined on the system where the SMF record was created.

Format

STRING= string|LASTENTRY
POS= numeric position
USERID= user ID filter criteria
JOBNAME= jobname filter criteria
AINDIC={Y|N}
LIFACT={Y|N|R}
LIFTIM=interval

Parameters

STRING=string|LASTENTRY
Required keyword specifying the character string to be searched for. The string can be 1 to 44 characters long. To identify the fully-qualified last level of a data set name, add a space as the last character and enclose the string in single quotation marks. Consider this example. You have two data sets: 
         DSN.NAME.AB
         DSN.NAME.ABC
Specify STRING=DSN.NAME.AB,POS=1 if you want SR availability events created for both data sets. Specify STRING='DSN.NAME.AB ',POS=1 if you want events created only for the first data set.

When EQQLSENT is invoked with STRING=LASTENTRY it generates an end of table indicator. After having invoked EQQLSENT with keyword parameters STRING and POS a number of times, EQQLSENT must be invoked one last time with STRING=LASTENTRY in order to complete the table.

To create an empty EQQDSLST, just invoke EQQLSENT once, with STRING=LASTENTRY. When an empty list is used by IEFU83, no SR events are created.

POS=numeric position
A required keyword specifying the numeric position where the string begins.
USERID=string
Optional keyword specifying a generic character string to be compared with the SMFxxUID field, which contains the user identification associated with the job, started task, or TSO user that requested the activity against the data set that resulted in the data set close. The string can be 1 to 8 characters long. For this parameter the following wildcards are allowed:
  • *: to match any sequence of characters.
  • %: to match any single character. For example, if you specify AB%, ABC is a match, AB or ABCD are not a match.
Note: The SMF user ID field may contain a blank value. See z/OS® System Management Facilities for more information about the SMFxxUID or SMFxxUIF field.

If you need to control SR availability events based on the user ID and the SMF value is blank in your installation, consider using the IEFUJI exit to insert the user ID. You are recommended to specify SETUID=YES on the EQQEXIT macro when you generate the IEFUJI exit: this sets the JMRUSEID field, which SMF then copies to the SMF user ID field.

If you want to update the JMRUSEID field yourself, the user ID is most easily taken from the ACEEUSRI field in the ACEE, pointed to from the ASXB, pointed to from the ASCB. This can be located as follows: PSAAOLD ===> ASCB ACSBASXB ===> ASXB ASXBSENV ===> ACEE ACEEUSRI ===> userid

The DSECTs needed are mapped by these macros:
Area Macro Library
PSA IHAPSA SYS1.MACLIB
ASCB IHAASCB SYS1.MACLIB
ASXB IHAASXB SYS1.MODGEN
ACEE IHAACEE SYS1.MACLIB

The JMR, mapped by IEFJMR, is already available in the EQQEXIT expansion in IEFUJI.

JOBNAME=string
Optional keyword specifying a generic character string to be compared with the SMF14JBN, SMF15JBN, or SMF64JMN field, which contains the name of the job, started task or TSO user that requested the activity against the data set that resulted in the data set close. The string can be 1 to 8 characters long. For this parameter the following wildcards are allowed:
  • *: to match any sequence of characters.
  • %: to match any single character. For example, if you specify AB%, ABC is a match, AB or ABCD are not a match.

If the data set is to be processed by FTP, JOBNAME corresponds to the ** USERID ** under which the data set is received. That is, the USERID supplied when the remote host opened the FTP session to PUT the data set, or when a local user (or batch job) opened the FTP session to GET the data set.

AINDIC={Y|N}
Optional keyword specifying that the special resource is available (Y) or unavailable (N). The default is that the resource available.
LIFACT={Y|N|R}
Optional keyword specifying the value to which the global availability of the special resource is reset, after the interval of time specified by LIFTIM has expired. Allowed values are:
Y
Sets the global availability to Yes
N
Sets the global availability to No
R
Sets the global availability to blank

This keyword is valid only if LIFTIM is specified. The default is R.

LIFTIM=interval
Optional keyword specifying the interval of time, in minutes, after which the global availability of the special resource is reset to the value specified by LIFACT. The allowed range is from 1 to 999999.
Note:
  1. The output from assembling the EQQLSENT macro must be placed in the EQQDSLST member in the data set referenced by the ddname EQQJCLIB.
  2. Generation Data Group data sets are specified by the group name. For example, when a GDG data set with the name 'DSN.OPCSUBS.GDG.G0001V00' is closed the special resource event contains resource name 'DSN.OPCSUBS.GDG'.
  3. For a partitioned data set, the member name is not part of the resource name in the SR event.
  4. For VSAM data sets the resource name in the SR event is the cluster name (without the DATA or INDEX suffix).

Examples

   EQQLSENT STRING=SYS1.MAN,POS=1
   EQQLSENT STRING='TEST.DSCLOSE ',POS=1,USERID=SYSOP
   EQQLSENT STRING=CP2,POS=12
   EQQLSENT STRING=EQQDATA.EXCL,POS=5
   EQQLSENT STRING='DSN.OPCSUBS.GDG ',POS=1
   EQQLSENT STRING=LASTENTRY
   END
In this example, SMF records with:
  • A data set name beginning with SYS1.MAN, or
  • Data set name TEST.DSCLOSE and user ID SYSOP
  • Records with CP2 in position 12, such as DSN.OPCSUB.CP2, or
  • Records that have EQQDATA.EXCL starting in position 5
  • The root of a GDG data set name
will cause SR availability events to be generated.

Messages

The following messages can be generated at assembly time:
  • KEYWORD STRING IS REQUIRED
  • KEYWORD POS IS REQUIRED
  • POSITION MUST BE BETWEEN 1 AND 43
  • NULL NAME NOT VALID
  • NAME (STRING) GREATER THAN 44 CHARACTERS
  • POSITION INVALID FOR NAME (STRING)
  • USERID STRING NOT VALID
  • JOBNAME STRING NOT VALID
  • AINDIC MUST BE EITHER Y OR N
  • POSITION NOT VALID FOR NAME (STRING)
  • LIFACT MUST BE Y, N, OR R
  • LIFTIM LENGTH NOT VALID
  • LIFTIM VALUE NOT VALID
  • LIFTIM VALUE 0 NOT ALLOWED