Reference Guide › Command Reference › TRACE Command

TRACE Command

Use the TRACE command to trace macro execution.

TRACE {"Parms"}

Parms:

  MACRO "Macroparms"
| LIST [userid [macname]]
| STOP {tracenumber | * | [USER] userid}
| CLOSE {tracenumber | * | [USER] userid}

Macroparms:

[macname | *]
[LINES first last]
[OPT option]
[USER userid]
[TO destuser]
[TYPE | MSG | PRINT]

Definitions

LIST [userid [macname]]

Lists all active traces and their trace number for the specified user IDs and macros. Both userid and macname can contain the pattern matching characters % and *. The default value for userid is the issuing user ID and the default for macname is all macros.

MACRO

Indicates that the command is to trace the specified macros. A trace number is generated from this parameter which you can use later to stop tracing.

[macname]

Specifies the filename of the executable macros to trace. The macro name can contain the pattern matching characters % and *. The default is all macros. You must specify the macname parameter if you use any of the subsequent parameters.

[LINES first last]

Indicate the numbers of the first line and the last line of the range of macro lines to trace. The default for first is 0 and the default for last is the last line of the macro.

[OPT option]

Specifies the amount of information the command is to include in the trace messages. If the macros are written in EXEC2, you can use one of the following options:

• ALL
• ERR
• OFF
• ON

If the macros are written in REXX, you can use one of the following options:

• A
• C
• ERR
• I
• N
• OFF
• R
• ALL
• E
• ERROR
• L
• O
• ON

[USER userid]

Specifies that the command is to trace the indicated macros when run by this userid; userid can contain the pattern matching characters * and %. The default is your user ID.

[TO destuser]

Specifies the user ID to receive trace messages. The default is the user ID specified on the USER parameter. Specifying a destuser value of ‘*’ sends the messages or print file to the CA VM:Director product server.

[TYPE | MSG | PRINT]

Indicates where to send the trace messages:

• TYPE sends the messages to the terminal of the TO user ID; when the TO user ID and the USER user ID are the same, TYPE is the default. When the user ID specified on the TO parameter is different than the user ID specified on the USER parameter, CA VM:Director changes the TYPE parameter to MSG
• MSG sends the messages using CP MSGNOH or MSG to the terminal of the TO user ID; when the TO user ID and the USER user ID are different, MSG is the default
• PRINT sends the messages in a printer spool file to the virtual reader of the TO user ID

STOP {tracenumber | * | [USER] userid}

Cancels the specified active trace. The tracenumber is the number CA VM:Director assigns to each trace; you can use the LIST parameter to determine this number. The * cancels all traces currently defined on the system. The USER userid parameter cancels all traces that apply to the specified user ID. The USER keyword is required only if the user ID is all numeric.

CLOSE {tracenumber | * | [USER] userid}

Closes a printer spool file for the specified active trace, but tracing continues. Use the CLOSE parameter only to close traces that were started with the PRINT parameter. The tracenumber is the number CA VM:Director assigns to each trace; use the LIST parameter to determine this number. The * cancels all traces currently defined on the system. The USER userid parameter cancels all traces that apply to the specified user ID. The USER keyword is required only if the user ID is all numeric.

Description

Traces remain active until stopped using the TRACE STOP command. If messages are going to a printer spool file, you can close the file and start a new spool file by using the TRACE CLOSE command. If these is more than one trace defined for a userid / macroname combination, CA VM:Director uses only the first trace definition against the macro.

Each TRACE command that specifies the PRINT parameter uses a new virtual printer device on the service virtual machine. CA VM:Director imposes a maximum of 240 virtual printers in the address range of 0010 ‑ 00FF for use with trace output going to spooled printer files. If this limit is reached and a virtual printer cannot be defined, the TRACE command waits until a virtual printer is made available.

If a macro to be traced is run from the CA VM:Director service virtual machine, the TRACE command ignores the LINES, USER, and TO parameters, and types the trace messages to the service virtual machine console.

If a macro you are tracing calls a user exit written as an EXEC, the TRACE command will not trace the user exit. You can trace user exits only by inserting the appropriate trace function in the user exit itself. User exit trace output always goes to the service virtual machine console.

Note: (CA VM:Secure only) Tracing a macro’s execution reveals passwords being checked or set. However, if the CA VM:Secure Password Encryption Facility is being used, only the encrypted passwords are revealed.

Example

User ID MAINT wants to trace the CHGMDISK command every time it is used by user ID MARY. Enter:

vmdirect trace macro chgmdisk user mary to maint print

Each time MARY issues the CHGMDISK command, CA VM:Director sends the trace messages to a new spool file in MAINT’s reader queue.