ctaStartTrace

Starts tracing on a remote server.

Prototype

DWORD ctaStartTrace ( CTAHD ctahd)

Argument

Description

ctahd

Context handle for the server on which tracing is started. ctahd cannot be a void context handle because void contexts do not have queues.


Return values

Return value

Description

SUCCESS

 

CTAERR_INVALID_CTAHD

An invalid context handle was passed as an argument to a function, or the context was destroyed by another thread.

CTAERR_NOT_INITIALIZED

Natural Access is not initialized. Call ctaInitialize first.

CTAERR_SVR_COMM

Server communication error.


Events

Event

Description

CTAEVN_TRACE_MESSAGE

This event passes trace messages from the server to the client applications. The buffer field of the CTA_EVENT structure points to an array containing the message text. Trace messages are text in the same format as they appear in the Natural Access Server (ctdaemon) log file.


Details

After an application initiates a call to ctaStartTrace, the trace messages are sent as CTAEVN_TRACE_MESSAGE events to the queue on which the ctahd context was created.

See also

ctaSetGlobalTraceMask, ctaStopTrace

Example

int DemoRemoteTrace(CTAQUEUEHD ctaqueuehd, CTAHD ctahd)
{
     DWORD ret;

          /* Start tracing */
          ret = ctaStartTrace(ctahd);
          if ( ret != SUCCESS )
             return ret;

          /* Set tracemask on server */
          ret = ctaSetGlobalTraceMask(ctahd,CTA_TRACEMASK_ALL_COMMANDS);
          if ( ret != SUCCESS )
             return ret;
          
          for (;!kbhit();)
          {
               // Retrieve an event from the event queue.
               CTA_EVENT cta_event;
               ret = ctaWaitEvent( ctaqueuehd, &cta_event, 1000 );
               
          // Check if buffer is owned by Natual Access and must be freed by
          // us below.
              bool const bCtaOwnsBuf = (cta_event.buffer != NULL && 
              (cta_event.size & CTA_INTERNAL_BUFFER));
              if (bCtaOwnsBuf)
              {
                  cta_event.size &= ~CTA_INTERNAL_BUFFER; 
                     // clear flag from size
              }
              if (cta_event.id == CTAEVN_TRACE_MESSAGE) 
                     // if it's a trace event
              {
                  if (!cta_event.buffer)
                  {
                      continue;
                  }
               
                   const char * const pszText = (char*)cta_event.buffer;
               
                   printf( "%s", pszText );
               }
               
               if (bCtaOwnsBuf)
               {
                   ctaFreeBuffer( cta_event.buffer ); 
                      // our reponsibility to free
               }
          }
     
         /* Stop tracing */
         ret = ctaStopTrace( ctahd );
         if ( ret != SUCCESS )
             return ret;

          return SUCCESS;
          
}