Usage Monitor commands

The Usage Monitor commands are passed to the Usage Monitor from the HZAZIN input file, or by an operator MODIFY command.

The syntax rules are as follows:

All commands are three characterslong.
Operands or subparameters are specified inparentheses.
Multiple subparameters are separated bycommas.
The command must not contain any embeddedblanks.
Commands must start in columnone.

To record the settings the Usage Monitor is using, place the display commands at the end of the HZAZIN file.

Details of each command follow.

CAP - Set hardware capacity collection status

CAP is used to specify if the Usage Monitor is to produce records containing information about the hardware capacity of the system. Collecting this information is important when hardware capacity changes dynamically.

A change to this setting does not take effect until the next collection repository switch.

Y

Specifies that hardware capacity data is collected and writtenout.

N

Specifies that hardware capacity data is not collected or written out. If no CAP command is issued, the default is CAP(Y).


Command purpose	Example code
Collect hardware capacity data.	F HZACJMON,CAP(Y)
Do not collect hardware capacity data.	F HZACJMON,CAP(N)

CIC – Allow or disable program usage data from CICS regions

The CIC command provides a system-wide control mechanism to allow or disallow program usage data to be collected by the Usage Monitor CICS global user exit (GLUE) program.

Y: Specifies that customized CICS regions are able to present program usage data to the Usage Monitor forcollection.
N: Specifies CICS program usage monitoring is disabled throughout the operating system image.

If no CIC command is issued, the default is CIC(Y).

D-A - Display output allocation parameters

D-A is used to display dynamic allocation details to be used in the creation of output data files. The data set name, DCB attributes, primary and secondary space quantities, and unit and optional volume serial number are shown.

The following code example displays the current dynamic allocation values.

F HZACJMON,D-A

D-C - Display the counters and statistics

D-C is used to display the Usage Monitor activity and status indicators. The purpose of this command is to assist HCL technical support in problem diagnosis. The meaning of the output generated by this command is not published.

The following code example displays the current value of internal Usage Monitor counters.

F  HZACJMON,D-C

D-D- Display the data set name inclusion and exclusion lists

D-D- is used to display the data set name masks in the inclusion list, followed bythe data set name masks in the exclusion list.

The inclusion and exclusion lists do not need to be populated in order to collect data. The absence of any entries in the exclusion list means that data collection is not filtered by program library data set names.

The following code example displays the current data set name inclusion and exclusion lists.

F HZACJMON,D-D

D-I - Display the system identifier

D-I is used to display the system identifier, which is written in the output header record. It can be altered by the SID command.

The following example code displays the current system identifier used by the Usage Monitor.

F HZACJMON,D-I

D-S - Display the status settings

D-S is used to display several miscellaneous settings. Other commands are used to alter the individual settings, but this command provides a convenient way to list the current values.

Place at the end of the HZAZIN file to confirm monitoring settings.

The following example code displays the current values of settings.

F HZACJMON,D-S

D-T- Display the automatic switch-and-write time setting

D-T is used to display the time-of-day specified for automatic collection repository switching and consequent writer task creation. When data from after this time-of-day is detected, data collection is automatically switched to a new repository, and write-out of data in the old repository is started.

The UTC or GMT switch time is calculated using local time current at collection repository creation time. The time when a collection repository is terminated is set when it is created. Changes to the system local time offset, such as those caused by a change to daylight saving time, do not alter the UTC or GMT that the current collection repository is closed. The time of the switch after the next switch is calculated using the new local time.

The following example code displays the current automatic switch-and-write time setting.

F HZACJMON,D-T

D-X - Display the active exclude list

D-X is used to display the active program name mask exclude list. Data is not collected for programs with names that match the mask in any active entry in the exclude list.

The following example code displays the current exclude list entries.

F HZACJMON,D-X

DCB - Set output DCB attributes

DCB is used to set DCB attributes, which are optimal for a specific device type.

If no DCB command is issued, the default is DCB(3390).

DCB(3390)

Sets the output DCB to

