The parameters are explained in this section. First, select one of the four required parameters that define the function that the interface is to perform (SETUP, FORMAT, TERM, QUIT). Next, select the optional parameters that you need.

The required parameters are as follows:

SETUP

Initialize the interface by allocating and initializing control blocks and loading the component trace format table. Most of the other keywords can be specified to define the processing options.

FORMAT

Locate the specific entry in the format table and call the format routine. The CTE keyword identifies the record to be formatted.

TERM

End the interface by calling the filter routine one last time to issue any final reports and release all the allocated resources.

QUIT

End the interface by calling the filter routine one last time to release all the allocated resources acquired by the formatter.

The optional parameters are as follows:

,API=epaaddr

Specifies the location of a word that contains the location of the EZBCTAPI routine. Use this keyword in the SETUP call to pass the entry pointer address to the interface. This might be useful to avoid the overhead of loading and deleting this reentrant interface module. If the API keyword is not used, then the EZBCTAPI routine is loaded by the SETUP function and deleted by the TERM or QUIT function.

,COMP=name

Specifies the location of an 8-byte character field containing the name of the CTRACE component for trace records that are obtained from the real-time TCP/IP networking monitoring NMI. If not specified, the component name of SYSTCPDA is used. For trace records that are obtained from the real-time application-controlled TCP/IP trace NMI, this parameter is ignored.

,CTE=record

Specifies the location of a component trace record. Used with the FORMAT function.

,ENTRYID=entryId_list

Specifies a list of entry identifiers used to select a subset of CTE entries. The format of the list is fullword count, followed by a list of two fullword pairs. The fullword count contains the number of fullword pairs that follow. The first word of the pair contains the low value of the entry ID and second word contains the high value of the entry ID. For example, to format only type 5 data trace records, use the following code:

DC    F'1,5,5'

The count is one pair of words, and the low and high values are both 5.

,LDTO=stcktime

Specifies the location of an 8-byte store clock field. This field is in units of STCK timer units. It contains the local date time offset. This field is used to convert STCK time stamps in the component trace records to local time. If not specified, the field CVTLDTO is used as the default.

,LSO=stcktime

Specifies the location of an 8-byte store clock field. This field is in units of STCK timer units. It contains the leap seconds time offset. This field is used to convert STCK time stamps in the component trace records to GMT time and local time. If not specified, the field CVTLSO is used as the default.

,MAXLINE=number

Specifies the location of a word that contains the maximum line width for formatted output. The minimum value is 60 and the maximum value is 250. The default value is 80.

,NMCTF=epaaddr

Specifies the location of a word that contains the location of the EZBNMCTF stub routine. This might be useful to avoid the overhead of loading and deleting this reentrant interface module. This keyword should be used on each invocation that will invoke the interface (MF=(E)). If the NMCTF keyword is not specified, then the EZBNMCTF routine is called by the macro as an external reference and EZBNMCTF must be link-edited with the application program.

,OBTAIN=epaaddr

Specifies the location of a word that contains an entry point location of a routine used by the interface to obtain storage. The default is a routine that uses the STORAGE (OBTAIN) macro to obtain the storage from the operating system. If the OBTAIN keyword is specified then the RELEASE keyword must be specified. It is passed these pointers in a parameter list addressed by register 1:

• The work area
• The 4-word user token (see the USERTOKEN definition later in this section)
• The word where the location of the obtained storage is returned
• The word with the length of the storage to be obtained

The following return codes are supported:

• 00: The storage was obtained. The location of the storage is returned.
• 04: The storage could not be obtained. The address is null.

Standard calling conventions are used to call the routine in the same environment when the EZBCTAPI interface was called.

,OPTIONS=options

Specifies the address of options to be passed to the packet trace formatter. These options are described by EZBYPTO data area. See EZBCTAPI NMI: Passing options to the trace formatter for more information.

,PRTSRV=epaaddr

Specifies the location of a word that contains entry point location of a routine used by the interface and formatter to print lines of text and messages. It is passed these parameters in a parameter list addressed by register 1:

• The BLSUPPR2 parameter list.
• The 4-word user token (see the USERTOKEN definition later in this section).

The following return codes are supported from the print routine:

• 00: The line of text was printed.
• 04: The line was not printed and future output is to be suppressed.

Standard calling conventions are used to call the routine in the same environment when the EZBCTAPI interface was called.

To generate the BLSUPPR2 parameter list use the BLSUPPR2 macro:

PPR2 BLSUPPR2 DSECT=YES

