Establishing and Removing Connections

Use the ft_connect(), ft_rrequest(), and ft_aereset() functions to connect, release connections, and reset connections in an orderly manner.

ft_connect()

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
Return_code
ft_connect(ae_label, return_event_name, called_dir_name, 
           input_dcb, inout_dcb, connection_id)
Ae_label                       ae_label;
Local_event_name               return_event_name;
Ae_dir_name                    called_dir_name;
struct Ft_connect_in_dcb       *input_dcb;
struct Ft_connect_out_dcb      **inout_dcb;
Connection_id                  *connection_id;

Use ft_connect() to establish a connection from ftam_init to an FTAM responder. Remember, you must first invoke ft_aeactivation() to start ftam_init.

You will use the returned connection_id on all subsequent, context sensitive FTAM calls to uniquely identify the connection to the desired filestore.

When invoking ft_connect(), the document types, functional_units, and service_classes are negotiated with the responder. When the request is complete, check these fields in the inout_dcb to see if the responder accepted these values, accepted a subset of these values, or rejected these values.
You must set either the input_dcb->called_presentation_address or the called_dir_name. If you set both fields, input_dcb->called_presentation_address takes precedence. Refer to the "FTAM Data Structures" chapter to set either of these parameters.
Specifying these fields requires that you set up the appropriate structures. You can do so manually (as explained in the "FTAM Data Structures" chapter) or you can call one of the following utilities.
To have the system set the P_address, call convert_paddr; the source is in /opt/ftam/demos/cnvrt_addr.c.
To have the system set the Ae_dir_name, call convert_ddn; the source is in /opt/ftam/demos/cnvrt_addr.c.

For instructions on using these utilities, read the on-line README document in /opt/ftam/demos/cnvrt_addr.c. The "Example Programs" chapter also contains the source for convert_paddr and convert_ddn.

For HP-UX responders, the login name (connect_in_info.initiator_identity) must exist on the remote node, and the file_store_pw must be that user's password. Other responders may or may not have similar expectations.
The inout_dcb structure contains the responder's reply to the requested connection parameters.

Ft_connect_in_dcb

struct Ft_connect_in_dcb {
       struct  P_address             called_presentation_address;
       enum    Ae_title_option       called_ae_title_option;
       Ae_title                      *called_ae_title;
       Uint32                        called_ae_invoke_id;
       Uint32                        called_ap_invoke_id;
       Uint8                         number_of_retry;
       Uint32                        delay_between_retry;
       Uint32                        connection_resource_wait_timer;
       struct  Object_id             context_name;
       struct  Ft_connect_req_info   connect_in_info;
};
struct  Ft_connect_req_info  {
     Ft_service_class                  service_class;
     Ft_functional_units               functional_units;
     Ft_attribute_groups               attribute_groups;
     enum  Ft_qos                      quality_of_service;
     struct  Ft_contents_type_element  *contents_type_list;
     Ft_initiator_identity             initiator_identity;
     Ft_account                        account;
     Ft_single_file_pw                 file_store_pw;
};

Ft_connect_out_dcb

struct  Ft_connect_out_dcb {
        Uint32                      size;
        struct Api_rc               result;
        struct P_address            
responding_presentation_address;
        Ae                          responding_ae;
        Uint32                      responding_ae_invoke_id;
        Uint32                      responding_ap_invoke_id;
        struct Object_id            context_name;
        struct Ft_connect_cnf_info  *connect_out_info;
};

struct Ft_connect_cnf_info {
       enum  Ft_state_result             state_result;
       enum  Ft_action_result            action_result;
       Ft_service_class                  service_class;
       Ft_functional_units               functional_units;
       Ft_attribute_groups               attribute_groups;
       enum  Ft_qos                      quality_of_service;
       struct Ft_contents_type_element   contents_type_list;
       struct Ft_diagnostic              *diagnostic;
       enum  Ft_acse_result              acse_result;
       struct Ft_acse_diagnostic         acse_diag;
};

ft_connect() Parameters

