The FTAM API is a low-level interface providing access to the FTAM protocol machine. To use the FTAM API, you must have a good working knowledge of the FTAM standard. You should obtain a copy of the FTAM standard (ISO 8571) for active reference purposes.

Similar to the OSAK API, the FTAM API is a parameter block interface. That parameter block is the osifpb structure. The osifpb is used by the FTAM API user to specify which FTAM service primitive to send and what the parameters should be. It is also used by the FTAM API to tell the API user which FTAM service primitive was received and what the parameters are. The osifpb structure contains a field for each parameter in any of the FTAM primitives. In this document, parameter refers to a field of the osifpb structure.

Chapter 4, Data Structures describes the osifpb structure and the other structures used by the FTAM API.

This section shows a typical way that the FTAM API can be used to establish an association and perform a protocol exchange sequence with the peer entity.

The FTAM service primitives available through the FTAM API map to a set of constants that must be set in the osif_block_type parameter of the osifpb structure. These constants are described in Section 4.1, “FTAM Parameter Block ”.

These values determine the type of FTAM service primitive that a particular osifpb structure represents. The block type will be set to one of the defined constants upon receipt of an incoming FTAM event. A single value refers to either a request or an indication depending on the context in which the osifpb structure is used.

For example, if an F-INITIALIZE-request is to be sent to an FTAM responder,then the osif_block_type parameter must be set to OSIF_PBDEF_INIT_REQ. The osif_send function call can then be used to send the F-INITIALIZE-request to the remote responder. If the responder receives an osifpb as part of an osif_get_event function call and the osif_block_type parameter is set to OSIF_PBDEF_INIT_REQ, then the osifpb received describes an F-INITIALIZE-indication.

Except for the osif_get_event call, all API calls are blocking in nature. Blocking means that control does not return to the user program until the requested call has completed successfully or unsuccessfully. The osif_get_event call may be used either in blocking or non-blocking mode. If it is used in non-blocking mode, the osif_get_event call can poll for events by using the timeout parameter.

The API must be provided with buffers after a port is assigned but before any other operations. This is accomplished with calls to osif_give_buffer. Once you give the API a buffer and the structure that points at the buffer ( osif_buffer_list structure) through the osif_give_buffer function call, the API owns the buffer. You should not try to use the buffer until the APIreturns the buffer to you. Buffers are returned to the user when you deassign the port using the buffer_list argument of the osif_deassign_port function call or when an event is received by the osif_get_event function call.

If the API has insufficient buffers to complete an osif_get_event request, the call returns an OSIF_FAILURE status and the OSIF_NOBUFFS error. If this situation occurs, your application should provide additional buffers using the osif_give_buffer call and retry the osif_get_event call.

osif_give_buffer(...)osif_get_event(...)

When an event is received successfully, the osif_get_eventcall might return user buffers in the osifpb structure using the osif_returned_buffer parameter. The osif_returned_buffer parameter might also return a null value. The osif_returned_buffer parameter is a pointer to the osif_buffer_list structure which points at the user buffer. Once you have finished using all the parameters in an osifpb structure, you can reuse the buffers that the osif_returned_buffer parameter points at by passing them back to the API using the osif_give_buffer call. Do not return buffers to the API before you are finished using them, because information might be lost in the process.

The user data, which corresponds to the F-DATA service primitive, is passed to the FTAM API through the osif_userdata parameter of the osifpb. osif_userdata is implemented as an osif_sdesc structure, which contains a pointer to the data buffer containing the user's file data, and an integer which is the buffer length. Only one buffer can be used for each transfer. The FTAM API does not support buffer chains. The FTAM API owns the buffer (that is, the user should not change it) until the call returns. If the buffer contents change, the unpredictable results might cause the call to fail.

For outgoing F-DATA requests, the buffer used is supplied by the user. Its allocation is a local matter. The data buffer becomes available to the user when the osif_send function returns.

For incoming F-DATA indications, the specified buffer in the osif_userdata parameter is taken from the osif_give_buffer pool. The buffer may or may not become available to the user upon receipt of the F-DATA-indication (osif_get_event call). Buffers will be owned by the API until the API relinquishes control of the buffer through the use of the osif_returned_buffer parameter.

