Running traces

This information describes how to run a trace of a transform. The service representative in the IBM® Support Center might ask you to run a trace to aid in diagnosing a problem. If so, the representative will tell you how and where to send the trace information. You do not have to interpret the trace. Send it to your service representative.

Tracing can slow performance considerably. Turn tracing on for only as long as necessary to capture the error.

Tip: For some error conditions, the PCL to AFP transform writes more detailed error messages to the transform's stderr file when tracing is turned on. If you have trouble diagnosing a problem, you can turn tracing on and look for more messages in the stderr file.

To trace transforms, you can either specify the -T transform option or set the AOPTRACEON environment variable:

Specify the -T option to trace a specific transform request, or to trace all transform requests for a specific printer.
Set the AOPTRACEON environment variable to trace all transform requests, or to trace all transforms that use a transform class that you configure for tracing.

You can specify the -T option in these ways:

On the pcl2afp, pdf2afp, ps2afp, or sap2afp command.
In the filter-options job attribute on a print command. By using the lp command, the Infoprint Port Monitor for Windows, and some other print commands you can specify Infoprint Server job attributes.
In the Filter options field in a printer definition in the Printer Inventory.

When you request a trace by using either the -T option or the AOPTRACEON environment variable, the transform writes the trace in a file in the directory that is specified in the AOPTRACEDIR environment variable or to the default directory (/var/Printsrv/trace or /var/Printsrv/xfd). One trace file can contain trace information for multiple print jobs because each instance of a transform appends trace information to the same trace file. The transform's stderr file contains either the name of the trace file or the trace information itself.

These environment variables in the Infoprint Server transform configuration file, aopxfd.conf, turn tracing on and specify where the trace is written:

AOPTRACEON

Set this variable to any value to turn on tracing. The transform traces all transform requests that use this transform class. Any value turns on tracing. To turn tracing off, do not specify this environment variable.

Default: Tracing is turned off.

Example:

environment = {AOPTRACEON ->
1}

AOPTRACEDIR

Specify the full path name of the directory where the transform writes trace information. You can specify the same directory for different transform classes. The name of the trace file identifies the transform and transform class, and contains a time stamp.

This directory must exist. If the directory does not exist, the transform writes trace information to the transform's stderr file. For information about how to find the stderr file, see Finding the transform stderr file.

Defaults:

sap2afp and pcl2afp transforms

AOPTRACEDIR -> /var/Printsrv/trace

pdf2afp and ps2afp transforms

When AOPTRACEON is turned on or when the permissions of /var/Printsrv/trace are drwxrwxrwx or drwxrwx-wx, AOPTRACEDIR -> /var/Printsrv/trace
Otherwise, AOPTRACEDIR -> /var/Printsrv/xfd

When trace information is written to /var/Printsrv/xfd:

The trace information is appended to the ps2afp.#.stderr file for each instance of the transform. The stderr file is automatically cleaned up when you restart Infoprint Server Transform Manager.
RACF® message ICH408I is written to the log. You can ignore it.

Examples:

environment = {AOPTRACEDIR -> /var/Printsrv/xfd}
environment = {AOPTRACEDIR -> .}

For an example of a transform entry in the transform configuration file that specifies these variables, see Trace the transform.

Tip: Specifying AOPTRACEDIR -> . has these benefits and limitations:

The trace is recorded in the transform's working directory, for example, /var/Printsrv/ps2afp.0.d. This location keeps the trace closely associated with any other items that might be produced when the job runs (for example, a memory dump). The transform's working directory is a secure location, which protects any sensitive information trace might contain.
The trace is automatically cleaned up when you restart the Infoprint Server Transform Manager.
However, when you restart the Infoprint Server Transform Manager, the transform's working directory and its contents are deleted. Be sure to look in all the active transform directories to find the trace that you are interested in.

Examples:

To request a trace by specifying the -T option on a transform command:
```
pdf2afp -o outputfile -T myfile.pdf
```
To request a trace by specifying the -T option on a transform command when you use the AOPBATCH program:
```
//AOPBATCH JOB  ...
//TRANSFRM EXEC PGM=AOPBATCH,PARM='/ps2afp -T -o //DD:OUTPUT DD:INPUT'
//INPUT    DD   DSN=HLQ.INPUT.PS,DISP=SHR
//OUTPUT   DD   DSN=HLQ.OUTPUT.AFP,DISP=(NEW,CATLG,DELETE),
// DCB=(RECFM=VBM,LRECL=32756,BLKSIZE=32760),SPACE=(CYL,(1,1))
//STDOUT   DD   SYSOUT=*
//STDERR   DD   SYSOUT=*
```
Note: To continue the PARM parameter:
- Extend the parameter to column 71. Do not code an apostrophe in column 71.
- Code // in columns 1 and 2 of the following statement.
- Continue the parameter in column 16 of the following statement even if doing this splits the parameter.
To request a trace by specifying the -T option on an lp command:
```
lp -d myprinter -o "filter-options='-T'" myfile.pdf
```

To request a trace by specifying the -T option in a printer definition:

                                                                    
                                  Processing                         
                                                                    
 Supported data formats and associated filters:                      
 Data format:  Filter:                                                
 / PostScript  ps2afp.dll %filter-options  -T_________________ (extend)
 / PCL         pcl2afp.dll %filter-options -T_________________ (extend)
 / PDF         pdf2afpdll %filter-options  -T_________________ (extend)
 / SAP         sap2afpdll %filter-options  -T_________________ (extend)

To submit a transform request to a transform class that specifies the AOPTRACEON environment variable. If the administrator defined a transform class that is called trace in the Infoprint Server transform configuration file (aopxfd.conf), use these commands to submit a trace request to it.
```
pdf2afp -c trace -o myfile.afp myfile.pdf
lp -o "filter-options='-c trace'" -d myprinter myfile.pdf
```