Appendix D - HLLAPI Trace Utility
This appendix describes the HLLAPI trace utility. This set of programs is designed to help developers who are writing applications using the Banyan HLLAPI interface with Advanced 3270/SNA. This appendix discusses the following topics:
What files are involved in tracing HLLAPI calls, and what each file does. How to load the HLLAPI trace. Information to help you interpret the data generated by the HLLAPI trace utility. The HLLAPI Trace Programming Interface. This programming interface is for developers who want to write customized trace routines.
There are five programs in the HLLAPI Trace utility.
TRON TRACE TRDS TRUN TRPR
TRON turns the trace utility on. Use the following command format to start HLLAPI trace.
TRON proto maxbytes
Proto is the prototype file name to use. Trace files are formed as proto.0 and proto.1. For example, if you specify the name TRFILE, TRON creates two files called TRFILE.0 and TRFILE.1.
When the first file reaches the maximum size, that file is closed and the output is directed into the second file. When the second file reaches the maximum size, the second file is closed and trace starts to overwrite the first file. This continues until trace is disabled.
If you do not specify a path for the files, the files will be created in the same subdirectory as TRON.EXE.
Maxbytes is a limit on the size of each trace data file. 0, which is the default, causes no limit to be used.
TRACE is the resident portion of the trace utility. It is manipulated through the programs described in this section. For instructions on loading this program into memory, refer to the section called "Loading the HLLAPI Trace Utility," later in this appendix.
TRDS disables tracing and forces a close of the current trace data file.
TRUN forces a close of the current trace data file, and unloads the HLLAPI trace utility from memory.
TRPR inteprets trace data files and displays the interpreted results. To run this program, enter the following command format at the DOS prompt:
TRPR file0 file1 ... filen
TRPR can interpret as many files as you can fit on the command line. The files are interpreted in the order that they appear on the command line.
Loading the HLLAPI Trace Utility
When TRACE is resident, HLLAPI calls are traced in to and out of any EEHLLAPI compatible DOS interface. TRACE must be loaded after the HLLAPI interface. The following batch file loads the trace utility.
RA3270
HLLAPI
E3270 %1
TRACE
The configuration file you specify on the command line should have the Go Resident field on the Workstation Control Parameters screen set to YES.
TRACE intercepts Interrupt 7f in order to perform the tracing function.
There are two types of trace output. Trace Type 0 generates detailed information about the HLLAPI call. Trace Type 1 displays the number of times that the previous Trace Type 0 data occurs.
The format of the trace data for Trace Type 0 is shown in Table D-1.
| Offset | Length | Description |
| 0x00 | 1 byte | This byte contains a 0. This sets the Trace Type to 0. |
| 0x01 | 2 bytes | These two bytes are a direction flag. If the value set here is either 0 or 1, the trace represents data going into HLLAPI. If the value set is greater than 1, trace data is coming from HLLAPI. |
| 0x03 | 3 bytes | HLLAPI Parameter Control Block header. The value of these three bytes is 'PCB.' |
| 0x06 | 1 byte | HLLAPI function code value. |
| 0x07 | 2 bytes | String segment address. |
| 0x09 | 2 bytes | String offset address. |
| 0x0B | 2 bytes | Data length value. |
| 0x0D | 1 byte | Unused. |
| 0x0E | 2 bytes | Return code value. |
| 0x10 | 2 bytes | Maximum user string size. (Must equal 25000.) |
| 0x12 | 2 bytes | Length of string data. If = 0, then no string data. |
| 0x14 | n bytes | String data (if any). |
The format of the trace data for Trace Type 1 is shown in Table D-2.
| Offset | Length | Description |
| 0x00 | 1 byte | This byte contains a 1. This sets the Trace Type to 1. |
| 0x01 | 4 bytes | Previous entry duplication count. |
HLLAPI Trace Programming Interface
Communication with the HLLAPI trace utility is supported through Interrupt 0x2fh. The following HLLAPI trace function calls enable tracing, disable tracing, and unload TRACE from PC memory.
On Input:
ax = 0d70ah
bx = 0
ds:dx = Pointer to argument block
This function turns on the trace function. TRACE must be present in PC memory for this function to work properly.
The argument block for function 0 is shown in Table D-3.
| Offset | Length | Description |
| 0x00 | 4 bytes | Offset/seg of ASCIIZ prototype pathname.Trace Type is set to 1. |
| 0x04 | 4 bytes | Maximum size of each trace file flip flops between 2 files) |
On Input:
ax = 0d70ah
bx = 1
This function turns off the HLLAPI trace function, but leaves it in memory so that it can be enabled at a later time.
On Input:
ax = 0d70ah
bx = 2
This function disables the HLLAPI trace function, and removes it from memory.
