Data Manipulation Language Statements › #TRNSTAT

#TRNSTAT

The #TRNSTAT statement enables your program to access transaction statistics about task-related activities. The system allocates a block of storage, called a transaction statistics block (TSB), in which to accumulate these statistics.

Three versions of the #TRNSTAT statement collect and write transaction statistics:

• #TRNSTAT TYPE=BIND starts recording transaction statistics for the requestor's logical terminal.
• #TRNSTAT TYPE=ACCEPT copies transaction statistics from the TSB and places them in a storage area associated with the issuing task and/or writes them to the DC/UCF log file.
• #TRNSTAT TYPE=END stops collecting transaction statistics for the requestor's logical terminal and optionally writes the statistics to a storage area associated with the issuing task and/or to the DC/UCF log file.

Note: Do not attempt to collect transaction statistics using the #TRNSTAT statement if your Assembler program is a subroutine to a CA ADS dialog.

For more information about the transaction statistics block (TSB), see the DSECT Reference Guide.

Syntax

►►────#TRNSTAT TYPE=──┬─BIND────────────────────────────────────────────┬─────►
                      ├ ACCEPT ─────┬───(388)──────────────────────┬────┤
                      │             └ LENgth= ─── parm-value ──────┘    │
                      └ END     ────┬───(388)──────────────────────┬────┘
                                    └ LENgth= ─── parm-value ──────┘

 ►─────PLIST= ──┬─(SYSPLIST)──────────────┬───────────────────────────────────►
                └ parm-value-list-pointer ┘

 ►─┬────────────────────────────────┬─────────────────────────────────────────►
   └─ ,RECORD=record-name-register ─┘
 ►─┬────────────────────────────────┬─────────────────────────────────────────►
   └─ ,ID=identifier-name-register ─┘

 ►─┬─────────────────────┬────────────────────────────────────────────────────►
   └─ ,TASK= ─┬─ YES ◄ ─┬┘
              └─ NO ────┘
 ►─┬──────────────────────┬───────────────────────────────────────────────────►
   └─ ,WRITE= ─┬─ YES ◄ ─┬┘
               └─ NO ────┘

 ►─┬─────────────────────────────────┬────────────────────────────────────────►
   └─ ,COND= ─┬── NO ◄ ────────────┬─┘
              ├── ALL ─────────────┤
              │   ┌──── , ─────┐   │
              └─(─▼─┬─ DEAD ─┬─┴─)─┘
                    ├─ SBNF ─┤
                    ├─ INVP ─┤
                    └─ NOTR ─┘

 ►──┬───────────────────────────┬─────────────────────────────────────────────►
    └─ ,DEADXIT=deadlock-label ─┘
 ►──┬─────────────────────────────────────────────┬───────────────────────────►
    └─ ,SBNFXIT=statistics-block-not-found-label ─┘

 ►──┬─────────────────────────────────────────┬───────────────────────────────►
    └─ ,INVPXIT=invalid-parameter-list-label ─┘

 ►──┬────────────────────────────────────────────────────┬────────────────────►
    └─ ,NOTRXIT=no-transaction-statistics-allowed-label ─┘

 ►──┬──────────────────────┬──────────────────────────────────────────────────►◄
    └─ ,ERROR=error-label ─┘

Parameters

TYPE=

Specifies the type of transaction statistics activity.

BIND

Defines the beginning of a transaction for the purposes of collecting transaction statistics. The system allocates a block of storage to collect these statistics. Because this block is owned by the logical terminal associated with the current task, the #TRNSTAT=BIND can only be used with terminal tasks.

Note: If a terminal statistics block (TSB) is already allocated for the logical terminal associated with the current task, the BIND request writes any existing statistics to the log and clears the TSB for new statistics.

When a #TRNSTAT TYPE=BIND request is issued, the system assigns the transaction a 40-character identifier. The first 32 characters are the identifier of the signed-on user, if any. The last 8 characters are the identifier of the logical terminal associated with the current task.

ACCEPT

Requests that the system return the contents of the TSB to a preallocated location in program storage and/or write the block to the DC/UCF log file by the WRITE option described below. The system does not delete the contents of the TSB as a result of the ACCEPT option; transaction statistics can accumulate between #TRNSTAT statements where the ACCEPT option is specified. To prevent the program from altering the contents of the TSB and to ensure integrity of the data, the system returns a copy of the TSB to the program.

LENGTH (parm-value)

Specifies the length of the TSB to be returned. Can be specified as a value, register or storage area.

Default: 388

END

Ends the transaction and frees the TSB. The system ends the transaction when the task issuing the #TRNSTAT TYPE=END request terminates. Optionally, END can write the TSB to a preallocated location in program storage by using the RECORD option described below. To prevent the program from altering the contents of the TSB and to ensure integrity of the data, the system returns a copy of the TSB to the program.