RECFM=VB,LRECL=27994,BLKSIZE=27998

Use when the output device has 3390 compatible geometry.

DCB(3380)

Sets the output DCB to

RECFM=VB,LRECL=23472,BLKSIZE=23476

Use when the output device has 3380 compatible geometry.

DCB(UNKN)

Sets the output DCB to

RECFM=VBS,LRECL=32756,BLKSIZE=0

The system determines the optimal block size for the device used by dynamic allocation. Use when the output device type is not known until allocation time.

Some FTP products do not process a file with RECFM=VBS correctly, even when no records are actually spanned.

DEL - Deleting program mask entries

DEL is used to remove program name masks from filter tables. Both default and user-added entries can be removed. The required operand specifies one or more program name masks.

mask

Specifies a 1 - 8 character program name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.

*ALL* Specifies every currently active mask. This mask cannot be specified with any other mask.

Except for short test periods, it is expected that default exclusion masks such as IGG* remain active.

Table 1. Examples of using the DEL command
Command purpose	Example code
Remove all entries, so that all possible programs are monitored.	F HZACJMON,DEL(ALL)
Remove exclusion masks to monitor LE and REXX modules.	F HZACJMON,DEL(CEE,IRX)
Remove an exclusion mask to monitor the program called CEE.	F HZACJMON,DEL(CEE)

DSN - Setting the data set name prefix

DSN is used to specify the first part of the data set names used for the output files. The prefix is specified in the required operand. The HZAZIN file must contain a DSN command.

You can use symbols in the construction of the data set name prefix. Available symbols include all z/OS static symbols, &SMF, the SMF identifier for the system, and & SYSLPAR, the logical partition name for the system.

dsnpref

Specifies a 1 - 26 character data set name prefix. It can contain one or more data set qualifiers, and must not end in a period after any symbol substitution.

Usage Monitor needs RACF ALTER access to the data sets to be able to create them. The following example code shows how to get output files with names of the form SYS3.HZA.

HZACJMON.Dyyyyddd.Thhmmsst:
F HZACJMON,DSN(SYS3.HZA.HZACJMON)

DUR - Set execution duration

DUR is used to specify a fixed short-term execution duration of the Usage Monitor started task. When the specified time has elapsed the Usage Monitor will terminate automatically. The Usage Monitor stop time is calculated by adding the specified duration to the current time when the command is processed.

Any subsequent WRT commands are ignored.

The DUR command is not normally used in standard operations where the Usage Monitor is to remain active until system shutdown. When it is used, it is normally placed in the HZAZIN file to specify a predetermined length of execution for sampling or testing purposes.

Hhmm: Specifies a time duration in hour and minute notation. The value must be four decimal digits. The minimum value is 0001 and the maximum value is 2400. The last two digits (mm) must be in the 00 - 59 range.

The following example code instructs the Usage Monitor to stop after 150 minutes.

F HZACJMON,DUR(0230)

EXC - Adding program mask exclusion entries

EXC is used to add program name masks to the exclusion table. The required operand specifies one or more program name masks.

mask

Specifies a 1 - 8 character program name mask.

If the mask ends in an asterisk only, characters before the asterisk are compared.

Otherwise, an exact program name is deemed to have been specified.

*DFLT*

Specifies every supplied default entry in the exclusion table is to be made active, and all user-added entries are to be removed from thefexclusion table. This mask cannot be specified with any other mask. Except for short test periods, it is expected that default exclusion masks such as IGG* would remain active.

Table 2. Examples of using the EXC command
Command purpose	Example code
Reset the exclusion table to its default status.	F HZACJMON,EXC(DFLT)
Exclude the collection of data for Language Environment modules and REXX modules.	F HZACJMON,EXC(CEE,IRX)
Exclude the collection of data for the program CEE.	F HZACJMON,EXC(CEE)

HOF - Adjust for hypervisor STCK TOD clock offset

