Overview of FTAM Concepts

This section takes a high-level approach to explaining concepts you should know before writing FTAM applications. This section also refers to specific FTAM functions. For detailed information regarding these concepts and functions, refer to the Table of Contents for specific chapters and sections.

The Virtual Filestore (VFS)

A real filestore uses a variety of mechanisms to structure, store, and retrieve real files. For example, files on HP-UX systems are stored and accessed as a stream of bytes; on other systems files might be stored and accessed as fixed- or variable-length records, or in other ways.

To conceal these storage and access differences, the FTAM specification defines a Virtual Filestore, or VFS. The VFS provides a uniform interface to all real file systems. It uses a system-independent model for describing files and their attributes. Though it represents real files, it masks the system- dependent differences in style and structure. (Refer to Figure 1-1 “HP-UX FTAM Virtual Filestore (VFS)”.)

FTAM implementations map the VFS onto a real filestore. The mapping function (from the open system to the real system) absorbs the style and specification differences. You do not need to know the vendor, operating system, or file system with which you want to communicate. You need only know a file's complete name and where it is located. (However, you may need to read the other vendor's PIC statement.)

Figure 1-1 HP-UX FTAM Virtual Filestore (VFS)

FTAM Shadow Files

Because the VFS is generalized, certain VFS concepts have no direct correspondence to the HP-UX file system. For example, a VFS file might have fixed-length records. Such records are not defined for the HP-UX file system.

To provide HP-UX files with FTAM VFS attributes, HP-UX uses two files: an actual file and an optional shadow file.

The actual file contains the data for the file. The ownership and permissions for the file are related to, but distinct from, the FTAM attributes for the file.
The shadow file contains only the FTAM VFS attributes for the file.

The actual and shadow files taken together make an "FTAM file." The shadow file for an HP-UX file has the same name as the HP-UX file, prefixed by "._". For example, the FTAM file named myfile has a corresponding shadow file named ._myfile. Like all files that begin with a period, FTAM shadow files can be listed with the following command:

$ ls -a

Certain FTAM attributes—such as document type—exist only in the shadow file. Other FTAM attributes—such as file name—are mapped to normal HP-UX file attributes. Some FTAM attributes—such as access control— include a combination of HP-UX file attributes and shadow file information.

The shadow file is not always necessary to read or delete a file. For these actions, FTAM uses default attributes. However, whenever FTAM creates or modifies a file, it always creates a corresponding shadow file.




	NOTE: Other FTAM products from other vendors may implement the VFS using methods other than shadow files.

Shadow File Cautions

Use caution when employing HP-UX utilities with FTAM-related files. The following examples illustrate the kinds of issues that can arise:

If you use mv to rename or relocate an FTAM-related file, the corresponding shadow file will not be rename or relocated. Subsequent FTAM access to the file will use default VFS attributes, which may or may not apply.
If you use cp to create a new copy of an FTAM-related file, a corresponding shadow file will not be created. Subsequent FTAM access to the copy will use default VFS attributes, which may or may not apply.
If you use chmod or chown to change the HP-UX permissions or ownership of an FTAM-related file, the new attributes may conflict with the attributes stored in the corresponding shadow file. Subsequent FTAM access to the file may have unexpected results or cause inconsistencies.
If you use rm to remove an FTAM-related file, the corresponding shadow file will not be removed.

Shadow files that are inadvertently severed from their corresponding actual files remain as clutter. Furthermore, they could potentially interfere with future FTAM operations on files that have the same name as the original actual file.

Regimes

An FTAM transaction is built by calling FTAM functions in steps (or nested state sequences) called regimes. A regime is the period during which you can issue a specific set of FTAM functions. The regime determines the activities that can occur at a given time and therefore, creates the rules (protocols) for the FTAM state machine.

Regimes are nested, in the following order. Applications must pass through outer regimes to gain access to the inner ones. They must also exit the regimes in proper order, leaving the inner regimes to gain access to the outer ones.

FTAM Regime
File Selection Regime
File Open Regime
Data Transfer Regime

Figure 1-2 FTAM Regime Order

FTAM Regime	The FTAM regime requests FTAM services for the connection. The FTAM regime, also called the FTAM Association or FTAM Initialization regime, is the outermost regime.
File Selection Regime	The File Selection regime references (selects) a specific file. You can change and read attributes during this regime.
File Open Regime	During the File Open regime, a file's contents are available for access: reading, writing, locating, and erasing.
Data Transfer Regime	The Data Transfer regime is the innermost regime; it supports the transfer of actual data.

FTAM Communication

The following sections describe the basic means of FTAM communication: initiators, responders, application entities, synchronous calls, asynchronous calls, high and low level functions, and context free and context sensitive functions.

Initiators and Responders

As noted earlier, you write a program (user program) to access the FTAM interface using a library of functions. FTAM uses the initiator to make requests and the responder to service them. (Refer to Figure 1-3 “FTAM Communication Process”.)

Initiator

The initiator submits requests on behalf of you. When you submit a request (i.e., call a function), the initiator sends your request to a responder.

The executable name for an HP-UX initiator is ftam_init (located in /opt/ftam/lbin). To use an FTAM function, you must link your application with the libmapftam.a library. The ftam_init process is also known as the initiator server provider process (SPP). Refer to the "Using FTAM" chapter for information on linking FTAM libraries.
The ftam_init is invoked when you call ft_aeactivation(), and serves also as a responder for local FTAM requests. For information on ft_aeactivation(), refer to the "Managing FTAM Connections" chapter.
The ftam_init is invoked when you call a high level function with the default ae_label (i.e., pointer to a NULL location). For information on high level functions, refer to the "Using FTAM" chapter.

