OSI/FTAM Programming Guide

NonStop FTAM Programming
HP NonStop OSI/FTAM Programming Guide—528612-001
3-25
FTAM-2 Files
You must use a separate data element for each string. String length must be less than
or equal to the value of maximum-string-length proposed by the
FTM_OPEN_REQ_ or FTM_FILE_OPEN_REQ_ procedure or returned in the
contents-type parameter by the FTM_OPEN_CNF_ or FTM_FILE_OPEN_CNF_
procedure. If the string length is greater than the proposed maximum-string-length, the
initiator returns an error to the application.
Reading FTAM-2 Files
To read an FTAM-2 file, first open the file using an FTM_OPEN_REQ_ or
FTM_FILE_OPEN_REQ_ procedure with a process-mode parameter of read. If you
want to transfer node descriptors as well as data, use a fadu-id parameter value of
begin and an access-context parameter value of FA on the FTM_READ_REQ_
procedure call. Alternatively, you can use an access-context parameter value of
UA. In this case, the node-descriptor data elements are not returned, and it is not
possible to distinguish between different nodes of the file.
The entire file is then returned by successive F-DATA indication events. After receiving
each data indication event (ZFTM-VAL-EVT-DATA-IND), call the FTM_DATA_IND_
procedure one or more times to retrieve the data. (For the structure of the
data-value parameter for files with an access-context parameter of UA, see
Figure 3-8 on page 3-23, and for files with an access-context parameter of FA, see
Figure 3-9 on page 3-24.)
Each encoded string in the F-DATA indication is placed in a separate data element as
raw data. Node descriptors are placed in separate data elements of type
ZFTM-VAL-DE-FADU in the same way as described above for writing files.
You can read individual nodes of an FTAM-2 file by using a fadu-id of first, last,
current, next, previous, or a node number. If you are reading just one node, use an
access-context of UA because you do not need a node descriptor in that case. For
information about the above fadu-id values, refer to Section 2, ISO FTAM Concepts
or ISO 8571, Part 2.
The universal-class parameter of the contents-type parameter returned by the
FTM_OPEN_CNF_ or FTM_FILE_OPEN_CNF_ procedure call determines how your
application interprets carriage-return/line-feed pairs. If the universal-class
parameter indicates a character set with format effectors, the application interprets
carriage return/ line-feed pairs as end-of-line indicators. Otherwise, the end of each
encoded string implies carriage-return/line-feed formatting actions; each line is
provided in a separate data element. These interpretations remain valid whether your
application is reading an entire FTAM-2 file or only a single FTAM-2 node.
The initiator checks the length of each string against the maximum-string-length
value proposed in the contents-type parameter of the open request or returned in
the open confirm. If the string length is greater than the proposed maximum-string
length, the initiator issues a provider abort.