OSI/AS Programming Manual

Sending and Retrieving User Data
APS Procedures Programming Concepts
2–48 056783 Tandem Computers Incorporated
When your application receives one of these primitives on a call to
APS_EVENT_RECEIVE_ , the data is stored in the API internal data area. To read the
data into your buffer, you then call APS_DATA_GETPARAM_. (If you call
APS_DATA_GETPARAM_ when no user data is available, you receive the error code
ZAPS-ERR-NO-DATA.) Although the primitives marked with an asterisk (*) in the
table can contain incoming user data only for session version 2, it is recommended that
your application call APS_DATA_GETPARAM_ for all the listed primitives, to be sure
no data is missed.
To find out if the incoming data is too long to fit into your buffer, include more-data
in your APS_DATA_GETPARAM_ procedure call. OSI/AS returns the length of the
user data not yet returned to you. Call APS_DATA_GETPARAM_ repeatedly until
more-data is returned as zero. For information on how to do this, see Table 2-18
and the considerations for the APS_DATA_GETPARAM_ procedure in Section 3.
Table 2-18 gives the sequence of procedure calls needed to retrieve user data. The
sequence of procedures is explained after the table.
.i.User data:retrieving:sequence of procedures for
.i.Procedures, APS:data retrieval sequence
Table 2-18. Sequence of Procedures to Retrieve User Data
Procedure What You’re Asking OSI/AS
Other procedure(s) See steps following this table.
APS_DATA_GETPARAM_ Transfer data to my buffer.
APS_DATA_GETPARAM_ (If more data) Transfer more data.
The following steps explain the user data retrieval sequence given in Table 2-18. See
also the next subsection, “Avoiding Concatenation of Incoming User Data.”
1. During an established connection, you receive a primitive that can contain user
data (see Table 2-17). Consult Table 2-2 or Table 2-4 and then call the procedure, if
any, listed (preceding APS_DATA_GETPARAM_) for that primitive.
2. Call APS_DATA_GETPARAM_ to transfer data to your buffer. Since the data is
already in the API internal data area, no file-system I/O is needed. Even in nowait
mode, do not call MFM_AWAITIOX_ to complete the APS_DATA_GETPARAM_
procedure call.
For a presentation or ACSE connection, decode the user data; see “User Data
Encoding,” earlier in this section.
3. If the value returned by more-data of the previous call shows that you have not
yet read all the data, call APS_DATA_GETPARAM_ again. Use the value
returned by next-position of the previous call as the start-position .
4. Call APS_DATA_GETPARAM_ again (and again, if necessary), until more-data
is zero.