UNIFACE TRACE FACILITY
The Uniface
Trace Facility extends the Uniface product with trace facilities and enhances
the existing code that makes up the product to use the trace facilities to
generate trace output..
Trace statements
are categorised in groups and levels, so that specific parts of the software
may be traced, to varying degrees of detail. Categories may be specific
sub-products (e.g. a database driver) or functional groups (e.g. memory
allocation). Levels provide a distinction between high-level events and the
more obscure.
With every trace
statement, the tracing module will generate extra info regarding the category
and level of the particular trace call, date and time, call number, etc. It is
possible to selectively switch on and off each specific type of information.
Support members
have the following assignment-file or command-line parameters at their disposal
to activate the tracing facilities (note: the settings are order-dependent and
have an immediate effect on the state of the tracing system). When specified on
the command line, the '$' must be omitted.
$trc_type=deferred[=N]
| cached | direct
Optional
Determines the type of I/O for trace-writes. When
'cached' or 'direct', a trace statement will write its output to a file; in
case 'direct' is specified, output is flushed directly to disk whenever written
to the file. When 'deferred', output will be held in an internal buffer until
it is full (N is the size in Kb, default is 10); only then a file is opened and
the data is written to disk. This is useful in cases where a program (e.g. a
PSV) is not able to open file handles until certain conditions are met. Until
then, trace statements may still do their job.
Default is 'cached'.
Optional
A level specification contains both level and
category specification. The Level may be 0 (none), 1 (very general), 5
(moderate) or 9 (all details). The category specification indicates the
category/ies for which the level applies. Examples:
(Assume the Motif driver is identified by 'M', the
C-ISAM driver by 'c', and other parts by letters ranging from 'a'..'z' and
'A'..'Z')
$trc_levels=1c
Only C-ISAM-specific trace statements will generate
output, on the highest, most general level.
$trc_levels=9c
All C-ISAM-specific trace statements will generate
output, all details are visible.
$trc_levels=9c1M
All C-ISAM details and only the most general Motif
trace calls.
$trc_levels=9cM
All C-ISAM details plus all Motif details: the level
carries over to the next letter (category).
$trc_levels=9A-Za-z5M0c
Enable A..Z and a..z with level 9, but Motif on
level 5 and C-ISAM none.
Default level = 9.
Optional
Determines the extra information that is written to
the trace file for every trace statement. Available types of information:
num The
number of calls so far to the trace facility
prg Program
name
pid Program
id
cat Category
of this trace statement
lvl Level
on which this trace statement is issued
dtm Date/time
number in seconds from 1970 (Local time)
all All
of the options above
Default is 'cat,num'.
Mandatory when tracing is to be enabled.
Starts tracing immediately. If no file name is
specified or the file cannot be opened, output goes to stderr. Warning: when
output is to be deferred, then specify that first! When $trc_type is specified
after trc_start, a file or stderr may already be opened, which may be very
undesirable (e.g. initial phase of PSV startup).
The list of
trace categories and areas included in the next section already shows a number
of areas where we have reserved categories for.
Trace categories ordered by category
This section
contains the areas were tracing is or will be implemented ordered by their
category. In the next section a list is included were the ordering is done on
trace area.
Category:
Trace area:
a ORA
b DB3
c
CIS
d RMS/RMJ
e RDB
f INS
g INF
h SYB
i reserved for ALB
j reserved for TUR
k reserved for KSM
l CTR
m DB2
n reserved for IMS
o reserved for VSM
p TXT
q SEQ
r reserved for NMP
s reserved for TCP
t reserved for DNT
u reserved for SNA
v reserved for future use by generic
driver code
w reserved for future use by drivers of
Compuware/Uniface
strategic partners.
x
y
z
A reserved for Workbenches Product
Centre: Model synchroniser
B AME
C DDE
D reserved
E
F reserved for message frame output.
G reserved for Desktop Product Centre,
Windows: Operating System Interface.
H reserved for Desktop PC, Windows: UPI
calls.
I reserved for Desktop PC, Windows: OWI
calls.
J reserved for Desktop PC, Windows:
Miscellaneous
K
L
M reserved for Desktop PC, Motif.
N
O UODBC.
P
Generic Network Utilities.
Q Characterset conversions.
R PolyServer Protocol.
S reserved for Desktop PC, Macintosh.
T
U
V
W
X
Y
Z
Trace categories ordered by trace area
Area: Category:
Description:
AME
B Application Model
Editor
CIS
c C-ISAM
CTR
l C-tree
DB2
m DB2
DB3
b DB3
DDE
C Dynamic Data Exchange
INF
g Informix
INS
f Ingres
ORA
a Oracle
RDB
e Rdb
RMJ
d RMS with journaling.
RMS
d RMS
SEQ
q SEQ
SYB
h Sybase
TXT
p TXT
Below the list of implemented traces is included.
Every possible trace is listed in the following way:
XXX_Y_ZZZZZZ The trace identifier.
Level: The trace level: range 1-9
Where: The
position in the code
Syntax:
The syntax of a trace is
(usually) the trace identifier followed by a message. This message maybe just a
single piece of text but may also contain variables or parameters. These
parameters are indicated as %p followed by a sequence number so we refer to
them in the explanation.
Example:
To get an idea on how the
trace may look, an example can be included: this shows how parameters in the
trace syntax are replaced by their actual values.
What: Explanation of trace.
Trace area:
Mnemonic: Category:
The part of the code
generating the trace, multiple areas allowed.
NOTES:
1.
Traces
generated by drivers are included in the list with trace identifiers as
starting with ‘XXX’. When they are actually generated, the ‘XXX’ is replaced by
the driver mnemonic. This means that for example the ‘XXX_E_CALLHE’ trace that
is implemented for trace areas ‘RMJ’ and ‘RMS’ may be found in the trace output
like ‘RMJ_E_CALLHE’ and ‘RMS_E_CALLHE’.
2.
Some of the
traces listed in the next section may not contain information for certain parts
of the trace description. This information will be provided in future versions
of this document. They will, however, always have values for the trace
identifier, the level, the syntax and the trace area.
MSW_I_3GLASP
Level: 9
Where:
Syntax: MSW_I_3GLASP Command to
spawn AME is %p1
Example:
What:
Trace area:
Mnemonic:
AME Category: B
MSW_I_3GLCBC
Level: 9
Where:
Syntax: MSW_I_3GLCBC
Constructing bitmapcache
Example:
What:
Trace area:
Mnemonic:
AME Category: B
MSW_I_3GLDBC
Level: 9
Where:
Syntax: MSW_I_3GLDBC
Destructing bitmapcache
Example:
What:
Trace area:
Mnemonic:
AME Category: B
MSW_I_3GLFIL
Level: 9
Where:
Syntax: MSW_I_3GLFIL Filtering
out: %p1
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_3GLSTA
Level: 9
Where:
Syntax: MSW_I_3GLSTA Starting
the AME
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLCMP
Level: 9
Where:
Syntax: MSW_I_4GLCMP
UCOMPOMEDIAGRAM()
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLFOC
Level: 9
Where:
Syntax: MSW_I_4GLFOC
UTAKEFOCUS()
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLPRP
Level: 9
Where:
Syntax: MSW_I_4GLPRP
UPREPOMEDIAGRAM()
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLRES
Level: 9
Where:
Syntax: MSW_I_4GLRES Restarting
the AME
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLSAV
Level: 9
Where:
Syntax: MSW_I_4GLSAV
USAVEOMEDIAGRAM()
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLSET
Level: 9
Where:
Syntax: MSW_I_4GLSET
USETOMEPARAM Field: %p1 Form: %p2
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLSIT
Level: 9
Where:
Syntax: MSW_I_4GLSIT
USETOMEITEM() Item: %p1 Data: %p2
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_4GLSTO
Level: 9
Where:
Syntax: MSW_I_4GLSTO Stopping
the AME
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_7GLACT
Level: 9
Where:
Syntax: MSW_I_7GLACT
UOMEACTIVE() says: %p1
Example:
What: Traces the activity of the AME: (%p1) can
be either "yes" or "no"
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_I_DDCADD
Level: 9
Where:
Syntax: MSW_I_DDCADD Receiving
new data from advise. Item: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDCADS
Level: 9
Where:
Syntax: MSW_I_DDCADS Starting a
request transaction
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDCADT
Level: 9
Where:
Syntax: MSW_I_DDCADT Stopping
an advise transaction
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDCEXE
Level: 9
Where:
Syntax: MSW_I_DDCEXE Starting
an execute transaction
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDCPOK
Level: 9
Where:
Syntax: MSW_I_DDCPOK Starting a
poke transaction
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDCREQ
Level: 9
Where:
Syntax: MSW_I_DDCREQ Starting a
request transaction
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSADS
Level: 9
Where:
Syntax: MSW_I_DDSADS Request to
start an advise. Topic: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSADT
Level: 9
Where:
Syntax: MSW_I_DDSADT Request to
stop an advise. Topic: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSCON
Level: 9
Where:
Syntax: MSW_I_DDSCON Request
for conversation. Topic: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSDIS
Level: 9
Where:
Syntax: MSW_I_DDSDIS Client is
disconnecting
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSEXE
Level: 9
Where:
Syntax: MSW_I_DDSEXE Processing
an execute transaction. Command: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSPOK
Level: 9
Where:
Syntax: MSW_I_DDSPOK Processing
a poke transaction. Topic: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_I_DDSREQ
Level: 9
Where:
Syntax: MSW_I_DDSREQ Processing
an (advise) request. Topic: %p1
Example:
What:
Trace area:
Mnemonic:
DDE Category: C
--------------------------------------------------------------------------------
MSW_W_3GLMAM
Level: 6
Where:
Syntax: MSW_W_3GLMAM Warning:
the AME is still active
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
MSW_W_3GLSON
Level: 6
Where:
Syntax: MSW_W_3GLSON Warning:
the AME is not active
Example:
What:
Trace area:
Mnemonic:
AME Category: B
--------------------------------------------------------------------------------
XXX_E_CALIER
Level: 1
Where:
Syntax: XXX_E_CALIER %p1%p2
Call to "%p3" returned %p4
Example:
What:
Trace area:
Mnemonic: CIS Category: c
CTR l
ORA a
--------------------------------------------------------------------------------
XXX_E_CALLHE
Level: 1
Where: After the API call that returned the
error.
Syntax: XXX_E_CALLHE %p1%p2
Call to "%p3" returned %p4 (hex)
Example: RMS_E_CALLHE S0 Call to
"sys$get" returned 1827 (hex)
What: The (long) error (%p4) returned by a call
to an API function
(%p3) by driver function (%p1) in mode (%p2). The error is
displayed in hex format.
Trace area:
Mnemonic: RMJ Category: d
RMS d
--------------------------------------------------------------------------------
XXX_E_SQLERR
Level: 1
Where: After a SQL-statement that caused an
error.
Syntax: XXX_E_SQLERR %p1%p2
Error %p3 during %p4 of %p5
Example:
What: The error (%p3) returned by the action
indicated by (%p4) on
(%p5).
Syntax: XXX_E_SQLERR %p1%p2
Error %p3 during %p4 of cur. %p5
Example:
What:
Syntax: XXX_E_SQLERR %p1%p2
Error %p3 during %p4
Example:
What:
Syntax: XXX_E_SQLERR %p1%p2
Error %p3 during decl. cur. %p4 of %p5
Example:
What:
Syntax: XXX_E_SQLERR %p1%p2
Error %p3 during prep. (id=%p4) of %p5
Example: RDB_E_SQLERR Q2 Error
42000 during prep. (id=0) of select * from
t.test
What: The error (%p3) returned by the
preparation of statement (%p5).
(%p4) holds the statement id from a possible earlier preparation.
Trace area:
Mnemonic: INS Category: f
RDB e
--------------------------------------------------------------------------------
XXX_I_CALLHS
Level: 9
Where: After the API call that returned
successful.
Syntax: XXX_I_CALLHS %p1%p2
Successful call to "%p3" returned %p4 (hex)
Example: RMS_I_CALLHS F1
Successful call to "sys$get" returned 10001 (hex)
What: The (long) return value (%p4) from the
call to an API function
(%p3) by driver function (%p1) in mode (%p2). The return value is
displayed in hex format.
Trace area:
Mnemonic: RMJ Category: d
RMS d
--------------------------------------------------------------------------------
XXX_I_DBDRV
Level: 1
Where: Right after the driver entrypoint.
Syntax: XXX_I_DBDRV %p1%p2 Path=%p3 entity=%p4
Example: RMS_I_DBDRV S0 Path=1 entity=UFORM.RMS
What: The indication that the database driver
is invoked with function
(%p1), mode (%p2), path (%p3) and entity (%p4). The entity is
only valid when the function is not equal to logon, logoff,
commit, rollback, info, message or SQL.
Trace area:
Mnemonic: CIS Category: c
CTR l
DB2 m
DB3 b
INF g
INS f
ORA a
RDB e
RMJ d
RMS d
SEQ q
SYB h
TXT p
--------------------------------------------------------------------------------
XXX_I_DBHRTN
Level: 2
Where: Just before the final return in the driver
and before the
XXX_I_EDBDRV trace.
Syntax: XXX_I_DBHRTN %p1%p2
Drv. returns %p3 (hex) in udrverr
Example: RMS_I_DBHRTN W0 Drv.
returns 184ec (hex) in udrverr
What: The database or driver error in hex (%p3)
that is returned by the
driver after function (%p1) and mode (%p2).
Trace area:
Mnemonic:
RMS Category: d
--------------------------------------------------------------------------------
XXX_I_DBRTN
Level: 2
Where: Just before the final return in the driver
and before the
XXX_I_EDBDRV trace.
Syntax: XXX_I_DBRTN %p1%p2 Drv. returns %p3 in udrverr
Example: TXT_I_DBRTN Z0 Drv. returns 0 in udrverr
What: The database or driver error (%p3) that
is being returned by the
driver after function (%p1) and mode (%p2). Note that (%p3) may
also be zero after a successful completion of the driver function.
Trace area:
Mnemonic: CIS Category: c
CTR l
INF g
INS f
ORA a
RDB e
SEQ q
SYB h
TXT p
--------------------------------------------------------------------------------
XXX_I_DRVPAR
Level: 1
Where: In the code that reads the driver
parameter string. Typically
this will be the first 'Info-call'.
Syntax: XXX_I_DRVPAR %p1%p2
Drv. param %p3
Example: RDB_I_DRVPAR I0 Drv.
param dual channels, read committed
What: The parameter string (%p3) as read by the driver. Other
parameters are function (%p1) and mode (%p2). Note that some
drivers may not produce this trace when there is no driver
parameter string specified.
Trace area:
Mnemonic: CIS Category: c
CTR l
DB2 m
INF g
INS f
ORA a
RDB e
SEQ q
SYB h
TXT p
--------------------------------------------------------------------------------
XXX_I_EDBDRV
Level: 1
Where: Just before the final return in the
driver.
Syntax: XXX_I_EDBDRV %p1%p2
Exit=%p3
Example: RMS_I_EDBDRV S0 Exit=5
What: The return value (%p3) of the driver for
function (%p1) and mode
(%p2).
Trace area:
Mnemonic: CIS Category: c
CTR l
DB2 m
DB3 b
INF g
INS f
ORA a
RDB e
RMJ d
RMS d
SEQ q
SYB h
TXT p
--------------------------------------------------------------------------------
XXX_I_ERRCOD
Level: 2
Where: In the message-function of a driver.
Syntax: XXX_I_ERRCOD %p1%p2
Error %p3 translated into: %p4
Example: RDB_I_ERRCOD M2 Error 0
translated into: Exception RDB6040 driver
( 3) : Preparation of
statement failed. Exception Rdb Version
6.0 (42000) : %SQL-F-RELNOTDEF, Table TEST is not defined in
database or schema
What: The error (%p3) and its translation into
an error message (%p4).
Trace area:
Mnemonic: CIS Category: c
CTR l
INF g
INS f
ORA a
RDB e
SEQ q
SYB
h
TXT p
--------------------------------------------------------------------------------
XXX_I_ERRHCO
Level: 2
Where:
Syntax: XXX_I_ERRHCO %p1%p2
Error %p3 (hex) translated into: %p4
Example:
What:
Trace area:
Mnemonic:
RMS Category: d
--------------------------------------------------------------------------------
XXX_I_ESQL
Level: 9
Where:
Syntax: XXX_I_ESQL %p1%p2 Successful %p3 of %p4
Example:
What:
Syntax: XXX_I_ESQL %p1%p2 Successful %p3 of cur. %p4
Example:
What:
Syntax: XXX_I_ESQL %p1%p2 Successful %p3
Example:
What:
Syntax: XXX_I_ESQL %p1%p2 Successful decl. cur. %p3 for %p4
Example:
What:
Syntax: XXX_I_ESQL %p1%p2 Successful prep. (id=%p3) of %p4
Example:
What:
Trace area:
Mnemonic:
RDB Category: e
XXX_I_SELFID
Level: 1
Where:
Syntax: XXX_I_SELFID %p1%p2
Drv. U%p3.%p4
Example:
What:
The identification of the driver with U_MAJOR (%p3) and U_MINOR
(%p4). Other parameters are function (%p1) and mode (%p2).
Trace area:
Mnemonic: CIS Category: c
CTR l
DB2 m
DB3 b
INF g
INS f
ORA a
RDB e
RMJ d
RMS d
SEQ q
SYB h
TXT p
XXX_I_SQL
Level: 9
Where:
Syntax: XXX_I_SQL %p1%p2 Starting %p3 of %p4
Example:
What:
Syntax: XXX_I_SQL %p1%p2 Starting %p3 of cur. %p4
Example: RDB_I_SQL O1 Starting exec. imm. of SET CONNECT 'T_RW'
What:
Syntax: XXX_I_SQL %p1%p2 Starting %p3
Example:
What:
Syntax: XXX_I_SQL %p1%p2 Starting decl. cur. %p3 for %p4
Example:
What:
Syntax: XXX_I_SQL %p1%p2 Starting prep. (id=%p3) of %p4
Example: RDB_I_SQL L0 Starting prep. (id=0) of SET TRANSACTION READ
ONLY NOWAIT
What:
Trace area:
Mnemonic:
RDB Category: e