OPTION command

The OPTION statement is only valid from the parmlib. The main purpose of the OPTION statement is to specify the number and size of the in-memory data buffers. It can also be used to specify other processing options that are effective for the duration of the entire Access Monitor started task.

The OPTION statement has the following syntax (part 1 and part 2):

Option (part 1)

Read syntax diagramSkip visual syntax diagramBufsize(1024bufsize)BufsizeMB(1024bufsizemb)Numbufs(10numbufs)RACFExitMode(FASTSTOREDIRECTCSVDYNEX)PRECONSOLIDATENOPRECONSOLIDATESetSRVClassNoSetSRVClassCollectionDataset(MultiIntervalSingleInterval)NoShowStatisticsShowStatistics(C2PAMSTSmember-name)NoIncludeOwnResourceIncludeOwnResourceNoCaptureProgramsCapturePrograms(DefProgramCtlProgramSpecProgramCtlLibrary)NoCaptureLocalRACListCaptureLocalRACListNoCaptureUSSEventsCaptureUSSEventsALLOCATIONMEMBER(C2PAMALCalloc-member)

OPTION (part 2)

Read syntax diagramSkip visual syntax diagramRPH(AgingFactor(9value)TuneUpFactor(10value)TuneDownFactor(10value))NoEventsToAlertEventsToAlert(TYPE(,VERIFYNOVERIFYAUTHNOAUTHFASTNOFASTDEFINENODEFINE)CLASS( class-name))ALLOCATIONMEMBER(C2PAMALCalloc-member)

The keywords and variables have the following values:

Bufsize/BufsizeMB
The Bufsize/BufsizeMB keyword can be specified only when the OPTION statement is used during startup or during RESTART processing. It is ignored during CONSOLIDATE processing.

Bufsize/BufsizeMB specifies the size of the in-memory buffers used for storing the Access Monitor records during the interval period. Make sure that the buffer is large enough to contain all Access Monitor records collected during that period. If the buffer is too small, the Access Monitor data-capturing routines attempt to switch to an unused buffer. If no unused buffer is available, a buffer overflow message is issued, and the buffer containing the oldest data is used instead.

If you use the Bufsize keyword, specify the required buffer size in kilobytes. If you use the BufsizeMB keyword, specify the size in megabytes. Valid sizes for the buffers are between 1 kilobyte and 1 gigabyte. The size that you specify is rounded up to the nearest megabyte. If you use both keywords in an OPTION statement, the last value specified is used by the program. The buffers are allocated in 64-bit storage and count towards the specified MEMLIMIT of the started task. The use of multiple buffers during periods of high activity can significantly reduce the required buffer size. In general, it is more efficient to specify, for example, 10 buffers of 1 megabyte instead of 2 buffers of 5 megabytes.

Numbufs
The Numbufs keyword can be specified only when the OPTION statement is used during startup or during RESTART processing. It is ignored during CONSOLIDATE processing.

Numbufs specifies the number of buffers allocated. Valid values for numbufs are between 2 and 32. Make sure that the total number of buffers is sufficient to hold all captured Access Monitor records during periods of high activity.

To reduce the bufsize required to save all data collected during high-activity periods, specify multiple buffers. If no additional buffers are available, the oldest buffer is used instead, resulting in data loss.

RACFEXITMODE
The RACFEXITMODE keyword can be specified only when the OPTION statement is used during startup or during RESTART processing. It is ignored during CONSOLIDATE processing.

The RACFEXITMODE keywords specify whether functional sub exits are called using z/OS® dynamic exit services, or are called using a direct branch instruction. Using z/OS dynamic exit services provides additional flexibility and recovery, but uses more resources. Using a direct branch instruction is more efficient, but does not provide additional flexibility or recovery above that which is provided by the called sub exit. Possible choices for the parameters are:

FASTSTORE
This keyword indicates that dedicated modules are used that combine the router function and the functional routine. These modules use Cell Pool storage that is allocated in the user's address space. Cell Pool storage is not automatically returned to the system when it is no longer used. Instead, it is kept for future reuse. The Cell Pool storage that zSecure uses is allocated in subpool 249, which is private storage in the area between 16MB and 2GB. In most environments, use of FASTSTORE is more efficient than DIRECT mode.

The FASTSTORE mode exploits Cell Pool storage. Therefore, it avoids certain resource contentions that might occur in the CSVDYNEX or DIRECT mode. Using FASTSTORE mode also causes less switching to General Purpose processors for tasks that are zIIP-eligible. The FASTSTORE mode is preferred for most environments.

DIRECT
This keyword indicates that the RACF® exit router module uses a direct branch instruction to call the functional sub exits. This option uses less system resources than the CSVDYNEX mode. The zSecure routines use the STORAGE macro to acquire and release working storage.

