TRACE=option {,option} {,option}
This setting can be specified to cause various types of debugging trace messages to be output during normal A-Shell operation. Unless otherwise noted, TRACE messages are output to the file ashlog.log, typically in the same directory as miame.ini, or as specified by LOGDIR. This file is automatically "rolled over" when it reaches a certain size (generally 3 MB), with several prior versions archived as ashlog.001, ashlog.002, etc. Trace messages written to the log file may also be output to the System Messages Window. Some of the traces output directly to the screen, or as noted in the table below.
Most of these settings can be adjusted with SET.LIT, and all of them can be queried and set using MX_GETTRACE / MX_SETTRACE. Note also that for Windows and ATE, they can be enabled/disabled via the System Messages window mentioned above.
It is recommend that you enable the INOUT, BASERR, and SIGHUP traces by default (e.g. TRACE=INOUT,BASERR,SIGHUP) as they leave a trail of information that is very useful for reviewing system activity and researching errors without creating an excess number of log entries.
The following table shows the options used with the TRACE function. The "Used In" column specifies if the option applies to the TRACE system parameter ("INI") or to the SET TRACE command ("SET").
Option |
Used In |
Description |
|---|---|---|
AMOS |
INI, SET |
Logs information related to the use of XCALL AMOS and operations that involve the launching of another ashell session. |
AMSORT |
INI, SET |
Displays information (in a pop-up window) during sorting operations, showing the type of sort, current phase, memory usage, etc. If sorts are talking a long time, this can be very useful for determining what is happening, and how much memory you might need to improve the performance. (For very large sorts, we also offer an add-on "world class" sort module that is much faster and more flexible, but requires a small license fee; contact us for details.) |
ATE |
INI, SET |
Logs details of the GUI commands and responses sent between a server and an ATE client. Note that this command might make sense to activate on both the server and the client, as they have different perspectives. This will result in two log files, one on the server and on the ATE client.and responses. |
INI, SET |
Logs all ASB errors, indicating if they were trapped or not, along with other details typically lost in the translation between the user experiencing the error and the programming investigating it. Highly recommended for nearly all installations. |
|
CGI |
INI,SET |
Logs details related to XCALL CGIUTL. Also see XCALL and SOCKS traces. |
DEBUG |
SET only |
This is a catch-all for logging all kinds of information. It should only be used in focused circumstances, since the amount of tracing data quickly becomes overwhelming. May also be activated via the –trace switch on the A-Shell command line. |
ERS |
INI only |
same as "EFS." |
EFS |
SET only |
Traces the A-Shell stream (sequential file i/o) wrappers used when the Encrypted File System (EFS) is enabled. Also sometimes "overloaded" to trace specific unrelated operations for debugging purposes, usually on a temporary basis |
INI, SET |
Traces RUN, CHAIN, command line and XCALL AMOS statements. |
|
FOPENS |
INI, SET |
Logs information about file opens (both programs and data). Under Windows, this also includes how many microseconds it takes to open the file, which can sometimes be useful in identifying bottlenecks due to network issues. |
GDIPRT |
INI, SET |
(Windows only) Logs and/or displays information about processing of print directives. |
GUI |
INI, SET |
(Windows only) Logs details about various low-level GUI operations. It is quite verbose. |
INI only |
Writes debugging information to ashlog.log as each new instance of A-Shell is opened or closed, indicating the number of jobs running at that point. Highly recommended for virtually all installations. |
|
ISAM |
INI, SET |
Logs ISAM operations. |
INI, SET |
Causes all unresolved lock/unlock operations on the jobtbl.sys file to be traced in the file jobtbl.lck. |
|
JOBS |
INI only |
Logs details relating to the job table operations (quite verbose). |
KBD |
INI, SET |
Logs keyboard operations (quite verbose). |
LOCKS |
INI, SET |
Displays debugging information on the bottom status of the window related to record locking operations. In particular, it provides a sense of how many retries or how long the job is waiting for access to a record. In the case of FLOCK, it will also display all of the relevant locking parameters whenever the subroutine is forced to wait and whenever it exits with a non-zero error code. |
LP |
INI, SET |
(Possible in INI context, but not recommended.) Displays on the screen details about printing, including processing of any EZSPL configuration file, plus the printer init commands, plus the actual communication or initialization operations with the printer itself. Extremely useful for debugging printing problems. (SET TRACE LP ON, then using PRINT to print a dummy file, like ersatz.ini). |
MALLOC |
INI,SET |
Log details of all memory allocations. |
QOP |
INI |
Logs details relating to queue block operations. |
RW |
INI, SET |
Log all random/isam file reads and writes, INPUT and PRINT file operations, SERCH reads. |
INI, SET |
Log receipt of SIGHUP (hangup) and SIGTERM (kill) signals, along with information indicating how the signal was responded to, whether the program and ashell session were shut down, etc. We recommend you set this switch permanently in miame.ini (TRACE=SIGHUP) since they should be relatively rare and frequently either worth investigating directly, or they provide an explanation for something else you are investigating. |
|
SIGNAL |
INI, SET |
(Unix only) Same as the SIGHUP option, but also displays on the screen the name of any trapped signal received by the process. See Job Terminations for more information relating to handling of incoming signals. |
SOCKS |
INI, SET |
Logs details about TCP (socket) operations, including those embedded in CGIUTL. |
SQL |
INI, SET |
Logs information about SQL operations. |
SYSERR |
INI, SET |
Display (in a pop-up window on screen) details about all errors. This is sometimes useful for see the system error details corresponding to a particular A-Shell error, but can also be annoying since it presents the appearance of a serious error having occurred, sometimes in situations that weren’t really very serious at all. |
USRMEM |
INI, SET |
Log details about "user memory" operations – i.e. loading of programs, subroutines, function key translation files, etc. |
XCALL |
INI, SET |
Logs most subroutine calls. Certain extremely common routines, like MIAMEX, are not logged, unless the XDEBUG trace is also activated. In CGIUTL, creates additional logging in cgiutl.log file. |
XDEBUG |
INI only |
Increases the verbosity of several other traces. |
XTREE |
INI only |
Logs XTREE operations. |
See Also