LENGTH (parm-value)

Specifies the length of the TSB to be returned. Can be specified as a value, register or storage area.

Default: 388

PLIST (parm-value-list-pointer)

Specifies the location of the storage area where he system builds the #TRNSTAT parameter list.

RECORD=

(#TRNSTAT TYPE=ACCEPT or END requests only); specifies the location of the storage area into which the system places the TSB.

record-name-register

A register that contains the location of the area, the symbolic name of the area, or an absolute expression.

ID=

(for #TRNSTAT TYPE=BIND requests only) Specifies the location of a storage area that contains an 8-byte identifier to be placed in the Transaction Statistics Block.

identifier-name-register

Specifies a register that contains the location of the identifier, a symbolic name of the identifier's location, or an absolute expression.

TASK=

(for #TRNSTAT TYPE=BIND or END requests only) Specifies the action that is taken relative to the current task.

YES

(Default)

(for #TRNSTAT TYPE=BIND requests only) Specifies that the collection of statistics starts at the beginning of the current task.

(for #TRNSTAT TYPE=END requests only) Specifies that if statistics are being written to the DC/UCF log file, they are written at the end of the current task.

NO

(for #TRNSTAT TYPE=BIND requests only) Specifies that the collection of statistics starts at the time of the execution of the #TRNSTAT macro.

(for #TRNSTAT TYPE=END requests only) Specifies that if statistics are being written to the DC/UCF log file, they are written immediately.

WRITE=

(for #TRNSTAT TYPE=ACCEPT or END requests only) Specifies that the system writes the contents of the TSB to the DC/UCF log file.

YES

(Default) Specifies that the system writes the TSB to the log file.

NO

Specifies that the system does not write the TSB to the log file.

COND=

Specifies whether the #TRNSTAT request is conditional and under what error conditions control should be returned to the issuing program.

NO

(Default); specifies that the request is not conditional.

ALL

Specifies that control is returned to your program if the #TRNSTAT request cannot be serviced for any of the reasons described under condition.

condition

Specifies one or more conditions under which the system returns control to the issuing program. Multiple conditions must be enclosed in parentheses

and separated by commas. The following options can be specified:

• DEAD (TYPE=BIND only) specifies that storage for the TSB is not available; waiting would cause a deadlock.
• SBNF specifies that a TSB for the user terminal cannot be found for a #TRNSTAT TYPE=ACCEPT or END request. This condition is probably due to a #TRNSTAT BIND not having been issued.
• INVP specifies that the requested task is not associated with a logical terminal or that the request is invalid.
• NOTR specifies that transaction statistics or task statistics are not enabled in the DC/UCF system.

DEADXIT=deadlock-label

Specifies the symbolic name of a routine to which the system returns control if storage for the TSB is not available, and waiting would cause a deadlock.

SBNFXIT=statistics-block-not-found-label

Specifies the symbolic name of a routine to which the system returns control if a TSB for the terminal cannot be found for a #TRNSTAT TYPE=ACCEPT or END request.

INVPXIT=invalid-parameter-list-label

Specifies the symbolic name of the routine to which the system returns control when the requested task is not associated with a logical terminal or when the request is invalid.

NOTRXIT=no-transaction-statistics-allowed-label

Specifies the symbolic name of a routine to which the system returns control when transaction statistics or task statistics are not enabled in the DC/UCF system.

ERROR=error-label

Specifies the symbolic name of a routine to which the system returns control if a condition specified in the COND parameter occurs for which no other exit routine was coded.

Example

The #TRNSTAT statement shown below requests that the system return the contents of the TSB to TSBAREA in program variable storage and to write the block to the DC/UCF log file. Control is returned to the program if this request would result in a deadlock or if the TSB cannot be found.

#TRNSTAT TYPE=ACCEPT,RECORD=TSBAREA,WRITE=YES,COND=(SBNF,DEAD)

Status Codes

By default, the #TRNSTAT statement is unconditional; any runtime error will result in an abend of the issuing task.

After completion of the #TRNSTAT request, the value in register 15 indicates the outcome of the operation. The following is a list of Register 15 values and the corresponding meaning:

X'00'

The request has been serviced successfully. For TYPE=BIND only, an existing TSB has been written to the DC/UCF log.

X'04'

The request has been serviced; a new TSB has been allocated (TYPE=BIND only).

X'08'

Storage for the TSB is not available and waiting would cause a deadlock (TYPE=BIND only).

X'0C'

No TSB exists; a #TRNSTAT TYPE=BIND request has not been issued (TYPE=ACCEPT or END only).

X'10'

The task issuing the #TRNSTAT request is not associated with a logical terminal or the request is invalid.

X'14'

The collection of task statistics or transaction statistics was not enabled during system generation.