Using API Tracing

API tracing allows you to get detailed information about your program's interactions with the HP FTAM API without your having to access your source code. It provides the return value of each API call made by your program as well as the input parameters to each call.

API Tracing Variables

HP FTAM API tracing is controlled by the following three global variables.

ft_trace indicates the trace level to be used. The default value of ft_trace is 0, which indicates no tracing, but the value may instead be defined in the %<api_trace.h> file as either of the following:
- API_TR_ENTRY_EXIT — procedure entry and exit are traced. No parameter information is displayed. This is useful if you are interested only in seeing what FTAM calls your program is making. This value is defined as 0x1.
- API_TR_INPUT — input parameters to the FTAM functions, as well as procedure entry and exit, are traced. This is useful is you want to verify that FTAM is actually receiving the values you expect. This value is defined as 0x2.
ft_trace_fp is a file pointer that is used to write the trace records. The default is stderr. You can redirect the trace information to be saved to a specific file, and then use fopen to open the file.
ft_trace_max_udata indicates the maximum amount of user data (in bytes) to be displayed during tracing. The default is 16.

Enabling API Tracing

The following steps show how to enable API tracing in your program.

To include the appropriate definitions, add lines similar to the following to your program:

#include %<api_trace.h>
extern int ft_trace;
extern FILE *ft_trace_fp;
extern int ft_trace_max_udata

Within your program, enable tracing by changing the value of the ft_trace variable from 0 to either API_TR_ENTRY_EXIT or API_TR_INPUT. (The "Resolving FTAM Problems" chapter in the HP FTAM/9000 User's Guide provides information on enabling and disabling API tracing during an interactive FTAM session.)
If you want the trace output to be written to a file, redirect the trace output from stderr as follows.
ft_trace_fp = fopen("/tmp/my_ft_trace","a");
If you want more than the first 16 bytes of data to be displayed, increase the value of the ft_trace_max_udata variable. For example:
ft_trace_max_udata = 256
If you want API tracing to be a runtime option, use the -t option shown in the following sample code, and enter program_name -t at runtime.

The following example shows how to use the variables.

#include %<api_trace.h>
extern int ft_trace;
extern FILE *ft_trace_fp;
extern int ft_trace_max_udata;
..

main (argc,argv)
Int argc;
char **argv;
{
/* To run, enter "program name -t" to enable tracing*/
/* Check if tracing needs to be turned on */

if ((argc ==2) & &  (strcmp(argv{1}, "-t") == 0))
{
/* Turn tracing on, create trace file */

ft_trace = API_TR_INPUT;
ft_trace_fp = fopen("/tmp/my_trace_file", "a");
ft_trace_max_udata = 256

else
ft_trace = 0 /*To be safe, always initialize it*/

/*Then do whatever you have to do*/
}

Interpreting the Trace File

Every time a routine is entered and exited, the time (in hh:mm:ss format) and the name of the call are shown. First the -> arrow indicates the beginning of the call, then the input parameters are shown, and then the %<- arrow indicates the exit. The number following the %<- arrow is the integer value of the return code for that call. A value of 0 indicates that there were no errors. If an integer other than 0 is returned, refer to the /opt/ftam/includei/mapftam.h file to determine which return code corresponds to the integer, and then refer to the "FTAM return_codes" chapter of the HP FTAM/9000 Reference Manual for the cause of the return code and corrective actions you can take.

The following is an example trace file for an HP FTAM session.

Tue Sep 1 08:55:14 1992 ->ft_aeactivation()
   my_ae_name = 0x5a718
   return_event_name = 0
   input_dcb->authentication = NULL
   input_dcb->my ae_title_option = User_object_id_option
   input_dcb->my ae_title = 0x5a908
Tue Sep 1 08:55:15 1992 %<-ft_aeactivation() = 0

Tue Sep 1 08:55:15 1992 ->ft_connect()
   ae_label = 0x202c0006
   return_even_name = 0
   called_ae_name = 0x5a9bc
   input_dcb->called_presentation_address = 0x0
   input_dcb->called_ae_title_option = User_object_id_option
   input_dcb->called_ae_title = 0x5ac14
   input_dcb->called_ae_invoke_id = 0x80000000
   input_dcb->called_ap_invoke_id = 0x80000000
   input_dcb->number_of_retry = 0
   input_dcb->delay_between_retry = 0
   input_dcb->connection_resource_wait_timer = 0
   input_dcb->context_name = 1 0 8571 1 1
   input_dcb->connect_in_info.service_class:
     FT_SC_TRANSFER
     FT_SC_TRANSFER_AND_MGMT
   input_dcb->connect_in_info.functional_units:
     FT_FU_READ
     FT_FU_WRITE
   input_dcb->connect_in_info.attribute_groups
     FT_AG_STORAGE
     FT_AG_PRIVATE
   input_dcb->connect_in_info.quality_of_service = FT_NO_RECOVERY
   input_dcb->connect_in_info.contents_type_list: 0x5ac74
   input_dcb->connect_in_info.contents_type_list.contents_type.connects_form =      
     FT_DOCUMENT_TYPE
   contents_type->contents_info.document.name.length = 5
   contents_type->contents_info.document.name.element: 1 0 8571 5 3
   input_dcb->connect_in_info.initiator_identity = "root"
   input_dcb->connect_in_info.account = "account"
   input_dcb->connect_in_info.file_store_pw = "ftam"
Tue Sep 1 08:55:17 1992 %<-ft_connect() = 0

Tue Sep 1 08:55:18 1992 ->ft_open()
   connection_id = 65535
   processing_mode:
     FT_PM_READ
     FT_PM_REPLACE
     FT_PM_EXTEND
     FT_PM_ERASE
   contents_type->contents_info.document.name.length = 5
   contents_type->contents_info.document.name.element: 1 0 8571 5 3
   return_event_name = 0
   input_dcb->concurrency_control = NULL
Tue Sep 1 08:55:18 1992 %<-ft_open() = 0

Tue Sep 1 08:55:18 1992 ->ft_read()
   connection_id = 65536
   fadu_identity->fadu_form = FT_FADU_LOCATION
   fadu_identity->fadu_info.fadu_location = FT_FIRST
   access_context = UNSTRUCTURED_ALL_DATA_UNITS
   return_event_name = 0
Tue Sep 1 08:55:18 1992 %<-ft_read() = 0

Tue Sep 1 08:55:19 1992 ->ft_close()
   connection_id = 65535
   return_event_name = 2
Tue Sep 1 08:55:19 1992 %<-ft_close() = 0

Using API Tracing

Technical documentation

» Table of Contents

» Glossary

» Index

API Tracing Variables

Enabling API Tracing

Interpreting the Trace File