HOF is used to control whether the TOD clock offset in a logical partition is to be applied to collected data, or not. When HOF(N) is set, data timestamps are derived from the local time as supplied by z/OS. When HOF(Y) is set, the hypervisor STCK date and time offset from field SMF89HOF in SMF type 89 records is subtracted from z/OS local time to form the collected timestamp values.

For Usage Monitor data, the HOF setting at the time that the writer task is attached after the closure (or switch) of a collection repository is used.

For Inquisitor data, the HOF setting active at the time of the Inquisitor program initialization is used.

HOF(Y) will not cause any change to data timestamp values unless the Usage Monitor has processed a type 89 SMF record. For this to occur, SMF parameter settings must specify the collection of type 89 records, and at least one SMF interval must have ended while the Usage Monitor is active before the output file data generation commenced.

If the Usage Monitor has been stopped before an Inquisitor scan commences, the Inquisitor program uses the HOF status current at the time of Usage Monitor termination.

Y: Specifies the hypervisor STCK TOD clock offset will be used to adjust date and time values present in collected data.
N: Specifies the date and time values present in collected data will be based wholly on the local time, as maintained by z/OS.

IDD - Deleting data set name inclusion entries

IDD is used to remove data set name masks previously added by the IDS command.

mask

Specifies a 1 - 44 character data set name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.

The following example code deactivates the SYS3.LINKLIB inclusion mask.

F HZACJMON,IDD (SYS3.LINKLIB)

IDS - Adding data set name inclusion entries

IDS is used to supply data set name masks, which specify data set names to be excluded from exclusion processing. Program usage data fetched from data sets with names matching inclusion masks, is collected without reference to the data set name mask exclusion list.

Inclusion masks only affect data collection if there are active exclusion masks. An inclusion mask is normally expected to match a subset of data set names, which would match an exclusion mask.

mask

Specifies a 1 - 44 character data set name mask. If the mask ends in an asterisk only characters before the asterisk are compared. Percent signs in the mask indicate that any character in that location is considered a match. If the mask contains a slash character (/), the value is considered to be a UNIX path name mask rather than a data set name mask.

You can use the following example code if your intention is to not collect program usage data for data sets with a high-level qualifier of SYS3, except for SYS3.LINKLIB. SYS3.LINKLIB is the only data set with a high-level qualifier of SYS3 for which program usage data is to be collected.

XDS(SYS3.*) IDS(SYS3.LINKLIB)

IPH – Control collection of TCPIP Host details

JIPH is used to control the reporting of the TCPIP host name and IP address. Program usage data sets created by the Usage Monitor will normally have the TCPIP host details present in the header information, but this data can be suppressed by specifying IPH(N).

Y: Specifies that the Usage Monitor will call HZAPHOST to procure TCPIP hostdetails
N: Specifies that the Usage Monitor will not report TCPIPhost details in the program usage files.

If no IPH command is issued, the default is IPH(Y).

JAC - Set job account collection status

JAC is used to specify if the Usage Monitor is to consider the account code of jobs significant when aggregating data. The Usage Monitor normally aggregates data.

Based on the program name, the job name, and the user ID. This setting is used to add the job account, truncated after 20 characters, to the aggregation key.

Do not instruct the Usage Monitor to collect and preserve all job account codes if they are not important to the administration of your system. Collecting and preserving job accounts can significantly increase data volumes.

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that job account codes are used.
N: Specifies that job account codes are ignored.

If no JAC command is issued, then job accounts are used. The default is JAC(Y).

JID - Control the preservation of batch job identifiers

JID is used to control whether all batch job identifiers are to be preserved or not. Normally usage data for each program is aggregated by job name and user ID with only the most recent job identifier being retained. JID provides the option of keeping all batch job identifiers so that the number of jobs using a program can be counted, and usage can be attributed to specific individual jobs. Job identifier aggregation for started tasks and TSO user sessions is always equivalent to JID(N) and is not affected by this setting.

Y: Specifies that batch job identifiers should not be overlaidand that different batch job identifiers should prevent data aggregation.
N: Specifies that normal aggregation by job name and user ID is to proceed without considering job identifier differences.

