Filter facility

This monitor uses a filter facility to determine what resources to monitor and what data to collect. The default filter is ISGAMF08. Example of a filter is shown in Figure 3.

You can display the name of the active filter with command:

F JOBNAME,L

and you can dynamically change the active filter with command:

F JOBNAME,I=xx

Note that changing the filter options does not purge data that was already collected by the previous filter options.

The name of the filter should be ISGAMFxx where xx can range from 00 through 09.

Sample filter ISGAMF00 in SYS1.SAMPLIB is an exact copy of the default member ISGAMF08. If the filter needs to be changed, it should be assembled and linkedited in an authorized library or SYS1.LINKLIB with AC(0).

Build the filter option using the following two macros:

GFLG: Generates the flag byte to control the monitor.

You must only use this macro once in the table.

Figure 1. GFLG Filter Example

       GFLG  FILTER=Y/N,MATCH=Y/N

             REQTYPE = ALL (REQUESTs that pass other filtering)
             REQTYPE = NCRESERVE (Only gather Non-converted Reserves. Only 
                                  gather requests that result in actual hardware 
                                  reserves and pass other filtering)

                       DEFAULT=ALL

            FILTER  =  N (TRACE ALL)

                       DEFAULT=Y

            MATCH   =  Y (TRACE IF A NAME ENTRY MATCHES COLLECTED DATA)
            MATCH   =  N (DO NOT TRACE IF A NAME ENTRY MATCHES
                                    COLLECTED DATA)

                       DEFAULT=Y

NAME: The NAME keyword is used to generate the name list. The NAME types can be MAJOR, MINOR, and JOB/STC/TSU. Note that a names list is not required. When the NAME keyword is not provided, only the FILTER and REQTYPE keywords are used to determine if an event should be traced.

Figure 2. NAME Filter Example

           NAME  N=,M=,T=,[L=]

                     N= Major name        1 to  8 chars

                     M= Minor name        1 to 52 chars

                     T=type on entry   U=Resource - Major & Minor names
                                       M=Major name
                                       J=jobname
                                       S=started-task
                                       T=tso-user

       OPTIONAL ==>  L=length of compare - valid values 1-60
                       default=length of character string (except
                       for Major name which is considered 8 byte).
                       If L is higher than character string, the NAME
                       is padded with blanks.
                       Used only with T=U,J,S,T

The trace control operates at two hierarchical levels.

Level one:

The resources whose MAJOR name is specified in a name entry with keyword T=M are not traced. For example, if the resources with major name SYSDSN have to be discarded, code the following:

       GFLG  FILTER=Y

       SVCF                   /*this statement is required*/

       NAME  N=SYSDSN,T=M

Level two:

The resources whose MAJOR and MINOR is specified in a NAME entry with keyword T=U are processed according to the GFLAG setup:

GFLAG MATCH=Y writes a trace entry if the ENQ/DEQ resource matches a name entry type=U
GFLAG MATCH=N writes a trace entry if the ENQ/DEQ resource does not match a name entry type=U

Example 1: If the resources representing the temporary data sets for year '96 (resource major SYSDSN minor SYS96039.xxxx.yyyy) have to be discarded, code the following:

       GFLG  FILTER=Y,MATCH=N

       SVCF                   /*this statement is required*/

       NAME  N=SYSDSN,M=SYS96,T=U,L=13

           note: checked with length of 13 bytes
                 (8 major name and first 5 minor name bytes)

Example 2: If only the resources with major names SYSZVVDS and SYSIGGV2 have to be traced, code the following:

       GFLG  FILTER=Y,MATCH=Y

       SVCF                   /*this statement is required*/

       NAME  N=SYSZVVDS,T=U,L=8        NAME  N=SYSIGGV2,T=U,L=8

           note: checked with length of 8 bytes
                 (8 major name, any minor name)

The resources used by JOB/STC/TSU whose name is specified in a NAME entry with keyword T=J/S/T are processed according to the GFLAG setup:

GFLAG MATCH=Y writes a trace entry if the requester name matches a name entry type=J/S/T
GFLAG MATCH=N writes a trace entry if the requester name does not match a name entry type=J/S/T

