This topic summarizes the steps to install and trace a BMC ThruPut Manager installation exit.

Summary of Installation Steps

The following steps summarize the installation of a BMC ThruPut Manager exit:

1. Link the exit into the appropriate library, making sure that it has the correct attributes as described below.
2. Insert a TM EXIT initialization statement in the TMSS initialization stream, specifying the name of the module and the initial status of the exit (active or inactive). See below.
3. Restart BMC ThruPut Manager to include the exit.

Where Exits Should Reside

When installing exits you must consider the following points:

• Installation exits must reside in an MVS authorized library, since BMC ThruPut Manager must be authorized.
• Reentrant exit load modules are LOADed in protect key 0.
• Installation exits can run in 31-bit addressing mode and use any RMODE.
• Exits can reside in the Extended LPA.
• For Job Analyzer exits:

–They must be located in LPA or a LNKLST data set such as SYS1. LINKLIB.

–Since they are reLOADed for each job processed, an installation with a high batch job rate might wish to place the exits in the Link Pack Area.

LLA must be refreshed to load a new version. If the modules are in LPA, unless you give a different name to the new modules and alter the TM EXIT statement, the new copies are not picked up until the system is re-IPLed.

Exit Tracing

To assist in development and debugging, BMC ThruPut Manager provides a means of tracing the installation exit parameter lists. Tracing should be done with caution, since it can be CPU intensive and impact overall system performance.

Exits are designated as eligible for tracing through the TMSS initialization statement TM EXIT or the /TM EXIT operator command.

Once exits have been marked eligible, tracing is initiated through the /TM TRACE operator command or the TM TRACE initialization statement.

Both the /TM TRACE command (or TMSS initialization statement) and the /TM EXIT command (or TMSS initialization statement) must be issued to enable tracing for a specific installation exit.

Tracing Methods

Job Analyzer exits and TMSS exits require different tracing methods. For TMSS exits there is no job's system messages data set for tracing data to be displayed, so an alternate method through GTF is provided.

Tracing Exits From Job Analyzer

For Job Analyzer exits the job's system messages data set is used to print the tracing data. The exit parameters and installation data areas are printed as a hexadecimal and EBCDIC dump of each data area on the job's system messages data set.

A delimiter header is provided to separate the tracing data produced by each exit. This header contains:

• The exit number.
• The exit return code, if any, formatted in hexadecimal.
• Following the header, the installation exit parameters and data areas are formatted.

Each formatted data area is preceded by an identification line containing the data area's four character mnemonic, its address, its length, and its storage key. The data areas formatted for all Job Analyzer exits are:

UXPLThe installation exit parameter list.

UXCPThe installation exit common parameters.

UXP#The variable parameters for this installation exit.

UCOMThe 16 byte user communication area.

UJDSThe set of User Descriptors.

In addition, the following data areas are dumped for some exits:

ACCTFor Exit 2.

The accounting fields from the EXEC statement ACCT field are dumped if present for the EXEC Statement exit.

PARMFor Exit 2.

The EXEC statement PARM field is dumped for the EXEC Statement exit.

JFCBFor Exit 3.

The job file control block is dumped for the DD Statement exit.

JFCEFor Exit 3.

The job file control block extension is dumped if present for the DD Statement exit.

VLSTFor Exit 3 and Exit 7.

The DD statement volume list is dumped for the DD Statement exit (exit 3), and the entire list of volumes for the job is dumped for the Job Information Collection exit (exit 7).

USERFor Exit 5, Exit 7 and Exit 8.

The volume user data field is dumped for the Volume Status exit (exit 5), and the job user data segment is dumped for the Job Information Collection exit (exit 7) and the Requeue exit (exit 8).

SRMFor Exit 6.

The Step Resource Matrix is dumped for the Job Action Modification exit.

Since Job Analyzer exit calls are associated directly with specific jobs, it is also possible to limit tracing to only certain jobs. This is accomplished by using options of the /TM TRACE command or the TM TRACE TMSS initialization statement, described below.

Tracing Exits From TMSS

For TMSS exits, the exit parameters are traced via GTF using the GTRACE macro instruction. This produces GTF USR records with an event identifier of 249.

GTF must be active to trace TMSS exits. The GTF trace options must include tracing for USR event number 249.

You must use AMDPRDMP to format and print these records. TMSS exits result in at least two GTF records for each installation exit call and return. More than one record is required because the length of a GTF USR record is limited to 256 bytes.