The default setting of JID(N) applies each time the Usage Monitor is started.

JNM - Control the collection of job names

JNM is used to specify whether the Usage Monitor collects the names of jobs which use programs or not. If the names of jobs which use the various programs are not considered to be important, you can dispense with the collection of these names. The advantage of not collecting individual job names is the reduction in processing times and data volumes caused by the aggregation of data into fewer records. When individual job names are not collected, usage is summed over broad address space categories, such as JOB, STC, TSO, and SYS. The total usage counts collected by the Usage Monitor for each program are not affected by this setting.

A change to this setting takes effect at the next collection repository switch.

Y: Specifies that the name of each job running a program is to be collected.
N: Specifies that only a broad address space category of each job running a program is to be collected, instead of the individual job name.
If no JNM command has been issued, then job names are collected. JNM(Y) is the default.

LDI – Set LOAD exclusion inactive

LDI is used to deactivate a LOAD exclusion entry previously activated by the LDX command. Names specified as operand values should exactly match names already used in LDX commands.

mask: Specifies a 1 - 8 character program name mask

LDX – Add or activate a LOAD exclusion

Normally when programs are loaded into storage, the Usage Monitor deems that the loaded programs are being used. However, there are software packages which load programs as part of a process to analyze these programs for software control purposes. When this happens, usage is attributed to each of the loaded programs even though they were not given control or actually used. In such cases, you may choose to specify the name of the program performing the analysis in an LDX command in order to exclude the referencing of the loaded programs from data collected by the Usage Monitor.

When a program is explicitly loaded into and deleted from storage, the Usage Monitor checks the active program name of the task against the list of active LDX entries. If the name of the active program – the program assumed to be issuing the LOAD and DELETE requests – matches the value stored in an active LDX entry, then the Usage Monitor will exclude the event from the collected usage data.

Usage collected from events where the operating system gives control to programs (such as ATTACH and LINK requests) are not affected by LDX entries.

mask: Specifies a 1 - 8 character program name mask

LLC - Link list correction

LLC is used where sites make a number of dynamic link list changes. This command updates the HZACJMON data to point to the correct load library. Use this command only if you enable dynamic link list updates, which alter the relative concatenation numbers of persisting libraries.

Y: A BLDL is performed at write time by the writer task and, if found, the data set name is overlaid. To avoid performance problems, especially during system shutdown, ensure that LLA remains active until the Usage Monitor has terminated.
N: Do not check for dynamic list updates.

If no LLC command is issued, then the default setting of LLC(N) is current.

A change to this setting does not take effect until the next collection repository switch.

LPA - Set link pack area program monitoring status

LPA is used to specify whether the monitoring of programs in the Link Pack Area (LPA) is to occur or not. All types of LPA are included in this category.

Y: Specifies that LPA program usage is to bemonitored.
N: Specifies that LPA program usage is not to bemonitored.

If no LPA command is issued, then LPA program usage data is collected. LPA(Y) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

PLN - Set the sysplex name

PLN is used to override the name of the sysplex contained in the output header record. The actual sysplex name is used as a norm, but an override allows control over which systems have their inventory updated when the PLX=Y Inquisitorsetting is used. The value specified here should match the PLEXNAME= value specified for the corresponding Inquisitor scans. Overriding the sysplex name is not usually needed unless PLX=Y is used and the sysplex grouping does not match the shared DASD grouping. Symbols can be employed in the construction of the sysplex name. Available symbols include all z/OS system symbols, &SMF, the SMF identifier for the system, and &SYSLPAR, the logical partition name for the system.

plexname: Specifies a string which is to be resolved to an identifier 1-8 bytes in length.

PRE - Collect usage for long running programs

PRE is used to specify if the Usage Monitor is to collect usage for programs which started before the current collection cycle. Without this data collection a Usage Monitor collection cycle will have no usage data for programs which started running before the cycle started and remain running when the cycle ends. If a job or task runs for more than two days, most days will not have any usage recorded for the main program unless this additional data collection is enabled.