With the FTAM API, you can design an FTAM responder that is either an active application or a passive application.

A presentation address (p-address) specifies service access points (SAPs) for the service providers of all the upper layers to be accessed. For FTAM product, a p-address always contains presentation, session, and transport selectors. It also must have an NSAP. This information is contained in the osif_local_p_addrs and osif_peer_p_addrs parameters of the osifpb. The osif_ae_entry structure is used for these parameters.

psap.ssap.tsap.

The p-address value can include character strings or octet strings. Octet strings must be preceded by %x (or %X). Each selector is terminated on its right by a delimiter (.). If a particular selector is not required, the delimiter (.) must still be included.

PSAP..TSAP.

For the FTAM API Version 3.2, the NSAP and provider information is contained in a linked list pointed to by the nsap_queue_ptr field of the osif_ae_entry structure. The template information is contained in a linked list pointed to by the template_queue_ptr field of the osif_ae_entry structure. Chapter 3, FTAM File Services provides more details about these data structures.

OSIT$LOOP_CONS%x22

As discussed in Section 1.9, “Using Presentation Addresses ”, with FTAM API Version 3.2, the osif_ae_entrystructure is enhanced to provide additional addressing capabilities. In Version 3.2, the osif_ae_entry structure contains two additional fields (see Section 4.9, “Application-Entity Entry”).

This change requires that FTAM API applications written to earlier versions of the API be recompiled and relinked. However, no code changes are required unless you want to use the new addressing capabilities.

The FTAM API checks the nsap_queue[0].nsap.lengthfield of the osif_ae_entry structure to determine which API format is in use. If the value of length is non-zero, the API determines that the FTAM Version 3.0 format is being used and ignores the new fields in the osif_ae_entry structure. If the value of length is zero, the API determines that the Version 3.2 format is being used. In this case, the API ignores the nsap_queue array and instead looks for information in the new fields.

$ CC/EXTERN_MODEL=COMMON_BLOCK/SHARE_GLOBALS example.c

example.c is the name of your program that uses the FTAM API.

$ LINK example.obj, API.OPT/OPTION

sys$library:osif$fmsg_ptr.obj, -
sys$library:osif$api.olb/lib, -
sys$library:osif$asn1code.olb/lib, -
sys$share:osak$osakshr.exe/share, -
sys$share:osak$prv.exe/share, -
sys$share:vaxcrtl.exe/share

Note that even if you are using DEC C instead of VAX C on your VAX system, you must link with VAXCRTL.EXE. For OpenVMS Alpha, API.OPT is the same except do not link with VAXCRTL.EXE (DECC$SHR.EXE is pulled in automatically for you).

FTAM on UNIX Version 3.0 and later ships with a sharable library (the FTAM API on previous versions shipped a static library for the API). The following example shows how to build with the sharable library. See also the makefile for the FTAM API example files for an example of how to build.

cc example.c -lftam -o example

Sample programs are provided written in C to demonstrate how to use the FTAM API calls. Build files are provided to demonstrate how to compile and link programs that use the FTAM API. These example programs create, rename, and delete a file on the system running the example responder. The example programs are located in the following files:

On OpenVMS, the address information supplied in the example programs work without modification if the example initiator and example responder are run on the same OpenVMS system.

REMOTE_NSAP     NSAP of system running responder

If you wish to run the initiator and responder on different systems, see comments in the example programs themselves for instructions.

To compile and link the example program, use the provided build files as follows.

$ set default sys$common:[syshlp.examples]$ @osif_api_bld.com

# cd /usr/examples/ftamapi# make

To run the example programs, first run the example responder in one process, then run the example initiator in a second process. Note that the example responder does not use the OSAK server on OpenVMS or the ftam_listener on UNIX. The example responder executable is an active application (see Section 1.8, “Passive Versus Active Responders” for a discussion of passive versus active responders).

In using the FTAM API, you must be aware of service sequences. These sequences are closely tied to the FTAM regimes. The following list summarizes the sequences and functions of FTAM phases. It also shows the correlations between different phases. For example, Phase 1 is associated with Phase 8 because establishing and ending an association are two activities that are closely related.

