Gaining Access to FTAM Files

After establishing a connection, either select (ft_select()) or create (ft_create()) a file for further manipulation. You must always select a file before opening it (ft_open()), though the selection automatically occurs if you create the file.

After performing FTAM operations, close (ft_close()) the file and then deselect (ft_deselect()) or delete (ft_delete()) it. The file remains intact if you deselect it; if you delete the file, it no longer exists.

ft_create()

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return code
ft_create (connection_id, filename, contents_type, 
          requested_access, file_status, return_event_name, 
          input_dcb, inout_dcb)
 
Connection_id                            connection_id;
Ft_filename                              filename;
struct Ft_contents_type                  contents_type;
Ft_file_actions                          requested_access;
enum Ft_file_status                      file_status;
Local_event_name                         return_event_name;
struct Ft_create_in_dcb                  *input_dcb;
struct Ft_create_out_dcb                 **inout_dcb;

Use ft_create() to create a new file. If successful, ft_create() automatically selects the file.

Invoke ft_create() in the FTAM regime to move to the File Selection regime.
During ft_connect(), you must negotiate the FT_FU_LTD_MGMT functional_units to use ft_create().
If the file already exists, the file_status parameter determines whether a new file is created or the request fails. (Refer to the "Ft_file_status" section in the "FTAM Data Structures" chapter for options on setting this field.)
The subset of the input_dcb->attributes.mask field (of type struct Ft_attributes) that is valid for ft_create() is as follows.
FT_AN_ACCESS_CONTROL FT_AN_FILE_AVAILABILITY FT_AN_FUTURE_FILESIZE FT_AN_ID_OF_CREATOR
FT_AN_LEGAL_QUAL FT_AN_PERMITTED_ACTIONS FT_AN_PRIVATE_USE FT_AN_STORAGE_ACCOUNT
If you do not specify permitted_actions, FTAM uses the requested_access values for the permitted_actions values.
FTAM uses the exposed parameters filename and contents_type and does not use input_dcb->attributes.values.filename and input_dcb- >attributes.values.contents_type.

Ft_create_in_dcb

struct  Ft_create_in_dcb {
      struct  Ft_attributes            attributes;
      struct  Ft_concurrency_control   *concurrency_control;
      Ft_single_file_pw                create_file_pw;
      struct  Ft_file_passwords        file_passwords;
      Ft_account                       account;
};

Ft_create_out_dcb

struct  Ft_create_out_dcb {
      Uint32                       size;
      struct  Api_rc               result;
      enum    Ft_state_result      state_result;
      enum    Ft_action_result     action_result;
      struct  Ft_attributes        attributes;
      struct  Ft_diagnostic        *diagnostic;
};

ft_create() Parameters

ft_create() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
filename	Mandatory Input	Path name of the file you are creating; must be in the syntax of the real filestore
contents_type	Mandatory Input	Specifies the document type of the newly created file
requested_access	Mandatory Input	Specifies the actions you want available for the connection (during the File Selection regime and those regimes nested within it)
file_status	Mandatory Input	Determines the action to take if the file already exists
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb->attributes	Optional Input	Uniquely identifies the file you are creating; do not use input_dcb->attributes.filename and input_dcb->attributes.contents_type
input_dcb-> concurrency_control	Optional Input	File access locks required on the actions specified in requested_access
input_dcb-> create_file_pw	Optional Input	Establishes permission to create files in the current filestore; HP-UX responders ignore this value
input_dcb-> file_passwords	Optional Input	Passwords associated with the actions specified by requested_access
input_dcb->account	Optional Input	HP-UX responders accept, but ignore, this value
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> state_result	Output	Indicates whether the request moved from the FTAM regime to the File Selection regime; if a failure returns, you will also receive an action_result of FT_AR_PERMANENT_ERROR
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb->attributes	Output	Contains values of the attributes of the file you created (those attributes accepted by the responder)
inout_dcb->diagnostic	Output	Provides ISO-specific error information

ft_select()

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return_code
ft_select (connection_id, filename, requested_access, 
           return_event_name, input_dcb, inout_dcb)
 
Connection_id                          connection_id;
Ft_filename                            filename;
Ft_file_actions                        requested_access;
Local_event_name                       return_event_name;
struct Ft_select_in_dcb                *input_dcb;
struct Ft_select_out_dcb               **inout_dcb;