ft_connect() Parameter	Type	Description
ae_label	Mandatory Input	Uniquely identifies the AE (ftam_init) you want to service the request
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)
called_dir_name	Mandatory Input if no called_ presentation_address given; otherwise, Optional Input	Directory distinguished name identifying the responder to which you want to connect
input_dcb->called_ presentation_address	Mandatory Input if no called_dir_name given; otherwise, Optional Input	Contains addressing information for the remote responder
input_dcb-> called_ae_title_option	Optional Input	Dictates the interpretation of called_ae_title If it indicates Dir_dist_name_option, called_dir_name must be usable as an address for the remote responder Default is No_value_option
input_dcb-> called_ae_title	Optional Input	Optional ae_title sent to the peer AE Can be either a directory distinguished name or an object_id Determined by how you set called_ae_title_option
input_dcb-> called_ae_invoke_id	Optional Input	HP-UX responders accept, but ignore, this undefined value; default setting is NO_VALUE
input_dcb-> called_ap_invoke_id	Optional Input	HP-UX responders accept, but ignore, this undefined value; default setting is NO_VALUE
input_dcb-> number_of_retry	Optional Input	Number of times (in tenths of seconds) to retry the connection attempt; default is zero
input_dcb-> delay_between_retry	Optional Input	Amount of time (in tenths of seconds) to wait between retrying to establish the connection; default is zero
input_dcb->connection_ resource_wait_timer	Optional Input	Maximum time (in tenths of seconds) to wait for an available association resource; default is zero
input_dcb-> context_name	Mandatory Input	Association Control Service Element (ACSE) context name; you must set this value to 1 0 8571 1 1
input_dcb->connect_ in_info.service_class	Mandatory Input	Determines whether you transfer, access, or manage a file on this connection
input_dcb->connect_ in_info.functional_units	Mandatory Input	Determines which functions are available per connection
input_dcb->connect_ in_info.attribute_groups	Mandatory Input	Specifies the set of attributes (level of support) available on the association
input_dcb->connect_in_ info.quality_of_service	Optional Input	Determines the level of available recovery; FTAM does not automatically attempt recovery
input_dcb->connect_in_ info.contents_type_list	Optional Input	Specifies the allowable document type for the connection
input_dcb->connect_in_ info.initiator_identity	Optional Input	Login account name, which must exist on the node to which you are connecting
input_dcb->connect_ in_info.account	Optional Input	HP-UX responders accept, but ignore, this value
input_dcb->connect_in_ info.file_store_pw	Optional Input	Login password for the initiator_identity
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->responding_ presentation_address	Output	presentation_address returned by the responder
inout_dcb-> responding_ae	Output	ae_title returned by the responder
inout_dcb->responding_ ae_invoke_id	Output	HP-UX responders accept, but ignore this undefined value
inout_dcb->responding_ ap_invoke_id	Output	HP-UX responders accept, but ignore this undefined value
inout_dcb-> context_name	Output	context_name accepted by the responder
inout_dcb->connect_ out_info->state_result	Output	Indicates whether the request moved through regimes; if a failure returns, you will also receive an action_result of FT_AR_PERMANENT_ERROR
inout_dcb->connect_ out_info->action_result	Output	Specifies the overall success or failure of the request
inout_dcb->connect_ out_info->service_class	Output	Highest service_class the responder supports
inout_dcb-> connect_out_info-> functional_unit	Output	functional_units accepted by the responder
inout_dcb-> connect_out_info-> attribute_groups	Output	attribute_groups accepted by the responder
inout_dcb-> connect_out_info-> quality_of_service	Output	Level of available recovery; FTAM does not automatically attempt recovery
inout_dcb-> connect_out_info-> contents_type_list	Output	contents_types (document types) accepted by the responder
inout_dcb->connect_ out_info->diagnostic	Output	Provides ISO-specific error information
inout_dcb->connect_ out_info->acse_result	Output	Indicates overall result of ACSE processing
inout_dcb-> connect_out_info-> acse_diagnostic	Output	Provides Association Control Service Element (ACSE) diagnostic information
connection_id	Output	Uniquely identifies the connection to the filestore; use this connection_id as input to subsequent calls to identify the connection

ft_rrequest()

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

Use ft_rrequest to release a specific connection; afterwards, the connection no longer exists; you must establish a new connection (using ft_connect()).

The ft_rrequest() input_dcb parameter does not contain information; therefore, pass a NULL pointer for the input_dcb parameter.

Ft_relreq_in_dcb

struct  Ft_relreq_in_dcb {
        struct Ft_release_req_info   release_in_info;
};
struct Ft_release_req_info {
        char      *ft_rel_info;
};

Ft_relreq_out_dcb

struct  Ft_relreq_out_dcb {
        Uint32                         size;
        struct  Api_rc                 result;
        struct  Ft_release_cnf_info    *output_info;
};

struct  Ft_release_cnf_info {
        struct  Ft_charging    *charging;
};

ft_rrequest() Parameters

ft_rrequest() Parameter	Type	Description
connection_id	Mandatory Input	Uniquely identifies the connection you want to release
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->output_ info->charging	Output	HP-UX responders do not use charging, though it may contain information from other responders

ft_aereset()

#include %</opt/ftam/include/map.h>
#include %</opt/ftam/include/mapftam.h>
Return_code
ft_aereset(ae_label, return_event_name, inout_dcb)
Ae_label                       ae_label;
Local_event_name               return_event_name;
struct Ft_output               **inout_dcb;

Use ft_aereset() to abort all open connections and return ftam_init to its initial state.

Ft_output

struct  Ft_output {
        Uint32                size;
        struct  Api_rc        result;
};

ft_aereset() Parameters

ft_aereset() Parameter	Type	Description
ae_label	Mandatory Input	Uniquely identifies the AE (ftam_init) you want to reset
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)
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)