The ICHRFX02 and ICHRTX00 exits are not supported in DIRECT mode. If you select DIRECT mode, these exits are automatically installed in FASTSTORE mode.

CSVDYNEX
This keyword indicates that the RACF exit router module uses z/OS dynamic exit services for calling the functional sub exits. This option provides additional flexibility and recovery for the called sub exits.

The ICHRFX02 and ICHRTX00 exits are not supported in CSVDYNEX mode. If you select CSVDYNEX mode, these exits are automatically installed in FASTSTORE mode.

If the RACFEXITMODE keyword is not specified, or if no value is specified, RACF® exits are called using the FASTSTORE method.

PRECONSOLIDATE, NOPRECONSOLIDATE
This keyword indicates if Access Monitor uses in-memory pre-consolidation. Pre-consolidation implies that the count of similar events is maintained in the records in the in-memory buffers. The date and time on the first record in the in-memory buffer is used for all pre-consolidated events. If pre-consolidation is not active, every event with its own date and time stamp is individually recorded in the in-memory buffer and passed to the CKRCARLA program for consolidation. Pre-consolidation has the advantage that fewer event records are created and processed. This can lead to a significant reduction in the required in-memory buffer size, used CPU time and virtual storage. For most situations, using pre-consolidation is preferred. The default value is PRECONSOLIDATE.
SETSRVCLASS, NOSETSRVCLASS
Determines whether the started task runs within the SYSSTC service class. The SYSSTC service class is intended for high priority system tasks. The collection of events and saving the collected data should be done in a timely manner. Therefore, a sufficiently high priority setting is important. If you must assign a lower dispatching priority, create an applicable WLM classification rule that assigns the required WLM service class. You must also specify NoSetSRVClass on the OPTION statement to prevent the program from resetting itself to the SYSSTC service class.

If you are running on a single processor system, careful analysis of your workload is required and using NoSetSRVClass might be preferred.

The default value of this option is SETSRVCLASS.

CollectionDataset
The CollectionDataset keyword can be specified only when the OPTION statement is used during startup or during RESTART processing. It is ignored during CONSOLIDATE processing.
The CollectionDataset keyword specifies whether the daily collection data set is used for data collected during a single SMF interval or during multiple SMF intervals.
SingleInterval
At the start of the collection process, a daily collection data set is created. At the end of the SMF interval, the captured data is written to the data set, and the data set is closed and renamed. A new data set is created to contain the data from the next SMF interval. This has the advantage that data that is collected during the day is available for analysis. However, it requires more processing resources. Data from the day is split over multiple data sets. If the default SMF interval is used, there are 48 data sets per day. These data sets are consolidated into a single daily consolidation data set. The daily collection data sets are then deleted.
MultiInterval
At the start of the collection process, a daily collection data set is created. At the end of the SMF interval, the captured data is written to the data set, and the data set is prepared for additional data from the next SMF interval. Data that is collected during the day is available only after consolidation (either through a CONSOLIDATE command, or as the result of the automatic daily consolidation). Data is normally kept in a single data set that contains all SMF intervals of the day. The multiple SMF intervals are consolidated into a daily consolidation data set. The daily collection data set is then deleted.
SHOWSTATISTICS, NOSHOWSTATISTICS
This keyword determines if the specified CARLa member is included and run at the end of every SMF interval. At the end of the SMF interval, the data that is collected in storage is written out to the daily collection data set. The default member C2PAMSTS writes information about the number and type of events that are collected during this interval to the z/OS® system log and to the joblog of the STC. The following figure shows example output:
C2P8000I Access data for period 31Aug2016 21:40:23 - 31Aug16 21:45:30 
C2P8001I Totals           1365                                        
C2P8001I        Auth      1090                                        
C2P8001I        Fast         7                                        
C2P8001I        Define       2                                        
C2P8001I        Verify     266                                        
C2P8002I Output records    100

Using the SHOWSTATISTICS keyword and the provided C2PAMSTS member requires that you use the provided C2PAMCOL member for daily collection. The C2PAMCOL member contains the DEFTYPE and DEFINE statements that are used in C2PAMSTS to calculate the number of output records. The C2PAMSTS member is included from the SC2PSAMP concatenation in the started task procedure. The default value for this keyword is NOSHOWSTATISTICS.