Grouping is a convenience that allows you to combine several services into a single communications unit. Grouping functions can occur at many points within an association. Note that the service specifications used here represent the full series of service primitives associated with each service.

When using grouping, you must understand that service classes introduce restrictions. Service classes are defined as combinations of functional units. As a result, grouping can occur only in certain sequences as outlined in the FTAM standard (ISO 8571-3, Annex E). Matching F-BEGIN-GROUP and F-END-GROUP services must occur within the same regime.

The following sections show some sample service sequences that you might use when performing various operations.

The API provides all the service primitives offered by ISO 8571 through the use of function calls and data structures. The function calls allow services to be performed, and the data structures provide a way for entering and receiving FTAM parameters from the FTAM protocol machine. The information provided by the parameter block is referenced by the osif_send and osif_get_event calls described in Chapter 5, Function Calls .

The FTAM parameter block (osifpb) describes the FTAM protocol data unit transmitted between peer entities. All of the parameters used by the FTAM primitives, the application-wide types, and the file attribute types are associated with a particular descriptor that has a particular format. Section 3.4, “Parameter Description” provides more details about the parameters and descriptors.

Parameters are assigned to the osifpb parameter block through simple assignment statements. The address or value of the parameters must be stored in the address or value field of the descriptor in osifpb, depending on whether it is a string or an integer. If the value is a bit string, the value field of the descriptor is filled in directly. The length of the parameters must also be assigned. If the length is not assigned, the parameter is ignored.

If the parameter has a default and the length is zero, the default is applied by the API. If the length is a non-zero value, then the default is not applied.

Chapter 4, Data Structures provides more details on the FTAM parameter block data structure (osifpb) and the other data structures used by the API to pass parameter information.

This section describes the parameters of osifpb and their possible values. The parameters are listed alphabetically. For more details about their usage, refer to the FTAM standard (ISO 8571-3 and ISO 8571-4).

osif_access_context (Access Context)

Specifies the file access structure for read operations. See Section 4.18, “File Access Data Unit Access Context ” for more information.

osif_access_control (Access Control attribute)

Defines conditions under which file access is valid. This value is set at file creation, but it can be altered by the change attribute action. A condition consists of one or two terms stating the type of access allowed (an action list term or a concurrency access term), together with a set of zero to three terms testing for matching attribute values (initiator identity, access passwords, or calling AE-title). See Section 4.15, “Access Control ” for more information.

osif_access_passwords (Access Passwords)

Provides passwords for the actions specified in the requested access parameter. This parameter is available only if the security attribute group has been negotiated. See Section 4.16, “Access Passwords ” for more information.

osif_account (Account)

Identifies the account to charge for the cost of a regime establishment. It is used to set the current account activity attribute. If this parameter is not specified, the activity attribute is unset or retains its previous value. The current account activity attribute reverts to its previous value at the end of a regime.

osif_action_result (Action Result)

osif_activity_ident (Activity Identifier)

Used only when the recovery functional unit has been negotiated on F-INITIALIZE. Its value (an integer) is used in reestablishing the data-transfer regime after a failure.

osif_application_context (Application Context Name)

Represents the properties of the association. The initiator proposes a name that the responder may accept and return or the responder may return a different name. The application context name returned by the responder is used for the established association.

osif_attribute_groups (Attribute Groups)

osif_attribute_names (Attribute Names)

Indicates which file attributes from the kernel or negotiated attribute groups are read. The possible groups are the kernel group, the storage group, the security group, and the private group.

osif_block_size

Passes the size of the osifpb parameter block.

osif_block_type

Passes the function code for the FTAM primitive. See Section 4.1, “FTAM Parameter Block ” for more information.

osif_character_sets

Describes the character sets used in the file if they are different from the default, ISO 646.

osif_charging (Charging)

Passes cost information attributed to the account during the regime being released. This parameter can be used only if the account parameter was specified at the beginning of the regime. See Section 4.19, “Charging ” for more information.

