OSI/FTAM Programming Reference Manual

FTM Procedures
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4-55
FTM_DATA_IND_
Considerations
•
To complete this procedure call successfully, you must have previously called the
FTM_READ_REQ_, and the association must be in the data-transfer regime.
•
You must call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data.
•
The size of the data-value buffer, which you specify via the buffer-size
parameter, must be large enough to contain ZAPS-DDL-DATA-HDR, ZAPS-DDL-
DATA-ELEMENT-HDR, and the current data element. The surest buffer size to use
is 25 KB because that size ensures that the application can retrieve the entire
FDATA indication in one call to the FTM_DATA_IND_ procedure. (An application
can call FTM_DATA_IND_ multiple times if the application’s data-value
parameter is too small to receive all available data in one call.)
However, for an application managing many associations, a buffer size of 25 KB
might consume too much of the application’s memory. If you wish to specify a
smaller buffer, bear in mind that the minimum buffer size is the sum of the length of
ZAPS-DDL-DATA-HDR, the length of ZAPS-DDL-DATA-ELEMENT-HDR, and the
value of the negotiated or default maximum-string-length parameter, which
will allow you to read a single data element and its headers.
•
If data is available (and buffer-size contains a valid nonzero value), the
minimum information returned in data-value includes the following:
°
ZAPS-DDL-DATA-HDR
°
ZAPS-DDL-DATA-ELEMENT-HDR
°
At least 1 octet of data.
•
To determine the size of the incoming data without actually retrieving the data, call
FTM_DATA_IND_ with buffer-size and start-position set to 0. The
more-data output parameter then returns the number of octets to be read.
•
The data-value parameter is identical for both the FTM_DATA_REQ_ and
FTM_DATA_IND_ procedure calls. This parameter consists of a data header
followed by a series of one or more data elements. Each data element consists of
a data element header and the actual data. Figure 4-2
on page 4-50 shows the
structure of data-value.
ZAPS-DDL-DATA-HDR and ZAPS-DDL-DATA-ELEMENT-HDR of the
data-value structure are defined in the file ZAPSDDL. The TAL and C
equivalents are located in the files ZAPSTAL and ZAPSC, respectively. For
descriptions of both structures, see Appendix A, DDL Definitions.
All structures are word addressed and must therefore begin on word boundaries. If
the length of one of the data elements is an odd number, the initiator inserts a pad
byte at the end of the data. For sample program code illustrating how to
accommodate pad bytes, see the OSI/FTAM Programming Guide.