Responder

The responder receives and services an initiator's request. If applicable, it returns a response.

The executable name for an HP-UX responder is ftam_resp (located in /opt/ftam/lbin). The ftam_resp is a daemon process that provides the interface for the HP-UX file system (real filestore) to the FTAM VFS. Note that the ftam_resp is also known as the responder SPP.
One ftam_resp process exists for each active, remote FTAM connection. Connections to a local responder do not require an invocation of ftam_resp.
An ftam_resp daemon process must be active to receive remote connection requests. After receiving a request, ftam_resp forks the process to create another ftam_resp process, which then processes all requests associated with that connection.

Figure 1-3 FTAM Communication Process

Application Entities (AEs)

An application entity (AE) is a uniquely identified component of your application that associates it with the OSI communications network. An AE may be an FTAM initiator or responder.

Before locating, accessing, or manipulating FTAM files, you must establish communication (initialize an FTAM regime) with the AE (FTAM responder) that services the desired filestore.

Identify the AE by specifying either the entity's presentation address (P_address) or its directory distinguished name (Ae_dir_name). These addresses are defined during system configuration and when nodes are added to the network. Consult your system administrator for the address information.




	NOTE: Refer to the "FTAM Data Structures" chapter for information on the P_address and Dir_dn structures. Refer to the Installing and Administering HP FTAM/9000 manual and the OSI Troubleshooting Guide for information on the presentation address and directory distinguished name configuration.

Once you establish the FTAM regime, you can access and manipulate FTAM files in that filestore. You can perform two types of file actions on the VFS: actions on complete files and file access actions. For example, you can create and delete a complete file or access a portion of a file's contents.

Synchronous and Asynchronous Operations

FTAM functions use two modes of operation: synchronous and asynchronous:

Synchronous Operations

Synchronous function calls return only after the request is completely processed. Therefore, all output information is available when the call returns. Make synchronous function calls when the results must be processed in a specific sequence.

Asynchronous Operations

Asynchronous function calls return as soon as ftam_init validates the request. Processing continues on the request. To determine whether the request returns successfully from the responder, you must call em_wait(). Output information is available only after the em_wait() function indicates that processing of the request has completed. Use asynchronous function calls when making multiple requests and when the order in which results are processed does not matter. You can perform other operations while an asynchronous request is being processed.




	NOTE: Refer to the "Handling Errors" chapter for information on checking for errors on synchronous and asynchronous calls. Refer to the "Using Support Functions" chapter for information on using em_wait( ).

File Attributes

An FTAM file has two distinct parts: its attributes and its contents. Attributes describe the file (e.g., size, creator), and are either file attributes or activity attributes:

File Attributes	Define the file properties that are available to all initiators. File attributes are stored with the file or created with the file. File attributes are an inherent part of the file (e.g., size). Some file attributes identify structural aspects of the file contents.
Activity Attributes	Define the properties that exist only while a specific FTAM connection is being used. These attributes are not part of the file (e.g., file_store_password).

Document Types

An FTAM document type corresponds to a file type on most systems. In real filestores, common file types include stream text files, record-oriented text files, binary files, and directories which contain files. These file types are represented by the following FTAM document types:

FTAM-1 Unstructured, stream-oriented text files
FTAM-2 Record-oriented text files
FTAM-3 Unstructured, stream-oriented binary files
INTAP-1 Record files
NBS-9 Directories, which contain files

For more information on document types, refer to the "Document Types and Constraint Sets" chapter. For information on setting document types, refer to the "FTAM Data Structures" chapter.

Constraint Sets

Document types restrict the type of file by specifying constraint sets. Constraint sets specify the allowable file structures and the ways in which access actions can modify the structure. Constraint sets are either Unstructured or Sequential Flat. (Refer to Figure 1-5 “FADU Defined by Unstructured Constraint Set” and Figure 1-6 “FADU Defined by Sequential Flat Constraint Set” for file structure information of these two types.) For more information on constraint sets, refer to the "Document Types and Constraint Sets" chapter.

Access Contexts

Constraint sets restrict the type of access contexts available. Access contexts specify how the information in the file is accessed. You specify access contexts only when reading a file.

Figure 1-4 FTAM Document Types

FTAM File Structure Model

The FTAM file model consists of a hierarchical structure (ordered tree) containing various levels.

Each node in the tree contains a node descriptor. Node descriptors reference specific parts of a file. However, a node descriptor may be empty.
Each node in the tree contains a data unit (DU). This data unit contains the actual file contents.

A file access data unit (FADU) is the smallest unit you can access in an FTAM file. A FADU is the complete information content of a subtree (i.e., node descriptors and data units). FADUs may be nested and may contain several data units.

The two file structures described by the Unstructured and Sequential Flat constraint sets are identified in the following illustrations.

An Unstructured constraint set contains one FADU consisting of one node descriptor and one data unit.
Figure 1-5 FADU Defined by Unstructured Constraint Set
A Sequential Flat constraint set contains a root FADU with an unlimited number of FADUs one level beneath it.
Figure 1-6 FADU Defined by Sequential Flat Constraint Set