When the additional data collection is enabled, previously fetched programs resident in the regions of started task and batch job address spaces where SMF interval recording is active have usage recorded in each collection cycle which encompassed the end of at least one SMF interval.

This setting can affect usage figures. For example, the main program of a constantly running task can accrue a usage count of around 30 over a month even though it was really only used once for an extended period.

Y: Specifies that usage for previously running programs is to be collected.
N: Specifies that usage for previously running programs is not to becollected. The default setting of PRE (Y) applies each time the Usage Monitor is started.

PRI - Set the data set space primary allocation

PRI is used to specify the primary space allocation quantity in tracks. It is used for output data set allocations.

trks

Specifiesa number of tracks from 0 to 150,000.

If no PRI command is issued, the primary space allocation is 750 tracks. The Usage Monitor uses the RLSE space allocation attribute.

The following example code sets the primary space allocation to 900 tracks.

F HZACJMON,PRI(900)

PRS - Set registered software activity data collection status

PRS is used to specify if the Usage Monitor is to output records containing information about the activity of registered software. Registered software uses the system Register service. The data contains information about the usage of registered software, and information about software registration settings from the PARMLIB member IFAPRDxx.

A change to this setting does not take effect until the next collection repository switch.

Y

Specifies that registered software information is collected and output.

N

Specifies that registered software information is neither collected noroutput.

If no PRS command is issued, then registered software data is collected.

PRS(Y) is the default.

QSZ – Specify collection element queue area size

QSZ is used to specify the virtual storage size of the SCOPE=COMMON memory object which forms the area where collected usage data is queued to the Usage Monitor address space for storing into the collection repository. The QSZ value specifies the number of storage segments the area occupies, where a segment is one megabyte in size.

The QSZ value used is fixed for the life of the Usage Monitor address space. To change the QSZ value the Usage Monitor started task must be recycled.

segments: Specifies a number of segments from 1 to 200.
If no QSZ command is issued, a 10MB queue area will be used. The queue area is processed as a LIFO stack, which means that only the necessary number of pages needed to hold the peak queue length will need to be backed by physical storage, no matter how large the QSZ value is set.

REF - Refresh Usage Monitor settings

REF is used at any time to reset Usage Monitor settings according to commands in the HZAZIN file, without stopping and starting the Usage Monitor. The detailed results of the refresh operation are written to the HZAZMSG file.

The processes of a refresh operation include:

Verify that HZAZIN is stillallocated.
OpenHZAZIN.
Set the program exclusion list to the default list.
Deactivate all data set exclusion list elements.
Deactivate all data set inclusion list elements. v Process the commands in HZAZIN.
Close HZAZIN.
Issue either HZAZ059I or HZAZ060I, as appropriate.

The following example code changes Usage Monitor settings to updated values from HZAZIN.

F HZACJMON,REF

SEC - Set the data set space secondary allocation

SEC is used to specify the secondary space allocation quantity in tracks. It is used for output data set allocations.

trks

Specifies a number of tracks from 0 to 150,000.

If no SEC command is issued, the secondary space allocation is 300 tracks. The Usage Monitor uses the RLSE space allocation attribute.

The following example code sets the secondary space allocation to 600 tracks.

F HZACJMON,SEC(600)

SID - Set the Usage Monitor system identifier

SID is used to override the system identifier contained in the output header record. The SMF system identifier is used as a norm, but an override enables the data from separate systems to be differentiated in all instances where duplicate SMF identifiers are in use. Symbols can be employed in the construction of the system identifier.

Available symbols include all z/OS system symbols, &SMF, the SMF identifier for the system, and &SYSLPAR, the logical partition name for the system.

sid

Specifies a string which is to be resolved to an identifier 1-4 bytes inlength.

Table 3. Examples of using the EXC command
Command purpose	Example code
Set the output system identifier to PROD.	F HZACJMON,SID(PROD)
Set the header record system identifier to the current LPAR name. The LPAR name must not exceed four characters in length.	F HZACJMON,SID(&SYSLPAR)