Use ft_select() to choose an existing file for file management or access (e.g., reading attributes, opening a file). You select a file based only on its filename.

Invoke ft_select() in the FTAM regime to move to the File Selection regime.
FTAM uses the exposed parameters filename and contents_type and does not use the corresponding values stored in input_dcb->attributes.
If the file you are selecting has access control, the following conditions exist.
- The requested_access parameter must be a subset of the values stored in action_list field in struct Ft_access_control_element.
- FTAM will detect conflicts between the initiator_id and the identity field of the access_control_element.
- The HP-UX implementation of FTAM does not use the file_passwords parameter. Other implementations might.

Ft_select_in_dcb

struct  Ft_select_in_dcb {
      struct  Ft_attributes            attributes;
      struct  Ft_file_passwords        file_passwords;
      Ft_account                       account;
      struct  Ft_concurrency_control   *concurrency_control;
};

Ft_select_out_dcb

struct  Ft_select_out_dcb {
      Uint32                        size;
      struct  Api_rc                result;
      enum    Ft_state_result       state_result;
      enum    Ft_action_result      action_result;
      struct  Ft_attributes         attributes;
      struct  Ft_diagnostic         *diagnostic;
};

ft_select() Parameters

ft_select() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
filename	Mandatory Input	Path name of the file you are selecting; must be in the syntax of the real filestore
requested_access	Mandatory Input	Specifies the actions you want available for the connection (during the File Selection regime and those regimes nested within it)
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb->attributes	Optional input	FTAM does not use this field; provided for future use
input_dcb-> file_passwords	Optional Input	Passwords associated with the actions specified by requested_access
input_dcb->account	Optional Input	HP-UX responders accept, but ignore, this value
input_dcb-> concurrency_control	Optional Input	File access locks required on the actions specified in requested_access
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> state_result	Output	Indicates whether the request moved from the FTAM to the File Selection regime; if a failure returns, you will also receive an action_result of FT_AR_PERMANENT_ERROR
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb->attributes	Output	Contains values of the filename attribute of the file you selected HP-UX responders accept, but ignore, this value
inout_dcb->diagnostic	Output	Provides ISO-specific error information

ft_open() (LLCS)

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return_code
ft_open (connection_id, processing_mode, contents_type, 
         return_event_name, input_dcb, inout_dcb)
 
Connection_id                          connection_id;
Ft_processing_mode                     processing_mode;
struct Ft_contents_type                contents_type;
Local_event_name                       return_event_name;
struct Ft_open_in_dcb                  *input_dcb;
struct Ft_open_out_dcb                 **inout_dcb;

Use ft_open() after selecting or creating a file to access operations.

Invoke ft_open() in the File Selection regime to move to the File Open regime.
During ft_connect(), you must negotiate the FT_FU_READ or FT_FU_WRITE functional_units to use ft_open().
The input_dcb->concurrency_control parameters must be the same or more restrictive than the input_dcb->concurrency_control parameters set on ft_create() and ft_select().
If the file you are opening has access control, the following conditions exist:
- The processing_mode parameter must be a subset of the values stored in action_list field in the access_control_element corresponding to the initiator_id used to establish the connection.
- The HP-UX implementation of FTAM does not use the file_passwords parameter. Other implementations might.

Ft_open_in_dcb

struct  Ft_open_in_dcb  {
      struct  Ft_concurrency_control   *concurrency_control;
};

Ft_open_out_dcb

struct  Ft_open_out_dcb {
      Uint32                            size;
      struct  Api_rc                    result;
      enum    Ft_state_result           state_result;
      enum    Ft_action_result          action_result;
      struct  Ft_contents_type          contents_type;
      struct  Ft_concurrency_control    *concurrency_control;
      struct  Ft_diagnostic             *diagnostic;
};

ft_open() Parameters

ft_open() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
processing_mode	Mandatory Input	Establishes a valid subset of actions negotiated in the File Selection regime
contents_type	Mandatory Input	Specifies the document type
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb-> concurrency_control	Optional Input	File access locks required on the actions specified in requested_access
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> state_result	Output	Indicates whether the request moved from the File Selection to the File Open regime; if a failure returns, you will also receive an action_result of FT_AR_PERMANENT_ERROR
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb-> contents_type	Output	contents_type of the opened file (as accepted by the responder)
inout_dcb-> concurrency_control	Output	concurrency_control of the opened file (as accepted by the responder)
inout_dcb->diagnostic	Output	Provides ISO-specific error information

