MONITOR INVOKE

Open Application Program Interface › TUNCALL Verbs and Keywords › MONITOR INVOKE

MONITOR INVOKE

The INVOKE keyword specifies that a monitor request is queued to measure one or more jobs. The parameters indicate the jobs and how they will be measured.

When invoking a monitor you must specify a profile name, an address space ID, or a job name. If you specify a job name or an address space ID, a profile is created by using the address space name. If the profile already exists, it will be updated.

If you specify a profile name, the jobs to be measured are taken from that profile. Similar to invoking a monitor with the ISPF client, if no matching job is found, the monitor is queued and waits until the start of a matching job step is detected.

When invoking monitors other options help refine the job or jobs to be measured, the number of jobs to be measured, the job steps, and the duration of the measurement.

With CA Mainframe Application Tuner, the address spaces can be selected on one of five different keywords:

Keyword	Definition	Notes
ASID	address space ID	When this option is used, the other four are ignored. ASID is a length of 4. for example, 0473,
JOBNAME	name of the address space	This field can contain wildcard characters. Max length is 8.
STEPNAME	step currently executing	This field can contain wildcard characters. Max length is 8.
PROCSTEP	if there are JCL procedures involved, the current procedure step	This field can contain wildcard characters. Max length is 8.
PROGRAM	name of the program at job step start	Normally this keyword is on the EXEC PGM=name JCL statement. Max length is 8.

Because some of these options can contain wildcard characters, it is possible that multiple jobs might match the criteria at the same time. If this situation occurs, CA Mainframe Application Tuner will select the job with the lowest address space ID (ASID). If JOBNAME, STEPNAME, PROCSTEP, or PROGRAM is blank, none of those steps are considered when locating a matching job to measure.

Schedules can also be associated with the monitor as well but the schedule is not stored with the monitor profile. It exists only for the life of the measurement request.

The following table shows the list of valid keywords for MONITOR INVOKE.


