ITTFMTB — Generate component trace format table

Description

ITTFMTB generates a table called the component trace format table. It can also generate a map of the table. IPCS uses this table to control the formatting of trace data for program events that occur when the system runs. When you use ITTFMTB to generate information in the table, you are specifying the formatting style of the trace data. For information about IPCS, see z/OS MVS IPCS User's Guide and z/OS MVS IPCS Customization.

Invoke the macro once to define the beginning of the table and once to define the end of the table. In between, you can invoke the macro repeatedly to define the individual formats for the various traceable events.

This macro generates nonexecutable code, and therefore is not sensitive to the execution environment.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PSW key 0
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt Status:	Enabled or disabled for I/O and external interrupts
Locks:	No locks held

Programming requirements

None.

Restrictions

None.

Register information

This macro does not use any registers.

Performance implications

None.

Syntax

The ITTFMTB macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede ITTFMTB.

ITTFMTB

␢	One or more blanks must follow ITTFMTB.

MAP	Required choice. Select one of four options.
TABLEDATA=`tabname`	`tabname`: Symbol up to eight characters long.
EVENTDATA=`eventid`	`eventid`: A-type address.
TABLEEND

,ENTRYLENGTH=`elength`	Optional with TABLEDATA and not otherwise allowed.
	`elength`: A-type address.

,LOCBUFNAME=`bufname`	Required choice with TABLEDATA and not otherwise allowed.
	`bufname`: Symbol up to eight characters long.
,LOCBUFADDR=`bufaddr`	`bufaddr`: A-type address.

,FILTERNAME=`pgmname`	Optional choice with TABLEDATA and not otherwise allowed.
	`pgmname`: Symbol up to eight characters long.
,FILTERADDR=`pgmaddr`	`pgmaddr`: A-type address.

,MNEMONIC=`mnemonic`	Required with EVENTDATA and not otherwise allowed.
	`mnemonic`: Symbol up to 32 characters long.

,DESCRIPTION=`text`	Required with EVENTDATA and not otherwise allowed. `text`: Symbol up to 32 characters long.

,MODELNAME=`modelname`	Optional choice with EVENTDATA and not otherwise allowed.
	`modelname`: Symbol up to eight characters long.
,MODELADDR=`modeladdr`	,MODELADDR=`modeladdr`

,FORMATNAME=`pgmname`	Optional choice with EVENTDATA and not otherwise allowed.
	`pgmname`: Symbol up to eight characters long.
,FORMATADDR=`pgmaddr`	`pgmaddr`: A-type address.

,OFFSETASID=`(ids)`	Optional with EVENTDATA and not otherwise allowed.
	`ids`: One or more A-type addresses, separated by commas.

,OFFSETJOBNAME=`(offsets)`	Optional with EVENTDATA and not otherwise allowed.
	`offsets`: One or more A-type addresses, separated by commas.

,VIEWSUMMARY=`scode`	Optional with EVENTDATA and not otherwise allowed.
	`scode`: A-type address.

,VIEWFULL=`fcode`	Optional with EVENTDATA and not otherwise allowed.
	`fcode`: A-type address.

,COMPONENTDATA=`cdata`	Optional with EVENTDATA and not otherwise allowed.
	`cdata`: A-type address.

,EXCEPTION	Optional choice with EVENTDATA and not otherwise allowed.
,NOEXCEPTION

Parameters

The parameters are explained as follows:

MAP: Specifies that a map of a format table is to be generated.
TABLEDATA=tabname: Specifies that the definition of an initialized format table is to be started. When you specify TABLEDATA, you also specify the name to be associated with the table and certain data that appears only once in the table.
EVENTDATA=eventid: Specifies the event identifier that is associated with a component trace event.
TABLEEND: Specifies the end of the definition of the format table.
,LOCBUFNAME=bufname: Specifies the name of the locate buffer exit routine that is loaded by the IPCS CTRACE subcommand. IPCS calls this routine to locate a component's trace buffers in a dump.
,LOCBUFADDR=bufaddr: Specifies the address of the locate buffer exit routine. IPCS calls this routine to locate a component's trace buffers in a dump.
,FILTERNAME=pgmname: Specifies the name of the component filter exit routine that is loaded by the IPCS CTRACE subcommand. IPCS calls this routine to provide component-specific filtering for that component's trace entries. No component filter exit is supplied if you do not specify one.
,FILTERADDR=pgmaddr: Specifies the address of the component filter exit routine. IPCS calls this routine to provide component-specific filtering for that component's trace entries. No component filter exit is supplied if you do not specify one.
,ENTRYLENGTH=elength: When elength is not zero, this parameter specifies the length of the fixed-length component trace entries that the component maintains. When elength is zero, it indicates that the component trace entries vary in length. A default of zero is assumed.
,MNEMONIC=mnemonic: Specifies a mnemonic name for the type of event being described. This name is the first information to be formatted on a line associated with an event entry of this type. The name permits the reader of formatted component traces to rapidly scan the output for patterns of events and events of particular interest.
,DESCRIPTION=text: Specifies descriptive, literal text to be associated with the type of trace entry being described. When this type of trace entry is formatted, the text appears at the end of the first line of the output. It helps the reader of the output to understand the significance of an entry, without having to access separate reference materials.
,MODELNAME=modelname: Specifies the name of the model that is to be used to format this trace entry. No model is used if MODELNAME or MODELADDR is not specified.
,MODELADDR=modeladdr: Specifies the address of the model to be used to format this trace entry. No model is used if MODELADDR or MODELNAME is not specified.
,FORMATNAME=pgmname: Specifies the name of the formatter routine that formats this trace entry. No formatter routine is called if FORMATNAME or FORMATADDR is not specified.
,FORMATADDR=pgmaddr: Specifies the address of the formatter routine that formats this trace entry. No formatter routine is called if FORMATADDR or FORMATNAME is not specified.
,OFFSETASID=(ids): If you want ASID filtering to be performed (as requested by an IPCS CTRACE subcommand), use this parameter to specify the offsets to the ASID fields. The ASID fields occur at various offsets in the trace entry. Specify up to 5 offsets. An offset value may not exceed decimal 65,535. If you do not specify OFFSETASID, ASID filtering is not performed
,OFFSETJOBNAME=(offsets): If you want job name filtering to be performed (as requested by an IPCS CTRACE subcommand), use this parameter to specify the offsets to the job name fields. The job name fields occur at various offsets in the trace entry. Specify up to 5 offsets. An offset value may not exceed decimal 65,535. If you do not specify OFFSETJOBNAME, job name filtering is not performed.
,VIEWSUMMARY=scode: Specifies the halfword view that the model processor uses to format summary fields from the trace entry. A default of X'8000' for scode is used if you do not specify this parameter.
,VIEWFULL=fcode: Specifies a halfword view (used by model processor) to format all fields from the trace entry. A default of X'0200' for fcode is used if you do not specify this parameter.
,COMPONENTDATA=cdata: This parameter is reserved for use by the component. If this parameter is not specified, a default of zero is assumed for cdata indicating that no component data is associated with the trace entry.
,EXCEPTION
,NOEXCEPTION: EXCEPTION specifies that this trace entry records an exceptional event. When the IPCS CTRACE subcommand is invoked with the EXCEPTION filtering option, only trace entries with the EXCEPTION attribute are formatted.
NOEXCEPTION specifies that the trace entries being described record normal events. These entries will not be formatted when the IPCS CTRACE subcommand is invoked with the EXCEPTION of the filtering option. The default is NOEXCEPTION.

Return and reason codes

None.