		     HDF Performance Data Capture
			     README.Pablo
			   September 16, 1998


This file briefly summarizes how to use the instrumented version of
HDF and the Pablo performance data capture libraries to gather data
about I/O behavior and procedure execution times.  More detailed
documentation is provided in a PostScript Pablo.ps. The same information
is also provided in Microsoft Word format in Pablo.doc and in PDF format in
Pablo.pdf.
				 ---

The Pablo software, including the performance data capture libraries
and analysis tools, are available via anonymous FTP on

	www-pablo.cs.uiuc.edu (128.174.237.148)

Version 5.1 or higher of the Pablo TraceLibrary is required.
				 ---

When linking your application, the instrumented HDF library must come
first, followed by PabloTraceExt, and finally PabloTrace.  For
example:

	-ldf-inst -lPabloTraceExt -lPabloTrace

				 ---

To gather performance data, your application must call HDFinitIOTrace
to initialize tracing, and HDFendIOTrace to terminate tracing.

C:	
	void HDFinitTrace(char *traceFName, unsigned procMask, int traceType );


	traceFName	IN:	name of the generated trace output file
	procMask	IN:	families of HDF procedures to trace
	traceType	IN:	an integer indicating the type of tracing
 				to be performed:
			        traceType = 0, no trace file is produced
				          = 1, perform Runtime Tracing
					  = 2, perform Summary Tracing
	(see the document Pablo.ps, Pablo.doc or Pablo.pdf for further 
         information)

	Purpose		Initializes tracing.

	Return value	None.

	Description	This routine causes HDF to generate trace
			events for I/O operations and procedure calls.

		        Runtime Tracing produces an SDDF file containing
  		 	a packet of information produced for each entry and
 			each exit from HDF traced routines.

	  		Summary Tracing produces an SDDF file containing one
			packet of information for each traced routine 
			summarizing all calls to that procedure.
	
			See Pablo.ps, Pablo.pdf, or Pablo.doc for further 
			explanation.

	Example		#include "ProcMasks.h"

			HDFinitTrace("trace.bin", DFP_mask + DFR8_mask, 1 )

	void HDFendTrace( void );

	Purpose		Terminates tracing.

	Return value	None.

	Description	This routine causes Pablo to cleanup files and end
                        tracing
			
FORTRAN:
	subroutine HDFinitTrace(tracefn, procMask, traceType )

	character*(*) tracefn	
	integer procMask
	integer traceType

	see description under C above

	Example 	include 'ProcMasks.inc'
			
			call HDFinitTrace( 'tracefn', dfp_mask + dfr8_mask, 22)

	subroutine HDFendTrace( )

	see description under C above

				 ---

The performance data can be manipulated by a variety of analysis tools
in the Pablo software.  The Pablo HDFanalysis component contains tools  
specifically for this analysis.