ft_close() (LLCS)

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return_code
ft_close (connection_id, return_event_name, input_dcb, 
          inout_dcb)
 
Connection_id                             connection_id;
Local_event_name                          return_event_name;
char                                      *input_dcb;
struct Ft_close_out_dcb                   **inout_dcb;

Use ft_close() to close a file when you finish processing it. After closing the file, the only actions you can perform on the file without re-opening it are ft_deselect(), ft_delete(), ft_rattributes(), and ft_cattributes().

The ft_close() input_dcb parameter does not contain information; therefore, pass a NULL pointer for the input_dcb parameter.
Invoke ft_close() in the File Open regime to return to the File Selection regime.

Ft_close_out_dcb

struct  Ft_close_out_dcb {
      Uint32                        size;
      struct  Api_rc                result;
      enum  Ft_action_result        action_result;
      struct  Ft_diagnostic         *diagnostic;
};

ft_close() Parameters

ft_close() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb	Optional input	Contains no information; pass a NULL pointer
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb->diagnostic	Output	Provides ISO-specific error information

ft_delete() (LLCS)

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return_code
ft_delete (connection_id, return_event_name, input_dcb, 
           inout_dcb)
 
Connection_id                             connection_id;
Local_event_name                          return_event_name;
char                                      *input_dcb;
struct Ft_delete_out_dcb                  **inout_dcb;

Use ft_delete() to remove a file from the filestore.

The ft_delete() input_dcb parameter does not contain information; therefore, pass a NULL pointer for the input_dcb parameter.
Invoke ft_delete() in the File Selection regime to move back to the FTAM regime after deleting the file.
During ft_connect(), you must negotiate the FT_FU_LTD_MGMT functional_units to use ft_delete().
During ft_select(), ft_create(), and ft_fopen() you must specify FT_FA_DELETE_FILE in requested_access to use ft_delete().

Ft_delete_out_dcb

struct  Ft_delete_out_dcb  {
      Uint32                        size;
      struct  Api_rc                result;
      enum  Ft_action_result        action_result;
      struct  Ft_charging           *charging;
      struct  Ft_diagnostic         *diagnostic;
};

ft_delete() Parameters

ft_close() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb	Optional input	Contains no information; pass a NULL pointer
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb-> charging	Output	HP-UX responders do not use charging, though it may contain information from other responders
inout_dcb->diagnostic	Output	Provides ISO-specific error information

ft_deselect()

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
 
Return_code
ft_deselect (connection_id, return_event_name, input_dcb, 
             inout_dcb)
 
Connection_id                             connection_id;
Local_event_name                          return_event_name;
char                                      *input_dcb;
struct Ft_deselect_out_dcb                **inout_dcb;

Use ft_deselect() to deselect a file when you finish processing, but do not want to remove it. You must re-select the file to perform further actions on it.

The ft_deselect() input_dcb parameter does not contain information; therefore, pass a NULL pointer for the input_dcb parameter.
Invoke ft_deselect() in the File Selection regime to move back to the FTAM regime.

Ft_deselect_out_dcb

struct  Ft_deselect_out_dcb {
      Uint32                        size;
      struct  Api_rc                result;
      enum    Ft_action_result      action_result;
      struct  Ft_charging           *charging;
      struct  Ft_diagnostic         *diagnostic;
};

ft_deselect() Parameters

ft_deselect() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies a specific connection to the filestore
return_event_name	Mandatory Input	If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero)
input_dcb	Optional input	Contains no information; pass a NULL pointer
inout_dcb->size	Mandatory input if using inout_dcb	Size (in Octets) of the inout_dcb structure and data
inout_dcb->result	Output	Pointer to the struct Api_rc containing the outcome of the operation: result_code and vendor_code (HP-UX—specific error)
inout_dcb-> action_result	Output	Specifies the overall success or failure of the request
inout_dcb->charging	Output	HP-UX responders do not use charging, though it may contain information from other responders
inout_dcb->diagnostic	Output	Provides ISO-specific error information