SIZ - Set the data space repository size

SIZ is used to specify the maximum number of entries that the collection repository can hold.

entries

Specifies a number of entries from 100 to 6,000,000.

If no SIZ command is issued, a data space capacity of 200,000 entries is used. Each entry occupies 232 bytes and contains a pointer to a separate part of the repository dedicated to holding data set and UNIX file names. Storage is conserved by only storing a single copy of each collected data set and UNIX file name. As each repository page has data placed in it for the first time, that page must be backed physically by the system. When a collection repository is full, a repository switch is triggered automatically. A repository switch also occurs when data stamped after the switch time is detected, or when a manual switch is requested by the SWI command.

The following example code sets the size of future collection repositories to 1,000,000 entries.

F HZACJMON,SIZ(1000000)

SJS - Controlling spawned job suffix preservation

When a spawned address space is created by a unit of work with a job name that is shorter than eight characters, the system appends a sequence digit in the 1 to 9 range to the job name, and this becomes the job name of the spawned address space. This approach means that the usage of programs generated by jobs with a specific name can be logged under as many as ten different job names. The system-generated job names usually do not assist in identifying the source of the work because there is often no other reconciliation data which also uses these generated names.

The SJS setting can be used to remove the spawned sequence number suffix so that all usage events for programs are logged under the original job name, resulting in fewer Usage Monitor records and reduced processing time. If the spawning job name is eight characters long and ends in a digit in the 1 to 9 range, then activity in spawned address spaces (but not the original address space) can be reported under a job name which is only the first seven characters of the original job name. If this is likely to present a problem, then useSJS(N).

Y: Spawned job name suffix digit is truncated.
N: No editing is performed of spawned address space job names.

SJS(Y) is the default if no SJS command has been issued since the Usage Monitor started.

SWI - Switch to a new collection repository

SWI causes a new collection repository to be created and used for subsequent data collection. A writer task processes the data contents of the repository that is being used at the time that the SWI command is issued.

The SWI command has no operands. It is invalid in the HZAZIN initial command file. As well as the switch caused by an explicit SWI command, automatic switches occur when a repository becomes full, and when data stamped after the switch time is detected. The SWI command might be rejected if the writer task is busy.

The following example code manually switches to a new repository.

F HZACJMON,SWI

UID - Control the collection of user details

UID is used to specify whether the Usage Monitor collects the identifiers and names of users who use programs or not. If the details of users who use the various programs are not considered to be important, then you can dispense with the collection of this information. The advantage of not collecting user information is the reduction in processing times and data volumes.

When user information is not collected, the user ID data item remains blank, and usernames are not output, regardless which UNM setting is current. The total usage counts collected by the Usage Monitor for each program are not affected by this setting.

If you want program usage attributed to individual users but do not want the names of users to be retained, use UID(Y) and UNM(N).

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that details of each user using a program are to be collected.
N: Specifies that details of each user using a program are not to becollected

If no UID command is issued after IPL, user details are collected. UID(Y) is the default.

UNK - Set the unknown event collection switch

UNK is used to specify whether events with incomplete data are to be collected or not. The database content is not affected. Collecting extra data is useful in determining why some usage events are not captured. It must be set only when requested by HCL support.

Y: Specifies that the "unknown" events are to be collected.
N: Specifies that the "unknown" events are not to be collected.

If no UNK command is issued, the unknown events are not collected. UNK(N) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

UNM - Set username collection status

Software security packages, such as RACF, have a name field for each user ID defined to the system. The Usage Monitor collects the user ID (up to eight characters long), and the contents of the name field (up to 20 characters long), as part of the data collection performed when programs are used. UNM is used to specify whether the names of users collected from the security package are output. The output of the user ID is controlled by the UID setting. This setting is checked by the writer task when the data in a collection repository is being processed for output.

Y

Specifies that collected usernames are written to the output file.

N

