Troubleshooting
Problem
Qshell supports multiple levels of tracing to understand the environment in which a command is run and to help debug problems. They are Internal / Utility Trace, "trace" Utility, and Execution Trace. The preferred trace is the Internal / Utility Trace.
Resolving The Problem
Internal / Utility Trace
Output location:
Output from the multiple shell jobs are collected in one trace file. By default, the internal trace is written to the file $HOME/qsh_trace .
Note: A valid home directory is required if the default trace file path is used. If the user profile's home directory does not exist, a "001-0023: Error found opening file" message will occur on the trace operation.
A alternate output file can be specified by setting the TRACEFILE environment variable. For example:
===> ADDENVVAR ENVVAR(TRACEFILE) VALUE('/tmp/qsh_trace') LEVEL(*JOB)
Note: If the variable is added to the *SYS Level, the user profile will need to sign off and then sign back on to pick up the change.
Enabling/disabling:
The internal and utility traces are turned on and off by using ONE of the following 3 options:
1) Use commands to dynamically turn on and turn off the internal trace:
set -t # Turn on
set +t # Turn off
2) Set the environment variable QIBM_ZSH_TRACE_LEVEL=3 before starting the shell. When the shell starts, it determines the value of the QIBM_ZSH_TRACE_LEVEL environment and turns on the trace. This allows you to trace the shell starting and utilities that are run by any of the profile files. To enable the trace, execute:
===> ADDENVVAR ENVVAR(QIBM_ZSH_TRACE_LEVEL) VALUE(3) LEVEL(*JOB)
To disable the trace:
===> RMVENVVAR ENVVAR(QIBM_ZSH_TRACE_LEVEL)
3) Use the STRTRC/ENDTRC CL commands to turn on/off the internal and utility traces. Do not collect this trace unless directed to do so. The disadvantage to this method is you have to run two or more separate traces for the Qshell Interpreter (QZSHSH) and Child Jobs (QP0ZSPW*) since they are not all traced together like the two other methods above. You can turn on and off the traces for the shell interpreter job with the following CL commands:
===> STRTRC SSNID(QSHELL) JOB((*ALL/*ALL/QZSHSH)) JOBTRCTYPE(*TRCTYPE) TRCTYPE((*QSHELL *VERBOSE))
===> STRTRC SSNID(QSHELL2) JOB((*ALL/*ALL/QP0ZSPW*)) JOBTRCTYPE(*TRCTYPE) TRCTYPE((*QSHELL *VERBOSE))
To end:
===> ENDTRC SSNID(QSHELL) DTALIB(QTEMP) PRTTRC(*YES)
===> ENDTRC SSNID(QSHELL2) DTALIB(QTEMP) PRTTRC(*YES)
Example Internal trace output:
- The number in parenthesis is the process ID of the job running the shell.
- The value before the colon is the name of the function.
- The remainder of the line is data for the function.
The information includes control flow, internal data structures, results of expansions, and error data. The following built-in utilities:
attr, catsplf, chgrp, chmod, chown, clrtmp, compress, cp, dataq, datarea, find, file, gencat, getjobid, grep, iconv, ls, mkdir, mkfifo, mv, pax, ps, rexec, rexx, rm, setccsid, sort, system
...also provide internal tracing that prints detailed information to the trace file. The information includes the input parameters and control flow.
"trace" Utility
The shell provides an undocumented trace utility that dumps internal data structures. When QSH takes an unexpected exception, it implicitly runs the trace utility to dump everything to the current trace file. You can also run the trace utility in a running shell session to capture current information.
The trace utility supports the following operands:
alias # dump the internal alias table (shows all currently defined aliases).
command # dump the internal command table (shows cached commands and the node tree for currently defined functions).
descriptor # dump the internal descriptor table (shows all open descriptors).
file # dump the file stack (shows all open script files).
job # dump the internal job table (shows all active jobs).
nls # dump the variant character tables.
redirection # dump the internal redirection table (shows all redirected descriptors).
stack # dump the internal memory stack (shows all allocated stack blocks).
static # dump the values of static variables.
syntax # dump the syntax tables.
trap # dump the internal trap table (shows current signal actions).
variable # dump the internal variable table (shows all currently defined variables).
For example, to dump the active variable table, type the following command:
$ trace variable
Output is added to the QSH $TRACEFILE
Execution Trace:
The execution trace prints each command on stderr after all expansions are completed and just before it is run by the shell. The output is preceded with the expansion of the PS4 variable, which by default is the string +.
The trace is turned on and off with the following commands:
$ set -x # Turn on execution trace
$ set +x # Turn off execution trace
Example output from an execution trace:
> ls $HOME/testdir
+ ls /home/myUsrPrf/testdir
file1.txt file2.txt file3.txt file4.txt
$
> set +x
+ set +x
$
Additional Internal / Utility Trace option for intermittent problems:
If the problem is intermittent, add the below to the start of the QSH script being executed:
now=$(date +"%Y.%m.%d.%H.%M.%S")
export TRACEFILE=/tmp/qsh_trace_$now
set -t
That will generate a new trace for every execution of the script and each trace file name will have a unique time stamp on it.
Change the output directory from /tmp to some other valid directory which the user has write access to.
After an interval with no failures, delete the trace files which failed to capture the failure.
Monitor the growth of the output directory size. The size and count of trace files are dependent on customer application.
Related Information
Document Location
Worldwide
[{"Product":{"code":"SWG60","label":"IBM i"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"Programming (Languages- compilers- tools)","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"Version Independent","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]
Historical Number
322324826
Was this topic helpful?
Document Information
Modified date:
06 March 2023
UID
nas8N1016326