Example 3: To see all the resources used by started task TSO, NET and TSO users starting with IPO1, (the resources with scope STEP are discarded by default), code the following:

       GFLG  FILTER=Y,MATCH=Y

       SVCF                   /*this statement is required*/

NAME  N=TSO,T=S,L=8
       NAME  N=NET,T=S,L=8
       NAME  N=IPO1,T=T,L=4

       note: stcs TSO end NET checked with length of 8, name padded
             with five blanks.

Example 4: Only collect events that result in a hardware reserve for RESERVEs issued against the SYSZVVDS resource.

       GFLG FILTER=Y,REQTYPE=NCRESERVE,MATCH=Y

       SVCF                   /*this statement is required*/

NAME N=SYSZVVDS,T=M,L=8

Example 5: Collect all events that result in a hardware reserve.

       GFLG FILTER=Y,REQTYPE=NCRESERVE

       SVCF                   /*this statement is required*/


       note: No name entries are provided so only the REQTYPE=NCRESERVE 
             filter is applied.

The following table summarizes the possible combinations and actions of the filter REQTYPE=NCRESERVE:

GFLG	No-Match	Match (*)
FILTER=Y, MATCH=Y	No-Trace	Trace
FILTER=Y, MATCH=N	Trace	No-Trace
FILTER=N	Trace	Trace
REQTYPE=NCRESERVE

(*)MATCH means that the resource name specified in a NAME entry type T=U matches the MAJOR and MINOR names of the ENQ/DEQ request, or for NAME entries type J/S/T, the job/stc/tso name matches the requester.

Example 6: Collect information about unauthorized ENQ requests (from all ENQ services) that fail when AUTHQLVL=2. AUTHQLVL indicates the list of authorized qnames in effect for the system in the global resource serialization complex. For information about authroized qnames and AUTHQLVL, see Authorized qnames.

       GFLG FILTER=Y,REQTYPE=AUTHQ2,MATCH=N

       SVCF                   /*this statement is required*/


       note: No name entries are provided so only the REQTYPE=AUTHQ2
             filter is applied.

The following table summarizes the possible combinations and actions of the filter REQTYPE=AUTHQ2:

GFLG	No-Match	Match (*)
FILTER=Y, MATCH=Y	No-Trace	Trace
FILTER=Y, MATCH=N	Trace	No-Trace
FILTER=N	Trace	Trace
REQTYPE=AUTHQ2

The following is a filter coding sample.

Figure 3. Filter Coding Example

**********************************************************************
*       SELECT ONE OF THE FOLLOWING
*       GFLAG DEFAULT FILTER=Y,MATCH=Y

GFLAG   EQU   *
*       GFLG  FILTER=N                       NO TRACE AT ALL
*
        GFLG  MATCH=N,FILTER=Y               NO MATCH -> TRACE
*
*       GFLG  MATCH=Y,FILTER=Y               MATCH    -> TRACE
*
**********************************************************************
*
        SVCF                       THIS STATEMENT IS REQUIRED
*
**********************************************************************
NAME1   EQU   *                    THIS STATEMENT IS REQUIRED
**********************************************************************
*       GENERATE THE NAME TABLE ENTRY WITH THE MACRO NAME
*
        NAME  N=SYSZTIOT,T=M        MAJOR NAME 'SYSZTIOT' NOT TRACED
        NAME  N=SYSZJWTP,T=M        MAJOR NAME 'SYSZJWTP'     "
        NAME  N=SYSZJES2,M=CVCB,T=U,L=12
        NAME  N=SYSDSN,M=SYS96,L=13,T=U
*
* Note:
* The GFLAG requests TRACE for NO-MATCH.
* The resources with the following MAJOR & MINOR are NOT TRACED
*
*       SYSZTIOT                all major SYSZTIOT
*       SYSZJWTP                all major SYSZJWTP
*       SYSZJES2 CVCB           checked with length of 12 chars.(8+4)
*       SYSDSN SYS96            checked with length of 13 chars.(8+5)
* (temp dsn for year '96)
*
***********************************************************************