'\" t
.\" Copyright (C), 2012  Dave Love, Liverpool University
.\" You may distribute this file under the terms of the GNU Free
.\" Documentation License.
.TH sge_dl 8 2012-01-18 
.SH NAME
dl \- setting SGE debug tracing information
.SH SYNOPSIS
.B "source $SGE_ROOT/util/dl.sh"
.br
.B dl
.I level
.SH DESCRIPTION
The
.I dl
shell script alias is obtained by sourcing one of the scripts
.I $SGE_ROOT/util/dl.sh
or
.IR $SGE_ROOT/util/dl.csh ,
for Bourne and C shell respectively.  It provides a convenient way to
set up the environment to produce certain SGE debugging
information.  It is mostly useful for maintainers, but may
occasionally be useful to users diagnosing problems.  (In that case it
probably indicates a need for extra user-level messages logged in the
spool area or elsewhere, which should be improved.)
.PP
The
.I level
argument specifies the printing of debugging output by the
SGE components as described below, or 0 to turn off
debugging output and reset the other environment variables concerned.
When tracing is on, output goes to the stderr stream.
.B dl
also sets (or, with argument 0, resets) the
.B SGE_ND
environment variable to make daemon programs run in the foreground
rather than actually daemonizing, and also
.BR SGE_ENABLE_COREDUMP ,
which enables core dumps from daemons which change user or group.  The
trace output is most often used for debugging daemons; some is
available from client programs but is typically less useful.
.SS "Debugging levels"
Debugging is specified in terms of "layers", describing particular
components of the system, such as libraries, indexed by a number:
.IP "TOP (0)"
General information;
.IP "CULL (1)"
List-processing (not used consistently);
.IP "BASIS (2)"
Apparently intended for low-level routines, such as string processing,
but used quite generally;
.IP "GUI (3)"
Operations in the
.I qmon
graphical client;
.IP "GDI (6)"
Grid Engine Database Interface for dealing with "objects" maintained
by the qmaster process;
.IP "PACK (7)"
Packing and unpacking network data.
.PP
The other indices are unused.
.PP
There are also different "classes" which determine the type/amount of
information printed, again indexed by a number:
.IP "TRACE (1)"
Tracing function enter/exit (generated by DENTER, DEXIT etc. macros);
.IP "INFOPRINT (2)"
General information (generated by DPRINTF);
.IP "TIMING (16)"
Time taken by execd to start a job;
.IP "LOCK (32)"
Locking/mutex information.
.PP
Other classes are defined, but currently unused.  For those and unused
layers, see the source file
.IR libs/uti/sge_rmon_monitoring_level.h .
.PP
The layers and classes are combined into a number of different
"levels" which may be used as the argument of
.B dl
to select the output layers and classes, as follows:
.TS
tab(@),box;
l|l|l.
Level @ Layer(s) @ Class(es)
_
0 @ \-                         @ turn off all
1 @ TOP                        @ INFOPRINT
2 @ TOP                        @ TRACE + INFOPRINT
3 @ TOP + CULL + GDI           @ INFOPRINT
4 @ TOP + CULL + GDI           @ TRACE + INFOPRINT
5 @ TOP + GUI + GDI            @ INFOPRINT
6 @ TOP + CULL + BASIS + GDI   @ LOCK
9 @ TOP + CULL + BASIS         @ INFOPRINT
10 @ TOP + CULL + BASIS + PACK @ TRACE + INFOPRINT
.TE
.PP
with other levels unused.  10 is not usually interesting.
.SH FILES
.IR $SGE_ROOT/util/dl.sh , $SGE_ROOT/util/dl.csh
.SH "ENVIRONMENT VARIABLES"
SGE_DEBUG_LEVEL, SGE_ND, and SGE_ENABLE_COREDUMP, as above