The BLSUPPR2 macro is described in the z/OS MVS Programming: Assembler Services Reference ABE-HSP.

The following fields are defined as:

PPR2BUF	Location of buffer containing the data to be printed
PPR2BUFL	Length of data in the buffer to be printed
PPR2MSG	The buffer contains a message
PPR2OVIN	Overflow indentation level (0 for the first line, 2 for subsequent lines)

The print buffer is in the EBCDIC code page. The buffer has been translated to change unprintable characters to periods. The new line character (X'15') is located in each data line and the print function is called for each new line. Should the data buffer be larger than the MAXLINE value minus 1, then the print function is called as many times as needed with the rest of the print line with PPR2OVIN set to 2.

,RELEASE=epaaddr

Specifies the location of a word that contains the entry point location of a routine used by the interface to release storage. The default is a routine that uses the STORAGE (RELEASE) macro to release the storage back to the operating system. If the RELEASE keyword is specified, then the OBTAIN keyword must be specified. It is passed these pointers in a parameter list addressed by register 1:

• The work area
• The 4-word user token (see the USERTOKEN definition later in this section)
• The word with the location of the storage to be released
• The word with the length of the storage to be released

The following return codes are supported:

• 00: The storage was released.
• 04: The storage could not be released.

Standard calling conventions are used to call the routine in the same environment when the EZBCTAPI interface was called.

,RETCODE=retcode

Specifies the location where the interface return code is stored. The return code is also in general purpose register (GPR) 15.

,REPORT=FULL

,REPORT=SHORT

,REPORT=SUMMARY

,REPORT=TALLY

Formats the report.

FULL

Formats the IP protocol headers and packet data. This includes the component mnemonic, entry identifier, date and time, and a description of the trace record. FULL is the default report option.

SHORT

Formats the IP protocol headers. This includes the component mnemonic, entry identifier, date and time, and a description of the trace record.

SUMMARY

Requests two lines per trace record. Key fields from each qualifying trace record are printed following the date, time, and entry description.

TALLY

Requests a list of trace entry definitions for the component and counts how many times each trace entry occurred.

,RSNCODE=rsncode

Specifies the location where the interface reason code is stored. The reason code is also in GPR 0. EZBCTAPI provides a reason code if the return code is other than 0.

,TABLE=name

Specifies the location of the 8-character field that contains the name for the format table or two words. The first word contains zeros and the second word contains the entry point address of the format table. If the parameter is not specified or the name is not used, then the EZBPTFM4 table is loaded. This might be useful to avoid the overhead of loading and deleting this format table. For trace records that are obtained from the real-time TCP/IP networking monitoring NMI, you can specify the EZBPTFM4 table name. If the EZBPTFM4 table name is not specified or the name is not used, the EZBPTFM4 table is loaded. For trace records that are obtained from the real-time application-controlled TCP/IP trace NMI, you must specify the EZBRCFMT table name.

,TIME=GMT

,TIME=LOCAL

Specifies the conversion of the time field in the component trace records. The default is TIME=LOCAL.

GMT

The time is shown as Greenwich Mean Time.

LOCAL

The time is shown as local time.

,USERTOKEN=token

Specifies the location of a 4-word field that is copied and passed to the print service routine and the storage functions. The default is four words of zeros.

,WORKAREA=workarea

The location of a 16 KB work area used by the interface for its control blocks, work area, and save areas. The work area is cleared by the SETUP function. This work area must remain intact until the TERM or QUIT function is called. The work area cannot be shared across tasks. Specification is optional; if not specified, a 16 KB work area is obtained.

,MF=(L,list_addr)

,MF=(L,list_addr,attr)

Requests that an EZBCTAPI parameter list be defined. list_addr is the name assigned to the list. attr is an optional attribute used to define the parameter list. The default is 0D. No other keywords can be used with this macro format.

,MF=G

Requests that the EZBCTAPI_t parameter list description be generated. No other keywords can be used with this macro format.

,MF=(M,list_addr)

,MF=(M,list_addr,COMPLETE)

Request that the EZBCTAPI parameter list be modified. COMPLETE requests that the parameter list be set to binary zeros before any modifications.

,MF=(E,list_addr)

,MF=(E,list_addr,COMPLETE)

Requests that the EZBCTAPI parameter list be modified. COMPLETE requests that the parameter list be set to binary zeros before any modifications. In addition, for the SETUP function the EZBCTAPI interface program is loaded, and for the TERM and QUIT functions the interface program is deleted (see the API keyword to modify this behavior). The interface program is then called.

Restriction: COMPLETE does not apply to TERM and QUIT functions.