ITZEVENT — Transaction trace EVENT record

The requirements for the caller are:

Any module that invokes this macro must include the macos CVT and IHAECVT.

To get the equate symbols for the return and reason codes, the caller should include the ITZYRETC macro.

None.

Before issuing the ITZEVENT macro, the caller does not have to place any information into any access register (AR).

Some callers depend on register contents remaining the same before and after issuing a macro. If the macro changes the contents of registers on which the caller depends, the caller must save them before issuing the macro and restore them after the macro returns control.

None.

The ITZEVENT macro is written as follows:

The parameters are explained as follows:

name

This is an optional symbol, starting in column 1, that is the name on the ITZEVENT macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

COMPONENT=component

This is a required input parameter that specifies the user component name used in formatting the standard transaction trace header.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,EVENTDESC=eventdesc

This is a required input parameter that specifies the event-related field used in formatting the standard transaction trace header.

Some examples might be START xxxxxxxx, END xxxxxxxx, ENTRYPTxxx, COMMIT, and ROLLBACK.

To code: Specify the RS-type address, or address in register (2)-(12), of an 16-character field.

,DATAFORMAT=TT

,DATAFORMAT=GTF

This is an optional parameter that specifies the kind of data that follows the transaction trace header in the trace record. The default is DATAFORMAT=TT.

,DATAFORMAT=TT

The data recorded will contain transaction trace-related data.

,DATAFORMAT=GTF

This indicates that a GTF data record follows the standard transaction trace header. A pointer to the GTF record is passed along with the length.

,DATAADDR=dataaddr

When DATAFORMAT=TT is specified, this is an optional input parameter that can be used to specify the address and length of the data to be appended at the end of the transaction trace header. This is event-specific data set up by the user of this macro.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,DATALEN=datalen

When DATAADDR=dataaddr and DATAFORMAT=TT are specified, this is a required input parameter that specifies the length of the data to be appended at the end of the transaction trace header. This is event-specific data, set up by the user of this macro.

The maximum length of data may not exceed 1K. If a length greater than 1K is specified, data will be truncated to record 1K of data.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

,DATAADDR=dataaddr

When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the address and length of the GTF record to be appended at the end of the transaction trace header.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,DATALEN=datalen

When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the length of the data to be appended at the end of the transaction trace header.

The maximum length of data may not exceed 1K. If a length greater than 1K is specified, data will be truncated to record 1K of data.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

,GTFID=gtfid

When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the event ID that is to be recorded with the data bytes. Decimal event IDs 0 through 1023 (X'3FF') are available for user events.

To code: Specify the RS-type address, or address in register (2)-(12), of a 2-character field.

,GTFFID=gtffid

When DATAFORMAT=GTF is specified, this is an optional input parameter that specifies the format appendage (fidname) that controls the formatting of the record. Formatting occurs when the trace output is processed by GTF trace. The format appendage name is formed by appending the 2-digit GTFFID value to the names AMDUSER, HMDUSR, and IMDUSR. Assign GTFFID values as follows:

• X'00' - The record is to be dumped in hex.
• X'01' to X'50' - The record contains user format identifiers.

Note: If you omit the GTFFID parameter, the system supplies a default fidname of zero.

To code: Specify the RS-type address, or address in register (2)-(12), of a 1-character field.

,FMTTYPE=HEX

,FMTTYPE=MODEL

,FMTTYPE=ROUTINE

This is an optional parameter that specifies the IPCS format routine type for the user data. Refer to z/OS MVS IPCS Customization for details about the IPCS format.

The formatting can be in Hex, Model format, or from a Format routine. If a FORMATRTN is specified, FMTTYPE must be set to Routine or Model. The default is FMTTYPE=HEX.

,FMTTYPE=HEX

The data is displayed in Hex format.

,FMTTYPE=MODEL

The data is displayed in a format provided in a model format routine.

,FMTTYPE=ROUTINE

The data is displayed in a format provided in a user format routine.

,FORMATRTN=formatrtn

When FMTTYPE=MODEL is specified, this is a required parameter that specifies the name of the routine to be used for formatting the user data.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,FORMATRTN=formatrn

When FMTTYPE=ROUTINE is specified, this is a required parameter that specifies the name of the routine to be used for formatting the user data..

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,FUNCTIONNAME=functionname

this is an optional input parameter that specifies the function (module|routine|label) that is making the trace entry. This value is displayed on the trace record formatted by IPCS.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,QUERY=YES

,QUERY=NO

This is an optional parameter that specifies whether query should be performed to determine if this work unit is to be traced.

Specifying QUERY=YES causes the same function to be performed as the ITZQUERY macro. If transaction trace is active for this work unit, a trace record is built and recorded. The default is QUERY=YES.

,QUERY=YES

Specifies that Query needs to be performed.

,QUERY=NO

Specifies that Query does not need to be performed.

The transaction trace token (TRACETKN) is a required input parameter. The TRACETKN is obtained by issuing a ITZQUERY macro just prior to issuing the ITZEVENT.

,MONTKN=montkn

When QUERY=YES is specified, an optional input parameter is specified and is used as the token to locate the current monitoring environment.

IBM® recommends that MONTKN be specified for a monitoring environment to keep the query pathlength short and fast.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

,TRACETKN=tracetkn

When QUERY=NO is specified, this is a required input parameter that specifies the transaction trace token returned from the previously performed query.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

Note: Some existing components and products may have difficulty finding space in their data areas to hold a 32-byte transaction trace token. Apply APAR OW50696 to shorten the significant portion of the token to 8 bytes. With service for OW50696 applied, only the first 8 bytes of the 32-byte token will contain values other than binary zeros. Components that might not be able to exploit component trace due to the size of the 32-byte token may save just the first 8 bytes between uses, expanding it for use with transaction trace APIs by padding with binary zeros.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

This is an optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION

This is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.

MAX

Specify MAX if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage your program needs.

If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list form parameter list is always long enough to hold all the parameters you might specify on the execute form of the macro when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

0

Specify 0 if you use the currently available parameters.

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

This is an optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area, use the modify form to set the appropriate options, and use the execute form to call the service.

IBM recommends that you use and execute forms of ITZEVENT in the following order:

• Use ITZEVENT ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
• Use ITZEVENT ...MF=(M,list-addr,NOCHECK) specifying the parameters that you want to change.
• Use ITZEVENT ...MF=(E,list-addr,NOCHECK) to execute the macro.

,list addr

This is the name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1)-(12).

,attr

This is an optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

This specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOCHECK

This specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

None.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.

  ITZEVENT COMPONENT=COMP,
       EVENTDESC=DESC,
       DATAADDR=TTDATA,
       DATALEN=TTLEN

  COMP   DC   CL8'COMP1  '
  DESC   DC   CL16'START TRAN  '
  TTDATA  DC  CL64
  TTLEN  DC   F'64'