Suboperands for User fields

CICS® PA can access user fields in the CMF performance records. The user fields are defined in the CICS Monitoring Control Table (MCT) as either character type, count type, or clock type. As with CICS-defined clock type fields, user clock type fields have two parts: an elapsed time and a count of the number of times the condition occurred. When specifying user fields to CICS PA, the elapsed time part of clock type fields is called CLOCKTIME, and the count part of clock type fields is called CLOCKCOUNT. Therefore, CICS PA makes it appear as if there are four types of user fields: CHARACTER, COUNT, CLOCKTIME, CLOCKCOUNT.

When specifying user fields in the command stream, certain suboperands must be used to identify the user fields in the CMF performance record. The OWNER suboperand is common to all user fields. Use OWNER to specify the eight-character owner name of the user field.

The owner of the User Field is the entry name assigned to the User Field in the DFHMCT ID= macro specification. If the entry name is not specified in the ID= parameter, CICS assigns a default entry name or owner of 'USER'. CICS PA does not have a default owner name. Even if the owner name is USER, the OWNER suboperand must be specified.

The remaining suboperands are different for CHARACTER type fields versus numeric (COUNT, CLOCKTIME, CLOCKCOUNT)
CHARACTER type
Use the OWNER suboperand when specifying CHARACTER type fields. Only one character user field can be defined for each owner name.

The syntax is:

   CHARACTER(OWNER(owner)[,SUBSTR(offset,length)])

When printing a character user field on the Performance List or Performance Summary report, CICS PA defaults to using the entire length of the character user field.

Use the SUBSTR suboperand to specify that only part of the character user field is to be printed.

The first value (offset) is the position of the first character to be printed (starting at 1), and the second value (length) is how many characters are to be printed. For example, if the character field value is “1234567”, specifying SUBSTR(1,2) results in “12”, and specifying SUBSTR(3,3) results in “345”.

When character user fields are used in a SELECT statement, the SUBSTR operand must be specified.

COUNT, CLOCKTIME, and CLOCKCOUNT types
Use the OWNER and NUMBER operands when specifying user field types COUNT, CLOCKTIME, and CLOCKCOUNT. Up to 256 count type fields and up to 256 clock type fields can be defined for each owner. The OWNER operand specifies the eight-character name of the user field owner. This is the entry name in the DFHMCT ID= macro specification for the user field, or the CICS-assigned default name of 'USER'. The NUMBER operand specifies the three-digit number that identifies a specific count or clock type field.

The optional COLLENGTH suboperand specifies the field column width in the report. This enables you to increase the width of a column to accommodate a number that has many digits when the number would otherwise be truncated in the report.

The operand syntax is 
   COUNT(OWNER(owner),NUMBER(nnn),[COLLENGTH(length)])
   CLOCKTIME(OWNER(owner),NUMBER(nnn),[COLLENGTH(length)])
   CLOCKCOUNT(OWNER(owner),NUMBER(nnn),[COLLENGTH(length)])

All COUNT, CLOCKTIME, and CLOCKCOUNT type fields can be summarized in the Performance Summary report. Additional operands are then required to define the type of summarization (see SUMMARY - Performance Summary report).

Example:

Consider a DFHMCT User Fields definition for owner (or group) USEREMP which consists of the following fields:
  • Character field FIELD1 with a length of 16
  • Count field COUNT1
  • Clock field CLOCK1
DFHMCT TYPE=EMP,
       CLASS=PERFORM,
       ID=(USEREMP.1),
       CLOCK=(1,CLOCK1),
       COUNT=(1,COUNT1),
       FIELD=(1,FIELD1),
       PERFORM=(SCLOCK(1),
       ADDCNT(1,1),
       MOVE(1,16))
The following command generates a Performance List report that shows the following user field values:
  • The first 8 characters of FIELD1
  • The last 8 characters of FIELD1
  • The counter in COUNT1
  • The elapsed time in CLOCK1
  • The counter in CLOCK1
CICSPA LIST(FIELDS(TRAN,STYPE,USERID,
                   CHARACTER(OWNER(USEREMP),SUBSTR(1,8)),
                   CHARACTER(OWNER(USEREMP),SUBSTR(9,8)),
                   COUNT(OWNER(USEREMP),NUMBER(001)),
                   CLOCKTIME(OWNER(USEREMP),NUMBER(001)),
                   CLOCKCOUNT(OWNER(USEREMP),NUMBER(001))))