osif_checkpoint_window (Checkpoint Window)

Used only when the recovery functional unit has been negotiated, this parameter indicates the maximum number of checkpoints that may remain unacknowledged. This integer value is inserted only by the sender and is used for F-INITIALIZE-request and F-INITIALIZE-response.

osif_concurrency_control (Concurrency Control)

Defines the possible actions on a file and their respective access locks during a file-select or file-open regime. See Section 4.14, “Concurrency Control ” for more information.

osif_contents_type (Contents Type attribute)

Identifies the abstract data type of the file contents. Its value is either a document type with optional parameters or an abstract syntax and a constraint set name. See Section 4.7, “Contents Type Parameter” for more information.

osif_contents_type_list (Contents Type List)

Lists the document types and abstract syntaxes and allows the negotiation of presentation context when establishing the FTAM regime. This parameter is mandatory in certain classes if the presentation context management functional unit is not being negotiated. See Section 4.6, “Contents Type Lists” for more information.

osif_create_password (Create Password)

Describes the access control parameter create-password used by F-CREATE-request as a character or octet string.

osif_date_time_creation (Date and Time of Creation attribute)

Indicates when the file was created in GeneralizedTime. It is set by the responder when the file is created and refers to the local date and time of the responder. If this parameter is not supported, set the type field of the descriptor to OSIF_UC_NULL. It cannot be altered by the change attribute action.

osif_date_time_last_attmod (Date and Time of Last Attribute Modification attribute)

Indicates when a file attribute value was last modified in GeneralizedTime. If this parameter is not supported, set the type field of the descriptor to OSIF_UC_NULL. It is altered by the responder whenever the change attribute action is successfully performed on one or more attributes. This attribute is not modified by an implicit change to an attribute and it cannot be altered by the change attribute action.

osif_date_time_last_modif (Date and Time of Last Modification attribute)

Indicates when the file contents were last modified in GeneralizedTime. If this parameter is not supported, set the type field of the descriptor to OSIF_UC_NULL. It is altered by the responder whenever the file has been opened for modification or extension and is closed. This attribute is not altered unless the file is opened to allow change of the contents. It is not altered when the file attributes are changed.

osif_date_time_last_read (Date and Time of Last Read Access attribute)

Indicates when the file contents were last read in GeneralizedTime. If this parameter is not supported, set the type field of the descriptor to OSIF_UC_NULL. It is altered by the responder whenever the file has been opened for reading and is closed. This attribute is not altered unless the file is opened and it cannot be altered by the change attribute action.

osif_diagnostic (Diagnostic)

Provides more details about the information given in the action result parameter for a successful action, a transient error, or a permanent error. See Section 4.5, “Diagnostics ” for more information.

osif_fadu (FADU Identity)

Specifies the target FADU to be used for file operations. The value of this parameter depends on the file operation. See Section 4.17, “File Access Data Unit ” for more information.

osif_fadu_lock (FADU Lock)

osif_fadu_locking (Enable FADU Locking)

Indicates whether locking is on a per-FADU basis or on a file basis as a Boolean value. This parameter is available only if the storage attribute group has been negotiated and the concurrency control parameter is present.

osif_fadu_operation (FADU Operation)

Indicates the action to be taken by the filestore provider on receiving transferred data.

osif_file_availability (File Availability attribute)

osif_filename (File name attribute)

Describes a list of the file name parameters by providing a pointer to the osif_fn structure. This attribute is set atfile creation, but can be altered by the change attribute action. See Section 4.4, “File Names ” for more information.

osif_filesize (File size attribute)

osif_filestore_password (Filestore Password)

Used by the responder to authenticate the initiator identity parameter. It is a character or octet string.

osif_ftam_qual_service (FTAM Quality of Service)

osif_functional_units (Functional Units)

osif_future_filesize (Future File size attribute)

Indicates the size in octets to which a file may grow due to modification and extension. This integer value is set at file creation, but it can be altered by the change attribute action.

osif_identity_creator (Identity of Creator attribute)

Indicates the value of the current initiator identity activity attribute at file creation as a GraphicString. This attribute cannot be altered by using the change attribute action.

