NAME

snalu62_api_trace_extract − Retrieves the API tracing characteristics. 
 
 

LIBRARY

 
/usr/shlib/libsnatprm.so
 
 
 

SYNOPSIS

 
#include <sna/snatprmdf.h>
 
STATUS_RTN snalu62_api_trace_extract(
       int ∗trace_size,
       API_TRACE_MASK ∗trace_mask,
       int ∗trace_buflen,
       int ∗trace_versions,
       char ∗trace_filename
       );
 
 
 

SUPPLIED PARAMETERS

 
None
 
 

RETURNED PARAMETERS

trace_size

A pointer to an int location to receive the current value of the trace_size characteristic.  This characteristic specifies the maximum trace file size (specified in 512-byte blocks). The value is in the range LU62_TR_FILESIZE_MIN to LU62_TR_FILESIZE_MAX blocks. When the next write operation would exceed the maximum file size, the tracing facility closes the tracing file and opens a new one (using the next highest version number).  A value of LU62_TR_DEFAULT_FILESIZE indicates that there is no maximum file size. 
 

trace_mask

A pointer to an API_TRACE_MASK structure to receive the value of the trace_mask characteristic.  This characteristic specifies a hexadecimal 32-bit mask that controls what the API tracing facility writes to the tracing file.  The mask is a hexadecimal string with the order of bits 31 to 0, left to right. It has the general format 0xNNNNNNNN, where N is a 4-bit hexadecimal value (nibble) specifying tracing options. 
 
 
See the Programming manual for a complete description of how the bits are interpreted.
 
A value of LU62_TR_DEFAULT_MASK means tracing is disabled. 

It is the trace_mask characteristic that controls whether the tracing facility is enabled.  When the characteristic is changed to a non-zero value, tracing begins. When the characteristic is changed to a zero value, tracing stops. 

Disabling tracing closes the active trace file.  If the trace file name characteristic has not been changed, renabling tracing causes the interface to append new trace data to the last trace file. 

trace_buflen

A pointer to an int location to receive the value of the trace_buflen characteristic.  This characteristic specifies the number of bytes of the output buffer to write (truncate to) on output.  A value of LU62_TR_DEFAULT_BUFLEN is interpreted as a maximum buffer length of 0x7FFFFFFF. 
 

trace_versions

A pointer to an int location to receive the value of the trace_versions characteristic.  This characteristic specifies the maximum number of versions of the trace file that the tracing facility should retain.  To allow the tracing facility to retain multiple versions of the same file, it appends a decimal version number to the base file name specified in the trace_filename parameter (filename.NNNN).  When the number of files with the same base name reaches the number specified in this variable, the tracing facility deletes a lower version file before opening a new version of the trace file.  A value of LU62_TR_DEFAULT_VERSIONS is interpreted as a value of LU62_TR_VERSIONS_MAX (see the note below). 

If no files with the same base file name are found, the tracing facility starts the version numbering at 0000. If a file with the same base file name already exists, the tracing facility starts the version numbering using a number one higher than the highest version number found. 

A value of LU62_TR_VERSIONS_MAX for this trace characteristic causes the tracing facility to retain the maximum number of trace file versions.  It also causes the tracing facility to stop when this maximum is reached.  This prevents any trace data from being deleted. 

This variable specifies the maximum number of files retained, not the highest version number. For example, if the current highest version number is 50, and the variable is set to 60, the trace facility does not stop at version 60; instead, it stops at version 109. 

trace_filename

A pointer to a char buffer of length LU62_TR_FILENAME_MAX + 1 to receive the the null-terminated file name for the tracing output. 
 
 

If the file name includes a version number (for example, ./snatrace.dat.555), the tracing facility does not use versioning. If the trace_versions characteristic is non-zero, the tracing facility ignores it.  If a file exists with the supplied version, the tracing facility overwrites it.  When the file reaches the specified maximum size, the tracing facility closes the file and opens a new one (overwriting the previous file). 

DESCRIPTION

 
Use this unarchitected verb to retrieve the values of the characteristics that control API tracing. If you specify the NULL pointer for a parameter, the trace facility does not return that characteristic.
 
 

RESTRICTIONS

 
None
 

RETURN VALUES

SNALU62_S_OKnormal successful completion

SNALU62_S_UNSUC
verb did not execute successfully
 
 
 

ERRORS

 
None

RELATED INFORMATION

 
Functions: snalu62_api_trace_set

Manuals: Compaq SNA APPC/LU6.2 Programming Interface for Tru64 UNIX Programming and IBM’s Systems Network Architecture Transaction Programmer’s Reference Manual for LU Type 6.2.