NAME

snalu62_api_trace_set − Sets (or modifies) the API tracing characteristics. 
 
 

LIBRARY

 
/usr/shlib/libsnatprm.so
 
 
 

SYNOPSIS

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

SUPPLIED PARAMETERS

trace_size

A int value specifying the maximum file size (specified in 512-byte blocks).  Specify the value LU62_TR_DEFAULT_FILESIZE to indicate that there is no restriction on the file size.  Specify the value LU62_TR_KEEP_FILESIZE to leave the value of the trace_size characteristic unchanged.  Otherwise, specify a value in the range LU62_TR_FILESIZE_MIN to LU62_TR_FILESIZE_MAX blocks. 

You typically specify a non-zero value for this parameter when the amount of disk space consumed by the trace file may be a problem.  When the tracing facility reaches the approximate maximum file size, it closes the tracing file and opens a new one (using the next highest version number).  If defined, the trace facility initializes this characteristic to the value of the SNATRACE_SIZE environment variable.  Otherwise, the trace facility initializes this characteristic to LU62_TR_DEFAULT_FILESIZE. 
 

trace_mask

An API_TRACE_MASK structure specifying a hexadecimal 32-bit mask that controls what the API tracing facility writes to the tracing file.  Specify the value LU62_TR_DEFAULT_MASK to indicate that tracing should be disabled.  Specify the value LU62_TR_RECOMMENDED_MASK to set the trace_mask characteristic to the value recommended by Compaq.  Specify the value LU62_TR_KEEP_MASK to leave the value of the trace_mask characteristic unchanged.  Otherwise, specify the mask as a hexadecimal string with the order of bits 31 to 0, left to right. 

The general format of the mask is 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.
 
If defined, the trace facility initializes this characteristic to the value of the SNATRACE_MASK environment variable.  Otherwise, the trace facility initializes this characteristic to LU62_TR_DEFAULT_MASK. 

It is the trace_mask characteristic which 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. 

trace_buflen

An int value specifying the number of bytes of the output buffer to write (truncate to) on output.  Specify the value LU62_TR_DEFAULT_BUFLEN to indicate that the interface should use the maximum buffer length (0x7FFFFFFF).  Specify the value LU62_TR_KEEP_BUFLEN to leave the value of the trace buffer length characteristic unchanged.  If defined, the trace facility initializes this characteristic to the value of the SNATRACE_BUFLEN environment variable.  Otherwise, the trace facility initializes this characteristic to LU62_TR_DEFAULT_BUFLEN. 
 

trace_versions

An int value specifying 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 referenced by 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. 

Specify the value LU62_TR_DEFAULT_VERSIONS or LU62_TR_VERSIONS_MAX to indicate that the interface should keep the maximum number of versions.  Specify the value LU62_TR_KEEP_VERSIONS to leave the value of the trace versions characteristic unchanged.  If defined, the trace facility initializes this characteristic to the value of the SNATRACE_VERSIONS environment variable.  Otherwise, the trace facility initializes this characteristic to LU62_TR_DEFAULT_VERSIONS. 

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 null-terminated ASCII string specifying the name of the trace file.  Specify the value LU62_TR_DEFAULT_FILENAME to indicate that the interface should use the default trace file name (./snatrace.dat).  Specify the value LU62_TR_KEEP_FILENAME to leave the value of the trace file name characteristic unchanged.  If defined, the trace facility initializes this characteristic to the string specified by the SNATRACE_FILE environment variable.  Otherwise, the trace facility initializes this characteristic to ./snatrace.dat. 

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). 

RETURNED PARAMETERS

 
None
 

DESCRIPTION

 
Use this unarchitected verb to modify the tracing characteristics. You must set all tracing characteristics. If you want to modify only a subset of the characteristics, use the LU62_TR_KEEP_char value for the characteristics that you want to retain along with the new values for the characteristics you want to change. 
 
 

RESTRICTIONS

 
None
 

RETURN VALUES

SNALU62_S_OKnormal successful completion

SNALU62_S_PARERR
parameter error, routine function-name
 
 
 
 

ERRORS

 
None

RELATED INFORMATION

 
Functions: snalu62_api_trace_extract

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.