 |
» |
|
|
|
This section discusses parameters to FTAM functions, focussing
on the input_dcb and inout_dcb parameters. For information on specific
parameters, determine the function using the parameter; then use
the Table of Contents to locate the chapter explaining that function. Parameters are the mechanisms for exchanging information between
your application and the FTAM interface. Parameters may be any of
the following types: Input to the function, Output from the function Exposed (in the function's parameter list) or Internal
(as a component of a data structure called a DCB in the parameter
list)
Data Control Blocks | |
Data control blocks (DCBs) are C structures used as function
parameters to pass information between your application and the
FTAM interface. Most FTAM functions use both an input_dcb and an inout_dcb. The values used within input_dcb depend on the function requirements.
If any of the input_dcb parameters are mandatory, you must pass
a non-NULL address of an input_dcb; otherwise, you can pass a NULL
value. You can allocate memory for the input_dcb two ways. Allocate the memory yourself (e.g.,
using malloc() or by using variables). Before the request, invoke ft_didcb() to allocate
memory for input_dcb. After the request completes, invoke ft_dfdcb()
to free the memory used by input_dcb.
After the function call returns, you can immediately reclaim
or reuse memory occupied by input_dcb. Use the inout_dcb to obtain output information in the user
program. When passing the inout_dcb to the interface, you must pass
an address that references either a non-NULL or NULL value. Except for size, all parameters in the inout_dcb are output
parameters. Note, however, some output parameters are exposed rather
than being part of the inout_dcb (e.g., connection_id on the ft_connect()
function call). The size and result fields are always present in the inout_dcb.
Other inout_dcb fields may be present, depending on the function. 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. 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.
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. 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.
|
Printable version