osif_identity_last_attmod (Identity of Last Attribute Modifier attribute)

Indicates the value of the current initiator identity as a GraphicString whenever the change attribute action is successfully performed on one or more attributes. This attribute cannot be changed using the change attribute action.

osif_identity_last_modify (Identity of Last Modifier attribute)

Indicates the value of the current initiator identity activity attribute as a GraphicString whenever the file has been opened for modification or extension and is closed. This attribute cannot be altered by using the change attribute action.

osif_identity_last_reader (Identity of Last Reader attribute)

Indicates the value of the current initiator identity activity attribute as a GraphicString whenever the file has been opened for reading and is closed. This attribute cannot be altered using the change attribute action.

osif_implementation_information (Implementation Information)

Needed only if you want to distinguish versions of implementations on different equipment.

osif_initiator_identity (Initiator Identity)

Identifies the calling user as a GraphicString.

osif_legal_qualification (Legal Qualification attribute)

osif_local_p_addrs (Local Address (host system))

The structure containing the application entity addresses (AP-title and AE-qualifier), presentation selector, session selector, transport selector, and up to five network service access points and transport options (template and provider).

osif_peer_p_addrs (Target Address (system accepting the connection))

The structure containing the application entity addresses (AP-title and AE-qualifier), presentation selector, session selector, transport selector, and up to five network service access points and transport options (template and provider).

osif_override (Override)

osif_permitted_actions (Permitted Actions attribute)

osif_pres_ctx_mgmt (Presentation Context Management)

Indicates whether the context management functional unit is used during the FTAM open and recovery procedures as a Boolean value.

osif_processing_mode (Processing Mode)

osif_prot_error_count (Protocol Error Count)

Indicates the number of returned errors. See Chapter 5, Function Calls for more information.

osif_protocol_error

Contains a list of layer-specific errors. See Chapter 5, Function Calls for more information.

osif_protocol_id (Protocol Version)

Indicates the protocol version. This parameter has a default value of version-1.

osif_recovery_mode (Recovery Mode)

osif_requested_access (Requested Access)

osif_returned_buffer

Is a pointer to osif_buffer_list structure. Buffers are returned to the user through this value. A null value can be returned. See Section 1.5, “Managing the User Buffer” for more information.

osif_scratchpad

Used by osifpb to manipulate data. See Section 4.1, “FTAM Parameter Block ” for more information.

osif_service_class (Service Class)

osif_state_result (State Result)

osif_storage_account (Storage Account attribute)

Identifies the accountable authority responsible for accumulated file storage charges as a GraphicString.

osif_threshold (Threshold)

Specifies the number of primitives within a group that are analyzed without failing before any part of the group can succeed.

osif_userdata

Describes the buffer containing the F-DATA as a string descriptor.

The use of the parameters is dependent on the FTAM primitive type. Any parameters that are not within the scope of the specific FTAM primitive type are ignored by the FTAM API. The relationship between the FTAM primitives and the parameters is shown in Table 3.1, “FTAM Primitives and Corresponding Parameters ”.

The osifpb structure has two parts — one for specific parameters and one for variable data. The osif_scratchpaddescriptor is used to distinguish these parts.

For specific parameters, usage of the scratch pad for request and response primitives is a local issue for the FTAM API user. The allocated data can be passed to the FTAM API locally through static or dynamic means or the data can be referenced by the osifpb descriptors and stored in the scratch pad.

For variable data, the usage of the scratch pad for indication and response primitives is different. The scratch pad is filled in by the FTAM API and the underlying FTAM protocol machine. As a result, the osifpb structures may point into the buffer supplied by the osif_give_buffercall or they may point to the scratch pad. The buffers from the osif_give_buffer call are returned to the FTAM API user in the osif_returned_buffer descriptor.

struct osifpb {

    unsigned int                osif_block_type;  /* block identifier  */
    unsigned int                osif_block_size;  /* size of the block */
    struct osif_buffer_list     *osif_returned_buffer;
    struct osif_prot_err        osif_protocol_error;
    int                         osif_prot_error_count;