Keyword	Default	Notes
PROFILE	none	name of the monitor profile to be used if no monitor profile exists with this name, one will be created field cannot contain wildcard characters 1-8 characters in length
JOBNAME	none	name of the address space to be measured if the ASID keyword is used, this keyword is ignored can contain wildcard characters 1-8 Characters in length
STEPNAME	none	name of the job step to be measured if the ASID keyword is used, this keyword is ignored can contain wildcard characters 1-8 Characters in length
PROCSTEP	none	name of the procedure-step to be measured if the ASID keyword is used, this keyword is ignored can contain wildcard characters 1-8 Characters in length
PROGRAM	none	name of the program at step-initiation time to be measured if the ASID keyword is used, this keyword is ignored can contain wildcard characters 1-8 Characters in length
ASID	none	absolute ASID of the job to be measured 4 characters in length
FROMUSER	none	TSO User ID that will receive any messages issued on behalf of the monitor request 1-8 characters in length
ELAPSTIME	60	Monitor duration in seconds for which the observation process is active Normal duration is 60 seconds Specify the duration in seconds for which the observation process is active; the default value is 60 seconds. You can also specify minutes by appending an uppercase M to the numeral: 10M. Monitor duration must be a numeric value from 1 to 999997 (16,666 minutes). This value is used to set the observation rate based on the number of observations requested. Specify NA to request that the monitor collect a number of samples equal to the number of Observations Requested regardless of how many observations or how much time it takes to collect that number of samples. The value NA will not be honored if CA MAT detects we are monitoring a Websphere servant and the Websphere Application Server Criteria Expert Mode option is set to N.
SAMPLECNT	6000	number of observations requested use this keyword with ELAPSTIME to set an initial observation rate defaults will cause CA Mainframe Application Tuner to observe the address space every 10 minutes range is 10-999999 Note: SAMPLECNT is being retained as a parameter for compatibility with other products.
DUMP	no operands	does not require any operands directs CA Mainframe Application Tuner to take an SVC dump when the measurement session ends for diagnostic purposes only
RECCNT	1	number of job steps to measure you can start multiple measurement sessions with a single command by specifying RECCNT greater than 1, and by using wildcard characters on one of the job selection fields range is 1-9999
SUCCNT	1	number of times the same job step is successively measured when a measurement session ends, another starts immediately if the same job step is executing and the SUCCNT count has not been reached range is 1-9999
DESCRIPTION	none	24-character description that can be associated with the monitor profile if the profile already exists, this field updates its contents
SCHEDULE	none	name of the schedule 1- to 8-character field for TUNCALL requests, this keyword is for documentation purposes only, and indicates the scheduling fields are to be used and validated if the scheduling fields are nonblank and SCHEDULE is blank, the scheduling fields are ignored
MSTEP	NO	indicates that four job selection keywords (JOBNAME, STEPNAME, PROCSTEP, and PROGRAM) are to be used to select all steps within the job to be measured specify YES to monitor all steps in the job that match any Step/Procstep/Program criteria specified
SMON	NO	entire job step is to be measured if YES, ELAPSTIME is used as an estimate of the job step execution time to set the initialing observation rate only
SAMPDELAY	0	number of seconds CA MAT delays measuring the job after the job step starts this feature helps bypass measuring one-time events like housekeeping routes range is 0-999
INCTASK1-4	none	1 to 4 different tasks are measured within the job step tasks are identified by the program name provided as part of the ATTACH macro fields can contain wildcard characters 1 to 8 characters in length
EXCTASK1-4	none	1 to 4 different task names are excluded from sampling tasks are identified by the program name provided as part of the ATTACH macro this feature helps eliminate unwanted wait-time or active time that is not pertinent to the measurement fields can contain wildcard characters 1 to 8 characters in length
TRAN1-4	none	specific CICS or IMS transactions measured if the transaction is not running, no sample is taken fields can contain wildcard characters 1 to 8 characters in length
TERM1-4	none	specific CICS or IMS terminal measured if there is no activity on the specified terminal, no sample is taken fields can contain wildcard characters 1 to 8 characters in length
USERID1-4	none	specific CICS or IMS user IDs measured if the listed user IDs have no activity, no sample is taken 1 to 8 characters in length
TASKLIB	none	DD statement in the measured address space from where programs are loaded the libraries included in this DD statement are used to assist in CSECT-level resolution of program activity and wait time 1 to 8 characters in length
MONDSN	user default	name of the monitor data set or a monitor data set name pattern used to create a new monitor data set when the measurement starts certain data set name node variables can be used to keep the name dynamic, such as &SYSTEM, &SYSDATE, or &SYSTIME see Monitor Data Set Name in the Installation Guide for additional information
USEREXIT1-2	none	name of a user exit that CA MAT calls during the measurement session this exit is loaded into common storage and is called for each matching TCB in the address space for each observation made of the target job
JOBCARD1-4	none	if BATCHREPORTS is also indicated, these are the job cards used when CA MAT submits the batch jobs to generate the batch reports at the end of a measurement session 1 to 8 characters in length
MONDSTRKS	20 tracks	number of tracks CA MAT allocates as the monitor data set's primary space allocation
MONDSSEC	20 tracks	number of tracks CA MAT allocates as the monitor data set's secondary space allocation
MONDSGEN	SYSDA	device generic name where the data set is allocated
MONDSVOL	none	optional volume-serial name where the data set resides
MONDCLAS	none	name of an SMS Data construct for the monitor data set
MONMCLAS	none	name of an SMS Management construct for the monitor data set
MONSCLAS	none	name of an SMS Storage construct for the monitor data set
TARGSYS1-4	none	1 to 4 names of matching sysplex images where the monitor request is sent these fields can contain wildcard characters if blank, the request is sent only to the local system
BATCH REPORTS	none	sets CA MAT to submit a batch job to generate batch reports at the end of a measurement session
REPDSN	none	specify a data set name to receive the generated batch report leave this field blank to write the report to SYSOUT specify.MONDSN to use the data set name of the monitor file a .BAT node will be appended to the monitor file name to create the file name some truncation may occur if the resulting name is longer than 44 characters if the data set is not found, it will be created
REPPTRKS	20 tracks	number of tracks CA MAT allocates as the report data set's primary space allocation
REPSTRKS	20 tracks	number of tracks CA MAT allocates as the report data set's secondary space allocation
REPUNIT SYSDA	none	device generic name where the report data set is to be allocated
REPVOL	none	optional volume-serial name where the report data set resides
REPDATA	none	name of an SMS Data construct for the report data set
REPMGMT	none	name of an SMS Management construct for the report data set
REPSTOR	none	name of an SMS Storage construct name for the report data set
Scheduling Fields
STARTDATE	none	starting date for the schedule must be in CCYY/MM/DD format
ENDDATE	none	ending date of the schedule must be in the format of CCYY/MM/DD mutually exclusive with DAYS
DAYS	1	number of days the schedule is active if the monitor session is still waiting at the end of the schedule, it is automatically terminated range 1-999
WEEKDAYS	no operands permitted	schedule checks only for days that are part of weekdays mutually exclusive with SPECIFICDAYS
WEEKENDS	no operands permitted	schedule checks only for days that are part of weekends mutually exclusive with SPECIFICDAYS
SPECIFICDAYS	no operands permitted	schedule is to be active only on specific dates one of the following days must be specified if SPECIFICDAYS is used: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY
MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY	no operands permitted	specific days of the week where the request is active (looking for a matching job) if one or more of these are listed, SPECIFICDAYS must also have been specified
STARTTIME1-4 and ENDTIME1-4	0000 - 2359	up to 4 different panels within a day where the schedule panel is open for matching jobs
GROUP	none	1-8 character name assigned to the profile group
TRIGGER	NO	YES indicates that the profile is a trigger for the group Y means that monitor sessions is started for all profiles in the group when the trigger profile is started
WebSphere Monitoring Criteria
WASEXPRT	N	WebSphere Expert Mode specify Y to collect normal PSW sample data when a WebSphere application is monitored specify N to disable PSW sampling (CA MAT will only collect WebSphere samples)
URLFILT1	none	transaction URL filter pattern 1 specify filters for the application-level transaction URL names that you want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma each URL filter field (1 through 4) will be concatenated together any transaction not matching a filter pattern will not be monitored
URLFILT2	none	transaction URL filter pattern 2 specify filters for the application-level transaction URL names that you want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma each URL filter field (1 through 4) will be concatenated together any transaction not matching a filter pattern will not be monitored
URLFILT3	none	transaction URL filter pattern 3 specify filters for the application-level transaction URL names that you want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma each URL filter field (1 through 4) will be concatenated together any transaction not matching a filter pattern will not be monitored
URLFILT4	none	transaction URL filter pattern 4 specify filters for the application-level transaction URL names that you want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma each URL filter field (1 through 4) will be concatenated together any transaction not matching a filter pattern will not be monitored
SYSFILT1	none	system class filter pattern 1 specify filters for any system class names that you do not want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma any system class URL matching a filter will not be sampled these filters are used in conjunction with the Global system class filters that are defined in TRPARM member TUNWSC00
SYSFILT2	none	system class filter pattern 2 specify filters for any system class names that you do not want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma any system class URL matching a filter will not be sampled these filters are used in conjunction with the Global system class filters that are defined in TRPARM member TUNWSC00
SYSFILT3	none	system class filter pattern 3 specify filters for any system class names that you do not want to monitor (up to 72 bytes) use * as a wildcard you can specify several filters and separate each pattern with a comma any system class URL matching a filter will not be sampled these filters are used in conjunction with the Global system class filters that are defined in TRPARM member TUNWSC00

