Using Regimes

Regimes define which functions an FTAM application can use at any time. As an application descends the regimes, you can use specific FTAM functions as described in the following figure and sections. The regime order is as follows.

Figure 2-1 FTAM Regime Order

FTAM Regime
File Selection Regime
File Open Regime
Data Transfer Regime

If you use high-level FTAM functions, you do not need to deal with regimes; FTAM takes care of these details.

Regime Guidelines

Refer to the following guidelines for working in regimes.

You must enter the outer regimes before entering the inner regimes. For example, you must enter the File Open regime before entering the Data Transfer regime.
You must exit inner regimes before you can exit outer regimes. For example, you must exit the File Open regime before exiting the File Selection regime.
After exiting an inner regime, you can re-enter the same regime (e.g., you can sequentially select several files in the FTAM regime).
You can terminate all regimes, no matter how deeply nested, using the abort request (ft_abort()).

Using the FTAM Regime

The FTAM functions requested during this regime are negotiated between the initiator and responder during the protocol exchange. (The initiator supplies information which the responder then verifies.)

Your FTAM application must supply the initiator identity. You may also request (i.e., try to negotiate) certain document types (file types), attribute groups, service classes, and functional units. Refer to the "FTAM Data Structures" chapter for detailed information regarding these negotiated services.

Document Types	File types FTAM-1, FTAM-2, FTAM-3, INTAP-1, and NBS-9. FTAM-1 is a text file, FTAM-2 is a record-oriented text file, FTAM-3 is a binary file, INTAP-1 is a record- oriented binary file, and NBS-9 is a directory.
Attribute Groups	Organize specific qualities or characteristics to a file (e.g., name and size); identify subsets of attributes.
Service Classes	Organize functional units into meaningful groups. Each service class identifies mandatory and optional functional units.
Functional Units	Specify which FTAM functions, within the selected service class, are allowed. The mandatory and optional functional units depend on the service class, which must support all selected functional unit values.

The responder verifies requests in one of the following ways.

Returns a positive confirmation that it accepts the request with no changes.
On ft_connect(), returns a positive confirmation that it accepts the request with the given (returned) changes to the initiator's request.
Returns a negative confirmation that it does not accept the request.

Entering the FTAM Regime

Functions Used Within the FTAM Regime

Exiting the FTAM Regime

Invoke ft_connect() to establish a connection

ft_select() moves you to the File Selection regime and selects a file

ft_create() moves you to the File Selection regime and creates, then selects a file

Invoke ft_rrequest() to release the connection and move you out of the FTAM regime. (Note: You will no longer be in a regime, but ftam_init will still be activated.)

Using the File Selection Regime

Enter the File Selection regime to reference a specific file. You must specify a filename. You cannot access a file's contents in the File Selection regime; you must enter the File Open regime to do so.

Entering the File Selection Regime

Functions Used Within the File Selection Regime

Exiting the File Selection Regime

Invoke ft_create() to create a new file

Invoke ft_select() to select an existing file

ft_rattributes() reads file attributes

ft_cattributes () changes file attributes

ft_open() moves you to the File Open regime and opens a file

Invoke ft_delete() to move to the FTAM regime and permanently remove the file

Invoke ft_deselect() to move back to the FTAM regime and deselect (but not remove) the file

Using the File Open Regime

The File Open regime makes the file's contents available for reading and writing.

Entering the File Open Regime

Functions Used Within the File Open Regime

Exiting the File Open Regime

Invoke ft_open() to access a file's contents

ft_locate() locates a specific place (FADU) in a file (FTAM-2 files only)

ft_erase() completely erases an entire file

ft_read() enters the Data Transfer regime and requests data transfer from an FTAM file

ft_write() enters the Data Transfer regime and requests data transfer to an FTAM file

Invoke ft_close() to move back to the File Selection regime and close the file to further access

Using the Data Transfer Regime

The Data Transfer regime is the innermost regime; it supports the transfer of actual data.

Entering the Data Transfer Regime

Functions Used Within the Data Transfer Regime

Exiting the Data Transfer Regime

Invoke ft_read() to request the transfer of data from an FTAM file

Invoke ft_write() to request the transfer of data to an FTAM file

ft_sdata() sends (writes) data

ft_rdata() receives (reads) data

ft_edata() ends the sending of data

Invoke ft_etransfer() to move back to the File Open regime and end data transfer

Invoke ft_cancel() to move back to the File Open regime and cancel the transfer of data

If you have received a cancellation indication, invoke ft_rcancel() to acknowledge the indication and move back to the File Open regime

Using Regimes

Technical documentation

» Table of Contents

» Glossary

» Index

Regime Guidelines

Using the FTAM Regime

Using the File Selection Regime

Using the File Open Regime

Using the Data Transfer Regime