Ft_data_unit

struct  Ft_data_unit {
     struct  Ft_data_unit          *next;
     enum Ft_structure_id          structure_id;
     union {
         struct Ft_data_element    *data_element;
         struct Ft_node_descriptor *node;
     } data;
};

Ft_data_unit Is Input To These Functions	Ft_data_unit Is Output From These Functions
ft_sdata()	ft_rdata()

Ft_data_unit is a linked list of data units (maximum 14 data units per call). Each data unit contains the data that FTAM manipulates (Figure 3-8 “Ft_data_unitcStructure”).

The responder uses Ft_data_unit to return data when you call ft_rdata().

For variable and fixed data, data element boundaries are preserved. You receive the exact sequence of data elements that existed in the original file.

If Ft_string_significance is FT_SS_NO_SIGNIFICANCE, data element boundaries are ignored. Up until the final data element, the responder returns the maximum string_length allowed per data element. The final data element contains the remaining data.

Figure 3-8 Ft_data_unitcStructure




	NOTE: To understand Ft_data_unit, you should be familiar with the concepts FADU, data unit, data element, and node descriptor. Refer to the "HP-UX FTAM Overview" chapter for descriptions.

*next	Points to the next Ft_data_unit structures in the linked list. The maximum is 14.
structure_id	Specifies which structure in the data union is applicable.
data	The data union contains data_element and node. The value you choose in Ft_structure_id dictates which structure you choose in the data union. The data_element is of type struct Ft_data_element and contains the actual data. The node is of type struct Ft_node_descriptor and indicates a new FADU.

Ft_structure_id

enum     Ft_structure_id  {
                        FT_DATA_UNIT        = 0,
                        FT_NODE_DESC        = 1,
                        FT_ENTER_SUBTREE    = 2,
                        FT_EXIT_SUBTREE     = 3,
                        FT_DATA_END_IND     = 4,
                        FT_CANCEL_IND       = 5
};

Ft_structure_id specifies which structure in the data union is applicable (Ft_data_element or Ft_node_descriptor) or it specifies the end or cancellation of data transfer (on output only).

FT_DATA_UNIT	Use FT_DATA_UNIT to send actual data. FT_DATA_UNIT dictates that you choose data_element in the data union.
FT_NODE_DESC	Use FT_NODE_DESC only for FTAM-2 document types to begin a new FADU. FT_NODE_DESC dictates that you choose node in the data union.
FT_ENTER SUBTREE FT_EXIT_SUBTREE	HP-UX responders return an error if you use either of these values.
FT_DATA_END_IND	When using ft_rdata(), FTAM returns FT_DATA_END_IND in inout_dcb.data_unit->structure_id to indicate data transmission is complete.
FT_CANCEL_IND	If an error occurs when transferring data, FTAM returns FT_CANCEL_IND in inout_dcb.data_unit->structure_id to indicate data transmission is cancelled. To acknowledge the data transfer was cancelled, you must issue ft_rcancel() to exit the Data Transfer regime.

Ft_data_element

struct  Ft_data_element {
        enum Ft_prim_type {
                         FT_DE_BOOLEAN             = 1,
                         FT_DE_INTEGER             = 2,
                         FT_DE_BIT_STRING          = 3,
                         FT_DE_OCTET_STRING        = 4,
                         FT_DE_NULL                = 5,
                         FT_DE_IA5_STRING          = 22,
                         FT_DE_UTC                 = 23,
                         FT_DE_TIME                = 24,
                         FT_DE_GRAPHIC_STRING      = 25,
                         FT_DE_VISIBLE_STRING      = 26,
                         FT_DE_GENERAL_STRING      = 27,
                         FT_DE_FLOATING_POINT      = 100,
                         FT_DE_UL_FLOAT            = 101,
                         FT_DE_UL_INTEGER          = 102,
                         FT_DE_ATTRIBUTES          = 200
                         FT_DE_RECORD_END          = 201
                         FT_DE_RECORD_CONT         = 202
        } prim_type;
        union Ft_primitive {
           Bool                         boolean;
           Sint32                       integer;
           struct Bit_string            bit_string; 
           struct Octet_string          octet_string;
           struct Octet_string          ia5string;
           Time                         utc;
           Time                         time;
           char                         *graphic_string;
           char                         *visible_string;
           struct Octet_string          general_string;
           double                       floating_point;
           struct Octet_string          ul_integer;
           struct Ft_ul_floating_point {
               Sint16                   sign;
               struct Bit_string        mantissa;
               struct Octet_string      exponent;
           } ul_floating_point;
           struct Ft_attributes         attributes;
           struct Octet_string          record_end;
           struct Octet_string          record_cont;
        } primitive;
};

