FTAM/9000 Programmer's Guide

158 Chapter 3
HP FTAM/9000 Data Structures
inout_dcb
You must either pass the address of an inout_dcb or you must pass the
address of a a NULL value. If you pass the address of an inout_dcb, you
must have enough memory to return size and result. You may or may not
supply additional values, depending on the function.
Memory Allocation for inout_dcbs
For asynchronous calls, the memory occupied by Ft_output and
Ft_xxx_out_dcb is logically inconsistent until the request completes.
Therefore, you should not reference the inout_dcb from the time the
asynchronous call returns SUCCESS until em_wait() verifies completion
of the request.
You can allocate memory for Ft_output and Ft_xxx_out_dcb in three
ways.
• The recommended method is to have the output inout_dcb parameter
reference the address of a NULL value when 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 or for asynchronous calls, after
em_wait() returns SUCCESS, you must call ft_dfdcb() to free the
memory (even though the FTAM interface allocated the memory).
• Allocate the memory yourself (e.g., using malloc() or using variables).
Ensure the size field is large enough to hold all possible return
information; otherwise, you may receive an
FTE004_OUTPUT_BUFFER_OVERFLOW error. For example, you
want to have a size large enough to store the inout_dcb structure and
all possible returning diagnostics (a linked list of 14).
• Before the request, invoke ft_didcb() to allocate memory for
Ft_xxx_out_dcb. Free the memory used by the input_dcb parameter
by invoking ft_dfdcb() after the function returns (synchronous calls)
or after em_wait() returns (asynchronous calls). Ensure the
size The size of the Ft_xxx_out_dcb structure and associated data
in Octets. The size parameter is mandatory input if using
Ft_xxx_out_dcb.
result The result is of type Api_rc and provides error information.