The first 8 bytes of each GTF record contain an identification field to relate the all of the records from one exit call or return event. In hexadecimal, this field has the following format:

cttttttt ttttttssWhere:

cIs 0 for an exit call and 8 for an exit return.

ttt...Is the value of the system Time of Day Clock.

ssIs the record sequence number for the current event.

All of the records for one event have the same value in the first 7 bytes of this field, while the sequence number identifies the specific contents of the record.

The remainder of a record with sequence number 01 contains the following fields:

• The return code from the exit or zero for an exit call (4 bytes).
• The address of the installation exit parameter list (4 bytes).
• The installation exit parameter list (16 bytes).
• The installation exit communication fields (16 bytes).
• The installation exit common parameters (144 bytes).

The remainder of a record with sequence number 02 contains the installation exit variable parameters. The length of this record depends on the length of the variable parameter area.

It is not possible to limit tracing to specific jobs for TMSS exit calls, since jobs processing and TMSS exit calls occur asynchronously.

TMSS Initialization Statements

To implement an exit, a TMSS initialization statement is needed.

Activation of exit tracing can be started either through the TMSS initialization statement TM TRACE or a command /TM TRACE. The initialization statements TM EXIT and TM TRACE are documented below. They are also documented is the System Programming Guide: Base Product publication.

The TM USER initialization statement is needed to define user areas. The user areas allow you to extend the job information collected for each job. The actual data placed in this areas is up to you.

TM EXIT

Define an Installation Exit

This statement specifies which installation exits are to receive control, and their initial status.

nnIs an exit number, from 1 to14, 19, 20, 21, 24, or 31.

module-nameSpecifies the name of the module to be given control at the exit point indicated by nn.

ACTIVESpecifies that the exit is loaded and its initial state is active.

This is the default.

INACTIVESpecifies that the exit is loaded but its initial state is inactive. It remains inactive until activated through an operator command.

PERMACTIVESpecifies that the exit is loaded and its state is permanently active. It cannot be deactivated through the use of the TM EXIT operator command.

DATA(character-string)This keyword allows you to specify a character string that is passed to the exit at exit invocation time.

character-stringA character string up to 255 characters long. If it includes special characters or blanks, it must be enclosed within single apostrophes.

TRACESets the initial status of this exit as being eligible for tracing.

NOTRACESets the initial status of this exit as not being eligible for tracing. This is the default.

Notes:

The same module name can be specified for more than one exit point.

Specifying a TM EXIT statement more than once for the same exit number causes an error.

TM EXIT statement processor enforces the requirement that Job Analyzer exits must come from LPA or a LINKLIST data set.

The TRACE/NOTRACE keywords of the TM EXIT statement determine the eligibility of the exit for tracing. No tracing is actually done unless there is also a TM TRACE initialization statement, or a TM TRACE command is issued. See the description of the TM TRACE statement or the TM TRACE operator command in this topic.

The TRACE/NOTRACE keywords establish the initial status of the exit's trace eligibility. This status can be altered after TMSS is started by using the TM EXIT command.

TM TRACE

Enable/Disable Tracing

This statement activates and deactivates the BMC ThruPut Manager tracing facility. The options described here allow you to trace installation exit activity. The trace facility can also be used to gather data for problem reporting, but these options should only be activated on the explicit instructions of Customer Support, therefore they are not documented here. If there is a need for this capability, Customer Support will provide the specific commands you should use.

ON EXITSRequired keywords to enable tracing of BMC ThruPut Manager installation exits.

Notes:

Tracing for Job Analyzer exits (1 through 9, and 19) goes to the job's SYSMSGS data set.

Tracing for TMSS exits (10 through 18, 30, and 31) goes to GTF; therefore, GTF must be active and the GTF trace options include tracing for USR event number 249.

An installation exit must be made eligible for tracing, either through the TM EXIT statement or the TM EXIT command. See the TM EXIT statement description or the TM EXIT command description in this topic.

If exit tracing is active for an exit when analysis of a job starts, all calls to that exit for that job are traced, even if an operator command disables tracing before the analysis is finished.

If more than one TM TRACE statement is specified for a system, the last statement is effective. A different TM TRACE statement can be applied to each system by using a FOR group.

TM USER

Define User Areas

This statement defines user areas that can be associated with each job. Space is then provided for you to place data. This statement is not accepted within a FOR GROUP.

JOB(nnn)Indicates that you want a user area allocated to each job.

The default value is 100.

