QtrcGetActiveLevel()--Get Active Trace Level

 #include <qtrc.h>

 int QtrcGetActiveLevel
         (const char     *Component,
          unsigned int   *Active_Level);

The QtrcGetActiveLevel() function retrieves the active trace level for the specified Component and places the result into the integer pointed to by Active_Level.

A successful call to the QtrcGetActiveLevel() function results in one of the following values for the Active_Level:

If the specified Component is not defined to a trace collection, the Active_Level value is set to QTRC_LEVEL_NONE (0). Components are defined to a trace collection using the Start Trace (STRTRC) CL command.

Parameters

Component

(Input)

A pointer to the null-terminated component name. The component name should be 10 characters in length or less. If more than 10 characters are specified, only the first 10 characters are used.

Active_Level

(Output)

A pointer to the integer variable to receive the active trace level value.

Authorities and Locks

None.

Return Value

0

QtrcGetActiveLevel() was successful.

value

QtrcGetActiveLevel() was not successful. value is set to indicate the error condition.

Error Conditions

If QtrcGetActiveLevel() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

Error Messages

None.

Usage Notes

1. The main purpose for using the QtrcGetActiveLevel() is to determine if the specified Component has been used on the Start Trace (STRTRC) CL command, for the Trace type (TRCTYPE) parameter. If the component and its trace level were used on STRTRC, the Active_Level returned by QtrcGetActiveLevel will reflect the trace level value that was used (*ERROR, *INFO, or *VERBOSE). If not, the Active_Level will indicate a trace level value of QTRC_LEVEL_NONE (0), which means trace is not currently active for the specified Component.
2. Using the QtrcGetActiveLevel() function may have a slight performance impact if called often, even when component tracing is not currently active. To help alleviate such performance impacts, the QtrcGetActiveLevel() function should be called sparingly, and the results saved into a variable for later use throughout a program or function call. The variable should be periodically updated, to ensure a current view of the component's active trace level. For example, the variable should be updated using the QtrcGetActiveLevel() function in the following conditions:
   
   
   • Upon entry to a program or major function.
   • After coming out of a wait.
   • After calling a long-running program or function.
   • After each iteration of a major loop cycle.

Related Information

• QtrcWriteHexDump()--Write Hexadecimal Dump Trace Data
• QtrcWriteHexDumpF()--Write Hexadecimal Dump Formatted Trace Data
• QtrcWriteStack()--Write Call Stack Trace Data
• QtrcWriteText()--Write Text Trace Data
• QtrcWriteTextPrintF()--Write Text Trace Data using Print Formatted
• QtrcWriteTextPPrintF()--Write Text Trace Data using Pointer-based Print Formatted
• QtrcWriteTextVPrintF()--Write Text Trace Data using Variable Argument List Print Formatted
• Start Trace (STRTRC) CL command
• For additional information about the QTRC Trace environment, see QTRC Trace APIs.

Example

The following example retrieves the active trace level for a component named MYCOMP. The example output assumes the Start Trace (STRTRC) CL command was used before calling the example, specifying TRCTYPE((MYCOMP *INFO)).

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <qtrc.h>
#include <stdio.h>
#include <errno.h>

int main(int argc, char *argv[])
{
  unsigned int myCompActLvl = QTRC_LEVEL_NONE;
  const char *myComp = "MYCOMP";
  int rc;

  rc = QtrcGetActiveLevel(myComp, &myCompActLvl);

  if (rc != 0) {
    printf("QtrcGetActiveLevel() failed with error %d\n",
           rc);
    return -1;
  }

  printf("%s active trace level is:  ",myComp);
  switch (myCompActLvl) {
    case QTRC_LEVEL_NONE:
      printf("NONE\n");
      break;
    case QTRC_LEVEL_ERROR:
      printf("ERROR\n");
      break;
    case QTRC_LEVEL_INFO:
      printf("INFO\n");
      break;
    case QTRC_LEVEL_VERBOSE:
      printf("VERBOSE\n");
      break;
  }

  return 0;
}

MYCOMP active trace level is:  INFO

[ Back to top | Problem Management APIs | APIs by category ]