Set Ft_data_element if you specified FT_DATA_UNIT in Ft_structure_id.

Ft_data_element contains an enum Ft_prim_type that indicates which primitive is relevant in union Ft_primitive (Figure 3-9 “Ft_data_element Structure”).

Figure 3-9 Ft_data_element Structure

prim_type

The prim_type specifies which field in the primitive union to select. Only a subset is valid for each document type:

FTAM-1

FTAM-2

FTAM-3 and INTAP-1

NBS-9

IA5_STRING

GENERAL_STRING

GRAPHIC_STRING

GENERAL_STRING

GRAPHIC_STRINGGENERAL_STRING

OCTET_STRING

ATTRIBUTE

primitive

The primitive is the specific unit that contains actual data. Set primitive to the value specified by prim_type. See the previous table. Note that the maximum string length is 7168 (7K) octets.

EXAMPLE:

This example sets a data_element for FTAM-2 document type.

struct Ft_data_unit                  data_unit;
 
 
data_unit.next = NULL;
data_unit.structure_id = FT_DATA_UNIT;
data_unit.data.data_element = (struct Ft_data_element *)
malloc(sizeof (struct Ft_data_element));
 
 
data_unit.data.data_element->prim_type = FT_DE_GRAPHIC_STRING;
data_unit.data.data_element->primitive.graphic_string =
"This example shows data in a data element;"

Ft_node_descriptor

struct  Ft_node_descriptor {
        Ft_fadu_name        fadu_name;
        Uint16              arc_length;
        Bool                data_exists;
};

Set Ft_node_descriptor if you specified FT_NODE_DESC in Ft_structure_id (Figure 3-10 “Ft_node_descriptor Structure”).

Use Ft_node_descriptor only with FTAM-2 document types to begin a new FADU.

Figure 3-10 Ft_node_descriptor Structure

fadu_name

HP-UX responders accept, but ignore, the fadu_name field. HP recommends you set the fadu_name.length to zero and fadu_name.pointer to NULL.

arc_length

You must set arc_length to 1 since FTAM-2 is confined by the sequential flat constraint set (which has only one hierarchical level).

data_exists

You must set data_exists to TRUE since all FADUs must contain data.

EXAMPLE:

This example sets the node_descriptor for an FTAM-2 document type.

struct Ft_data_unit                  data_unit;
data_unit.next = NULL;
data_unit.structure_id = FT_NODE_DESC;
data_unit.data_node = (struct Ft_node_descriptor *)
     malloc(sizeof (struct Ft_node_descriptor));
data_unit.data.node->fadu_name.length = 0;
data_unit.data.node->fadu_name.pointer = NULL;
data_unit.data.node->arc_length = 1;
data_unit.data.node->data_exists = TRUE;




	NOTE: Creating the Ft_data_unit linked lists for FTAM-2 document types requires that you follow a few rules. First, familiarize yourself with the Ft_node_descriptor structure. Then read the next section, which describes the necessary rules.

Rules for Ft_data_unit Linked Lists (FTAM-2 Only)

The following rules apply to Ft_data_unit linked lists for FTAM-2 document types only.

If you have an empty file, you must begin the linked list with a node descriptor (not a data element).
If a file already contains data, you may or may not have a node descriptor, depending on whether you are starting a new FADU.
Do not immediately follow a node descriptor with another node descriptor.
You may, however, follow a data element with another data element (i.e., node descriptors may have multiple data elements).
You may submit an ft_sdata() request containing only a node descriptor, though you must follow it with an ft_sdata() request that starts with a data element.
Do not use more than one node descriptor per ft_sdata() request.
You must set node.arc_length to 1.
You must set data_exists to TRUE since FADUs must contain data.

Ft_data_unit

Technical documentation

» Table of Contents

» Glossary

» Index

Ft_structure_id

Ft_data_element

Ft_node_descriptor

Rules for Ft_data_unit Linked Lists (FTAM-2 Only)