Ingres CL TR
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - TR
Abstract
This is the specification of the TR facility provided by the compatibility library.
Revision: 1.2, 15-Nov-1997.
Document History
- Revision 1.2, 15-Nov-1997
- Converted to HTML.
- Revision 1.1, 20-Jul-94
- TR format arg decl correction - function returns VOID (24-jan-92)
- errata: TRmaketrace and TRsettrace are VOID. (20-mar-92)
- TR_FORMAT_FUNC type defined for the function passed into TRformat. (1-may-92).
- TR_F_APPEND added (26-jun-92).
- Revision 1.0, last modified 29-Aug-91
- Use CL_OFFSETOF in the example rather than the illegal "zero-points-to" trick.
- Interaction of SI, TE and TR was described.
- Typo that said '-' was the "delete leading whitespace" indicator has been changed to the correct '~'.
- Descriptions of curious field-width interpretations for %d and %d formats has been added.
- Description of TRformat operation with a NULL function has been added.
- Fixed other typos.
- TRset_file now has a system-independant way to set the log file to a reasonable place:
- TR_OUTPUT and TR_L_OUTPUT.
Specification
Introduction
The TR routines format and write trace information on the trace output file(device) or files(devices) defined for a user session (thread) and accept trace input from the input file(device). TR includes routines to set and fetch trace flags.
Library
CL
Intended Uses
The TR routines are used to format and display tracing information on one or more files. The trace output may be sent to a terminal only, to a log file only or to both.
SI, TE and TR files may be open and used in the same program. SI and/or TR may do i/o to the terminal when it is in the default TE_NORMAL mode, assuming flushes (SIflush, TEflush, TRflush) of pending output are done. When in TE_FORMS or TE_CMDMODE, operations by SI or TR to the terminal are undefined. Output may be mixed as long as flush calls are made before using a new interface and the terminal mode restrictions are obeyed. Mixing input from one file between SI and TR gives undefined results.
Assumptions
DBMS code must use only the TR routines for printing debugging and trace information. It must not use SI for that purpose. The formatting routines are extensive to format complicated control structures like control blocks, and memory dumps. TR includes formatting commands for symbolic representation of ordinals and bit masks as well as commands to systematically step through arrays of structures or arrays of pointers to objects.
Log output of a previous run can be used by TRrequest. The input command ignores output data. This allows the same trace input options to be run and the resulting file diff'd or just used to setup for bug fixing.
Concepts
TRset_file must be called before any TRdisplay or TRrequest calls are made; otherwise, TRdisplay and TRrequest are no-ops. TRmaketrace must be called prior to calling TRgettrace or TRsettrace.
The TRdisplay routine wraps long lines at 132 columns so that they are visible on the printer.
Trace vectors are a sequence of bits. The number of bits in a trace vector is a multiple of the size of an i2 (see TRmaketrace).
Header File <tr.h>
The header file <tr.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
TRdisplay - format and write trace output
Characters from the format string are passed to the trace terminal and/or the trace file. If a format specifier is recognized parameters are read from the argument list and are displayed in the form described by the format specifier. All output is formatted into 132 character lines and long lines are broken into multiple lines.
A format specifier is of the following form:
% [~] [ width ] [. [ size ] ] directive
Where width and size are decimal number or '#' or '*'. The '#' means get the value from the parameter list. The '*' means get the value indirectly from the parameter list, or get the value from an offset within a structure or array if currently in a structure or array. The optional leading '~' controls the automatic deletion of trailing blanks and the corresponding shrinking of the field width. This is most useful when formatting fixed size text strings with potential for trailing blanks.
A formatting directive is one of the following:
b Print base address of structure. Width means how wide a field to use in displaying the string, if none is given as many characters as needed to display the words are used. Size is not used.
c Format a text character. If the character is not printable a '.' is substituted. Width and size are ignored. One parameter is used, this is the character to format. If this is in a structure the parameter is used as an offset from the base address of the structure.
d Format an integer in decimal. Width means how wide of a field to use in displaying the number, if none is given as many characters as needed to display the number are used. Size means how large an integer to get when displaying values in structures or arrays. One parameter is used, this is the number to format. If this is in a structure then the parameter is used as an offset from the base address of the structure.
Note that "%d" operates differently from "%x" when a 'width' value is provided. Since "%d" formats the number into a varying-length string, a 'width' value may be provided to limit the length of the string if the values are known to be small. If the 'width' value results in truncation, this truncation is performed FROM THE LEFT. Also note that negative width is not supported. Some examples follow:
· 0x01234567 in %d format: 19088743
· 0x01234567 in %5d format: 19088
· 0x01234567 in %2d format: 19
· 0x01234567 in %-5d format: 5d
· 0x01234567 in %~5d format: 19088
e The float or double arg is converted in the style [-]d.dddeSdd, where there is one digit before the decimal point and the number of digits after it is equal to the precision; when the precision is missing, a default of 3 is used; if the precision is zero, no decimal point appears. The exponent always contains at least two digits.
f The float or double arg is converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal point is equal to the precision specification. If the precision is missing 3 decimal digits are output; if the precision is explicitly 0, no decimal point appears.
g The float or double arg is converted to decimal notation in the sytle [-]ddd.ddd, where the number of digits after the decimal point is equal to the precision specification. If the precision is missing, 3 decimal digits are output; if the precision is explicitly 0, no decimal point appears. If the number is a display of zero, the number is displayed in 'e' format with the decimal points aligned.
p Format a PTR argument, in a system specific way, usually hex. Necessary widths vary depending on the size of pointers on the machine.
s Format a C character string. Width means how wide a field to use in displaying the string, if none is given as many characters as needed to display the string are used. If size is given it is assumed to be the length of the string, otherwise a null character terminates a string. One parameter is used, this is a pointer to the string to format. If this is in a structure then the parameter is used as an offset from the base address of the structure to get the pointer.
t Format a text string. Width means how wide a field to use in displaying the string, if none is given as many characters as needed to display the string are used. Size is ignored. The first parameter is the length of the string, the second parameter is a pointer to the string. There is no special meaning when inside a structure.
v Format a bit field into words. Width means how wide a field to use in displaying the string, if none is given as many characters as needed to display the words are used. Size is used inside a structure to determine the size of the integer to fetch. The first parameter is a character string containing words separated by ','. The words from left to right correspond to the bits from least significant to most significant. If the bit is on, the word is copied to the output. The second parameter is the value to use, or the offset from the base address of the structure.
w Format an integer into a word. Width means how wide a field to use in displaying the string, if none is given as many characters as needed to display the words are used. Size is used inside a structure to determine the size of the integer to fetch. The first parameter is a character string containing words separated by ','. The words from left to right correspond to the numbers 0 through whatever. The second parameter is the value to use, or the offset from the base address of the structure.
x Format an integer in hexidecimal. Width means how wide of a field to use in displaying the number, if none is given as many characters as needed to display the number are used. Size means how large of an integer to get when displaying values in structures or arrays. One parameter is used, this is the number to format. If this is in a structure then the parameter is used as an offset from the base address of the structure.
NOTE: if 'width' is not provided to "%x", the number is zero-padded and displayed in an 8 byte string. If 'width' is provided, the number is still internally zero-padded into an 8 byte string and then truncated to the given width FROM THE LEFT. Also note that negative width is not supported.
Some examples follow:
· 0x01234567 in %x format: 01234567
· 0x01234567 in %5x format: 01234
· 0x01234567 in %2x format: 01
· 0x01234567 in %-5x format: 5x
· 0x01234567 in %~5x format: 01234
@ Format the current time and date. Width means how wide of field to use in displaying the time and date. This takes no parameters.
( Start repeating group. Width means how many times to repeat the format items following this until the %). A repeating group can not be used inside an array or structure.
) End repeating group. Terminates a repeated format group.
< Backup parameter. If width is set this backs up the corresponding number of parameters otherwise it backs up one parameter.
*? Repeat character. Width determines how may times the characters following the * is copied to the output.
% Print a '%'.
[ Start array of pointers. Width is used to tell how many pointers to follow. The first parameter is the address of the array of pointers. If this is in a structure, this is an offset to the pointer to the array of pointers. The format and the parameter are rescanned with the next pointer until all pointers are exhausted. This can be nested within an array, structure or repeat group.
] End array of pointers. Delimits an array of pointers.
{ Start array of structures. Width is used to tell how many structures to display. Size is the size of the structure item so that it can increment to the next item. The first parameter is the address of the structure. If this is in a structure this is an offset to the structure to be displayed. The format and the parameters are rescanned with the next structure address until all structures have been displayed. This can be nested within an array, structure or repeat group.
} End array of structures. Delimits an array of structures.
Inputs:
| format | String describing the formatting actions to perform. |
| ... | Variable number of arguments to substitute into the output string. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TRdisplay(format, ...) char *format;
TRformat - format text into memory
This function will format text into a memory buffer and then call a caller provided function to dispose of the buffer contents.
The caller-supplied function may be omitted, if it is desired to use TRformat for its buffer formatting capabilities only. However, the following notes should be kept in mind if this capability is used:
There is no way for TRformat to return the length of valid data in 'buffer' if a function is not supplied. Therefore, this capability should only be used to format fixed length strings.
TRformat() does not null-terminate the formatted buffer. An embedded newline should not be included in the format string. Each time a newline is encountered in the format string, TRformat calls the supplied function and begins formatting again from the start of the buffer. The caller must ensure that the supplied buffer is large enough. Each time the supplied buffer fills up, TRformat calls the supplied function and begins formatting again from the start of the buffer. The user function is called like:
(*fcn)(arg, length, buffer)
where 'length' is the length of valid data in 'buffer'. There is a typedef for this function:
typedef VOID TR_FORMAT_FUNC( i4 *arg, i4 offset, char *buffer );
Inputs:
| fcn | Function to call back. |
| arg | Argument to pass to fcn. |
| l_buffer | Length of buffer. |
| format | Format string. |
| ... | Variable number of arguments. |
Outputs:
| buffer | Pointer to buffer to use. |
Returns:
| None |
Definition:
VOID TRformat(fcn, arg, buffer, l_buffer, format, ...) TR_FORMAT_FUNC *fcn; PTR arg; char *buffer; i4 l_buffer; char *format; i4 parameter;
TRflush - flush trace buffers
This routine will flush TRdisplay output buffers.
Inputs:
| None |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TRflush()
TRgettrace - test a trace flag
Test a specific word and/or bit of a word that was previously initialized by calling TRmaketrace. TRgettrace uses the vector that was used in the last call to TRmaketrace. If no calls have been made to TRmaketrace, then it always returns FALSE.
Inputs:
| word | The index of the word to set. |
| bit | The bit within the word to test, or, if < 0, indicates that word 'word' is to test. |
Outputs:
| None |
Returns:
| FALSE | if the bit isn't set. |
Definition:
bool TRgettrace(word,bit) i4 word; i4 bit;
TRmaketrace - setup a trace vector
Initialize a trace vector based on the flags that are passed to this routine. The address of the trace vector is remembered for future calls to TRgetrace or TRsettrace.
Trace flags have syntax:
["-t" | "-tn1" | "-tn2.n3" | "-tn4/n5" ]
where t is whatever single character was set by argument tflag. The four options mean 'set' all flags in the trace vector, 'set' word n1, 'set' bit n3 in word n2, and 'set' words n4 through n5.
The nature of the 'set' operation is defined by the input variable tonoff.
Inputs:
| argv | A null-terminated array of character strings to scan for trace arguments. |
| tflag | The character that must follow the '-' in trace arguments. |
| tsize | The size of the trace vector in i2's. |
| tonoff | Whether to turn the bits on or off. |
Outputs:
| tvect | Sets bits in tvect determined by the arguments passed. The name of tvect if remembered as the default. |
Returns:
| None |
Definition:
VOID TRmaketrace(argv, tflag, tsize, tvect, tonoff) char **argv; char tflag; i4 tsize; i4 *tvect; bool tonoff;
TRrequest - read from trace input file
Read a line of input from the trace input file. If there if a log file, the input line is logged to the log file preceded by a comment designator. Input records that have comment designators are skipped.
Inputs:
| record | Record buffer address. |
| record_size | Size of record buffer. |
| prompt | Prompt to use, 0 gets default. |
Outputs:
| read_count | The number of bytes read. |
| err_code | system specific error information is returned in this structure. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TRrequest(record, record_size, read_count, err_code, prompt) char *record; i4 record_size; i4 *read_count; CL_ERR_DESC *err_code; char *prompt;
TRset_file - set (open) trace input/output files
Changes the trace system log file and terminal output file. The log file contains a log of all inputs and output of the trace system. The terminal output contains only data written to the output.
The system independent way to set the terminal output file to the system's notion of the "standard output file" is to use TR_T_OUTPUT and TR_L_OUTPUT.
Inputs:
| flag | Flag to determine the action type. |
| One of: | |
| TR_F_APPEND | open the file for append. |
| TR_F_OPEN | open the file output. |
| TR_F_CLOSE | close file output |
| TR_T_OPEN | open trace output |
| TR_T_CLOSE | close trace output |
| TR_I_OPEN | open input |
| TR_I_CLOSE | close input |
If the TR_NOOVERRIDE_MASK is also specified, then a new file will not be opened if a file was previously opened.
filename
Pointer to the filename. To open the system's notion of the "standard output file" for TR_T_OPEN use, filename should be set to TR_OUTPUT. To open the system's notion of the "standard input file" for TR_I_OPEN use, filename should be set to TR_INPUT.
name_length
The length of the filename. If TR_OUTPUT was specified as the value of 'filename', then TR_L_OUTPUT should be specified as the value of name_length. If TR_INPUT was specified as the value of 'filename', then TR_L_INPUT should be specified as the value of name_length.
Outputs:
| err_code | Pointer to variable to store error. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TRset_file(flag, filename, name_length, err_code) i4 flag; char *filename; i4 name_length; CL_ERR_DESC *err_code;
Example:
STATUS TRset_file(TR_T_OPEN,TR_OUTPUT,TR_L_OUTPUT,&sys_err);
TRsettrace - set a trace flag in a vector
Sets or clears trace flags set in the default trace vector setup by TRmaketrace. If no trace vector has been setup then the call is ignored.
This routine is only used by FSGW.
Inputs:
| word | The index of the word to set. |
| bit | The bit within the word to set, or all bits if bit < 0. |
| set | The value to set either 0 or 1. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
VOID TRsettrace(word, bit, set) i4 word; i4 bit; bool set;
Example
/* Open up the terminal output trace. */
# ifdef VMS
TRset_file(TR_T_OPEN, "SYS$OUTPUT", 10, &err_code);
# endif
/* Different OS, open a file. */
# ifdef MVS
TRset_file (TR_F_OPEN, "dd:iierlog", 10, &err_code);
# endif
/* Simple trace display. */
TRdisplay("\n%.4s Control Block @0x%x..0x%x owned by 0x%x for %d bytes.
\n\n", &obj->obj_tag, obj, (char *)obj + obj->obj_size - 1,
obj->obj_owner, obj->obj_size);
/* Also open the file output trace. */
TRset_file(TR_F_OPEN, "DMFTEST.LOG", 11, &err_code);
/*
** Dump 16-bytes in hex and ascii preceeded by the address and converting
** non-printing characters to '.'.
*/
for (i = 0; i < obj->obj_size; i+= 16)
TRdisplay(" 0x%x:%< %4.4{%x%}%2< >%16.1{%c%}<\n", (char *)obj + i, 0);
/* Close the terminal file output trace. */
# ifdef VMS
TRset_file(TR_F_CLOSE, "SYS$OUTPUT", 10, &err_code);
# endif VMS
/*
** Display an array of structures.
*/
TRdisplay("%#.#{ BUF:0x%b DB:0x%x TAB:(%8d,%8d) PAGE: %8d\n\%8*
REF=%2d PRI=%2d TYPE=%w STATUS=%v\n\%8* TRAN=0x%x%x LKID=%x\n%8*
V=%x%x NV=%x%x\n\n%}",
bmcb->bm_bufcnt, sizeof(DM0P_BUFFER), bmcb->bm_buffers,
CL_OFFSETOF(DM0P_BUFFER, buf_lock_key.lk_key1),
CL_OFFSETOF(DM0P_BUFFER, buf_lock_key.lk_key2),
CL_OFFSETOF(DM0P_BUFFER, buf_lock_key.lk_key3),
CL_OFFSETOF(DM0P_BUFFER, buf_lock_key.lk_key4),
CL_OFFSETOF(DM0P_BUFFER, buf_refcount),
CL_OFFSETOF(DM0P_BUFFER, buf_priority),
"ROOT ,INDEX,LEAF ,DATA ",
CL_OFFSETOF(DM0P_BUFFER, buf_type),
"VALID,MODIFIED,FIXED,WRITE,LOCKED,CACHED,EXCLUSIVE,RBUSY,WBUSY",
CL_OFFSETOF(DM0P_BUFFER, buf_sts),
CL_OFFSETOF(DM0P_BUFFER, buf_tran_id.db_high_tran),
CL_OFFSETOF(DM0P_BUFFER, buf_tran_id.db_low_tran),
CL_OFFSETOF(DM0P_BUFFER, buf_lk_id),
CL_OFFSETOF(DM0P_BUFFER, buf_oldvalue.lk_high),
CL_OFFSETOF(DM0P_BUFFER, buf_oldvalue.lk_low),
CL_OFFSETOF(DM0P_BUFFER, buf_newvalue.lk_high),
CL_OFFSETOF(DM0P_BUFFER, buf_newvalue.lk_low));
/* Display and array of pointers to structures. */
TRdisplay("%#[%8* %.#s %4.2d %8.2w %4.2d %5.2d %3.2d\n%]",
mxcb->mx_a_count,
mxcb->mx_b_key_atts,
sizeof(mxcb->mx_b_key_atts->name),
CL_OFFSETOF(DMP_ATTS, name),
CL_OFFSETOF(DMP_ATTS, offset),
",,,,,,,,,,,,,,,,,,,,,,,,,,,,,,INT ,FLOAT,CHAR ",
CL_OFFSETOF(DMP_ATTS, type),
CL_OFFSETOF(DMP_ATTS, length),
CL_OFFSETOF(DMP_ATTS, precision),
CL_OFFSETOF(DMP_ATTS, key);
/* Open the trace file input. */
TRset_file(TR_I_OPEN, "SYS$INPUT", 9, &err_code);
/* Read a line from the trace input file. */
TRrequest(buffer, sizeof(buffer), &amount_read, &err_code, "prompt>");
/* Write the line to the trace terminal. */
TRdisplay("Echo - '%t'\n", amount_read, buffer);
|
Ingres Compatability Library |