nnnRepresents the number of bytes to be allocated. It can be from 1 to 255.

VOLUME(nn)Indicates that you want a user area allocated to each volume that is referenced by a job.

The default value is 12.

nnRepresents the number of bytes to be allocated. It can be from 1 to 99.

Notes:

If you are using the SPOOL File, changing this statement will require a SPOOL cold start.

If more than one TM USER statement is specified, the last one is effective.

Commands

Two commands are provided to help in the installation of exits. These commands are TM EXIT and TM TRACE. They are similar to the TMSS initialization statements TM EXIT and TM TRACE. There is one significant difference:

You cannot introduce a new exit with the TM EXIT operator command. Exits must be defined at TMSS startup time with the TM EXIT statement.

The commands are documented below. They are also documented in the Operating Guide publication.

TM EXIT

Activate or Deactivate Installation Exits

This command activates or deactivates BMC ThruPut Manager installation exits.

Scope: System

Duration: Until next TMSS restart.

? | HELPRequests the command syntax from HELP.

nnExit number. "nn" is 1 or 2 digits and must be a valid BMC ThruPut Manager installation exit number.

ACTIVATEActivates the exit.

The short form for this keyword is A.

DATASpecifies installation data to be passed to the exit at invocation, and can be 1-255 characters. If the data includes special characters or blanks, it must be enclosed in apostrophes('). To represent an apostrophe, code two consecutive apostrophes ('').

DEACTIVATEDeactivates the exit.

The short form of this keyword is DEACT.

DISPLAYDisplays the status of the specified exit.

If no exit number has been specified, the status of all the exits is displayed. This is the default.

The short form of this keyword is D.

NODATASpecifies that no data is to be passed to the exit at invocation. This can be used to remove the effects of a previous DATA keyword.

NOTRACEDisables tracing for this exit.

The short form of this keyword is N.

TRACEEnables tracing for this exit.

The short form of this keyword is T.

Example: /TM EXIT 12 ACTIVATE TRACEThis command activates Exit 12 with tracing.

/TM EXIT 1 DISPLAYThis command produces a display of the status of Exit 1:

DTM0330I TM EXIT DISPLAY
EXIT ---STATUS--- -MODULE- TRACE LEN ------------PARM DATA------------
 1 ACTIVATED(P) DTMUXTST ON 15 012345678901234Notes:

The exit must have been specified during TMSS initialization using the TM EXIT statement.

Those exits which have been marked as permanently active cannot be disabled using this command.

Tracing of exits requires both this command with the TRACE keyword and the TM TRACE command.

TM TRACE | TM T

Activate or Deactivate BMC ThruPut Manager Tracing

This command activates and deactivates the BMC ThruPut Manager tracing facility. The trace facility is provided to allow you to trace installation exit activity. Tracing can also be used to gather data for problem reporting to Customer Support, but these options should only be activated on the explicit recommendation of Customer Support, and therefore are not documented here. If there is a need for this capability, Customer Support will provide the specific commands you should use.

Scope: System

Duration: Until next IPL.

? | HELPRequests the command syntax from HELP.

ADDAdds the specified trace request to the tracing queue for the job name supplied. Tracing is performed only if the Job Analyzer processes a job that has the same job name.

The short form for this keyword is A.

DELETEDeletes the specified trace request from the tracing queue. If no ID is specified, all trace requests are deleted.

DISPLAYDisplay the status of exits. This is the default.

IDENTIFIER(id)Specifies the trace identification value. For an ADD, this identifier is needed if the trace request is to be deleted later.

The short form for this keyword is ID.

idA one to four character trace identification.

JOBNAME(jobname)Indicates that a job is to be traced. Tracing begins when this jobname is processed by the Job Analyzer. This option is effective only for Job Analyzer exits.

jobnameName of the job to be traced.

ONActivates global tracing for all exits and all jobs.

OFFDeactivates tracing.

Examples

/TM TRACE ADD ID(T1) JOBNAME(MYJOB)
/TM TRACE DELETE ID(T1)
/TM TRACE ONJob Analyzer exit tracing can be enabled with either the TM TRACE ADD or the TM TRACE ON command. Using the ADD option allows you to trace specific jobs.

Both the TM TRACE command with the ON keyword and the TM EXIT command with the TRACE keyword must be issued to enable tracing for a specific installation exit.

Tracing for Job Analyzer exits goes to the job's SYSMSGS data set.

GTF must be active to trace TMSS exits. The GTF trace options must include tracing for USR event number 249.