    struct osif_faduac          osif_access_context;
    struct osif_access_ctl      osif_access_control;
    struct osif_apwd            osif_access_passwords;
    struct osif_sdesc           osif_account;
    struct osif_bdesc           osif_action_result;
    struct osif_bdesc           osif_activity_ident;
    struct osif_sdesc           osif_application_context;
    struct osif_sdesc           osif_arc_length;
    struct osif_bdesc           osif_attribute_groups;
    struct osif_bdesc           osif_attribute_names;
    struct osif_bdesc           osif_character_sets;
    struct osif_charging_pb     *osif_charging;
    struct osif_bdesc           osif_checkpoint_window;
    struct osif_cc              osif_concurrency_control;
    struct osif_ct              osif_contents_type;
    struct osif_ctl             *osif_contents_type_list;
    struct osif_sdesc           osif_create_password;
    struct osif_sdesc           osif_date_time_creation;
    struct osif_sdesc           osif_date_time_last_attmod;
    struct osif_sdesc           osif_date_time_last_modif;
    struct osif_sdesc           osif_date_time_last_read;
    struct osif_sdesc           osif_delete_password;
    struct osif_access_ctl      osif_delete_values;
    struct osif_sdesc           osif_define_context;
    struct osif_diagnostics_pb  *osif_diagnostic;
    struct osif_sdesc           osif_encryption_name;
    struct osif_faduid          osif_fadu;
    struct osif_bdesc           osif_fadu_lock;
    struct osif_sdesc           osif_fadu_locking;
    struct osif_bdesc           osif_fadu_operation;
    struct osif_fn              *osif_filename;
    struct osif_bdesc           osif_filesize;
    struct osif_bdesc           osif_file_availability;
    struct osif_sdesc           osif_filestore_password;
    struct osif_sdesc           osif_ftam_coded;
    struct osif_bdesc           osif_ftam_qual_service;
    struct osif_bdesc           osif_functional_units;
    struct osif_bdesc           osif_future_filesize;
    struct osif_sdesc           osif_initiator_identity;
    struct osif_sdesc           osif_identity_creator;
    struct osif_sdesc           osif_identity_last_attmod;
    struct osif_sdesc           osif_identity_last_modify;
    struct osif_sdesc           osif_identity_last_reader;
    struct osif_sdesc           osif_implementation_information;
    struct osif_access_ctl      osif_insert_values;
    struct osif_sdesc           osif_legal_qualification;
    struct osif_ae_entry        osif_local_p_addrs;
    struct osif_bdesc           osif_override;
    struct osif_ae_entry        osif_peer_p_addrs;
    struct osif_bdesc           osif_permitted_actions;
    struct osif_bdesc           osif_pres_ctx_mgmt;
    struct osif_bdesc           osif_processing_mode;
    struct osif_sdesc           osif_protocol_id;
    struct osif_sdesc           osif_remove_context;
    struct osif_bdesc           osif_requested_access;
    struct osif_bdesc           osif_recovery_mode;
    struct osif_bdesc           osif_service_class;
    struct osif_bdesc           osif_session_version;
    struct osif_bdesc           osif_state_result;
    struct osif_sdesc           osif_storage_account;
    struct osif_bdesc           osif_threshold;
    struct osif_sdesc           osif_user_coded;
    struct osif_sdesc           osif_userdata;  /* User data used to */
    int                         osif_reserved; /* Reserved for alignment */
    unsigned char               osif_scratchpad[ SCRATCHPAD_SIZE ];
};

More information on the descriptors and their associated parameters is found in Section 3.2, “FTAM File Services and Parameters” and Section 3.4, “Parameter Description”.

struct osif_apwd {
struct osif_sdesc chng_attrib_password;
struct osif_sdesc delete_password;
struct osif_sdesc erase_password;
struct osif_sdesc extend_password;
struct osif_sdesc insert_password;
struct osif_sdesc read_attrib_password;
struct osif_sdesc read_password;
struct osif_sdesc replace_password;
};

Note that the type field of the osif_sdesc structure must be set to OSIF_UC_GRAPHIC or OSIF_UC_OCTET depending on the semantics of the password.