User event monitoring points: DFHMCT TYPE=EMP

You can use the DFHMCT TYPE=EMP macro to specify how the user data fields in performance class data records are added to or changed at each user event monitoring point. One TYPE=EMP macro must be coded for each user event monitoring point (EMP) at which user data is required.

The TYPE=EMP macro must be coded between the TYPE=INITIAL macro and the first TYPE=RECORD macro instruction.

TYPE=EMP

Indicates that this macro defines the user data to be collected at a user event monitoring point.

CLASS=PERFORM

Code this with the monitoring classes for which you want user data to be collected at this user EMP. The value PERFORM must be coded. The corresponding PERFORM operand must also be coded.

ID={number|(PP,number)|entryname.number}

Code this with the identifier of the user event monitoring point at which the user data defined in this macro is to be collected. If one of the forms number or (PP,number) is coded, a default entry name, USER, is provided.

number: A decimal integer in the range 1 through 255. Identification numbers between 1 and 199 are available for user EMPs. Numbers between 200 and 255 are reserved for IBM® licensed program EMPs. Code these numbers if you want to collect user data at EMPs defined in the code of IBM licensed programs.
(PP,number): An IBM licensed program EMP identification number. It is equivalent to specifying an ID value of 199 + number. The value of number is a decimal integer in the range 1 through 56.
entryname.number: Allows multiple use of number, a decimal integer in the range 1 through 255. Thus UNIQUE.3, DSN.3, and 3 are three different EMPs. A maximum of 98 entrynames can be specified against any particular number. Also, any count, clock, or byte-offset referred to by one of them is a different object from that referred to by any other.

In the following descriptions, any reference to a constant means a hexadecimal constant of up to eight hexadecimal digits; any shorter string is padded on the left with zeros. For example, to add or subtract decimal 14, the constant would be coded as 0000000E or just E (no quotation marks are required).

Any reference to the fields DATA1 and DATA2 means the two binary fullwords supplied by the user EMP coded in the application program. These are specified by the DATA1 and DATA2 operands of the EXEC CICS MONITOR command for defining user EMPs. Depending on the options coded, the DATA1 and DATA2 fields can be interpreted as numbers, masks for performing logical operations, or pointers to further information.

Any reference to a number means a decimal integer in the range defined in the description of the option.

CLOCK=(number,name1[,name2,...])

Assigns an informal name to one or more clocks. The informal name of any clock appears in its dictionary entry and is available to a postprocessor for use as, for example, a column heading.

The character string name1 is assigned to the clock specified by number at MCT generation. If specified, name2 is assigned to the clock number + 1. Similarly, any subsequent names are assigned to subsequent clocks. Any clock not named by this option receives the entry name value from the ID operand (the default is USER).

number must be in the range 1 through 256. The names specified must each be a character string up to eight characters long. If any string contains one or more blanks or commas, it must be enclosed in quotes.

COUNT=(number,name1[,name2,...])

Assigns an informal name to one or more count fields. The informal name of any count field appears in its dictionary entry and is available to a postprocessor for use as, for example, a column heading.

The character string name1 is assigned to the count field specified by number at MCT generation. If specified, name2 is assigned to the count field number+1. Similarly, any subsequent names are assigned to subsequent count fields. Any count fields not named by this option receive the entry name value from the ID operand (the default is USER).

FIELD=(1,name)

Assigns an informal name to the user byte-string field. This appears in its dictionary entry and is available to a postprocessor for use as, for example, a column heading.

name must be a character string up to 8 characters long. If it contains one or more blanks or commas, it must be enclosed in quotes.

PERFORM=(option[,...])

Code this operand when CLASS=PERFORM is specified. It specifies that information is to be added to or changed in the user fields of the performance class data record at this EMP.

The user fields for each user EMP distinguished by a separate entry name in the ID operand can comprise:

Up to 256 counters
Up to 256 clocks, each made up of a 8-byte accumulator and 4-byte count
A byte string of up to 8192 bytes

Note:

If the combined sizes of the objects (clocks, counts, and fields) implied in the specified options exceed 16384 bytes, assembly-time errors occur. You can avoid this by using fewer objects, either by collecting less data, or by clustering references to clocks and counts to avoid implied, but unused, objects.
When you define user data to be collected at a user event monitoring point, this extends the size of all CICS® performance class monitoring records. Each CICS monitoring record is the same size as the largest record; bear this in mind when specifying user data fields.

Actions are performed on the user fields according to the options specified.

PERFORM can be abbreviated to PER. Valid options for the PERFORM operand are:

ADDCNT(number,{constant|DATA1|DATA2})

The value of the user count field specified by number is to be incremented by constant or by the value of the field DATA1 or DATA2. number is a decimal integer in the range 1 through 256.

EXCNT(number,{constant|DATA1|DATA2})

A logical exclusive OR operation is to be performed on the value of the user count field specified by number, using constant or the value of the field DATA1 or DATA2. number is a decimal integer in the range 1 through 256.

MLTCNT(number1,number2)

A series of adjacent user count fields are to be updated by adding the values contained in adjacent fullwords in an area addressed by the DATA1 field. To use this option, both the DATA1 and DATA2 fields must be passed from the user EMP.

The user count fields that are to be updated start at the field specified by number1. The number of user count fields that are updated is the smaller of the values of number2 and the DATA2 field. If the DATA2 field is zero, the value of number2 is used. The series of adjacent fullwords used to add into the user count fields starts at the address specified in the DATA1 field. Successive fullwords are added into successive user count fields.

number1 and number2 are decimal integers in the range 1 through 256. The number of user counts generated is (number1 + number2 - 1). This value must also be in the range 1 through 256.

Note: Only one of the MLTCNT and MOVE options can be used in each DFHMCT TYPE=EMP macro.

MOVE(number3,number4)

A string of data is to be moved into the user byte-string field. To use this option, both the DATA1 and DATA2 fields must be passed from the user EMP.

The user byte-string field is updated starting at the offset specified by number3. The data to be moved starts at the address supplied in the DATA1 field. The maximum length of data that can be moved is given by number4 (in bytes), and the actual length of data that is to be moved is given by the value of the DATA2 field. If the value of DATA2 is zero, the length of the data given by number4 is moved.

number3 is a decimal integer in the range 0 to 8191, and number4 is a decimal integer in the range 1 to 8192. The maximum length of the user character field is (number3 + number4), and must be in the range 1 to 8192.

Note: Only one of the MLTCNT and MOVE options can be used in each DFHMCT TYPE=EMP macro instruction.

NACNT(number,{constant|DATA1|DATA2})

A logical AND operation is to be performed on the value of the user count field specified by number, using constant or the value of the field DATA1 or DATA2. number is a decimal integer in the range 1 through 256.

ORCNT(number,{constant|DATA1|DATA2})

A logical inclusive OR operation is to be performed on the value of the user count field specified by number, using constant or the value of the field DATA1 or DATA2. number is a decimal integer in the range 1 through 256.

PCLOCK(number)

The clock specified by number is to be stopped. The 4-byte count in the user clock field is flagged to indicate that the clock is now stopped. The accumulator is set to the sum of its contents before the previous SCLOCK and the elapsed period between that SCLOCK and this PCLOCK. number is a decimal integer in the range 1 through 256.

PCPUCLK(number)

This option performs the same function as PCLOCK, but uses the CPU-time of the CICS main task instead of elapsed time.

SCLOCK(number)

The clock specified by number is to be started. The value of the 4-byte count in the user clock field is incremented by 1 and flagged to show its running state. number is a decimal integer in the range 1 through 256.

SCPUCLK(number)

This option performs the same function as SCLOCK, but uses the CPU-time of the CICS main task instead of elapsed time.

SUBCNT(number,{constant|DATA1|DATA2})

The value of the user count field specified by number is to be decremented by constant or by the value of the field DATA1 or DATA2. number is a decimal integer in the range 1 through 256.

DELIVER

Performance class data accumulated for this task up to this point is delivered to the monitoring buffers. Any running clocks are stopped. The performance class section of the monitoring area for this task is reset to X'00', except for the key fields (transid, termid) and any data stored as a result of invoking the DFHAPPL special EMPs. Any clocks that were stopped by this option are restarted from zero for the new measurement period. The high-water mark fields are reset to their current values.