FTAM/9000 Programmer's Guide

62 Chapter 2
Using HP FTAM/9000
Using Parameters
For asynchronous calls, you should not access the inout_dcb memory
from the time the asynchronous call returns SUCCESS until em_wait()
verifies completion of the request; otherwise, the memory occupied by the
inout_dcb contains random data.
You can allocate memory for inout_dcb in three ways.
1. The recommended method is to have the inout_dcb address reference
a NULL value when first making the call.
• By doing so, the FTAM interface allocates the memory necessary;
thus, you avoid having to anticipate how much memory is
required.
• After the FTAM function returns (for asynchronous calls, after
em_wait() returns SUCCESS), you must call ft_dfdcb() to free the
memory.
NOTE The next two methods described require you to manually allocate
memory, and they carry some risk. It can be hard to predict how much
memory to allocate, and failure to allocate enough can cause a run-time
error. Consequently, HP encourages programmers to allow the FTAM
interface to allocate DCB memory. Use one of these last two methods
only if you have high performance requirements that are seriously
compromised by the allocation and deallocation time in the first method.
2. Allocate the memory yourself (e.g., using malloc() or using variables).
Ensure the size is large enough to hold the inout_dcb structure and all
data it may reference. This memory should include a diagnostic list
that may contain from 0 to 12 elements. You can then pass the
address of the allocated space to the interface.
3. Before the request, invoke ft_didcb() to allocate memory for
inout_dcb. Ensure the additional_size parameter is large enough to
hold the inout_dcb structure and all data it may reference. After
em_wait() returns SUCCESS, invoke ft_dfdcb() to free the memory
used by inout_dcb.