Example 1

This example shows a request that invokes a monitor for the job PROD01 where 6000 observations are to be made within 60 seconds. The output is to be sent to the monitor data set of 'CAMAT.&PROFILE.&SYSDATE.&SYSTIME'.

The variables within the monitor data set name are substituted at the time the monitor actually starts measuring the job. Because no profile name was specified, the profile name of PROD01 (the job name) is used.

The double quotation marks around monitor data set name ensures the single quotation marks around the monitor data set name are preserved. All messages are to be sent to the TSO user named PCNTL01.

MONITOR INVOKE -
   JOBNAME(PROD01) -
   SAMPLECNT(6000)
   ELAPSTIME(60) -
   MONDSN("'CAMAT.&PROFILE.&SYSDATE.&SYSDATE'") -
   FROMUSER(PCNTL01)

Example 2

This example shows a request that measures the next five jobs in which the first four characters of the job name starts with PROD and in which the program names start with PAY. Each step is to be measured three times successively.

This monitor has a schedule associated with the monitor request as well. This schedule, called PAYROLL, looks only for matching jobs on Monday nights starting at 11:00 PM until Tuesday morning at 3:00 AM and on Wednesday nights starting at 11:00 PM until Thursday morning at 3:00 AM.

The monitor data set name is to be set. Each measurement session is to last three minutes and will make 9000 observations. The schedule starts on the day the monitor is invoked and lasts for seven days.

MONITOR INVOKE -
   JOBNAME(PROD*) -
   PROGRAM(PAY*) -
   SAMPLECNT(9000) -
   ELAPSTIME(3M) -
   MONDSN("'CAMAT.&PROFILE.&SYSDATE.&SYSDATE'") -
   SCHEDULE(PAYROLL) - /* USED AS DOCUMENTATION */
   STARTDATE(&TODAY) -
   DAYS(7) -
   SPECIFICDAYS MONDAY WEDNESDAY -
   STARTTIME(2330) ENDTIME(0300)

Tell Technical Publications how we can improve this information