Specifies that collected usernames arediscarded.

If no UNM command is issued, then usernames are collected. UNM(Y) is the default.

A change to this setting does not take effect until the next collection repository switch.

UNT - Set the data set allocation unit

UNT is used to specify the allocation unit to be used for output data set allocations.

Unitname

Specifies a 1 - 8 character long unit name. If no UNT command is issued, SYSALLDA is used.

The following example code sets the allocation unit to WORKDA.

F HZACJMON,UNT(WORKDA)

USS - Set UNIX program monitoring status

USS is used to determine if the programs retrieved from Hierarchical File System (HFS) files are to be monitored.

Y: Programs fetched from HFS files are to be monitored.
N: Programs fetched from HFS files are not to be monitored.

If no USS command is issued, the programs retrieved from HFS files are not monitored. USS(N) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

VOL - Set the data set allocation volume

VOL is used to specify the allocation volume to be used for output data set allocations. The explicit nomination of a specific volume is necessary when there are no PUBLIC or STORAGE volumes in the allocation unit pool.

volume: specifies a 1 - 6 character long volume serial number.

If no VOL command is issued, a specific volume is not explicitly requested. You must then have PUBLIC or STORAGE volumes in the public allocation pool, unless the data sets are managed by SMS.

The following example code sets the allocation volume to SCR001.

F HZACJMON,VOL(SCR001)

WRT - Set the automatic switch-and-write time of day

WRT is used to specify a time-of-day to end data collection for the current collection repository, and automatically switch to a new one. The data write-out for the closed repository is also initiated at the same time. These events are triggered when data from after the specified time is detected.

The UTC or GMT switch time is calculated using the local time when the repository is created. The time that a data space is terminated is set when it is created. Changes to the system local time offset, such as those caused by a change to daylight saving time status, do not alter the UTC or GMT time that the current repository is closed. The time of the switch, after the next switch, is calculated using the new local time.

hhmm: Specifies a 24-hour time-of-day in hour and minute notation. The value must be four decimal digits. The first two digits (hh) must be in the 00 - 23 range. The last two digits (mm) must be in the 00 - 59 range.

If no WRT command is issued, the automatic switch time of midnight is used. That is, WRT(0000) is the default.

The following example code sets the automatic switch-and-write time to 10 minutes before midnight.

F HZACJMON,WRT(2350)

XDD - Deleting data set name exclusion entries

XDD is used to remove data set name masks which were added by the XDS command. XDD can also deactivate entries from the default exclusion list that was automatically created by the Usage Monitor.

mask: Specifies a 1 - 44 character data set name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.

The following example code deactivates the SYS3.* exclusion mask.

F HZACJMON,XDD(SYS3.*)

XDS - Adding data set name exclusion entries

XDS is used to supply data set name masks which specify data set names to be excluded from data collection. Program usage data for programs fetched from data sets with names matching exclusion masks is discarded. When the captured data set name has been matched to an inclusion mask set by the IDS command, the data is collected without reference to the exclusion mask list.

mask: Specifies a 1 - 44 character data set name mask. If the mask ends in an asterisk, only characters before the asterisk are compared.Percent signs in the mask indicate that any character in that location is considered a match. If the mask contains a slash character (/), the value is considered to be a UNIX path name mask rather than a data set name mask.

The following example code excludes program usage data from collection for programs fetched from data sets with a high-level qualifier of SYS3.

F HZACJMON,XDS(SYS3.*)

ZIP - Set the compressed output data switch

ZIP is used to control whether the writer task is to compress output data or not. Compressing the output data reduces data volume, in turn reducing data transfer time and storage space requirements. Dataset Zip compression is mandatory for use with the Linux on Z import and reporting application.

Y: Specifies that output data is to be compressed.
N: Specifies that output data is not to be compressed.

If no ZIP command is issued, then compressed data is output. ZIP(Y) is the default setting.

Monitoring usage in CICS regions