INCLUDEOWNRESOURCE, NOINCLUDEOWNRESOURCE
Determines whether Access Monitor records are created for Access Monitor events logged when users request access to their own resources. These resources might be, for example, private data sets or jobs running with a user's own userid. Using the INCLUDEOWNRESOURCE option can be helpful to diagnose suspected problems with missing events. However, because this option can significantly increase the amount of data collected, use it only when required. The default for this option is NOINCLUDEOWNRESOURCE.
CapturePrograms, NoCapturePrograms
Determines whether zSecure Access Monitor captures events for program access through the SAF Router exit ICHRTX00. When activated, the SAF Router exit is used to create ACCESS records for program access. Information is collected before any RACF processing takes place. No information is captured about the result of RACF processing. The default for this option is NOCAPTUREPROGRAMS.
If no sub-parameters are specified, Access Monitor collects information for all programs, independent of their RACF definition. It is also possible to specify that only events for selected programs are collected. The OPTION statement supports only the specification of one criterion, but you can repeat the OPTION statement when you need multiple selections. An OPTION statement with only the (NO)CAPTUREPROGRAMS keyword, without any subkeyword, overrides any previous program capture specification. You can specify the following program selection criteria:
DefProgram
The program is matched by a profile in the PROGRAM class. The matching PROGRAM profile can end with an asterisk. The program can be loaded from any controlled or non-controlled library. This selection can be used to locate (potentially unprotected) copies of controlled programs.
CtlProgram
The program is matched by a profile in the PROGRAM class, and was loaded from the corresponding library and optional volume.
SpecProgram
The program is matched by a non-backstop entry in the PROGRAM class. The matching PROGRAM profile can end with an asterisk. The program must be loaded from the corresponding library and optional volume.
CtlLibrary
The program was loaded from a controlled library. The program does not need to match any defined PROGRAM profile. Only the library name and the optional volume are inspected. This selection can be used to detect other programs that are loaded from controlled libraries. This can be relevant when setting up program access to data sets (PADS).
CaptureLocalRACLIST, NoCaptureLocalRACLIST
Determines whether zSecure Access Monitor captures events for FASTAUTH access events through the RACF post-processing exit ICHRFX02. When activated, this FASTAUTH exit is used to capture information about access events against LOCAL RACLISTed resources. The ICHRFX04 exit is used for GLOBAL RACLISTed resource classes, and for other situations where RACF calls the ICHRFX04 exit. The default for this option is NoCaptureLocalRACLIST.
CaptureUSSEvents, NoCaptureUSSEvents
Determines whether Access Monitor captures events for UNIX file and directory access events. When activated, the UNIX dynamic syscall exits are used to create ACCESS records for selected events. Specifying this option is effective only if the steps described in Required preparation for collecting UNIX event data are followed. The default for this option is NOCAPTUREUSSEVENTS.

Before starting to collect UNIX event information, ensure that your ACCESS files can accommodate the additional space requirement for these UNIX events. For information about estimating the required space, see Estimating the required space for UNIX event data.

RPH
Specifies the value for the RPH (Real (Resolved) Pathname) aging factor (AgingFactor), LRU stack increase factor (TuneUpFactor), or LRU stack decrease factor (TuneDownFactor). This option is intended to be used only at the request of IBM Software Support personnel.
EventsToAlert, NoEventsToAlert
Determines if information for certain events is forwarded to zSecure Alert. The default is not to forward any event information. If you specify only the EventsToAlert keyword without any detail keywords or parameters, VERIFY events are forwarded to zSecure Alert. The current release of Access Monitor only supports TYPE(VERIFY) as detail specification. Detail keywords and parameters for other events and selections are reserved in the syntax. These keywords and parameters are currently not supported and using them results in an error message.

To activate forwarding of supported captured events, specify either Option EventsToAlert or Option EventsToAlert(Type(Verify)). To deactivate forwarding of supported captured events specify either Option NoEventsToAlert or Option EventsToAlert(Type(NoVerify)).

If you activate event forwarding to zSecure Alert, the Access Monitor started task performs additional processing. At the beginning of every interval as defined through the REPORT statement, the started task verifies that events can be forwarded to zSecure Alert. If the Alert started task is not active, an error message is issued. Only activate event forwarding if you are using the event data to generate alerts, for example through predefined alert 1122.

Forwarding events to zSecure Alert has no effect on recording events in the Access Monitor ACCESS files.

ALLOCATIONMEMBER
The alloc-member specifies the name of the member that contains ALLOC statements for ddnames that are not, or that cannot be allocated through JCL. One reason that the ddnames cannot be allocated is that the allocation specifies a SYSOUT destination, while the C2PACMON started task is intended to run under the MSTR subsystem. The allocation member must be present in the samp-ddname as it is specified on the ddname keyword in the REPORT statement. For zSecure Access Monitor, the default for alloc-member is C2PAMALC, and the default for samp-ddname is SC2PSAMP. For more information about the contents of the C2PAMALC member, see Dynamic allocation member C2PAMALC.