Using Functions

FTAM functions may be high level or low level and may be context free or context sensitive. Refer to the following sections for information on these function types and for a list of available functions.

High Level Services (HLS) and Low Level Services (LLS)

FTAM functions are either a high level service (HLS) or a low level service (LLS). Both HLS and LLS perform the following operations.

Ensure the input and output data are provided
Ensure all mandatory parameters have valid values
Ensure all optionally supplied parameters have valid values
Provide both synchronous and asynchronous calling modes

Low Level Service

An LLS is a function that provides the lowest level of service for the FTAM application interface.

High Level Service

An HLS is a function that performs a sequence of LLS functions, thereby eliminating the need to make the LLS calls individually. For example, the HLS ft_fcopy() copies one file to another by performing all the necessary steps to do so. The ft_fcopy() function establishes connections with the source and destination nodes, opens and closes the file, reads and writes data, and terminates the regimes.

Context Free (CF) and Context Sensitive (CS) Functions

The term context refers to a dependency on the use of other functions.

Context Free

A function that is context free does not depend on prior use of other FTAM functions. You can call a context free function at any time.

All context free functions are high level services: ft_fcopy(), ft_fmove(), ft_frattributes(), ft_fcattributes(), and ft_fdelete().

Context Sensitive

A function that is context sensitive depends on prior use of other FTAM functions. You must call context sensitive functions in the correct sequence as defined by the FTAM protocol.

All context sensitive functions are low level services except for ft_fopen() and ft_fclose().

Available Functions

Figure 2-2 “Available FTAM Functions Per Regime” shows the low level FTAM functions available per regime. For example, you call ft_select() or ft_create() in the FTAM regime to move to the File Selection regime, where you can call ft_rattributes(), ft_cattributes(), and ft_open(). To move out of the File Selection regime, you call ft_deselect() or ft_delete().

Note that you do not have to be in a regime to call those functions shown outside the regimes.

Figure 2-2 Available FTAM Functions Per Regime

The following table briefly describes the FTAM functions.

Function	Description
em_fdmemory()	Free dynamic memory allocated by em_gperror()
em_ gperror()	Translate em_fdmemory(), em_ gperror(), and em_wait() errors (return_codes) to character strings
em_wait()	Notify you that an asynchronous call completed
ft_abort()	Abort a connection Low level, context sensitive
ft_aeactivation()	Activate ftam_init Low level, context free
ft_aedeactivation()	Deactivate ftam_init Low level, context sensitive
ft_aereset()	Reset ftam_init Low level, context sensitive
ft_bgroup()	Designate the beginning of a grouped set of functions Low level, context sensitive
ft_cancel()	Cancel data transfer in progress Low level, context sensitive
ft_cattributes()	Change file attributes Low level, context sensitive
ft_close()	Close a file Low level, context sensitive
ft_connect()	Establish a connection from ftam_init to a responder Low level, context sensitive
ft_create()	Create a file Low level, context sensitive
ft_delete()	Delete the currently selected file Low level, context sensitive
ft_deselect()	Deselect the currently selected file Low level, context sensitive
ft_dfdcb()	Dynamically free FTAM data control block Context sensitive
ft_didcb()	Dynamically initialize FTAM data control block Context free
ft_edata()	End a series of data units Low level, context sensitive
ft_egroup()	Designate the end of a set of grouped functions Low level, context sensitive
ft_erase()	Erase all or part of a file Low level, context sensitive
ft_etransfer()	End the transfer of data Low level, context sensitive
ft_fcattributes()	Select and change file attributes, and then deselect the file High level, context free
ft_fcattributes_aet()	Select and change file attributes, and then deselect the file High level, context free
ft_fclose()	Close and then deselect or delete a file High level, context sensitive
ft_fcopy()	Copy a file High level, context free
ft_fcopy_aet()	Copy a file High level, context free
ft_fdelete()	Select and delete a file High level, context free
ft_fdelete_aet()	Select and delete a file High level, context free
ft_fdmemory()	Free dynamic memory allocated by ft_gperror() Low level, context sensitive
ft_fmove()	Move a file High level, context free
ft_fmove_aet()	Move a file High level, context free
ft_fopen()	Select or create a file, and then open it High level, context sensitive
ft_frattributes()	Select and read file attributes, and then deselect the file High level, context free
ft_frattributes_aet()	Select and read file attributes, and then deselect the file High level, context free
ft_gperror()	Translate returned FTAM error codes to character strings Low level, context sensitive
ft_ireceive()	Receive an abort indication Low level, context sensitive
ft_locate()	Locate a specific part of an FTAM-2 file Low level, context sensitive
ft_nwcleared()	Note when an outstanding resource is cleared Low level, context sensitive
ft_open()	Open a file Low level, context sensitive
ft_rattributes()	Read file attributes Low level, context sensitive
ft_rcancel()	Either acknowledge the end of a data transfer in progress OR Respond to a cancel indication Low level, context sensitive
ft_rdata()	Receive a block of data Low level, context sensitive
ft_rdataqos()	Request transfer of data from a file Low level, context sensitive
ft_read()	Request transfer of data from a file Low level, context sensitive
ft_rrequest()	Release a connection Low level, context sensitive
ft_sdata()	Send a block of data Low level, context sensitive
ft_select()	Select a file Low level, context sensitive
ft_write()	Request transfer of data to a file Low level, context sensitive

Figure 2-3 Example Use of Low Level FTAM Functions

Typical Applications

Figure 2-3 “Example Use of Low Level FTAM Functions” on the previous page is an example series of low level FTAM functions used within an application.

The first column contains major segments (tasks) of a typical FTAM application.
The second column contains typical low level functions used to perform the application tasks. You will probably not use all the functions in each box for every application.

Using Functions

Technical documentation

» Table of Contents

» Glossary

» Index

High Level Services (HLS) and Low Level Services (LLS)

Context Free (CF) and Context Sensitive (CS) Functions

Available Functions

Typical Applications