The CICS Transaction Server for z/OS performs much of its program management outside of the contents supervisor framework that most applications use. For the Usage Monitor to accurately detect and record the use of programs in a CICS region, you must customize each CICS region where you require detailed program usage monitoring.

To prepare a CICS region to enable detailed monitoring, you must install the following components:

CICS global user exist(GLUE)programs
An enabling program to activate these user exit programs
An entry in the program list table (PLT) that triggers the enabling program

The customized JCLLIB library contains the following sample jobs that you can copy and use in your customization:

The HZASENAX member contains a sample job to translate, assemble and bind the enablingprogram.
The HZASPLTX member contains a sample job to create a PLT with the required entry to trigger the enabling program. If you use this sample job, verify the name of the enabling program and the PLT suffix before you submit the job.

The CICS program monitoring facility does not support releases earlier than CICS Transaction Server version 3, release 2. Different releases of the CICS Transaction Server require different versions of the GLUE programs. You must ensure that the correct version of these programs is used for each CICS region. You must also take care when upgrading regions to a later release of CICS so that the correct version of this module will be used with the newer software. The following table lists the required GLUE programs for different versions of the CICS transaction server.

Table 4. CICS Transaction Server release
CICS Transaction Server release	Exits program
Version 3, release 2	HZAZFTC0, HZAZEII0
Version 4, release 1	HZAZFTC1, HZAZEII1
Version 4, release 2	HZAZFTC2, HZAZEII2
Version 5, releases 1, 2, and 3	HZAZFTC3, HZAZEII3
Version 5, releases 4 and 5	HZAZFTC4, HZAZEII4

When you implement this CICS Transaction Server customization, the Usage Monitor can collect, and record data related to program name and data set name. The collected data is subject to the Usage Monitor program name and data set name selection and exclusion filters. You can stop data collections from all HZAZFTCx and HZAZEIIx GLUE programs with the CIC(N) Usage Monitor setting. CIC(Y) is the default setting if you do not issue a CIC Usage Monitor command.

Depending upon the level of program usage detail you require, you may find that the HZAZFTCx exit produces sufficient data for your needs without also installing the HZAZEIIx exit. If you want to access more detailed CICS data such as particulars of transactions and the end users involved, a specialized CICS monitor such as IBM Tivoli OMEGAMON XE for CICS on z/OS is required.

Customizing a CICS region to provide Usage data

Procedure

Copy the appropriate HZAZFTCx and HZAZEIIx global user exit (GLUE) programs from the SHZAMOD1 library to a DFHRPL library of the CICS region.
Customize and submit the HZASENAX job to create a program that enables the HZAZFTCx and HZAZEIIx exit programs:
1. Customize the sample job for translating, assembling, and binding the enabling program that is provided in the HZASENAX member in the customized JCLLIB library. For convenience, you can name this program HZAZENAx, where x is the same suffix character as the suffix of the HZAZFTCx and HZAZEIIx programs that it enables.
2. Check that the name specified in the PROGRAM operand of EXEC CICS ENABLE statement is the name of the enabling program.
3. Check that the name specified in EXEC CICS ENABLE PROGRAM statement is the name of the of the GLUE programs.
4. Link the HZAZENAx enabling program into the same DFHRPL library where you copied the HZAZFTCxand HZAZEIIx GLUE programs.
5. Submit the HZAZENAxjob.
Add an entry in the following format to the active program library table (PLT) of the CICS Transaction Server to install the HZAZENAx module: DFHPLT TYPE=ENTRY,PROGRAM=HZAZENAx
Place the entry before the DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM entry so that it loads early during CICS initialization to minimize the need for program resource definitions.
Ensure that the PLTPI setting for the CICS region specifies your newly updated PLT.

Results

When you complete this task, the use of programs that are given control by various mechanisms in the CICS Transaction Server are attributed to the CICS region address spaces that invoke them.

What to do next

You can stop data collection from all HZAZFTCx and HZAZEIIx glue programs with the CIC(N) Usage Monitor setting. The CIC(Y) option is the default if you do not issue a CIC Usage Monitor command.