HP FTAM/9000 Programmer’s Guide Edition 5 B1033-90014 HP 9000 Networking E0597 Printed in: U.S.A. © Copyright 1997, Hewlett-Packard Company.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty.
©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc.
Printing History The manual printing date and part number indicate its current edition. The printing date will change when a new edition is printed. Minor changes may be made at reprint without changing the printing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes. To ensure that you receive the updated or new editions, you should subscribe to the appropriate product support service.
Preface Purpose The purpose of the HP FTAM/9000 Programmer's Guide is to introduce you to the File Transfer, Access and Management (FTAM) concepts you must know to write FTAM applications. Additionally, this guide provides example programs and program fragments to illustrate the use of FTAM services. Audience The HP FTAM/9000 Programmer's Guide is for application programmers who want to learn to use FTAM and who are familiar with the C programming language.
Organization Chapter 1 HP FTAM/9000 OverviewThis chapter provides an overview of the standards on which HP based this FTAM implementation, and the general concepts you should know before writing FTAM applications. Reading the conceptual information is vital to understanding the terminology used throughout the remainder of the manual. Chapter 2 Using HP FTAM/9000This chapter describes how to start and stop the FTAM system and how to use FTAM regimes, functions, parameters, and libraries.
Chapter 8 Transferring HP FTAM/9000 DataThis chapter describes the functions used to transfer data to and from FTAM files Chapter 9 Handling ErrorsThis chapter describes troubleshooting FTAM, interpreting errors, and logging error information. Chapter10 Example ProgramsThis appendix provides complete examples of HLCF functions, creating FTAM connections, managing and accessing FTAM files, and transferring FTAM data. These programs also use the support functions throughout them.
FTAM Protocol Specifications ISO 8571, Information Processing Systems – Open Systems Interconnection – File Transfer, Access and Management International Standards ISO 8571 ISO 8571, Information Processing Systems – Open Systems Interconnection – File Transfer, Access and Management MAP 3.0 Interface Specifications MAP 3.
Contents 1. HP FTAM/9000 Overview Chapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 The HP-UX Implementation of FTAM . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Open Systems Interconnection (OSI) . . . . . . . . . . . . . . . . . . . . . . . . . .28 ISO/IS 8571 FTAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Manufacturing Automation Protocol (MAP) 3.0 . . . . . . . . . . . . . . . . . .
Contents Using Regimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regime Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the FTAM Regime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the File Selection Regime . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the File Open Regime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Data Transfer Regime .
Contents Directory Services Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72 Organizing Directory Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72 Using Directory Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Ae_dir_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Dir_dn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Ft_contents_type_element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Ft_contents_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_contents_form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_contents_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_document_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Ft_processing_mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 Ft_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Ft_service_class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150 Ft_single_file_pw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 inout_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Using em_hp_select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Waiting On FTAM and Non-FTAM Events . . . . . . . . . . . . . . . . . . Handling Signal Interrupts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using em_hp_sigio() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 181 185 188 Translating Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . em_gperror() . . . . . . . . . . . . . .
Contents ft_fmove_aet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 Ft_fmove_in_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222 Ft_fmove_out_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223 ft_fmove_aet() Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223 Reading and Changing Attributes (HLCF) . . . . . . . . . . . . . . . . . . . . . .226 ft_frattributes(). .
Contents 6. Managing HP FTAM/9000 Connections Chapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Connection Establishment Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Starting and Stopping Application Entities . . . . . . . . . . . . . . . . . . . . . ft_aeactivation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_aeactivation_in_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents ft_ireceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267 Ft_indication_out_dcb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268 ft_ireceive() Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269 7. Managing and Accessing HP FTAM/9000 Files Chapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273 Gaining Access to FTAM Files . . . . . . . . . . . .
Contents Opening and Closing Files (HLCS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . ft_fopen() (HLCS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_fopen_in_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_fopen_out_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ft_fopen() Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ft_fclose() (HLCS) . . . . . . .
Contents ft_egroup(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306 Ft_egroup_out_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306 ft_egroup() Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307 8. Transferring HP FTAM/9000 Data Chapter Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 Sequence of Transferring Data . . . . . . . . . . . . . . . . .
Contents ft_etransfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_etransfer_out_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ft_etransfer() Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ft_cancel(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ft_cancel_in_dcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 10. Example Programs Former Introduction ... need to change . . . . . . . . . . . . . . . . . . . . . . . . .354 Using HLCF Functions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355 Managing FTAM Connections Example. . . . . . . . . . . . . . . . . . . . . . . . .357 Using LLCS Functions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360 Setting Ae_dir_dn and P_address Utility Example . . . . . . . . . . . . . . . .373 Checking for Errors Example . . . .
Contents 24
1 HP FTAM/9000 Overview 25
HP FTAM/9000 Overview File Transfer, Access and Management (FTAM) is an international standard for transfer, access, and management of files in an open network. HP FTAM/9000 is an HP implementation of this standard; it offers the C language programmatic interface defined for MAP 3.0 FTAM, which in turn, provides you with the following capabilities.
HP FTAM/9000 Overview Chapter Overview Chapter Overview This chapter is an overview of the HP-UX implementation of FTAM. The chapter discusses both the standards on which HP FTAM/9000 is based and the high-level concepts you should know before writing FTAM applications (user programs). The major topics are as follows. • The HP-UX Implementation of FTAM • Open Systems Interconnection (OSI) • ISO/IS 8571 FTAM • Manufacturing Automation Protocol (MAP) 3.
HP FTAM/9000 Overview The HP-UX Implementation of FTAM The HP-UX Implementation of FTAM The HP-UX implementation of FTAM is compliant with the following standards and specifications. • Open Systems Interconnection (OSI) Model • ISO/IS 8571 FTAM • Manufacturing Automation Protocol (MAP) 3.0 Application Interface Specification • NBS (NIST) Phase III Implementors Agreements Additionally, HP implemented T1.3, T2.3, A1.3, and M1.3 profiles from the NBS (NIST) Phase III Implementors Agreements.
HP FTAM/9000 Overview The HP-UX Implementation of FTAM Manufacturing Automation Protocol (MAP) 3.0 The Manufacturing Automation Protocol (MAP) 3.0 Specification identifies standard protocols for each of the seven OSI layers. The MAP 3.0 Application Interface Specification defines the C-language programmatic interface to each Application service, including the HP-UX FTAM service.
HP FTAM/9000 Overview The HP-UX Implementation of FTAM Protocol Implementation Conformance Statement (PICS) The HP-UX FTAM Protocol Implementation Conformance Statement (PICS) defines the capabilities of HP-UX FTAM responders. You can use PIC Statements to determine if two implementations can communicate. Refer to the HP FTAM/9000 Reference Manual on how to obtain the HP-UX FTAM PICS. HP implements the profiles A1, M1, T1, and T2.
HP FTAM/9000 Overview Overview of FTAM Concepts Overview of FTAM Concepts This section takes a high-level approach to explaining concepts you should know before writing FTAM applications. This section also refers to specific FTAM functions. For detailed information regarding these concepts and functions, refer to the Table of Contents for specific chapters and sections. The Virtual Filestore (VFS) A real filestore uses a variety of mechanisms to structure, store, and retrieve real files.
HP FTAM/9000 Overview Overview of FTAM Concepts Figure 1-1 HP-UX FTAM Virtual Filestore (VFS) Real File A Shadow Real System Environment Actual Mapping Function Virtual File A OSI Environment Virtual File B Mapping Function Real File B Virtual File C Mapping Function Real File C Shadow Shadow Actual Actual 32 Chapter 1
HP FTAM/9000 Overview Overview of FTAM Concepts FTAM Shadow Files Because the VFS is generalized, certain VFS concepts have no direct correspondence to the HP-UX file system. For example, a VFS file might have fixed-length records. Such records are not defined for the HP-UX file system. To provide HP-UX files with FTAM VFS attributes, HP-UX uses two files: an actual file and an optional shadow file. • The actual file contains the data for the file.
HP FTAM/9000 Overview Overview of FTAM Concepts • If you use cp to create a new copy of an FTAM-related file, a corresponding shadow file will not be created. Subsequent FTAM access to the copy will use default VFS attributes, which may or may not apply. • If you use chmod or chown to change the HP-UX permissions or ownership of an FTAM-related file, the new attributes may conflict with the attributes stored in the corresponding shadow file.
HP FTAM/9000 Overview Overview of FTAM Concepts Figure 1-2 FTAM Regime Order FTAM Regime File Selection Regime File Open Regime Data Transfer Regime FTAM Regime The FTAM regime requests FTAM services for the connection. The FTAM regime, also called the FTAM Association or FTAM Initialization regime, is the outermost regime. File Selection Regime The File Selection regime references (selects) a specific file. You can change and read attributes during this regime.
HP FTAM/9000 Overview Overview of FTAM Concepts Initiators and Responders As noted earlier, you write a program (user program) to access the FTAM interface using a library of functions. FTAM uses the initiator to make requests and the responder to service them. (Refer to Figure 1-3.) Initiator The initiator submits requests on behalf of you. When you submit a request (i.e., call a function), the initiator sends your request to a responder.
HP FTAM/9000 Overview Overview of FTAM Concepts Figure 1-3 FTAM Communication Process User Program ftam_init ftam_resp Fork ftam_resp FTAM Connection Request Moves Across Network Application Entities (AEs) An application entity (AE) is a uniquely identified component of your application that associates it with the OSI communications network. An AE may be an FTAM initiator or responder.
HP FTAM/9000 Overview Overview of FTAM Concepts NOTE Refer to the “FTAM Data Structures” chapter for information on the P_address and Dir_dn structures. Refer to the Installing and Administering HP FTAM/9000 manual and the OSI Troubleshooting Guide for information on the presentation address and directory distinguished name configuration. Once you establish the FTAM regime, you can access and manipulate FTAM files in that filestore.
HP FTAM/9000 Overview Overview of FTAM Concepts NOTE Refer to the “Handling Errors” chapter for information on checking for errors on synchronous and asynchronous calls. Refer to the “Using Support Functions” chapter for information on using em_wait( ). File Attributes An FTAM file has two distinct parts: its attributes and its contents. Attributes describe the file (e.g.
HP FTAM/9000 Overview Overview of FTAM Concepts Constraint Sets Document types restrict the type of file by specifying constraint sets. Constraint sets specify the allowable file structures and the ways in which access actions can modify the structure. Constraint sets are either Unstructured or Sequential Flat. (Refer to Figure 1-5 and Figure 1-6 for file structure information of these two types.) For more information on constraint sets, refer to the “Document Types and Constraint Sets” chapter.
HP FTAM/9000 Overview Overview of FTAM Concepts FTAM File Structure Model The FTAM file model consists of a hierarchical structure (ordered tree) containing various levels. • Each node in the tree contains a node descriptor. Node descriptors reference specific parts of a file. However, a node descriptor may be empty. • Each node in the tree contains a data unit (DU). This data unit contains the actual file contents. A file access data unit (FADU) is the smallest unit you can access in an FTAM file.
HP FTAM/9000 Overview Overview of FTAM Concepts • A Sequential Flat constraint set contains a root FADU with an unlimited number of FADUs one level beneath it. Figure 1-6 FADU Defined by Sequential Flat Constraint Set Node Desc. Node Desc. DU FADU A 42 Node Desc. DU FADU B Node Desc.
2 Using HP FTAM/9000 Before writing HP FTAM/9000 applications, you should understand FTAM libraries, regimes, functions, and parameters.
Using HP FTAM/9000 Chapter Overview Chapter Overview This chapter describes how to start and stop FTAM and explains information you should know before writing applications. The primary sections are as follows. • Starting and Stopping the FTAM System • Generating FTAM Programs • Using Regimes • Using Functions • Using Parameters • General Recommendations NOTE This chapter refers to specific functions. For detailed information on a function, refer to the Table of Contents for the correct chapter.
Using HP FTAM/9000 Starting and Stopping the FTAM System Starting and Stopping the FTAM System The HP OSI Transport Services (OTS/9000) startup procedure automatically starts the ftam_resp daemon (HP FTAM responder). You may occasionally need to start or stop only the FTAM portion of the system. NOTE Bringing down the FTAM portion of the HP OSI network system is destructive and abruptly terminates any activity using the VFS associated with the local responder.
Using HP FTAM/9000 Generating FTAM Programs Generating FTAM Programs Before using FTAM, you must include header files and link your programs with the libmapftam.a and libmap.a libraries. Another important library is the lint(1) library used for detecting bugs. Header Files In your *.c files (source files), you must have the following lines at the beginning of your program to include the appropriate header files. #include % #include % libmapftam.
Using HP FTAM/9000 Using Regimes 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.
Using HP FTAM/9000 Using Regimes • 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.
Using HP FTAM/9000 Using Regimes • 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.
Using HP FTAM/9000 Using Regimes 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 t
Using HP FTAM/9000 Using Functions 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.
Using HP FTAM/9000 Using Functions 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().
Using HP FTAM/9000 Using Functions Figure 2-2 Available FTAM Functions Per Regime ft_aedeactivation() ft_aereset() ft_abort() ft_aeactivation() FTAM Regime File Selection Regime File Open Regime Data Transfer Regime ft_read() ft_write() ft_etransfer() ft_cancel ft_rcancel() ft_locate() ft_erase() ft_open() ft_rattribute() ft_cattribute() ft_select() ft_create() ft_close() ft_sdata() ft_rdata() ft_edata() ft_rdataqos() ft_deselect() ft_delete() ft_connect() ft_rrequest() Chapter 2 53
Using HP FTAM/9000 Using Functions The following table briefly describes the FTAM functions.
Using HP FTAM/9000 Using Functions Function Description 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
Using HP FTAM/9000 Using Functions Function Description 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
Using HP FTAM/9000 Using Functions Function Description 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
Using HP FTAM/9000 Using Functions Figure 2-3 Example Use of Low Level FTAM Functions Activate mapftam_init Establish FTAM Connections ft_aeactivation ft_connect Select or Create FTAM Files ft_select ft_create Read or Change FTAM File Attributes ft_rattributes ft_cattributes Open FTAM Files ft_open Access FTAM Files ft_locate ft_erase Transfer FTAM Files ft_read ft_sdata ft_write ft_edata ft_rdata ft_cancel ft_etransfer ft_rdataqos Close FTAM Files ft_close Deselect FTAM Files ft_deselect ft
Using HP FTAM/9000 Using Functions Typical Applications Figure 2-3 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 HP FTAM/9000 Using Parameters Using Parameters This section discusses parameters to FTAM functions, focussing on the input_dcb and inout_dcb parameters. For information on specific parameters, determine the function using the parameter; then use the Table of Contents to locate the chapter explaining that function. Parameters are the mechanisms for exchanging information between your application and the FTAM interface.
Using HP FTAM/9000 Using Parameters Data Control Blocks Data control blocks (DCBs) are C structures used as function parameters to pass information between your application and the FTAM interface. input_dcb Contains only function input parameters. inout_dcb Contains parameters used for both input and output, and parameters used for output only. Most FTAM functions use both an input_dcb and an inout_dcb. input_dcb The values used within input_dcb depend on the function requirements.
Using HP FTAM/9000 Using Parameters For asynchronous calls, you should not access the inout_dcb memory from the time the asynchronous call returns SUCCESS until em_wait() verifies completion of the request; otherwise, the memory occupied by the inout_dcb contains random data. You can allocate memory for inout_dcb in three ways. 1. The recommended method is to have the inout_dcb address reference a NULL value when first making the call.
Using HP FTAM/9000 General Recommendations General Recommendations Observe the following recommendations for programming with FTAM: • FTAM functions are not re-entrant. Do not call any FTAM function within a signal handler. • The inout_dcb pointer should reference a NULL value on input. This way, you do not have to anticipate the necessary output memory; the FTAM interface will allocate it for you. (Remember to later free the memory using ft_dfdcb().) • You are guaranteed a minimum of 10 local to local (i.
Using HP FTAM/9000 General Recommendations Handling Strings, HP-UX Lines, and FTAM-1 Lines NOTE This section applies to FTAM-1 files only and to strings as they are used within low level FTAM calls. This section clarifies the meaning of a string, HP-UX line, and FTAM-1 line. When transferring data with low level calls, you must understand FTAM-1 lines. If you are reading or writing local HP-UX files using low level calls, you must understand how to convert between HP-UX lines and FTAM lines.
3 HP FTAM/9000 Data Structures HP FTAM/9000 functions use data structures to handle information consistently and to pass information between cooperating applications.
HP FTAM/9000 Data Structures NOTE Your understanding of FTAM data structures is vital to your success in creating FTAM applications.
HP FTAM/9000 Data Structures Chapter Overview Chapter Overview This chapter describes the structures used for Directory Services, Event Management functions (e.g., em_wait(), em_gperror(), and em_fdmemory()), and FTAM. Additionally, the chapter describes header files, setting bits with defined constants, and basic data types.
HP FTAM/9000 Data Structures Header Files Header Files Two header files, map.h and mapftam.h, contain the necessary FTAM structures, constants, and type definitions. Complete header files are available online in /opt/ftam/include. map.h This header file contains definitions for the constants and structures shared by MAP-based OSI services and those used the Event Management functions em_wait(), em_fdmemory(), and em_gperror(). To communicate with remote systems, you must use the map.
HP FTAM/9000 Data Structures Using Defined Constants To Set Bits Using Defined Constants To Set Bits Certain structures require that you use defined constants to set bits to request specific items like attributes, actions, and concurrency control. You request an item by setting a bit to ON (1). Refer to the following table for a list of defined constants and their corresponding structures.
HP FTAM/9000 Data Structures Basic Data Types Basic Data Types The FTAM interface uses the following data types. These basic types are unambiguous typedef synonyms for well-known intrinsic C data types.
HP FTAM/9000 Data Structures Basic Data Types Octet_string struct Octet_string { Uint32 length; Octet_pointer pointer; }; /* List of Octets */ The Octet_string is a widely used map.h structure containing the following fields. length Number of Octets in the pointer array. pointer Pointer to a array of Octets.
HP FTAM/9000 Data Structures Directory Services Data Structures Directory Services Data Structures Directory Services holds and provides access to information about objects (generally existing in telecommunications and information processing). Directory Services stores information in an area collectively known as the Directory Information Base (DIB). FTAM uses Directory Services to identify responders. One analogy is that Directory Services is like a telephone directory that lists responders.
HP FTAM/9000 Data Structures Directory Services Data Structures Figure 3-1 Example Directory Services (X.
HP FTAM/9000 Data Structures Directory Services Data Structures Using Directory Services FTAM uses Directory Services whenever you call ft_connect() or high level calls to specify your directory or the directory with which you want to communicate.
HP FTAM/9000 Data Structures Directory Services Data Structures Ae_dir_name typedef Dir_dn *Ae_dir_name; Ae_dir_name is the primary structure for setting the directory distinguished name when calling ft_connect(), ft_aeactivation(), and all high level, context free (HLCF) functions. The embedded structures are Dir_dn, Dir_rdn, and Dir_ava ( Figure 3-2). To have the system automatically set the Ae_dir_name structure, call convert_ddn; the source is in /opt/ftam/demos/cnvrt_addr.c.
HP FTAM/9000 Data Structures Directory Services Data Structures Dir_dn typedef struct Dir_dn /* Directory Distinguished name */ { Sint8 n; /*No. of relative dist. names */ struct Dir_rdn *rdn; /*Ptr to a sequence of Dir_rdn */ } Dir_dn; Dir_dn identifies the directory distinguished name. • The first field (n) is the number of relative distinguished names (rdn). • The rdn field points to an array of Dir_rdn structures containing attribute value assertions (avas).
HP FTAM/9000 Data Structures Directory Services Data Structures Dir_rdn typedef struct Dir_rdn { Sint8 n; struct Dir_ava } Dir_rdn; /* Relative distinguished names */ /*Number of avas */ *avas; Dir_rdn identifies the relative distinguished name (Figure 3-4). • Each rdn is part of the directory distinguished name. Refer to the following example. • The first field (n) is the number of attribute value assertions (avas). • Each avas points to a Dir_ava structure containing attr_id, attr_value, and syntax_id.
HP FTAM/9000 Data Structures Directory Services Data Structures Figure 3-4 Dir_rdn Structure Dir_ava attr_id n Number of the Directory Entry attr_value length pointer Name of the Directory Entry syntax_id length element Future ISO Use length element Number of the Directory Entry attr_value length pointer Name of the Directory Entry syntax_id length element Future ISO Use attr_id Dir_rdn length element 2 ava n 1 ava Dir_ava attr_id length element Number of the Directory Entry attr
HP FTAM/9000 Data Structures Directory Services Data Structures Dir_ava typedef struct Dir_ava /* Attribute Value assertions */ { struct Object_id attr_id; struct Octet_string attr_value; struct Object_id syntax_id; /* for future use */ } Dir_ava; Dir_ava is the final embedded structure in the Ae_dir_name structure that defines the directory distinguished name (Figure 3-5). Each Dir_ava contains the following fields: attr_id (e.g., country), attr_value (e.g.
HP FTAM/9000 Data Structures Directory Services Data Structures attr_id The attr_id is an attribute type identifier that is of type struct Object_id. You must set attr_id in one of these two ways. • Set the first three fields to 2, 5, and 4. Set the fourth field to the directory entry identification number. You must use these numbers since they define a standard attribute type for the protocol.
HP FTAM/9000 Data Structures Directory Services Data Structures Setting Ae_dir_name Example This example sets the Ae_dir_name structure. #include “map.h” #include “mapftam.h” #include % #include % /* ** ** setup_ddn ** ** DESCRIPTION: ** This routine assigns valid values to the Ae_dir_name ** structure. ** ** ** PARAMETERS: ** Outputs: ** dirname : pointer to the Ae_dir_name structure ** Ae_dir_name is a pointer to struct ** Dir_dn.
HP FTAM/9000 Data Structures Directory Services Data Structures be “3”. */ (void)addrdn( & (*dirname)->rdn[3], 3, “machine_name”); /* AE = ftam_resp The Application Entity attribute id is defined by ISO to be “3”. */ (void)addrdn( & (*dirname)->rdn[4], 3, “ftam_resp”); } /* *** addrdn ** ** DESCRIPTION: ** This routine sets up the Dir_rdn structure using the input ** parameters for values.
HP FTAM/9000 Data Structures Ae_label Ae_label typedef Uint32 Ae_label Ae_label Is Input To These Functions Ae_label Is Output From These Functions ft_aedeactivation() ft_aeactivation() ft_aereset() ft_fcattributes() ft_connect() ft_fcopy() ft_fcattributes() ft_fdelete() ft_fcopy() ft_fmove() ft_fdelete() ft_frattributes() ft_fmove() ft_frattributes() Ae_label identifies the ftam_init activated on a successful ft_aeactivation() request.
HP FTAM/9000 Data Structures Ae_title Ae_title typedef union Ae_title { struct Object_id ae_object_id; struct Dir_dn ae_dir_dn; } Ae_title; Ae_title Is Input To These Functions ft_aeactivation() Ae_title Is Output From These Functions ft_connect() ft_connect() The my_ae_title input to ft_aeactivation() specifies the ae_title of the ftam_init to activate. The called_ae_title input to ft_connect() enables you to specify an optional ae_title for the responder.
HP FTAM/9000 Data Structures Ae_title_option Ae_title_option enum { Ae_title_option No_value_option, Dir_object_id_option, /* Object_id value obtained from the * network or local system directory */ User_object_id_option, /* Object_id value supplied by the * user */ Dir_dist_name_option, /* Use the distinguished name value * provided by the my_dir_name * or called_dir_name parameter. */ User_dist_name_option /* Distinguished name value supplied * by the user.
HP FTAM/9000 Data Structures Ae_title_option Ae_title_option ft_aeactivation() ft_connect() User_object_id_option Supported Supported Dir_dist_name_option Not supported Not supported User_dist_name_option Not supported Not supported No_value_option Ignore the Ae_title on ft_aeactivation() and ft_connect(); no Ae_title is sent to the remote system. • For ft_aeactivation(), use my_dir_name. • For ft_connect(), use the P_address if it exists; otherwise, use called_dir_name.
HP FTAM/9000 Data Structures Api_rc Api_rc typedef struct Api_rc { Return_code return_code; /* MAP errors */ Return_code vendor_code; /* Optional Vendor defined errors */ } Api_rc; Api_rc (Application Interface return_code) provides you with error information when a function fails. Every function has a parameter of this type, usually in its inout_dcb and usually defined as the result parameter.
HP FTAM/9000 Data Structures Api_rc return_code Specifies the MAP 3.0 error that occurred. These errors are listed as defined FTExxx constants. Refer to the HP FTAM/9000 Reference Manual for a list of possible errors, their causes, and corrective actions. • A return_code value of SUCCESS (zero) indicates the request went through the application interface, ftam_init, and responder, and returned back to the user program.
HP FTAM/9000 Data Structures Connection_id Connection_id typedef Uint32 Connection_id; Connection_id Is Input To These Functions ft_abort() ft_bgroup() ft_cancel() ft_cattributes() ft_close() ft_create() ft_delete() ft_deselect() ft_edata() ft_egroup() ft_erase() ft_etransfer() ft_fclose() ft_fopen() ft_ireceive() ft_locate() ft_nwcleared() ft_open() ft_rattributes() ft_rcancel() ft_rdata() ft_read() ft_rrequest() ft_sdata() ft_select() ft_write() Connection_id Is Output From These Functions ft_connect(
HP FTAM/9000 Data Structures Ft_access_context Ft_access_context enum Ft_access_context { FT_AC_ENUM_DEFAULT FT_HIERARCHICAL_ALL_DATA_UNITS FT_HIERARCHICAL_NO_DATA_UNITS FT_FLAT_ALL_DATA_UNITS FT_FLAT_ONE_LEVEL_DATA_UNITS FT_FLAT_SINGLE_DATA_UNIT FT_UNSTRUCTURED_ALL_DATA_UNITS FT_UNSTRUCTURED_SINGLE_DATA_UNIT = = = = = = = = -1, 0, 1, 2, 3, 4, 5, 6 }; Ft_access_context Is Input To These Functions ft_read() Ft_access_context Is Output From These Functions None Ft_access_context specifies how you want
HP FTAM/9000 Data Structures Ft_access_context FT_FLAT_ALL_DATA_UNITS For FTAM-2 files, specifies that you will see both file structure and data. FT_UNSTRUCTURED_ALL_DATA_UNITS For FTAM-2 files, specifies that you will see only data. For FTAM-1 and FTAM-3 files, reads the whole file.
HP FTAM/9000 Data Structures Ft_access_control Ft_access_control struct Ft_access_control { struct Ft_access_control_element struct Ft_access_control_element }; Ft_access_control Is Input To These Functions ft_cattributes() *insert_ace; *delete_ace; Ft_access_control Is Output From These Functions None ft_create() ft_fcattributes() ft_fopen() Use Ft_access_control to add users to and delete users from the access list (Ft_access_control_elements) for a particular file.
HP FTAM/9000 Data Structures Ft_access_control Figure 3-7 Ft_access_control Ft_access_control Structure Ft_access_control_element Ft_access_control_element *insert_ace *next *next *delete_ace action_list action_list conc_access conc_access identity identity *access_passwords *access_passwords *location *location Ft_access_control_element Ft_access_control_element *next *next action_list action_list conc_access conc_access identity identity *access_passwords *access_passwords *loca
HP FTAM/9000 Data Structures Ft_access_control Ft_access_control_element struct Ft_access_control_element { struct Ft_access_control_element Ft_file_actions Uint32 Ft_initiator_identity struct Ft_file_passwords Ae }; *next; action_list; conc_access; identity; *access_passwords; *location; Ft_access_control_element defines not only who can access a file, but also how they can access it. HP-UX initiators and responders use only the identity and action_list fields.
HP FTAM/9000 Data Structures Ft_access_control For ft_open(), the processing_mode parameter must be a subset of the values stored in action_list. The action_list is of type Ft_file_actions. Refer to the “Ft_file_actions” section for detailed information. conc_access The HP-UX implementation of FTAM ignores this value. You can set the bits in conc_access, but HP-UX initiators and responders will not use it. Other FTAM implementations might.
HP FTAM/9000 Data Structures Ft_access_control *access_passwords Specifies a user password for each element listed in the action_list. HP-UX initiators and responders do not use this information; access_passwords is only used with other FTAM implementations. Points to the Ft_file_passwords structure. Refer to the “Ft_file_passwords” section for detailed information. *location A pointer of type Ae.
HP FTAM/9000 Data Structures Ft_account Ft_account typedef char *Ft_account; Ft_account Is Input To These Functions ft_connect() Ft_account Is Output From These Functions None ft_create() ft_fcattributes() ft_fcopy() ft_fdelete() ft_fmove() ft_fopen() ft_frattributes() ft_select() HP-UX responders accept, but ignore, Ft_account. Setting the value to NULL is a recommended practice.
HP FTAM/9000 Data Structures Ft_attribute_groups Ft_attribute_groups typedef Uint16 Ft_attribute_groups; Ft_attribute_groups Is Input To These Functions ft_connect() Ft_attribute_groups Is Output From These Functions ft_connect() Ft_attribute_groups specifies the level of support for attributes. Attributes are grouped as either kernel, storage, security, or private. • The kernel attributes are always present (i.e., you do not negotiate them).
HP FTAM/9000 Data Structures Ft_attribute_groups The available attribute groups and their associated attributes are as follows: Kernel Group Provides basic attributes that are always available. filename permitted_actions contents_type Storage Group Provides additional information on how the file is stored.
HP FTAM/9000 Data Structures Ft_attribute_groups Security Group Allows FTAM to enforce what users may operate on the file and what access each user has. access_control legal_qualification * Private Group ISO does not define the private attributes group. private_use * * HP-UX responders accept, but ignore, these values. To set attribute groups, use the FT_AG_xxx defined constants in the mapftam.h file.
HP FTAM/9000 Data Structures Ft_attribute_names Ft_attribute_names typedef Uint32 Ft_attribute_names; Ft_attribute_names Is Input To These Functions ft_cattributes() Ft_attribute_names Is Output From These Functions None ft_create() ft_fcattributes() ft_fopen() ft_frattributes() ft_rattributes() This section discusses Ft_attribute_names as a primary structure. For information on Ft_attribute_names as it relates to the mask field in struct Ft_attributes, refer to the “Ft_attributes” section.
HP FTAM/9000 Data Structures Ft_attribute_names Use Ft_attribute_names to set the attribute values you want available for each file. Use the FT_AN_xxx defined constants in the mapftam.h file.
HP FTAM/9000 Data Structures Ft_attributes Ft_attributes struct Ft_attributes { Ft_attribute_names struct Ft_attribute_values mask; values; }; Ft_attributes Is Input To These Functions Ft_attributes Is Output From These Functions ft_cattributes() ft_cattributes() ft_create() ft_create() ft_fcattributes() ft_fcattributes() ft_fopen() ft_fcopy() ft_select() ft_fmove() ft_fopen() ft_frattributes() ft_rattributes() ft_select() Every file contains attributes that uniquely identify the file and a
HP FTAM/9000 Data Structures Ft_attributes Attributes You Can Change Attributes You Cannot Change filename permitted_actions storage_account* contents_type file_availability* date_time_of_creation future_filesize* date_time_of_modification access_control date_time_of_read legal_qualification* date_time_of_attribute_mod private_use* identity_of_creator identity_of_modifier identity_of_reader identity_of_attribute_mod filesize * With HP-UX FTAM responders, changing these values has no effect.
HP FTAM/9000 Data Structures Ft_attributes Ft_attribute_names typedef Uint32 Ft_attribute_names; Ft_attribute_names Is Input To These Functions Ft_attribute_names Is Output From These Functions ft_cattributes() ft_cattributes() ft_create() ft_create() ft_fcattributes() ft_fcattributes() ft_fopen() ft_fopen() ft_frattributes() ft_frattributes() ft_rattributes() ft_rattributes() Ft_attribute_names is the type for the mask field in Ft_attributes.
HP FTAM/9000 Data Structures Ft_attributes Ft_attribute_values struct Ft_attribute_values { Ft_filename Ft_permitted_actions struct Ft_contents_type Ft_account Time Time Time Time Ft_initiator_identity Ft_initiator_identity Ft_initiator_identity Ft_initiator_identity enum Ft_file_availability Sint32 Sint32 struct Ft_access_control Ft_legal_qualification struct Octet_string filename; permitted_actions; contents_type; storage_account; date_time_of_creation; date_time_of_modification; date_time_of_read; dat
HP FTAM/9000 Data Structures Ft_attributes filename Character string that identifies the name of the file. permitted_actions Specifies all allowable actions on the file (without specifying who is allowed to perform the actions). The permitted_actions is type Ft_permitted_actions. • For each file, set bits in permitted_actions for the actions you are allowing to be performed.
HP FTAM/9000 Data Structures Ft_attributes storage_account Identifies the accountable authority responsible for accumulated file storage charges. HP-UX FTAM responders set storage_account so that the indication no value available (0) returns if you invoke ft_rattributes() or ft_frattributes(). If you invoke functions that contain storage_account in the input_dcb, HP-UX responders accept, but ignore, the value. Specifies, respectively, the following dates.
HP FTAM/9000 Data Structures Ft_concurrency_control file_availability The file_availability is of the following type: enum Ft_file_availability { FT_IMMEDIATE_AVAIL, FT_DEFERRED_AVAIL }; For HP-UX responders, you can access the file immediately regardless of which value you select. For some implementations, file_availability indicates whether a delay occurs before you can access the file. filesize Specifies the maximum size (in Octets) of the file.
HP FTAM/9000 Data Structures Ft_concurrency_control Ft_concurrency_control Is Input To These Functions Ft_concurrency_control Is Output From These Functions ft_create() ft_fopen() ft_fcopy() ft_open() ft_fcattributes() ft_fdelete() ft_fmove() ft_fopen() ft_frattributes() ft_open() ft_select() Concurrency locks define whether users can simultaneously access a file. Ft_concurrency_control specifies the type of available concurrency locks for each action on a file.
HP FTAM/9000 Data Structures Ft_concurrency_control Ft_file_lock enum Ft_file_lock { FT_NOT_REQUIRED FT_SHARED FT_EXCLUSIVE FT_NO_ACCESS = = = = 0, 1, 2, 3 }; Ft_file_lock enumerates the type of locks on a file. It is the enumerated type for values in struct Ft_concurrency_control. For example, if you want to be able to read a file, but you do not want other users to be able to, set the concurrency_control.read lock to FT_EXCLUSIVE.
HP FTAM/9000 Data Structures Ft_concurrency_control • The ft_open() concurrency control must be identical to—or more restrictive than—the ft_select() concurrency control; it may not be less restrictive CAUTION When a system has an NFS-mounted file system , two different files can have the same device id and inode number. If both are used by FTAM concurrently, the locks applied to one file could interfere with a select or open operation on the other file.
HP FTAM/9000 Data Structures Ft_contents_type_element Ft_contents_type_element struct Ft_contents_type_element { struct Ft_contents_type_element struct Ft_contents_type *next_element; contents_type; }; Ft_contents_type_element Is Input To These Functions ft_connect() Ft_contents_type_element Is Output From These Functions ft_connect() On input, Ft_contents_type_element is the requested document types per connection; on output, it is a linked list of allowable (negotiated) document types per connectio
HP FTAM/9000 Data Structures Ft_contents_type Ft_contents_type struct Ft_contents_type { enum Ft_contents_form union Ft_contents_info contents_form; contents_info; }; Ft_contents_type specifies the allowable document type for a particular file. Ft_contents_type is the type for the contents_type field in struct Ft_contents_type_element (a linked list of allowable document types per connection). This structure is also nested within the values field, which is of type struct Ft_attributes.
HP FTAM/9000 Data Structures Ft_contents_type Ft_contents_info union Ft_contents_info { struct Ft_document_type struct Ft_abs_con_set_pair document; abs_con_set_pair; }; Ft_contents_info specifies the document type. • If you specified FT_DOCUMENT_TYPE in Ft_contents_form, specify the document. • If you specified FT_CONTENTS_UNKNOWN in Ft_contents_form, Ft_contents_info is ignored. • As noted under Ft_contents_form, HP-UX responders do not permit use of the abs_con_set_pair structure.
HP FTAM/9000 Data Structures Ft_contents_type name Specifies the name of the document type and is of the following type struct Object_id (from map.h). struct Object_id { Uint16 length; Sint32 *element; }; /* List of integers */ • Set the length field to 5 for all document types except NBS-9; for document type NBS-9 set length to 6. struct Ft_contents_type cont_type; cont_type.contents_info.document.name.
HP FTAM/9000 Data Structures Ft_contents_type Ft_dt_ftam_1. struct Ft_dt_ftam_1 { enum Ft_class Uint16 enum Ft_string_significance }; class; string_length; significance; • The class must be FT_CL_IA5_STRING or FT_CL_GENERAL_STRING. • The string_length supported by responders must be at least 0 to 134; for HP-UX responders, string_length is unlimited. • The significance must be FT_SS_NO_SIGNIFICANCE. Ft_dt_ftam_2.
HP FTAM/9000 Data Structures Ft_contents_type Ft_dt_intap_1. struct Ft_dt_intap_1 { Uint16 enum Ft_string_significance }; record_length; significance; • Ft_dt_intap_1 defaults to FT_CL_OCTET_STRING. • The record_length is unlimited. • The significance must be FT_SS_VARIABLE or FT_SS_FIXED. Ft_dt_nbs_9. struct Ft_dt_nbs_9 { Ft_attribute_names }; mask; • mask is a 32-bit unsigned integer. Use any of the FT_AN_xxx defined constants to set bits in the mask. See Ft_attribute_names for details.
HP FTAM/9000 Data Structures Ft_data_unit Ft_data_unit struct Ft_data_unit { struct Ft_data_unit enum Ft_structure_id union { struct Ft_data_element struct Ft_node_descriptor } data; }; Ft_data_unit Is Input To These Functions ft_sdata() *next; structure_id; *data_element; *node; Ft_data_unit Is Output From These Functions ft_rdata() Ft_data_unit is a linked list of data units (maximum 14 data units per call). Each data unit contains the data that FTAM manipulates (Figure 3-8).
HP FTAM/9000 Data Structures Ft_data_unit Figure 3-8 Ft_data_unitcStructure Up to 14 struct Ft_data_unit per call NOTE Ft_data_unit Ft_data_unit Ft_data_unit *next *next *next structure_id structure_id structure_id data data data To understand Ft_data_unit, you should be familiar with the concepts FADU, data unit, data element, and node descriptor. Refer to the “HP-UX FTAM Overview” chapter for descriptions. *next Points to the next Ft_data_unit structures in the linked list.
HP FTAM/9000 Data Structures Ft_data_unit Ft_structure_id specifies which structure in the data union is applicable (Ft_data_element or Ft_node_descriptor) or it specifies the end or cancellation of data transfer (on output only). FT_DATA_UNIT Use FT_DATA_UNIT to send actual data. FT_DATA_UNIT dictates that you choose data_element in the data union. FT_NODE_DESC Use FT_NODE_DESC only for FTAM-2 document types to begin a new FADU. FT_NODE_DESC dictates that you choose node in the data union.
HP FTAM/9000 Data Structures Ft_data_unit union Ft_primitive { Bool boolean; Sint32 integer; struct Bit_string bit_string; struct Octet_string octet_string; struct Octet_string ia5string; Time utc; Time time; char *graphic_string; char *visible_string; struct Octet_string general_string; double floating_point; struct Octet_string ul_integer; struct Ft_ul_floating_point { Sint16 sign; struct Bit_string mantissa; struct Octet_string exponent; } ul_floating_point; struct Ft_attributes attributes; struct Octet_
HP FTAM/9000 Data Structures Ft_data_unit FTAM-1 FTAM-2 IA5_STRING GENERAL_STRING GRAPHIC_STRING GENERAL_STRING FTAM-3 and INTAP-1 OCTET_STRING NBS-9 ATTRIBUTE GRAPHIC_STRING GENERAL_STRING primitive The primitive is the specific unit that contains actual data. Set primitive to the value specified by prim_type. See the previous table. Note that the maximum string length is 7168 (7K) octets. EXAMPLE: This example sets a data_element for FTAM-2 document type.
HP FTAM/9000 Data Structures Ft_data_unit Figure 3-10 Ft_node_descriptor Structure Up to 14 struct Ft_data_unit per call Ft_data_unit Ft_data_unit *next *next FT_NODE_DESC Ft_node_descriptor FT_DATA_UNIT *node fadu_name arc_length *data_element Ft_data_element prim_type primitive data_exists fadu_name HP-UX responders accept, but ignore, the fadu_name field. HP recommends you set the fadu_name.length to zero and fadu_name.pointer to NULL.
HP FTAM/9000 Data Structures Ft_data_unit Rules for Ft_data_unit Linked Lists (FTAM-2 Only) The following rules apply to Ft_data_unit linked lists for FTAM-2 document types only. • If you have an empty file, you must begin the linked list with a node descriptor (not a data element). • If a file already contains data, you may or may not have a node descriptor, depending on whether you are starting a new FADU. • Do not immediately follow a node descriptor with another node descriptor.
HP FTAM/9000 Data Structures Ft_dcb_type Ft_dcb_type enum Ft_dcb_type { FTiAeactivation FToAeactivation FTiAedeactivation FToAedeactivation FTiConnect FToConnect FTiRelease FToRelease FTiAbort FToAbort FTiAereset FToAereset FTiIreceive FToIreceive FToNwcleared FTiFCopy FToFCopy FTiFMove FToFMove FTiFDelete FToFDelete FTiFRattributes FToFRattributes FTiFCattributes FToFCattributes FTiFOpen FToFOpen FTiFClose FToFClose FTiSelect FToSelect FTiDeselect FToDeselect FTiOpen FToOpen FTiClose FToClose FTiCreate F
HP FTAM/9000 Data Structures Ft_dcb_type This Ft_dcb_type data type is continued from the previous page.
HP FTAM/9000 Data Structures Ft_delete_action Ft_delete_action enum Ft_delete_action { FT_DELETE_FILE FT_DONT_DELETE_FILE = 0, = 1 }; Ft_delete_action Is Input To These Functions ft_fclose() Ft_delete_action Is Output From These Functions None Ft_delete_action specifies whether to delete a file or only deselect it on an ft_fclose() function. FT_DELETE_FILE Closes, deselects, and then deletes the file. FT_DONT_DELETE_FILE Closes and deselects, but does not delete the file.
HP FTAM/9000 Data Structures Ft_delete_overwrite Ft_delete_overwrite enum Ft_delete_overwrite { FT_RECREATE_FILE FT_DONT_RECREATE_FILE = 0, = 1 }; Ft_delete_overwrite Is Input To These Functions ft_fcopy() Ft_delete_overwrite Is Output From These Functions None ft_fmove() Ft_delete_overwrite specifies whether or not to copy over (ft_fcopy()) or move over (ft_fmove()) an existing file. FT_RECREATE_FILE Copy or move the source file over the existing destination file.
HP FTAM/9000 Data Structures Ft_diagnostic Ft_diagnostic struct Ft_diagnostic { struct enum Uint16 enum enum Uint16 char Ft_diagnostic Ft_diag_type Ft_entity_ref Ft_entity_ref *next; diag_type; error_id; error_observer; error_source; suggested_delay; *further_details; }; Ft_diagnostic Is Input To These Functions ft_abort() ft_cancel() ft_edata() ft_rcancel() Ft_diagnostic Is Output From These Functions ft_cattributes() ft_close() ft_connect() ft_create() ft_delete() ft_deselect() ft_edata() ft_erase(
HP FTAM/9000 Data Structures Ft_diagnostic The further_details field may vary across different vendor responders. Refer to the HP FTAM/9000 Reference Manual for a list of HP-UX diagnostic messages, their probable causes, and possible corrective actions.
HP FTAM/9000 Data Structures Ft_diagnostic error_source Specifies the entity in which the error occurred. suggested_delay Specifies the amount of time to wait before attempting recovery if the Ft_diag_type is FT_TRANSIENT. HP-UX responders do not use this field; they never return a diag_type of FT_TRANSIENT. *further_details Provides additional information (a text message) about the cause of the error. This information may vary among different vendor responders.
HP FTAM/9000 Data Structures Ft_diagnostic FT_NOT_CATEGORIZED The error may have occurred or been detected anywhere. FT_INITIATING_FILE_SERVICE_USER The error is in the user program. FT_INITIATING_FILE_PROTOCOL_MACHINE The error is in or detected by the initiator. FT_SERVICE_-SUPPORTING_FILE_PROTOCOL_MACHINE The error is in one of the lower layers, probably the Presentation Service. FT_RESPONDING_FILE_PROTOCOL_MACHINE The error is in or detected by the responder.
HP FTAM/9000 Data Structures Ft_fadu_identity Ft_fadu_identity struct Ft_fadu_identity { enum Ft_fadu_form union Ft_fadu_info fadu_form; fadu_info; }; Ft_fadu_identity Is Input To These Functions ft_erase() Ft_fadu_identity Is Output From These Functions ft_locate() ft_locate() ft_read() ft_write() Ft_fadu_identity identifies the whole file (the single FADU) for FTAM-1, FTAM-3, and INTAP-1 files. This structure also identifies either the whole file or individual FADUs for FTAM-2 files.
HP FTAM/9000 Data Structures Ft_fadu_identity • The value specified in fadu_form dictates the value used in fadu_info. • For HP-UX responders, you must specify FT_FADU_LOCATION. HP-UX responders return an error if you use FT_FADU_NAME, FT_NAME_LIST, or FT_NUMBER.
HP FTAM/9000 Data Structures Ft_fadu_identity FT_NEXT The FADU immediately after the FADU where the file pointer is currently located. FT_BEGIN For ft_read(), ft_write(), and ft_erase(), initial location in the file, before all FADUs. For ft_locate(), earliest FADU in the file. FT_END The final location in the file, after all FADUs. *Invalid for use with HP-UX responders. • Use only FT_FIRST for FTAM-1, FTAM-3, INTAP-1, and NBS-9 document types (constrained by the Unstructured All constraint set).
HP FTAM/9000 Data Structures Ft_fadu_operation Ft_fadu_operation enum Ft_fadu_operation { FT_INSERT FT_REPLACE FT_EXTEND = 0, = 1, = 2 }; Ft_fadu_operation Is Input To These Functions ft_write() Ft_fadu_operation Is Output From These Functions None Ft_fadu_operation specifies the action you are taking on a FADU. FT_INSERT Inserts data at the end of a file (FTAM-2 only). FT_REPLACE Replaces the existing FADU contents (FTAM-1, FTAM-3, and INTAP-1 only).
HP FTAM/9000 Data Structures Ft_file_actions Ft_file_actions typedef Uint16 Ft_file_actions; Ft_file_actions Is Input To These Functions ft_create() Ft_file_actions Is Output From These Functions None ft_fopen() ft_select() If you have access control, Ft_file_actions specifies the allowable actions the designated users can perform on a file. If you do not have access control, Ft_file_actions specifies the requested actions on the file.
HP FTAM/9000 Data Structures Ft_file_passwords FT_FA_READ Reads contents of the file (FTAM-1, FTAM-3, and INTAP-1) or of the FADU (FTAM-2). FT_FA_INSERT Inserts data at the end of a file (FTAM-2 only). FT_FA_REPLACE Replaces the existing FADU contents (FTAM-1, FTAM-3, and INTAP-1 only). FT_FA_EXTEND Appends data to the end of the existing FADU (FTAM-1, FTAM-3, and INTAP-1 only). FT_FA_ERASE Erases the entire file. FT_FA_READ_ATTRIBUTE Reads the file attributes.
HP FTAM/9000 Data Structures Ft_file_passwords Ft_file_passwords Is Input To These Functions ft_create() Ft_file_passwords Is Output From These Functions None ft_fcopy() ft_fmove() ft_fcattributes() ft_fopen() ft_frattributes() ft_select() NOTE Since the HP-UX file system does not define file passwords, HP-UX FTAM responders do not use file password information. Ft_file_passwords specifies a user password for each action.
HP FTAM/9000 Data Structures Ft_file_status Ft_file_status enum Ft_file_status { FT_FS_ENUM_DEFAULT FT_NEW FT_OLD FT_REPLACE_CONTENTS FT_RECREATE FT_UNKNOWN = = = = = = -1, 0, 1, 2, 3, 4 }; Ft_file_status Is Input To These Functions ft_create() Ft_file_status Is Output From These Functions None ft_fopen() Ft_file_status determines what action to take in the file specified on ft_create() or ft_fopen() already exists.
HP FTAM/9000 Data Structures Ft_file_status FT_REPLACE_CONTENTS Existing file contents deleted Existing file attributes remain the same Existing file selected FT_RECREATE Existing file contents and attributes deleted New file created with attributes specified in struct Ft_attributes FT_UNKNOWN 142 Existing file selected Chapter 3
HP FTAM/9000 Data Structures Ft_filename Ft_filename typedef char *Ft_filename; Ft_filename s Input To These Functions ft_create() Ft_filename Is Output From These Functions None ft_fcattributes() ft_fcopy() ft_fdelete() ft_fmove() ft_fopen() ft_frattributes() Ft_filename identifies a specific file with a unique path name given in the syntax of the original file in the real filestore.
HP FTAM/9000 Data Structures Ft_functional_units Ft_functional_units typedef Uint16 Ft_functional_units; Ft_functional_units Input To These Functions ft_connect() Ft_functional_units Is Output From These Functions ft_connect() Ft_functional_units specifies which functions are available per connection. You must use the FT_FU_XXX defined constants to specify Ft_functional_units.
HP FTAM/9000 Data Structures Ft_functional_units • You must negotiate Ft_functional_units on the ft_connect() request. For example, if you want to be able to read a file, set FT_FU_READ when making the ft_connect() request. • Ft_service_class dictates the mandatory and optional functional_units (as noted in the following table). Ft_service_class must support all selected Ft_functional_unit values; otherwise, you receive an error. Refer to the “Ft_service_class” section for detailed information.
HP FTAM/9000 Data Structures Ft_functional_units See the previous page for the reference key to this table.
HP FTAM/9000 Data Structures Ft_initiator_identity Ft_initiator_identity typedef char *Ft_initiator_identity; Ft_initiator_identity Is Input To These Functions Ft_initiator_identity Is Output From These Functions ft_connect() None ft_fdelete() ft_fcattributes() ft_fcopy() ft_fmove() ft_frattributes() Ft_initiator_identity identifies the HP-UX login account if using HP-UX responders. This structure is the type for the following fields and specifies the following user identities.
HP FTAM/9000 Data Structures Ft_processing_mode Ft_processing_mode typedef Uint16 Ft_processing_mode; Ft_processing_mode Input To These Functions ft_open() Ft_processing_mode Is Output From These Functions None Ft_processing_mode specifies the current file action for ft_open () (i.e., specifies an action you want to perform now). • These actions must be a subset of those actions selected in requested_access (FT_FA_XXX defined constants).
HP FTAM/9000 Data Structures Ft_qos Ft_qos enum Ft_qos { FT_NO_RECOVERY FT_CLASS_1_RECOVERY FT_CLASS_2_RECOVERY FT_CLASS_3_RECOVERY = = = = 0, 1, 2, 3 }; Ft_qos Is Input To These Functions ft_connect() Ft_qos Is Output From These Functions ft_connect() Ft_qos determines the level of recovery by FTAM by specifying which recovery classes are active. The qos stands for quality of service. FT_NO_RECOVERY FTAM does not automatically attempt recovery.
HP FTAM/9000 Data Structures Ft_service_class Ft_service_class typedef Uint16 Ft_service_class; Ft_service_class Is Input To These Functions ft_connect() Ft_service_class Is Output From These Functions ft_connect() Ft_service_class specifies whether you transfer, access, or manage a file per connection.
HP FTAM/9000 Data Structures Ft_service_class File Transfer Allows you to transfer data FT_SC_TRANSFER File Transfer and Management FT_SC_TRANSFER_AND_MGMT Allows you to move or copy bulk data Allows you to manipulate whole files: Change attributes Create files Delete files Read attributes Combines all capabilities of File Transfer and File Management File Access Allows you to transfer data FT_SC_ACCESS Provides you with access to individual FADUs You can use any of the following combinations of se
HP FTAM/9000 Data Structures Ft_service_class • FT_SC_UNCONSTRAINED, FT_SC_TRANSFER and FT_SC_ACCESS • FT_SC_UNCONSTRAINED, FT_SC_MANAGEMENT, FT_SC_TRANSFER, and FT_SC_TRANSFER_AND_MGMT • FT_SC_UNCONSTRAINED, FT_SC_MANAGEMENT, FT_SC_TRANSFER, FT_SC_ACCESS, and FT_SC_TRANSFER_AND_MGT • You must negotiate Ft_service_class when calling ft_connect(). • Ft_service_class defines the mandatory and optional Ft_functional_units. Set these restrictions using the defined constants.
HP FTAM/9000 Data Structures Ft_service_class Service Class Mandatory Functional Units One or Both Functional Units Optional Functional Units Not Allowed Unconstrained • Kernel • Enhanced File Mgmt • File Access • Group • Limited File Mgmt • Read • Write Management • Kernel • Grouping • Limited File Management • Enhanced File Mgmt • File Access • Read • Write Transfer • Kernel • Grouping • Read • Write • Enhanced File Mgmt • Limited File Mgmt • File Access Transfer and Management • Kernel
HP FTAM/9000 Data Structures Ft_service_class • If using FT_SC_TRANSFER_AND_MGMT, you must use group #1 and #2, or use group #3, as follows. • Open the file with group #1, transfer data as needed, and close the file with group #2 OR • Use group #3 to select or create a file, read or change attributes, and deselect or delete the file. • If you select FT_SC_ACCESS, you can use any of the groupings.
HP FTAM/9000 Data Structures Ft_single_file_pw Ft_single_file_pw typedef struct Octet_string Ft_single_file_pw; Ft_single_file_pw s Input To These Functions ft_connect() ft_create() ft_fcattributes() ft_fcopy() ft_fdelete() ft_fmove() ft_frattributes() Ft_single_file_pw Is Output From These Functions None Ft_single_file_pw is of type struct Octet_string which contains a length field (Uint16) and a pointer field (Octet_pointer). The meaning of Ft_single_file_pw varies as noted in the following table.
HP FTAM/9000 Data Structures inout_dcb inout_dcb You receive large amounts of data from the FTAM interface. To reduce the number of exposed parameters, Ft_output and Ft_xxx_out_dcb contain a group of parameters. The xxx varies, depending on the function (e.g., Ft_rdata_out_dcb). Except for size, all inout_dcb parameters are output parameters.
HP FTAM/9000 Data Structures inout_dcb Ft_xxx_out_dcb struct Ft_xxx_out_dcb { Uint32 struct Api_rc Function-specific size; result; info; }; Ft_xxx_out_dcb Is Input To These Functions Only the Ft_xxx_out_dcb size parameter and only if you use Ft_xxx_out_dcb in those calls listed in the output column Chapter 3 Ft_xxx_out_dcb Is Output From These Functions ft_bgroup() ft_cancel() ft_cattributes() ft_close() ft_connect() ft_create() ft_delete() ft_deselect() ft_edata() ft_egroup() ft_erase() ft_etransfer
HP FTAM/9000 Data Structures inout_dcb You must either pass the address of an inout_dcb or you must pass the address of a a NULL value. If you pass the address of an inout_dcb, you must have enough memory to return size and result. You may or may not supply additional values, depending on the function. size The size of the Ft_xxx_out_dcb structure and associated data in Octets. The size parameter is mandatory input if using Ft_xxx_out_dcb.
HP FTAM/9000 Data Structures inout_dcb additional_size parameter is large enough to hold all possible return information (e.g., diagnostics and returned data); otherwise, you receive an FTE004_OUTPUT_BUFFER_OVERFLOW error. NOTE Your application must not perform any operations on or with an inout DCB parameter until em_-wait() indicates the call is complete. Failure to follow this rule can cause serious internal errors to occur, resulting in unpredictable behavior or software failures.
HP FTAM/9000 Data Structures input_dcb input_dcb struct Ft_xxx_in_dcb { . . .
HP FTAM/9000 Data Structures input_dcb You pass large amounts of data to the FTAM interface. To reduce the number of exposed parameters, the Ft_xxx_in_dcb contains optional and function-specific parameters. The input_dcb parameters may be mandatory or optional; they must occur after the exposed input parameters and before the inout_dcb parameters. If any of the input_dcb parameters are mandatory, you must pass the address of an input_dcb; otherwise, you may pass a NULL value.
HP FTAM/9000 Data Structures Local_event_name Local_event_name typedef Sint32 Local_event_name; Local_event_name Is Input To These Functions ft_abort() ft_aeactivation() ft_aedeactivation() ft_aereset() ft_bgroup() ft_cancel() ft_cattributes() ft_close() ft_connect() ft_create() ft_delete() ft_deselect() ft_edata() ft_egroup() ft_erase() ft_etransfer() ft_fcattributes() ft_fclose() ft_fcopy() ft_fdelete() ft_frattributes() ft_fmove() ft_fopen() ft_ireceive() ft_locate() ft_nwcleared() ft_open() ft_rattri
HP FTAM/9000 Data Structures Local_event_name Local_event_name uniquely identifies a specific asynchronous function call and also determines whether a call is synchronous or asynchronous. If the call is synchronous, the value must be zero (0). The em_wait() function uses Local_event_name to identify a completed asynchronous operation. This identification is the same value that you passed to the operation when you initiated it.
HP FTAM/9000 Data Structures P_address P_address struct P_address { struct Octet_string *p_selector; /* NULL if it is not present struct Octet_string *s_selector; /* NULL if it is not present struct Octet_string *t_selector; /* NULL if it is not present Sint16 n_nsaps; /* Number of NSAPs */ struct Octet_string *nsaps; /* ptr to a sequence of NSAPs */} /* Maximum length of psap_selector is 16 Octets. * Maximum length of ssap_selector is 16 Octets. * Maximum length of tsap_selector is 32 Octets.
HP FTAM/9000 Data Structures P_address p_selector Presentation Service Access Point Selector: unique value that allows network layers to identify the connection to its peer. s_selector Session Service Access Point Selector: unique value that allows network layers to identify the connection to its peer. t_selector Transport Service Access Point Selector: unique value that allows network layers to identify the connection to its peer.
HP FTAM/9000 Data Structures P_address 166 Chapter 3
4 Using Support Functions Use support functions for a variety of purposes, such as managing your memory. Refer to the “Example Programs” chapter for model programs using the support functions.
Using Support Functions NOTE References to Event Management functions mean the combination of em_fdmemory(), em_wait(), and em_gperror(). Support functions are not bound to a specific regime. The only exception is ft_nwcleared(), which is used only when ft_sdata() returns the error FTE008_NO_CON_RESOURCES.
Using Support Functions Chapter Overview Chapter Overview This chapter describes the following functions in the order listed.
Using Support Functions Managing Memory Managing Memory Use ft_didcb() and ft_dfdcb() to manage your DCB memory by allocating and de-allocating memory for DCB structures. Refer to the “Using FTAM” chapter for recommendations on allocating memory. ft_didcb() #include % #include %
Using Support Functions Managing Memory ft_didcb() Parameters ft_didcb() Parameter Type Description dcb_type Mandatory Input Identifies the DCB to initialize additional_size Optional Input inout_dcb only Specifies the amount of memory allocated beyond that allocated for the DCB dcb_pointer Input Address of the DCB to initialize Output Address of the DCB pointer Output Pointer to the struct Api_rc containing the outcome of the operation: result_code (MAP 3.
Using Support Functions Managing Memory ft_dfdcb() Parameters ft_dfdcb() Parameter Type Description dcb_pointer Mandatory Input Address of the DCB to free result Output Pointer to the struct Api_rc containing the outcome of the operation: result_code (MAP 3.0 error) and vendor_code (HP–UX—specific error) em_fdmemory() #include %
Using Support Functions Managing Memory em_fdmemory() Parameters em_fdmemory() Parameter Type Description memory_pointer Mandatory Input Points to the beginning of the string; address of the dynamic memory to free (allocated by em_gperror()) result Output Pointer to the struct Api_rc containing the outcome of the operation: result_code (MAP 3.0 error) and vendor_code (HP–UX—specific error) ft_fdmemory() #include % #include %
Using Support Functions Managing Memory ft_fdmemory() Parameters ft_fdmemory() Parameter Type Description memory_pointer Mandatory Input Points to the beginning of the string; address of the dynamic memory to free (allocated by ft_gperror()) result Output Pointer to the struct Api_rc containing the outcome of the operation: result_code (MAP 3.
Using Support Functions Responding to Asynchronous Calls Responding to Asynchronous Calls The MAP 3.0 Event Management interface plays a central role in your use of asynchronous calls to FTAM functions. It is common to have multiple asynchronous function calls outstanding. As responses to these calls come in, the FTAM Service Provider Process (SPP) queues them. The Event Management interface takes the first response off this queue and returns it to the caller as a MAP 3.0 event.
Using Support Functions Responding to Asynchronous Calls When to Use em_hp_select() The em_hp_select() function is a Hewlett-Packard proprietary extension to the MAP 3.0 specification. It can be regarded as a hybrid of the MAP 3.0 em_wait() function and the HP-UX select() system call. It is located in the common MAP library (libmap.a).
Using Support Functions Responding to Asynchronous Calls Using em_wait() #include % Return_code em_wait (timeout, return_event_name, result) Em_t timeout; Local_event_name *return_event_name; Api_rc *result; This section describes general use of asynchronous calls with em_wait(). For additional details on em_wait(), refer to the HP FTAM/9000 Reference Manual.
Using Support Functions Responding to Asynchronous Calls The following text describes the sequence of making asynchronous requests and checking for their successful return from the responder. 1. Submit one or more asynchronous requests, each with a unique return_event_name. 2. Call em_wait() to determine if the requests returned successfully from the responder; you cannot specify the return_event_name for which you want to wait.
Using Support Functions Responding to Asynchronous Calls Following is an example of the use of em_wait(). This example creates and opens a file by asynchronously calling ft_bgroup(), ft_create(), and ft_open(), followed by synchronously calling ft_egroup(). These functions were called with return_event_names of 1, 2, 3, and 0, respectively. The em_wait() function waits on these calls.
Using Support Functions Responding to Asynchronous Calls Using em_hp_select() #include % Return_code em_hp_select (timeout, return_event_name, nfds, readfds, writefds, exceptfds, result) Em_t timeout; Local_event_name *return_event_name int *nfds unsigned *readfds unsigned *writefds unsigned *exceptfds Api_rc *result; This section describes how to use em_hp_select() and provides two program examples. For additional details, refer to the HP FTAM/9000 Reference Manual.
Using Support Functions Responding to Asynchronous Calls Waiting On FTAM and Non-FTAM Events Use the em_hp_select() function when an application must simultaneously wait for both an FTAM and a non-FTAM event to occur. Without em_hp_select(), the application would need to implement a “busy- wait” loop to poll for the FTAM and non-FTAM events. However, this technique is very expensive in terms of CPU utilization, and degrades system performance.
Using Support Functions Responding to Asynchronous Calls For example, this function could be a batch entry console for file management. Several file transfers could be started without having to wait for each transfer to complete before starting the next. map_operation_completed (map_event, map_rc). This function processes the FTAM events by performing some action on the results of the FTAM operation that completed. The operation is identified by the map_event passed as input.
Using Support Functions Responding to Asynchronous Calls #include % #include % #define BITS_PER_INT 32 #define SET_MASK(f,fds) (fds)[((f)/BITS_PER_INT)] |= (1%<%<((f)%BITS_PER_INT)) #define TST_MASK(f,fds) ((fds)[((f)/BITS_PER_INT)] & (1%<%<((f)%BITS_PER_INT))) main() { Bool done; Local_event_name map_event; Return_code map_rc; Api_rc map_result; char *ret_str; char *ven_str; int nfds; unsigned readfds[2]; /* handles upto 64 fds */ /* Read and process the first command.
Using Support Functions Responding to Asynchronous Calls while ( ! done ) { readfds[0] = 0; readfds[1] = 0; SET_MASK(stdin, readfds); nfds = stdin + 1; map_rc = em_hp_select(FOREVER, & map_event, & nfds, readfds, NULL, NULL, & map_result); if ((map_rc == SUCCESS) || (map_rc == EME032_IPC_ERROR)) { if ((map_event != 0)) map_operation_completed(map_event, map_rc); if (TST_MASK(stdin, readfds)) done = read_and_process_command(); } else { ret_str = NULL; ven_str = NULL; map_rc = em_gperror(& map_result, & ret_
Using Support Functions Responding to Asynchronous Calls Handling Signal Interrupts Suppose an application needs the em_wait() function to return prematurely if a signal interrupt occurs. One case where this is applicable is when receipt of a signal should cause a new FTAM operation to be initiated or an outstanding operation to be aborted (e.g., the application is being terminated abruptly).
Using Support Functions Responding to Asynchronous Calls The following program example illustrates how to use em_hp_select() and an HP–UX pipe to implement the signal handling technique described previously. #include % #include %
Using Support Functions Responding to Asynchronous Calls /* Install the signal handler for the signal you want to trap. */ vec.sv_handler = signal_handler; vec.sv_mask = 0; vec.sv_flags = 0; sigvector(signal_you_want_to_trap, & vec, NULL); /* Initiate the asynchronous FTAM operations. The code for ** initiating these operations is not shown in this example. */ /* Wait for a MAP operation to complete or a signal to be caught.
Using Support Functions Responding to Asynchronous Calls Using em_hp_sigio() #include % Return_code em_hp_sigio (action, pid, result) Unit32 action; Sint32 pid; Api_rc *result; This section describes how to use em_hp_select() and provides a program example. For additional details, refer to the HP FTAM/9000 Reference Manual. Use em_hp_sigio() to enable the MAP Event Management interface to generate SIGIO signals whenever an asynchronous MAP event is pending.
Using Support Functions Responding to Asynchronous Calls /* ** Sample program for em_hp_sigio() ** ** This program is designed with three primary components: ** ** * a central control/dispatch component ** * a MAP event processing component ** * a Non-MAP event processing component ** ** The central control/dispatch component makes use of an array of semaphores ** to manage program suspension and resumption, and to keep track of which ** components (MAP or Non-MAP) have work to do.
Using Support Functions Responding to Asynchronous Calls #define WAIT 0 /* Tells sem_p)) to block if necessary */ #define NO_WAIT 1 /* Tells sem_p() to return immediately */ int sem_id; /* The semaphore array for async mgmt */ int sem_create(); /* Create semaphores on the system */ void sem_remove(); /* Remove semaphores from the system */ int sem_p(); /* Perform a P (get) operation */ void sem_v(); /* Perform a V (give) operation */ /* ** Signals and signal handler used to manage asynchronous event notifi
Using Support Functions Responding to Asynchronous Calls /* ** Activate MAP 3.0 Application Entity for FTAM or FTAM, then initiate ** asynchronous MAP 3.0 operations. */ initiate_MAP_operation(); /* ** Initialize and initiate Non-MAP asynchronous operations. */ initiate_NON_MAP_operation(); while (operations_to_wait_on_and_process) { /* ** Suspend processing until an asynchronous event occurs. */ printf(“\nSuspending processing until an event occurs.
Using Support Functions Responding to Asynchronous Calls /* ** ** ** ** ** ** ** ** */ if { Process Non-MAP event if one is pending. A non-blocking sem_p() operation is used to atomically test and decrement the pending Non-MAP event count. If a Non-MAP event is pending, sem_p() returns zero; otherwise, it returns non-zero. Note, event processing is specific to your own application; details are not included in this example.
Using Support Functions Responding to Asynchronous Calls /* ** ** ** */ if Determine the event type based on the signal received. Update the semaphore mask to include the event type specific semaphore.
Using Support Functions Responding to Asynchronous Calls /* ** sem_remove() ** ** This function removes the semaphore array from the system. */ void sem_remove(sem_id) int sem_id; { if (semctl(sem_id, 0, IPC_RMID, 0) == -1) { fprintf(stderr, “ERROR: removing semaphore, errno %d\n”, errno); exit(1); } } /* ** sem_p() ** ** This function performs a semaphore P (get) operation on the set of ** semaphores specified by 'sem_mask'.
Using Support Functions Responding to Asynchronous Calls if (sem_cnt > 0) { do { rc = semop(sem_id, sem_ops, sem_cnt); } while ((rc == -1) & & (errno == EINTR)); if ((rc == -1) & & !((sem_nowait) & & (errno == EAGAIN))) { fprintf(stderr, “ERROR: semaphore P (get), errno %d\n”, errno); exit(1); } } return(rc); } /* sem_p */ /* ** sem_v() ** ** This function performs a semaphore V (give) operation on the set of ** semaphores specified by 'sem_mask'.
Using Support Functions Translating Error Messages Translating Error Messages FTAM and Event Management functions return Return_codes. • To translate errors returned by Event Management to character strings, invoke em_gperror(). • To translate errors return by FTAM functions to character strings, invoke ft_gperror(). em_gperror() #include %
Using Support Functions Translating Error Messages em_gperror() Parameters em_gperror() Parameter Type Description input_result Mandatory Input Pointer to the Api_rc structure containing information to translate: return_code (MAP 3.
Using Support Functions Translating Error Messages ft_gperror() #include % Return_code ft_gperror (input_result, return_string, vendor_string, result) Api_rc *input_result; Octet **return_string; Octet **vendor_string; Api_rc *result; The ft_gperror() function translates the input_result structure from FTAM functions to character strings, as follows: • The input_result->return_code is translated to a character string called return_string.
Using Support Functions Translating Error Messages ft_gperror() Parameters ft_gperror() Parameter Type Description input_result Mandatory Input Pointer to the Api_rc structure containing information to translate: return_code (MAP 3.
Using Support Functions Determining Available Resources Determining Available Resources While sending data, limited flow control resources may prevent the operation from completing. This circumstance is indicated by the error FTE008_NO_CON_RESOURCES returning on ft_sdata() function calls. To determine when the resource clears, call ft_nwcleared(). ft_nwcleared() #include % #include %
Using Support Functions Determining Available Resources EXAMPLE: Connection_id struct Ft_data_unit Local_event_name struct Ft_sdata_out_dcb struct Ft_nwcleared_out_dcb Result_code This example shows the use of ft_nwcleared(). The connection_id and data_unit parameters were previously set.
Using Support Functions Determining Available Resources 202 Chapter 4
5 Using High Level, Context Free Functions 203
Using High Level, Context Free Functions High level functions simplify FTAM programming by performing a series of low level functions for you. Since the high level functions described in this chapter are context free, you can use them at any time. Applications written with high level, context free (HLCF) functions are smaller, easier to write, and less prone to error. Refer to the “Example Programs” chapter for model programs using the HLCF functions.
Using High Level, Context Free Functions Chapter Overview Chapter Overview This chapter describes the following HLCF functions in the order listed.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) Copying and Moving FTAM Files (HLCF) Use ft_fcopy() and ft_fcopy_aet() to copy files, and ft_fmove() and ft_fmove_aet() to move files with only one call. Since copying or moving files using low level calls requires most FTAM functions, you can save significant coding time and effort using ft_fcopy(), ft_fcopy_aet(), ft_fmove(), and ft_fmove_aet(). ft_fcopy() #include %
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) • If the file has access control elements, and an identity field matches the source_init_id, the input_dcb->src_concur_cntl must be a subset of the values stored in the conc_access field of struct Ft_access_control_element.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) Ft_fcopy_out_dcb struct Ft_fcopy_out_dcb { Uint32 struct Api_rc enum Ft_action_result struct Ft_attributes struct Ft_charging struct Ft_diagnostic size; result; action_result; attributes; *charging; *diagnostic; }; ft_fcopy() Parameters ft_fcopy() Parameter Type Description source_dirname Optional Input Directory distinguished name of the source filestore; NULL implies local filestore source_filename Mandatory Input
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fcopy() Parameter Type Description input_dcb-> source_filestore_pw Optional Input Login password for the source_init_id account input_dcb-> source_account Optional Input Identifies who is responsible for accumulated storage charges on source file; HP–UX responders accept, but ignore, this value. input_dcb-> source_file_passwords Optional Input (Used only with non-HP-UX responders.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fcopy() Parameter Type Description input_dcb-> src_concur_cntl Optional Input (Used only with non-HP-UX responders.) Sets the concurrency control for source_filename; compared to conc_access in struct Ft_access_control_element if an identity field matches the source_init_id input_dcb-> dest_concur_cntl Optional Input (Used only with non-HP-UX responders.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove() #include % #include %
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) • You must supply matching passwords in input_dcb->source_file_ passwords for FT_FA_READ, FT_FA_READ_ATTRIBUTE, and FT_FA_DELETE_FILE file actions if the following conditions exist.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove() Parameters ft_fmove() Parameter Type Description source_dirname Optional Input Directory distinguished name of the source filestore; NULL implies local filestore source_filename Mandatory Input Path name of the file you are moving; must be in the syntax of the real filestore destination_dirname Optional Input Directory distinguished name of the destination filestore; NULL implies local filestore destinatio
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove() Parameter Type Description input_dcb-> source_file_passwords Optional Input (Used only with non—HP– UX responders.) Structure containing the passwords for FT_FA_READ, FT_FA_READ_ATTRIBUTE, and FT_FA_DELETE_FILE.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove() Parameter Type Description input_dcb-> src_concur_cntl Optional Input (Used only with non—HP– UX responders.) Sets the concurrency control for source_filename; compared to conc_access in struct Ft_access_control_element if an identity field matches the source_init_id input_dcb-> dest_concur_cntl Optional Input (Used only with non—HP– UX responders.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fcopy_aet #include % #include %
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) • If the file has access control elements, and an identity field matches the dest_init_id, the input_dcb->dest_concur_cntl must be a subset of the values stored in the conc_access field of struct Ft_access_control_element. • You must supply matching passwords in input_dcb>source_file_passwords for FT_FA_READ and FT_FA_READ_ATTRIBUTE file actions if the following conditions exist.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) Ft_fcopy_out_dcb struct Ft_fcopy_out_dcb { Uint32 struct Api_rc enum Ft_action_result struct Ft_attributes struct Ft_charging struct Ft_diagnostic size; result; action_result; attributes; *charging; *diagnostic; }; ft_fcopy_aet() Parameters ft_fcopy_aet() Parameter Type Description source_ascii_ddn Optional Input Directory distinguished name of the source filestore in ASCII; NULL implies local filestore source_filename
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fcopy_aet() Parameter Type Description input_dcb-> source_filestore_pw Optional Input Login password for the source_init_id account input_dcb-> source_account Optional Input Identifies who is responsible for accumulated storage charges on source file; HP–UX responders accept, but ignore, this value input_dcb-> source_file_passwords Optional Input (Used only with non-HPUX responders.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fcopy_aet() Parameter Type Description input_dcb-> src_concur_cntl Optional Input (Used only with non-HPUX responders.) Sets the concurrency control for source_filename; compared to conc_access in struct Ft_access_control_element if an identity field matches the source_init_id input_dcb-> dest_concur_cntl Optional Input (Used only with non-HPUX responders.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove_aet() #include % #include %
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) • If the file has access control elements, and an identity field matches the dest_init_id, the input_dcb->dest_concur_cntl must be a subset of the values stored in the conc_access field of struct Ft_access_control_element. • You must supply matching passwords in input_dcb->source_file_ passwords for FT_FA_READ, FT_FA_READ_ATTRIBUTE, and FT_FA_DELETE_FILE file actions if the following conditions exist.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) Ft_fmove_out_dcb struct Ft_fmove_out_dcb { Uint32 struct Api_rc enum Ft_action_result struct Ft_attributes struct Ft_charging struct Ft_diagnostic size; result; action_result; attributes; *charging; *diagnostic; }; ft_fmove_aet() Parameters ft_fmove_aet() Parameter Type Description source_ascii_ddn Optional Input Directory distinguished name of the source filestore in ASCII; NULL implies local filestore source_filename
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove_aet() Parameter Type Description input_dcb-> source_account Optional Input Identifies who is responsible for accumulated storage charges on source file; HP–UX responders accept, but ignore this value input_dcb-> source_file_passwor ds Optional Input (Used only with non—HP– UX responders.) Structure containing the passwords for FT_FA_READ, FT_FA_READ_ATTRIBUTE, and FT_FA_DELETE_FILE.
Using High Level, Context Free Functions Copying and Moving FTAM Files (HLCF) ft_fmove_aet() Parameter Type Description input_dcb-> src_concur_cntl Optional Input (Used only with non—HP– UX responders.) Sets the concurrency control for source_filename; compared to conc_access in struct Ft_access_control_element if an identity field matches the source_init_id input_dcb-> dest_concur_cntl Optional Input (Used only with non—HP– UX responders.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) Reading and Changing Attributes (HLCF) Use ft_frattributes() and ft_frattributes_aet to read file attributes, and ft_fcattributes() and ft_fcattributes_aet() to change file attributes by making only one call. ft_frattributes() #include % #include %
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) • You must supply matching passwords in input_dcb->file_passwords for FT_FA_READ and FT_FA_READ_ATTRIBUTE file actions if the following conditions exist.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_frattributes() Parameters ft_frattributes() Parameter Type Description dirname Optional Input Directory distinguished name of the filestore; NULL implies the local filestore filename Mandatory Input Path name of the file that has the attributes you are reading; must be in the syntax of the real filestore ae_label Mandatory Input Unique identifier for ftam_init you want to service the request; if pointing to a NUL
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_frattributes() Parameter Type Description input_dcb-> concurrency_control Optional input (Used only with non—HP–UX responders.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes() #include % #include % Return_code ft_fcattributes (dirname, filename, ae_label, return_event_name, input_dcb, inout_dcb) Ae_dir_name dirname; Ft_filename filename; Ae_label *ae_label; Local_event_name return_event_name; struct Ft_fcattributes_in_dcb *input_dcb; struct Ft_fcattributes_out_dcb **inout_dcb; Use ft_fcattributes() to change file attributes.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) • You must supply matching passwords in input_dcb->file_passwords for FT_FA_READ and FT_FA_CHANGE_ATTRIBUTE file actions if the following conditions exist.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes() Parameter Type Description Output Unique identifies the ftam_init that serviced 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) input_dcb-> attribute_names Mandatory Input Mask that indicates which file attributes to change input_dcb-> attributes.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes() Parameter Type Description 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 input_dcb-> file_passwords Optional Input Structure containing the passwords for FT_FA_READ and FT_FA_CHANGE_ATTRIBUTE.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_frattributes_aet() #include % #include %
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) • HP–UX responders set storage_account, future_filesize, legal_qualifications, and private_use so that the indication no value available (0) returns when you invoke ft_frattributes_aet().
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_frattributes_ae t() Parameter Type Description 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->init_id Optional Input Login account input_dcb-> filestore_pw Optional Input Login password for init_id input_dcb-> file_passwords Optional Input Structure containing the passwords for FT_FA_READ and FT_F
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_frattributes_ae t() Parameter Type Description inout_dcb>attributes Output Contains values of the attributes of the file you read 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 Chapter 5 237
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes_aet() #include % #include %
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) • If the responder supports the conc_access field of struct Ft_access_control_element, and the file has access control elements, and an identity field matches the init_id, the input_dcb>concurrency_control must be a subset of the values stored in the conc_access. HP-UX responders do not support the conc_access field of struct Ft_access_control_element.
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes_aet() Parameters ft_fcattributes_aet () Parameter Type Description ascii_ddn Optional Input Directory distinguished name of the filestore in ASCII; NULL implies the local filestore filename Mandatory Input Path name of the file that has the attributes you are changing; must be in the syntax of the real filestore ae_label Mandatory Input Uniquely identifier for ftam_init you want to service the reques
Using High Level, Context Free Functions Reading and Changing Attributes (HLCF) ft_fcattributes_aet () Parameter Type Description 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 (MAP 3.
Using High Level, Context Free Functions Deleting Files (HLCF) Deleting Files (HLCF) To delete files, invoke ft_fdelete() or ft_delete_aet(). ft_fdelete() #include % #include %
Using High Level, Context Free Functions Deleting Files (HLCF) ft_fdelete() Parameters ft_fdelete() Parameter Type Description dirname Optional Input Directory distinguished name of the filestore; NULL implies the local filestore filename Mandatory Input Path name of the file you are deleting; must be in the syntax of the real filestore ae_label Mandatory Input Unique identifier for ftam_init you want to service the request; if pointing to a NULL location, the interface uses a currently activat
Using High Level, Context Free Functions Deleting Files (HLCF) ft_fdelete() Parameter Type Description 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 (MAP 3.
Using High Level, Context Free Functions Deleting Files (HLCF) ft_fdelete_aet() #include % #include % Return_code ft_fdelete_aet (ascii_ddn, filename, ae_label, return_event_name, input_dcb, inout_dcb) char *ascii_ddn; Ft_filename filename; Ae_label *ae_label; Local_event_name return_event_name; struct Ft_fdelete_in_dcb *input_dcb; struct Ft_fdelete_out_dcb **inout_dcb; The ft_fdelete_aet() function deletes files from the filestore.
Using High Level, Context Free Functions Deleting Files (HLCF) ft_fdelete_aet() Parameters ft_fdelete_aet() Parameter Type Description ascii_ddn Optional Input Directory distinguished name of the filestore in ASCII; NULL implies the local filestore filename Mandatory Input Path name of the file you are deleting; must be in the syntax of the real filestore ae_label Mandatory Input Unique identifier for ftam_init you want to service the request; if pointing to a NULL location, the interface uses
Using High Level, Context Free Functions Deleting Files (HLCF) ft_fdelete_aet() Parameter Type Description 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 (MAP 3.
Using High Level, Context Free Functions Deleting Files (HLCF) 248 Chapter 5
6 Managing HP FTAM/9000 Connections 249
Managing HP FTAM/9000 Connections To use context sensitive FTAM operations, you must first activate an application entity (AE) and then establish a connection. The AE that you activate is an FTAM initiator (ftam_init). Use connection management functions to control activations and connections. Refer to the “Example Programs” chapter for model programs using the connection management functions.
Managing HP FTAM/9000 Connections Chapter Overview Chapter Overview This chapter describes the following functions in the order listed.
Managing HP FTAM/9000 Connections Connection Establishment Process Connection Establishment Process A typical connection establish and release routine (algorithm) is as follows. You do not have an option regarding the sequence of these events, with the exception of step 4. (Refer to Figure 6-1.) 1. Activate ftam_init (using ft_aeactivation()). 2. Establish the connection (using ft_connect()) between ftam_init and the responder.
Managing HP FTAM/9000 Connections Connection Establishment Process Figure 6-1 Connection Establishment Process User Program ft_aeactivation() User Program ftam_init ft_connect() User Program ftam_init ft_rrequest() ftam_resp ftam_resp ftam_resp A forks another process New ftam_resp B services the request ftam_resp A waits for other connections A B ftam_resp ftam_resp User Program ft_deactivation() ftam_init ftam_resp User Program ftam_resp Chapter 6 253
Managing HP FTAM/9000 Connections Starting and Stopping Application Entities Starting and Stopping Application Entities Use ft_aeactivation() and ft_aedeactivation() to respectively start and stop ftam_init. ft_aeactivation() #include % #include %
Managing HP FTAM/9000 Connections Starting and Stopping Application Entities Ft_output struct Ft_output { Uint32 struct Api_rc size; result; }; ft_aeactivation() Parameters ft_aeactivation() Parameter Type Description my_dir_name Mandatory Input Directory distinguished name identifying the AE (ftam_init) you want to activate return_event_nam e Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero) input_dcb-> authe
Managing HP FTAM/9000 Connections Starting and Stopping Application Entities ft_aedeactivation() #include % #include % Return_code ft_aedeactivation(ae_label, return_event_name, inout_dcb) Ae_label *ae_label; Local_event_name return_event_name; struct Ft_output **inout_dcb; Use ft_aedeactivation() to deactivate the AE (ftam_init) servicing the request.
Managing HP FTAM/9000 Connections Establishing and Removing Connections 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 % #include %
Managing HP FTAM/9000 Connections Establishing and Removing Connections • 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.
Managing HP FTAM/9000 Connections Establishing and Removing Connections Ft_connect_out_dcb struct Ft_connect_out_dcb { Uint32 struct Api_rc struct P_address responding_presentation_address; Ae Uint32 Uint32 struct Object_id struct Ft_connect_cnf_info }; size; result; responding_ae; responding_ae_invoke_id; responding_ap_invoke_id; context_name; *connect_out_info; struct Ft_connect_cnf_info { enum Ft_state_result enum Ft_action_result Ft_service_class Ft_functional_units Ft_attribute_groups enum Ft_qos s
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_connect() Parameter Type Description 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_valu
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_connect() Parameter Type Description 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.
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_connect() Parameter Type Description 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_
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_rrequest() #include % #include %
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_rrequest() Parameters ft_rrequest() Parameter Type Description connection_id Mandatory Input Uniquely identifies the connection you want to release return_event_na me 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
Managing HP FTAM/9000 Connections Establishing and Removing Connections ft_aereset() Parameters ft_aereset() Parameter Type Description ae_label Mandatory Input Uniquely identifies the AE (ftam_init) you want to reset return_event_na me 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 Outp
Managing HP FTAM/9000 Connections Aborting Connections Aborting Connections Use ft_abort() to abort a connection and ft_ireceive() to determine why you received an abort indication. ft_abort() #include % #include %
Managing HP FTAM/9000 Connections Aborting Connections ft_abort() Parameters ft_abort() Parameter Type Description connection_id Mandatory Input Uniquely identifies the specific filestore connection to abort return_event_na me Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is 0 (zero) input_dcb-> info.action_result Mandatory Input Conveys the reason for the abort input_dcb-> info.
Managing HP FTAM/9000 Connections Aborting Connections The information regarding the type of abort returns in the indication_name parameter and may be useful for troubleshooting purposes. All diagnostics associated with the abort are returned in the inout_dcb.
Managing HP FTAM/9000 Connections Aborting Connections ft_ireceive() Parameters ft_ireceive() Parameter Type Description connection_id Mandatory Input Uniquely identifies the aborted connection 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
Managing HP FTAM/9000 Connections Aborting Connections 270 Chapter 6
7 Managing and Accessing HP FTAM/9000 Files 271
Managing and Accessing HP FTAM/9000 Files After establishing connections, you can manage and access FTAM files. Refer to the “Example Programs” chapter for model programs using these functions.
Managing and Accessing HP FTAM/9000 Files Chapter Overview Chapter Overview This chapter describes the following functions in the order listed.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files 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.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files • 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_ACTION S 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.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files 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
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_create() Parameter Type Description 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 Specif
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files • 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.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_select() Parameter Type Description 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
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_open() (LLCS) #include % #include %
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files Ft_open_out_dcb struct Ft_open_out_dcb { Uint32 struct Api_rc enum Ft_state_result enum Ft_action_result struct Ft_contents_type struct Ft_concurrency_control struct Ft_diagnostic size; result; state_result; action_result; contents_type; *concurrency_control; *diagnostic; }; ft_open() Parameters ft_open() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore proces
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_open() Parameter Type Description 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) in
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files Ft_close_out_dcb struct Ft_close_out_dcb { Uint32 struct Api_rc enum Ft_action_result struct Ft_diagnostic size; result; action_result; *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 synchrono
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_delete() (LLCS) #include % #include % Return_code ft_delete (connection_id, return_event_name, input_dcb, inout_dcb) Connection_id Local_event_name char struct Ft_delete_out_dcb connection_id; return_event_name; *input_dcb; **inout_dcb; Use ft_delete() to remove a file from the filestore.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files 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 Si
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_deselect() #include % #include % Return_code ft_deselect (connection_id, return_event_name, input_dcb, inout_dcb) Connection_id Local_event_name char struct Ft_deselect_out_dcb connection_id; return_event_name; *input_dcb; **inout_dcb; Use ft_deselect() to deselect a file when you finish processing, but do not want to remove it.
Managing and Accessing HP FTAM/9000 Files Gaining Access to FTAM Files ft_deselect() Parameter Type Description 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
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) Opening and Closing Files (HLCS) Use ft_fopen() and ft_fclose() to open and close files, respectively, using only one high level call. ft_fopen() Either selects or creates, and then opens a file ft_fclose() Closes a file, and then either deselects or deletes a file ft_fopen() (HLCS) #include % #include %
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) • If the file you are selecting and opening has access control, the following conditions exist. • The requested_access 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. • FTAM will detect conflicts between the initiator_id and the identity field of the access_control_element.
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) Ft_fopen_out_dcb struct Ft_fopen_out_dcb { Uint32 struct Api_rc enum Ft_state_result enum Ft_action_result struct Ft_attributes struct Ft_concurrency_control struct Ft_diagnostic size; result; state_result; action_result; attributes; *concurrency_control; *diagnostic; }; ft_fopen() Parameters ft_fopen() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore file
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) ft_fopen() Parameter Type Description input_dcb->account Optional 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 requ
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) ft_fclose() (HLCS) #include % #include %
Managing and Accessing HP FTAM/9000 Files Opening and Closing Files (HLCS) ft_fclose() Parameters ft_fclose() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore delete_action Mandatory Input Determines whether to delete or deselect the file 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 i
Managing and Accessing HP FTAM/9000 Files Reading and Changing Attributes (LLCS) Reading and Changing Attributes (LLCS) Use the ft_rattributes() and ft_cattributes() to read and change attributes using low level calls. If you are already in the File Selection regime, it is faster and easier to use low level calls to read and change attributes than to use high level calls (which re-connect and re-select). In other cases, the high level calls may be easier to use.
Managing and Accessing HP FTAM/9000 Files Reading and Changing Attributes (LLCS) Ft_rattributes_in_dcb struct Ft_rattributes_in_dcb { Ft_attribute_names attribute_names; }; Ft_rattributes_out_dcb struct Ft_rattributes_out_dcb { Uint32 struct Api_rc enum Ft_action_result struct Ft_attributes struct Ft_diagnostic size; result; action_result; attributes; *diagnostic; }; ft_rattributes() Parameters ft_rattributes() Parameter Type Description connection_id Mandatory Input Uniquely identifies a spec
Managing and Accessing HP FTAM/9000 Files Reading and Changing Attributes (LLCS) ft_rattributes() Parameter Type Description 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 read (those attributes accepted by the responder) inout_dcb>diagnostic Output Holds ISO-specific error information ft_cattributes() (LLCS) #include %
Managing and Accessing HP FTAM/9000 Files Reading and Changing Attributes (LLCS) Attributes You Cannot Change Attributes You Can Change access_control file_availability filename future_filesize* legal_qualification* private_use* storage_account* contents_type date_time_of_attribute_mod date_time_of_creation date_time_of_modification date_time_of_read filesize identity_of_attribute_mod identity_of_creator identity_of_modifier identity_of_reader permitted_actions * HP-UX responders accept, but ignore, the
Managing and Accessing HP FTAM/9000 Files Reading and Changing Attributes (LLCS) ft_cattributes() Parameters ft_cattributes() 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-> attribute_names Mandatory Input Mask that indicates which file attributes to change input_dc
Managing and Accessing HP FTAM/9000 Files Locating and Erasing FTAM Files Locating and Erasing FTAM Files Use the ft_locate() to locate FADUs (FTAM-2) and ft_erase() to erase FTAM files. ft_locate() #include % #include %
Managing and Accessing HP FTAM/9000 Files Locating and Erasing FTAM Files ft_locate() Parameters ft_locate() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore fadu_identity Mandatory Input Identifies the FADU to locate (FTAM-2 only) 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 informat
Managing and Accessing HP FTAM/9000 Files Locating and Erasing FTAM Files ft_erase() #include % #include % Return_code ft_erase (connection_id, fadu_identity, return_event_name, input_dcb, inout_dcb) Connection_id connection_id; Ft_fadu_identity fadu_identity; Local_event_name return_event_name; char *input_dcb; struct Ft_erase_out_dcb **inout_dcb; Use ft_erase() to erase a file's contents; attributes are not erased.
Managing and Accessing HP FTAM/9000 Files Locating and Erasing FTAM Files ft_erase() Parameters ft_locate() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore fadu_identity Mandatory Input Identifies the FADU to erase return_event_name Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is zero.
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions Grouping LLCS FTAM Functions Use ft_bgroup() and ft_egroup() to begin and end the grouping of low level FTAM functions and thus, increase performance. The ftam_init places these functions into one presentation service data unit (PSDU) before sending it across the network.
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions • You can specify either or both optional functions, or can choose not to use them. If you call both optional functions, you must do so in the order given in the table.
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions ft_bgroup() #include % #include % Return_code ft_bgroup (connection_id, threshold, return_event_name, input_dcb, inout_dcb) Connection_id connection_id; Uint32 threshold; Local_event_name return_event_name; char *input_dcb; struct Ft_bgroup_out_dcb **inout_dcb; Issue an asynchronous ft_bgroup() to start a set of grouped functions.
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions ft_bgroup() Parameter Type Description return_event_na me Mandatory Input Uniquely identifies the asynchronous call 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) ft_egroup() #include %
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions ft_egroup() Parameters ft_egroup() parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore return_event_na me Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is zero inout_dcb->size Mandatory input if using inout_dcb Size (in Octets) of the inout_dcb structure and data inout_dcb->result Outp
Managing and Accessing HP FTAM/9000 Files Grouping LLCS FTAM Functions 308 Chapter 7
8 Transferring HP FTAM/9000 Data 309
Transferring HP FTAM/9000 Data After opening a file, you can send and receive FTAM data. Refer to the “Example Programs” chapter for model programs using the functions described in the chapter.
Transferring HP FTAM/9000 Data Chapter Overview Chapter Overview This chapter describes the sequence of transferring data and describes the following functions in the order listed.
Transferring HP FTAM/9000 Data Sequence of Transferring Data Sequence of Transferring Data Sequences to use when transferring data are as follows. 1. ft_read() 2. ft_rdata() (multiple) 3. ft_etransfer() 1. 2. 3. 4. ft_write() ft_sdata() (multiple) ft_edata() ft_etransfer() • If you invoke ft_read() or ft_write(), you must exit the regime by invoking ft_etransfer(). • If you invoke ft_sdata(), you must end the sending of data by invoking ft_edata().
Transferring HP FTAM/9000 Data Reading Data Reading Data Use ft_read() to identify what you want to read. To receive the identified information from the responder, call ft_rdata() to tell ftam_init the number of data elements you want to receive. The ftam_init gathers and returns the information requested. ft_read() #include % #include %
Transferring HP FTAM/9000 Data Reading Data • If you specify FT_UNSTRUCTURED_ALL_DATA_UNITS in access_context for FTAM-2 files, you receive only the data elements, not the node descriptors (structuring information). If you specify FT_FLAT_ALL_DATA_UNITS in access_context for FTAM-2 files, you receive both data elements and node descriptors.
Transferring HP FTAM/9000 Data Reading Data ft_rdata() #include % #include % Return_code ft_rdata (connection_id, des_requested, return_event_name, inout_dcb) Connection_id connection_id; Uint16 des_requested; Local_event_name return_event_name; struct Ft_rdata_out_dcb **inout_dcb; Use ft_rdata() to receive the data you requested on ft_read(). Issuing ft_rdata() controls the number of data elements you read (i.e., controls the flow of information).
Transferring HP FTAM/9000 Data Reading Data ft_rdata() Parameters ft_rdata() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore des_requested Mandatory Input Maximum number of data elements you want to receive return_event_name Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is zero inout_dcb->size Mandatory input if using inout_dcb Size (in Octets) of th
Transferring HP FTAM/9000 Data Reading Data ft_rdataqos() #include % #include % Return_code ft_rdataqos (src_connection_id, dest_connection_id, des_requested, return_event_name, inout_dcb) Connection_id src_connection_id; Connection_id dest_connection_id; Uint16 des_requested; Local_event_name return_event_name; struct Ft_rdata_out_dcb **inout_dcb; Use ft_rdataqos() to receive the data you requested on ft_read().
Transferring HP FTAM/9000 Data Reading Data Ft_rdataqos_out_dcb struct Ft_rdataqos_out_dcb { Uint16 struct Api_rc Uint32 struct Ft_data_unit enum Ft_action_result struct Ft_diagnostic }; size; result; des_received; *data_unit; action_result; *diagnostic; ft_rdataqos() Parameters ft_rdataqos() Parameter Type Description src_connection_id Mandatory Input Uniquely identifies the source connection to the filestore dest_connection_id Mandatory Input Uniquely identifies the destination connection to t
Transferring HP FTAM/9000 Data Writing Data Writing Data Use ft_write() and ft_sdata() to write data. • Use ft_write() to request permission to write information to a file and to specify what to write (from the initiator to the responder). • Use ft_sdata() to send data. ft_write() #include % #include %
Transferring HP FTAM/9000 Data Writing Data • Invoke ft_write() in the File Open regime to move to the Data Transfer regime. • During ft_connect(), you must negotiate the FT_FU_WRITE functional_units to use ft_write(). • During ft_create() and ft_select(), you must set requested_access according to the document type. FTAM-1, FTAM-3, and INTAP-1 FT_FA_EXTEND FT_FA_REPLACE FTAM-2 FT_FA_INSERT • During ft_open(), you must set processing_mode according to the document type.
Transferring HP FTAM/9000 Data Writing Data ft_write() Parameters ft_write() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore fadu_identity Mandatory Input Identifies the FADU to which you write fadu_operation Mandatory Input Specifies the action you are taking on a file; depends on the document type return_event_na me Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchrono
Transferring HP FTAM/9000 Data Writing Data Use ft_sdata() to send data units to a file. You can send a maximum of 14 data units linked together for each ft_sdata() function call. • Invoke ft_sdata() in the Data Transfer regime; you do not move to another regime. • During ft_connect(), you must negotiate the FT_FU_WRITE functional_units to use ft_sdata(). • During ft_create() and ft_select(), you must set requested_access according to the document type.
Transferring HP FTAM/9000 Data Writing Data ft_sdata() Parameters ft_sdata() Parameter Type Description connection_id Mandatory Input Uniquely identifies a specific connection to the filestore data_unit Mandatory Input Linked list containing the data units to send; use data_unit to control the flow of data return_event_name Mandatory Input If the call is asynchronous, uniquely identifies the function call; if the call is synchronous, the value is zero inout_dcb->size Mandatory input if using
Transferring HP FTAM/9000 Data Ending Data Transfer Ending Data Transfer Use ft_edata() and ft_etransfer() to terminate data transfers in an orderly manner. Use ft_cancel() to prematurely terminate a data transfer after issuing an ft_read() or ft_write() request, and use ft_rcancel() to respond to a cancel indication. ft_edata() #include % #include %
Transferring HP FTAM/9000 Data Ending Data Transfer ft_edata() Parameters ft_edata() 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 zero input_dcb>action_result Mandatory Input Specifies that all data was sent input_dcb->diagnostic Optional Input ISO-specific error information; HP-UX
Transferring HP FTAM/9000 Data Ending Data Transfer ft_etransfer() #include % #include % Return_code ft_etransfer (connection_id, return_event_name, input_dcb, inout_dcb) Connection_id connection_id; Local_event_name return_event_name; char *input_dcb; struct Ft_etransfer_out_dcb **inout_dcb; Use ft_etransfer() to end the transferring of data (ft_read() or ft_write()). Use ft_etransfer() in one of the following sequences.
Transferring HP FTAM/9000 Data Ending Data Transfer ft_etransfer() Parameters ft_etransfer() 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 zero input_dcb Optional Input Contains no information; pass a NULL pointer inout_dcb->size Mandatory input if using inout_dcb Size (in Octets) o
Transferring HP FTAM/9000 Data Ending Data Transfer Use ft_cancel() to prematurely terminate the transferring of data. Using ft_cancel() does not abort the entire connection (as does ft_abort()). An example of using ft_cancel() could be when you are reading data from one FTAM file and writing to another, and you encounter an error when writing the data. You may want to cancel reading data from the FTAM file. Call ft_cancel() after ft_read() or ft_write(), rather than calling ft_etransfer().
Transferring HP FTAM/9000 Data Ending Data Transfer ft_cancel() Parameters ft_cancel() 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>action_result Mandatory Input Indicates failure of the data transfer; must be set to FT_AR_PERMANENT_ER ROR input_dcb->diagnostic Op
Transferring HP FTAM/9000 Data Ending Data Transfer ft_rcancel() #include % #include % Return_code ft_rcancel (connection_id, return_event_name, input_dcb, inout_dcb) Connection_id connection_id; Local_event_name return_event_name; struct Ft_rcancel_in_dcb *input_dcb; struct Ft_rcancel_out_dcb **inout_dcb; If an error occurs during a data transfer, the responder sends you a cancel indication.
Transferring HP FTAM/9000 Data Ending Data Transfer ft_rcancel() Parameters ft_rcancel() 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 zero input_dcb-> action_result Mandatory Input Indicates failure of the data transfer; set to the action_result received from the cancel indication in
Transferring HP FTAM/9000 Data Ending Data Transfer 332 Chapter 8
9 Handling Errors Before writing programs to detect errors, you should be familiar with the following concepts. (Refer to the “HP-UX FTAM Overview” and “Using FTAM” chapters for descriptions of these concepts.
Handling Errors • Synchronous and Asynchronous calls • Context Free and Context Sensitive calls • High and Low level services (HLS and LLS) You should also understand the various failure types and the differences in errors occurring on synchronous versus asynchronous calls. This chapter covers both of these topics.
Handling Errors Chapter Overview Chapter Overview This chapter first describes general troubleshooting procedures for FTAM. The remaining sections explain the actions listed in these general guidelines. The specific topics are as follows. • General Approach to Troubleshooting FTAM • Interpreting Errors • Function Return Values • Output Errors • MAP 3.
Handling Errors General Approach to Troubleshooting FTAM General Approach to Troubleshooting FTAM To write a supportable program, you must check for errors. If you receive an error, use the following guidelines and Figure 9-1 to help you resolve the problem. 1. Check all error codes (return_codes, vendor_codes, diagnostics). The “Interpreting Errors” section describes the values you interpret. 2. Use ft_gperror() to format errors into printable character strings and to obtain log instances. 3.
Handling Errors General Approach to Troubleshooting FTAM Figure 9-1 General Approach to Troubleshooting FTAM An FTAM function fails Check all error codes (return_code, vendor_code, and diagnostics) Call ft_gperror() to format errors into character strings and to obtain log instances Correct all errors.
Handling Errors Interpreting Errors Interpreting Errors Your program detects errors in two locations. • Function Return Values (includes Event Management (EM) values) • Output parameters Function Return Values Function return values indicate whether an error occurred. • Function return values return in the program as integers. • These values may occur because of errors on previous calls. For example, if the first call within a group fails, thereafter every function within the group fails.
Handling Errors Interpreting Errors Output Errors Information returned in the inout_dcb fields may be defined by MAP 3.0 FTAM, HP-UX FTAM, FTAM Protocol Machine (FPM), or the VFS. This Error Returns As MAP 3.0 FTAM error result.return_code HP-UX FTAM specific error result.vendor_code FPM or VFS error action_result state_result diagnostic MAP 3.0 FTAM Errors Errors detected by the interface, an ftam_init, or an FTAM responder are mapped to MAP 3.0 FTAM errors and returned to the user program.
Handling Errors Interpreting Errors Synchronous Calls • The MAP 3.0 FTAM result.return_code is always the same as the function return value. • If result.return_code is SUCCESS, the request successfully passed to the application interface, ftam_init, and responder, and returned back to the user program. Asynchronous Calls • If result.return_code indicates an error, the application interface, ftam_init, or responder detected the error. • The em_wait() function returns a value for a specific event.
Handling Errors Interpreting Errors FPM and VFS Errors FPM errors are generated in the FTAM protocol machine and VFS errors are generated in the Virtual Filestore. Both FPM or VFS errors return an action_result, and may optionally return a state_result or diagnostic. action_result. The action_result reflects the overall success or failure of the request and returns as either FT_AR_SUCCESS or FT_AR_PERMANENT_ERROR, respectfully.
Handling Errors Interpreting Errors struct Ft_diagnostic { struct Ft_diagnostic enum Ft_diag_type Uint16 enum Ft_entity_ref enum Ft_entity_ref Uint16 char }; Figure 9-2 *next; diag_type; error_id; error_observer; error_source; suggested_delay; *further_details; inout_dcb->diagnostic struct inout_dcb size Up to 12 struct Ft_diagnostic (Parenthetical fields are not always present) result (state_result) struct Ft_diagnostic (action_result) diag_type (diagnostic) error_id struct Ft_diagnostic error
Handling Errors Interpreting Errors enum FT_diag_type { FT_INFORMATIVE FT_TRANSIENT FT_PERMANENT = = = 0, 1, 2 }; error_id The actual error as defined by ISO/IS 8571. Refer to the HP FTAM/9000 Reference Manual for a list of the error_ids, causes, and corrective actions. error_observer The entity that detects the error; refer to mapftam.h.
Handling Errors Example Program Checking for Errors Example Program Checking for Errors This example checks the result.return_code, result.vendor_code, and Ft_diagnostic structures. This example also uses printf() statements to print the results. #include % #include % #include % /* ** error_handler ** ** DESCRIPTION: ** This routine is an example of handling failures experienced ** during the FTAM functions.
Handling Errors Example Program Checking for Errors /* ** Call ft_gperror to get the printable strings for ** the return_code and vendor_code. Print the ** strings returned from ft_gperror.
Handling Errors Logging Errors Logging Errors All errors return both in your programs and in the log files. When any of the OSI layers have an error, the error propagates up the stack, creating an error at each layer. The number that identifies the error is called a log instance. For example, if an error occurs at the Presentation layer, a related error also occurs at the Application layer. The same log instance occurs at least twice, identifying the related errors at both layers.
Handling Errors Example Program Containing Error Information Example Program Containing Error Information Given a vendor_code, the following example creates a log filter file (/tmp/input_file) that the troubleshooting tool osidump uses to check for errors (via log instances in the log file). The file created records a time period (during which the error is assumed to have occurred), the log class to filter on, and the log instance. Following the program is sample output.
Handling Errors Example Program Containing Error Information fprintf(fp, “%d/%d/%d\n”, clock->tm_mon+1, clock->tm_mday, clock->tm_year); fprintf(fp, “FORMATTER\tfilter\ttime_to \t”); fprintf(fp, “%d:%02d:%02d\t”, clock->tm_hour, clock->tm_min, clock->tm_sec); fprintf(fp, “%d/%d/%d\n”, clock->tm_mon+1, clock->tm_mday, clock->tm_year); /* set filter “class” to ERROR */ fprintf(fp, “FORMATTER\tfilter\tclass \tERROR\n”); if (log_instance) /* log instance present */ fprintf(fp, “FORMATTER\tfilter\tlog_instance\
Handling Errors Using API Tracing Using API Tracing API tracing allows you to get detailed information about your program's interactions with the HP FTAM API without your having to access your source code. It provides the return value of each API call made by your program as well as the input parameters to each call. API Tracing Variables HP FTAM API tracing is controlled by the following three global variables. • ft_trace indicates the trace level to be used.
Handling Errors Using API Tracing 2. Within your program, enable tracing by changing the value of the ft_trace variable from 0 to either API_TR_ENTRY_EXIT or API_TR_INPUT. (The “Resolving FTAM Problems” chapter in the HP FTAM/9000 User's Guide provides information on enabling and disabling API tracing during an interactive FTAM session.) 3. If you want the trace output to be written to a file, redirect the trace output from stderr as follows. ft_trace_fp = fopen(“/tmp/my_ft_trace”,“a”); 4.
Handling Errors Using API Tracing the integer value of the return code for that call. A value of 0 indicates that there were no errors. If an integer other than 0 is returned, refer to the /opt/ftam/includei/mapftam.h file to determine which return code corresponds to the integer, and then refer to the “FTAM return_codes” chapter of the HP FTAM/9000 Reference Manual for the cause of the return code and corrective actions you can take. The following is an example trace file for an HP FTAM session.
Handling Errors Using API Tracing Tue Sep 1 08:55:18 1992 ->ft_open() connection_id = 65535 processing_mode: FT_PM_READ FT_PM_REPLACE FT_PM_EXTEND FT_PM_ERASE contents_type->contents_info.document.name.length = 5 contents_type->contents_info.document.name.element: 1 0 8571 5 3 return_event_name = 0 input_dcb->concurrency_control = NULL Tue Sep 1 08:55:18 1992 %<-ft_open() = 0 Tue Sep 1 08:55:18 1992 ->ft_read() connection_id = 65536 fadu_identity->fadu_form = FT_FADU_LOCATION fadu_identity->fadu_info.
10 Example Programs 353
Example Programs Former Introduction ... need to change Former Introduction ... need to change You can learn from the code examples in this chapter, and pattern your applications after them. The examples are in the following order. Using HLCF Functions Example This routine synchronously calls the HLCF functions ft_fcopy(), ft_fcattributes(), and ft_fdelete(). Additionally, the routine uses ft_dfdcb() to free dynamically allocated data control blocks (DCBs).
Example Programs Using HLCF Functions Example Using HLCF Functions Example This example program synchronously calls the high level context free functions ft_fcopy(), ft_fcattributes(), ft_fdelete(). Additionally, the program uses ft_dfdcb() to free dynamic memory. Refer to the following three sections for associated routines: “Setting Ae_dir_name and P address Utility Example,” “Checking for Errors Example,” and “Common Code Example.” #include %
Example Programs Using HLCF Functions Example /* ** Free memory. */ res = ft_dfdcb((Octet *)fco_input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); res = ft_dfdcb((Octet *)fco_inout_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** Change the attributes of the destination file. ** ** Get the parameters for ft_fcattributes. ** Call ft_fcattributes and verify the outcome. */ (void)printf(“Changing attributes of the destination file...
Example Programs Managing FTAM Connections Example Managing FTAM Connections Example This example uses the ft_aeactivation(), ft_connect(), ft_rrequest(), ft_aedeactivation(), and ft_dfdcb() functions. Refer to the following sections for associated routines: “Setting Ae_dir_dn and P_address Utility Example,” “Checking for Errors Example,” and “Common Code Example.” #include % #include % #include “ftm_globs.h” #include %
Example Programs Managing FTAM Connections Example /* ** Activate “ftam_init”. ** ** Get the parameters for ft_aeactivation. ** Call ft_aeactivation and verify the outcome. */ (void)printf(“Activating ftam_init...\n”); aea_parm_in( & my_ae_name, & return_event_name, & aea_input_dcb, & aea_inout_dcb, & ae_label ); res = ft_aeactivation(my_ae_name, return_event_name, aea_input_dcb, & aea_inout_dcb, & ae_label); if (res != SUCCESS) error_handler(aea_inout_dcb->result, diag); /* ** Free memory.
Example Programs Managing FTAM Connections Example /* ** Deactivate “ftam_init”. ** ** Get the parameters for ft_aedeactivation. ** Call ft_aedeactivation and verify the outcome. */ (void)printf(“Deactivating ftam_init...\n”); aed_parm_in( & return_event_name, & aed_inout_dcb ); res = ft_aedeactivation(ae_label, return_event_name, & aed_inout_dcb); if (res != SUCCESS) error_handler(aed_inout_dcb->result, diag); /* ** Free memory.
Example Programs Using LLCS Functions Example Using LLCS Functions Example This example uses the following functions. Refer to the following sections for associated routines: “Setting Ae_dir_dn and P_address Utility Example,” “Checking for Errors Example,” and “Common Code Example.
Example Programs Using LLCS Functions Example #include % #include % #include “ftm_globs.h” #include % main() /* ** ftm_llcopy ** ** DESCRIPTION: ** This example program illustrates how to transfer a file ** using low level, context sensitive FTAM functions. This ** program transfers the source file to the destination directory.
Example Programs Using LLCS Functions Example char *etr_input_dcb; struct Ft_etransfer_out_dcb *etr_inout_dcb; struct Ft_nwcleared_out_dcb *nwc_inout_dcb; char *clo_input_dcb; struct Ft_close_out_dcb *clo_inout_dcb; char *des_input_dcb; struct Ft_deselect_out_dcb *des_inout_dcb; Em_t time; Api_rc result; struct Ft_attributes attr_src; Return_code res; Api_rc outcome; int i, j, index; Bool done; struct Ft_diagnostic *diag = NULL; (void)printf(“ftm_llcopy: starting\n”); /* ** Activate “ftam_init”.
Example Programs Using LLCS Functions Example /* ** Free memory.
Example Programs Using LLCS Functions Example /* ** Get the parameters for ft_egroup. ** Call ft_egroup and verify the outcome. */ egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); res = ft_egroup(conn_id[SRC], return_event_name, egr_input_dcb, & egr_inout_dcb); if (res != SUCCESS) error_handler(egr_inout_dcb->result, diag); /* ** Wait on the asynchronous events in the group.
Example Programs Using LLCS Functions Example /* ** Open the source file. ** ** Get the parameters for ft_open. ** Call ft_open and verify the outcome. */ (void)printf(“Opening the source file...
Example Programs Using LLCS Functions Example /* ** Get the parameters for ft_open. ** Call ft_open and verify the outcome. */ ope_parm_in( & processing_mode, & contents_type, & return_event_name, & ope_input_dcb, & ope_inout_dcb ); contents_type = attr_src.values.
Example Programs Using LLCS Functions Example /* ** Free memory.
Example Programs Using LLCS Functions Example /* ** Free memory. */ res = ft_dfdcb((Octet *)wri_inout_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** Replace the contents of destination file with the contents ** of source file. */ done = FALSE; while ( ! done ) { /* ** Read from the source file. ** ** Get the parameters for ft_rdata. ** Call ft_rdata and verify the outcome.
Example Programs Using LLCS Functions Example /* ** Send data to the destination file. ** ** Get the parameters for ft_sdata. ** Call ft_sdata and verify the outcome. */ if (rda_inout_dcb ->data_unit != NULL) { sda_parm_in(& return_event_name, & sda_inout_dcb); res = ft_sdata(conn_id[DST], rda_inout_dcb->data_unit, return_event_name, & sda_inout_dcb); if (res != SUCCESS) { /* ** If a “No connection resources” error was returned, ** wait until the resources are free.
Example Programs Using LLCS Functions Example /* ** Free memory. */ res = ft_dfdcb((Octet *)eda_input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); res = ft_dfdcb((Octet *)eda_inout_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** End the transfer of data to the source and destination files. ** ** Get the parameters for ft_etransfer. ** Call ft_etransfer and verify the outcome.
Example Programs Using LLCS Functions Example /* ** Get the parameters for ft_deselect. ** Call ft_deselect and verify the outcome. */ des_parm_in( & return_event_name, & des_input_dcb, & des_inout_dcb ); res = ft_deselect(conn_id[i], return_event_name, des_input_dcb, & des_inout_dcb); if (res != SUCCESS) error_handler(des_inout_dcb->result, des_inout_dcb->diagnostic); /* ** Get the parameters for ft_egroup. ** Call ft_egroup and verify the outcome.
Example Programs Using LLCS Functions Example /* ** Release the connections between ftam_init and the ** responders for the source file and the destination file. ** ** Get the parameters for ft_rrequest. ** Call ft_rrequest and verify the outcome. */ (void)printf(“Releasing connections...
Example Programs Setting Ae_dir_dn and P_address Utility Example Setting Ae_dir_dn and P_address Utility Example This routine sets the directory distinguished name and presentation address for the first three examples. #include % #include % #include “ftm_globs.h” #include % #include % /* ** ** convert_ddn ** ** DESCRIPTION: ** This routine scans a character string and sets up ** an Ae_dir_name.
Example Programs Setting Ae_dir_dn and P_address Utility Example *dirname = (struct Dir_dn *)malloc(sizeof(struct Dir_dn)); (*dirname)->rdn = (struct Dir_rdn *)malloc(index*sizeof(struct Dir_rdn)); /* ** Set the Ae_dir_name. */ (*dirname)->n = index; /* ** Parse the string and set up the Dir_dn structure. ** ** NOTE: index is set to “-1” since the string MUST start with ** a delimiter “/”.
Example Programs Setting Ae_dir_dn and P_address Utility Example /* ** Set up the syntax_id to NULL. -- For Future Use -*/ (*dirname)->rdn[index].avas->syntax_id.length = 0; (*dirname)->rdn[index].avas->syntax_id.element = NULL; /* ** Which attribute is this? Set the fourth element of the ** attr_id accordingly. */ if (strcmp(attr,“C”) == SUCCESS) { /* ** C = Country */ (*dirname)->rdn[index].avas->attr_id.
Example Programs Setting Ae_dir_dn and P_address Utility Example else { /* ** Move to the next character in the string and the next ** Dir_rdn structure in the Dir_dn structure. */ ++j; ++index; } } } } /* ** ** convert_paddr ** ** DESCRIPTION: ** This routine scans a character string and sets up ** a P_address.
Example Programs Setting Ae_dir_dn and P_address Utility Example /* ** Set the p_addr. */ j = 0; index = 0; while ( !null_flag ) { /* ** Has the end of the string been reached? */ if (name[j] == NULL) null_flag = TRUE; /* Parse the next field until a delimiter or the ** end of the string has been reached. */ if ((name[j] != ‘.’) & & ( !null_flag )) { temp[i] = name[j]; ++i; ++j; } /* ** Another field has been parsed; set up the correct p_addr field. */ if ((null_flag) || (name[j] == ‘.
Example Programs Setting Ae_dir_dn and P_address Utility Example /* ** Reset the counters and flags for the next field. */ i = 0; ++j; while (name[j] == ‘.’) { /* ** Move to the next field in the p_addr ** and the next character in the string. */ ++index; ++j; } } else { /* ** Move to the next field in the p_addr and the next ** character in the string.
Example Programs Setting Ae_dir_dn and P_address Utility Example void char_to_hex(ch_string, ch_length, padr_string, padr_length) char *ch_string; int ch_length; char *padr_string; Uint32 *padr_length; { static char hex[] = “0123456789ABCDEF”; int padr_index; int ch_index; char ch; char *position; if (ch_length % 2 != 0) { (void)printf(“Character string won't fit into P_address field\n”); exit(ERROR); } /* ** Fill the p_addr byte with zeros.
Example Programs Checking for Errors Example Checking for Errors Example This example checks the function return value and the result.return_code, result.vendor_code, and diagnostic structures. This example also uses printf() statements to print the results. Use this routine in conjunction with the first three examples in this chapter: Using HLCF Functions Example, Managing FTAM Connections Example, and Using LLCS Example. #include % #include %
Example Programs Checking for Errors Example /* ** ** ** */ res = Call ft_gperror to get the printable strings for the return_code and vendor_code. Print the strings returned from ft_gperror.
Example Programs Common Code Example Common Code Example This example contains global definitions and common code for the first three examples in this chapter: Using HLCF Functions Example, Managing FTAM Connections Example, and Using LLCS Functions Example. /* ** ftm_globs.h ** ** DESCRIPTION: ** This file contains global definitions for the example ** programs illustrating HLCF calls, connection management, ** and LLCS calls. ** */ #include %
Example Programs Common Code Example #define ATTRIBUTE_GROUPS (FT_AG_STORAGE | FT_AG_SECURITY | FT_AG_PRIVATE) /** Define functions that return values other than integers. */ void exit(); /* ** Define the “void” routines in the example routines.
Example Programs Common Code Example main() /* ** ftm_hlcopy ** ** DESCRIPTION: ** This example program uses high level, context free functions ** synchronously. This program copies a file, changes the ** attributes of the destination file and deletes the source file.
Example Programs Common Code Example /* ** Change the attributes of the destination file. ** ** Get the parameters for ft_fcattributes. ** Call ft_fcattributes and verify the outcome. */ (void)printf(“Changing attributes of the destination file...
Example Programs Common Code Example #include % #include % #include “ftm_globs.h” #include % main() /* ** ftm_llcopy ** DESCRIPTION: ** This example program illustrates how to transfer a file ** using low level, context sensitive FTAM functions. This ** program transfers the source file to the destination directory.
Example Programs Common Code Example struct Ft_nwcleared_out_dcb *nwc_inout_dcb; char *clo_input_dcb; struct Ft_close_out_dcb *clo_inout_dcb; char *des_input_dcb; struct Ft_deselect_out_dcb *des_inout_dcb; Em_t time; Api_rc result; struct Ft_attributes attr_src; Return_code res; Api_rc outcome; int i, j, index; Bool done; struct Ft_diagnostic *diag = NULL; (void)printf(“ftm_llcopy: starting\n”); /* ** Activate “ftam_init”. ** ** Get the parameters for ft_aeactivation.
Example Programs Common Code Example /* ** Free memory.
Example Programs Common Code Example /* ** Get the parameters for ft_egroup. ** Call ft_egroup and verify the outcome. */ egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); res = ft_egroup(conn_id[SRC], return_event_name, egr_input_dcb, & egr_inout_dcb); if (res != SUCCESS) error_handler(egr_inout_dcb-result, diag); /* ** Wait on the asynchronous events in the group.
Example Programs Common Code Example /* ** Open the source file. ** ** Get the parameters for ft_open. ** Call ft_open and verify the outcome. */ (void)printf(“Opening the source file...\n”); ope_parm_in( & processing_mode, & contents_type, & return_event_name, & ope_input_dcb, & ope_inout_dcb); res = ft_open(conn_id[SRC], processing_mode, contents_type, return_event_name, ope_input_dcb, & ope_inout_dcb); if (res != SUCCESS) error_handler(ope_inout_dcb-result, ope_inout_dcb-diagnostic); /* ** Free memory.
Example Programs Common Code Example /* ** Get the parameters for ft_open. ** Call ft_open and verify the outcome. */ ope_parm_in( & processing_mode, & contents_type, & return_event_name, & ope_input_dcb, & ope_inout_dcb ); contents_type = attr_src.values.
Example Programs Common Code Example /* ** Free memory.
Example Programs Common Code Example /* ** Free memory. */ res = ft_dfdcb((Octet *)wri_inout_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** Replace the contents of destination file with the contents ** of source file. */ done = FALSE; while ( ! done ) { /* ** Read from the source file. ** ** Get the parameters for ft_rdata. ** Call ft_rdata and verify the outcome.
Example Programs Common Code Example /* Send data to the destination file. ** ** Get the parameters for ft_sdata. ** Call ft_sdata and verify the outcome. */ if (rda_inout_dcb -data_unit != NULL) { sda_parm_in(& return_event_name, & sda_inout_dcb); res = ft_sdata(conn_id[DST], rda_inout_dcb-data_unit, return_event_name, & sda_inout_dcb); if (res != SUCCESS) { /* ** If a “No connection resources” error was returned, ** wait until the resources are free.
Example Programs Common Code Example /* ** Free memory. */ res = ft_dfdcb((Octet *)eda_input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); res = ft_dfdcb((Octet *)eda_inout_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** End the transfer of data to the source and destination files. ** ** Get the parameters for ft_etransfer. ** Call ft_etransfer and verify the outcome.
Example Programs Common Code Example /* Get the parameters for ft_deselect. ** Call ft_deselect and verify the outcome. */ des_parm_in( & return_event_name, & des_input_dcb, & des_inout_dcb ); res = ft_deselect(conn_id[i], return_event_name, des_input_dcb, & des_inout_dcb); if (res != SUCCESS) error_handler(des_inout_dcb-result, des_inout_dcb-diagnostic); /* ** Get the parameters for ft_egroup. ** Call ft_egroup and verify the outcome.
Example Programs Common Code Example /* ** Release the connections between ftam_init and the ** responders for the source file and the destination file. ** ** Get the parameters for ft_rrequest. ** Call ft_rrequest and verify the outcome. */ (void)printf(“Releasing connections...
Example Programs Common Code Example #include % #include % #include “ftm_globs.h” #include % #include % /* ** ** aea_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_aeactivation ** program.
Example Programs Common Code Example /* This is an example for setting the ae_title */ /* (*input_dcb)-my_ae_title_option = User_object_id_option; (*input_dcb)-my_ae_title = (struct Ae_title *)malloc (sizeof(struct Object_id)); (*input_dcb)-my_ae_title-ae_object_id.length = 6; (*input_dcb)-my_ae_title-ae_object_id.element = (Sint32 *)malloc (6*sizeof(Sint32)); (*input_dcb)-my_ae_title-ae_object_id.element[0] = 1; (*input_dcb)-my_ae_title-ae_object_id.element[1] = 3; (*input_dcb)-my_ae_title-ae_object_id.
Example Programs Common Code Example Return_code res; Api_rc outcome; struct Ft_diagnostic *diag = NULL; /* ** Initialize the parameters with valid values. */ *return_event_name = SYNCHRONOUS; /* ** Initialize the called_ae_name as the DDN identifying the ** responder. */ convert_ddn(called_ae_name, LOCAL_RESP); /* ** Initialize the input_dcb. */ res = ft_didcb(FTiConnect, 0, (Octet **)input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); /* ** Set up the presentation address.
Example Programs Common Code Example /* ** Set up the context_name for FTAM. */ (*input_dcb)-context_name.element = (Sint32 *)malloc(5*sizeof(Sint32)); (*input_dcb)-context_name.length = 5; (*input_dcb)-context_name.element[0] = 1; (*input_dcb)-context_name.element[1] = 0; (*input_dcb)-context_name.element[2] = 8571; (*input_dcb)-context_name.element[3] = 1; (*input_dcb)-context_name.element[4] = 1; /* ** Set up the service_class, functional_units, and attribute_groups. */ (*input_dcb)-connect_in_info.
Example Programs Common Code Example void con_parm_in(return_event_name, called_ae_name, input_dcb, inout_dcb, connection_id) Local_event_name *return_event_name; Ae_dir_name *called_ae_name; struct Ft_connect_in_dcb **input_dcb; struct Ft_connect_out_dcb **inout_dcb; Connection_id *connection_id; { Return_code res; Api_rc outcome; struct Ft_diagnostic *diag = NULL; /* ** Initialize the parameters with valid values.
Example Programs Common Code Example /* ** Set up the invoke ids. */ (*input_dcb)-called_ae_invoke_id = NO_VALUE; (*input_dcb)-called_ap_invoke_id = NO_VALUE; /* ** Set up the retry counters and timer. */ (*input_dcb)-number_of_retry = 0; (*input_dcb)-delay_between_retry = 0; (*input_dcb)-connection_resource_wait_timer = 0; /* ** Set up the context_name for FTAM. */ (*input_dcb)-context_name.element = (Sint32 *)malloc(5*sizeof(Sint32)); (*input_dcb)-context_name.length = 5; (*input_dcb)-context_name.
Example Programs Common Code Example /* ** Initialize “inout_dcb”. */ *inout_dcb = NULL; *connection_id = 0; } /* ** ** rre_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_rrequest parameters.
Example Programs Common Code Example void aed_parm_in(return_event_name, inout_dcb) Local_event_name *return_event_name; struct Ft_output **inout_dcb; { /* ** Initialize the parameters with valid values. */ *return_event_name = SYNCHRONOUS; *inout_dcb = NULL; } /* ** fco_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_fcopy parameters.
Example Programs Common Code Example /* ** Set the directory distinguished names to identify the ** responders on the source and destination nodes. */ convert_ddn(source_dirname, LOCAL_RESP); convert_ddn(destination_dirname, REMOTE_RESP); /* ** Initialize the filenames. */ *source_filename = SRC_FNAME; *destination_filename = DEST_FNAME; *ae_label = NULL; *return_event_name = SYNCHRONOUS; /* ** Initialize the input_dcb.
Example Programs Common Code Example /* ** ** fca_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_fcattributes parameters.
Example Programs Common Code Example /* ** Set up the changed attributes. */ (*input_dcb)-attribute_names |= FT_AN_STORAGE_ACCT | FT_AN_FILE_AVAILABILITY | FT_AN_FUTURE_FILESIZE | FT_AN_LEGAL_QUAL | FT_AN_PRIVATE_USE; cat_attribute_in( & ((*input_dcb)-attributes) ); (*input_dcb)-account = DEST_ACCOUNT; /* ** Initialize the inout_dcb. */ *inout_dcb = NULL; } /* ** ** fde_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_fdelete parameters.
Example Programs Common Code Example /* ** Initialize the input_dcb. */ res = ft_didcb(FTiFDelete, 0, (Octet **)input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); (*input_dcb)-init_id = SRC_ID; (*input_dcb)-filestore_pw.pointer = (Octet *)SRC_PW; (*input_dcb)-filestore_pw.length = SRC_PW_LEN; (*input_dcb)-delete_file_pw.pointer = (Octet *)DEL_PW; (*input_dcb)-delete_file_pw.length = DEL_PW_LEN; (*input_dcb)-account = DEST_ACCOUNT; /* ** Initialize the inout_dcb.
Example Programs Common Code Example Api_rc outcome; Return_code res; struct Ft_diagnostic *diag = NULL; /* ** Initialize the parameters with valid values. */ *filename = SRC_FNAME; *requested_access = FT_FA_READ | FT_FA_REPLACE | FT_FA_EXTEND | FT_FA_ERASE | FT_FA_READ_ATTRIBUTE | FT_FA_CHANGE_ATTRIBUTE | FT_FA_DELETE_FILE; *return_event_name = 2; /* ** Initialize the input_dcb.
Example Programs Common Code Example /* ** Initialize the parameters with valid values. */ *return_event_name = 3; *input_dcb = NULL; *inout_dcb = NULL; } /* ** ** rat_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_rattributes parameters.
Example Programs Common Code Example /* ** ** ope_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_open parameters.
Example Programs Common Code Example /* ** ** clo_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_close parameters.
Example Programs Common Code Example Api_rc outcome; Return_code res; struct Ft_diagnostic *diag = NULL; /* ** Initialize the parameters with valid values. */ *filename = DEST_FNAME; ftam_3(contents_type); *requested_access = FT_FA_READ | FT_FA_REPLACE | FT_FA_EXTEND | FT_FA_ERASE | FT_FA_READ_ATTRIBUTE | FT_FA_CHANGE_ATTRIBUTE | FT_FA_DELETE_FILE; *file_status = FT_NEW; *return_event_name = 2; /* ** Initialize the input_dcb.
Example Programs Common Code Example /* ** Initialize the parameters with all valid values. */ *return_event_name = 1; *threshold = 2; *input_dcb = NULL; *inout_dcb = NULL; } /* ** ** egr_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_egroup parameters.
Example Programs Common Code Example /* ** ** rea_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_read parameters.
Example Programs Common Code Example struct Ft_fadu_identity *fadu_identity; enum Ft_fadu_operation *fadu_operation; Local_event_name *return_event_name; char **input_dcb; struct Ft_write_out_dcb **inout_dcb; { /* ** Initialize the parameters with valid values. */ fadu_ident_in(fadu_identity); *fadu_operation = FT_REPLACE; *return_event_name = SYNCHRONOUS; *input_dcb = NULL; *inout_dcb = NULL; } /* ** ** sda_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_sdata parameters.
Example Programs Common Code Example /* ** ** rda_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_rdata parameters.
Example Programs Common Code Example /* ** Initialize the parameters with all valid values. */ *return_event_name = SYNCHRONOUS; res = ft_didcb(FTiDataEnd, 0, (Octet **)input_dcb, & outcome); if (res != SUCCESS) error_handler(outcome, diag); (*input_dcb)-action_result = FT_AR_SUCCESS; (*input_dcb)-diagnostic = NULL; *inout_dcb = NULL; } /* ** ** etr_parm_in ** ** DESCRIPTION: ** This routine assigns valid values to the ft_etransfer parameters.
Example Programs Common Code Example /* ** ** wait_parm_in ** ** DESCRIPTION: ** This routine sets up the parameter values and the expected ** outcome values for em_wait calls. This routine allows ** the test programs to specify which set of parameter values ** you want to set. ** ** ** PARAMETERS: ** OUTPUT: ** time : timeout value ** result : contains return_code field for em_wait ** */ void wait_parm_in(time, result) Em_t *time; Api_rc *result; { /* ** Initialize “time” to infinite.
Example Programs Common Code Example /* ** Initialize all fields of the Ft_file_passwords structure. */ file_passwords-read.length = 4; file_passwords-read.pointer = (Octet *)”read”; file_passwords-insert.length = 6; file_passwords-insert.pointer = (Octet *)”insert”; file_passwords-replace.length = 7; file_passwords-replace.pointer = (Octet *)”replace”; file_passwords-extend.length = 6; file_passwords-extend.pointer = (Octet *)”extend”; file_passwords-erase.length = 5; file_passwords-erase.
Example Programs Common Code Example /* ** Change the legal_qualification. */ attributes-values.legal_qualification = “I’m_bad”; /* ** Change the private_use. */ attributes-values.private_use.pointer = (Octet *)“private”; attributes-values.private_use.length = 7; } /* ** ** ftam_3 ** ** DESCRIPTION: ** This routine assigns a ftam_3 document type to the Ft_contents_type ** structure.
Example Programs Common Code Example /* ** ** attribute_in ** ** DESCRIPTION: ** This routine assigns valid values to the Ft_attribute structure. ** ** ** PARAMETERS: ** Outputs: ** attributes : pointer to the attributes structure ** */ void attribute_in(attributes) struct Ft_attributes *attributes; { /* ** Initialize all fields of Ft_attributes structure.
Example Programs Common Code Example /* ** ** concur_cntl_in ** ** DESCRIPTION: ** This routine assigns valid values to the Ft_concurrency_control ** structure. ** ** ** PARAMETERS: ** Outputs: ** concurrency_control : pointer to the Ft_concurrency_control ** structure ** */ void concur_cntl_in(concurrency_control) struct Ft_concurrency_control **concurrency_control; { /* ** Initialize the Ft_concurrency_control structure.
Example Programs Common Code Example /* ** ** nwc_parm_in ** ** DESCRIPTION: ** This routine assigns values to the ft_nwcleared parameters. ** ** ** PARAMETERS: ** OUTPUT: ** return_event_name : gets signalled when the event completes ** default: SYNCHRONOUS ** inout_dcb : contains return_code field ** ** */ void nwc_parm_in(return_event_name, inout_dcb) Local_event_name *return_event_name; struct Ft_nwcleared_out_dcb **inout_dcb; { /* ** Initialize the parameters with valid values.
Example Programs Common Code Example #include % #include % #include % void exit(); /* ** error_handler ** ** DESCRIPTION: ** This routine is an example of handling failures experienced ** during the FTAM functions. This routine will display the ** error messages.
Example Programs Common Code Example /* ** Traverse the diagnostic list and print the further_details strings.
Example Programs Common Code Example 428 Chapter 10
11 Document Types and Constraint Sets 429
Document Types and Constraint Sets Document Types Document Types Document types define the semantics for classes of files. A document type defines the type of file contents by specifying a constraint set and the possible data types in the file. Example file types include text files, binary files, sequential files, and directories. The following table shows information about the parameters in the cont_type.contents_info.document->parameters field for FTAM-1, FTAM-2, FTAM-3, and INTAP-1 document types.
Document Types and Constraint Sets Document Types FTAM-1 Document Type FTAM-1 has only one FADU that contains zero or more text strings. An FTAM-1 file contains only one string type, chosen from FT_CL_GENERAL_STRING, FT_CL_IA5_STRING, FT_CL_GRAPHIC_STRING, or FT_CL_VISIBLE_STRING (Figure 11-1) Figure 11-1 FTAM-1 Document Type Structure Data Unit Node Descriptor Text String FADU You can only read from or write to the whole data unit (not parts of it).
Document Types and Constraint Sets Document Types Figure 11-2 FTAM-1 Document Type Restrictions FTAM-1 Document Type Unstructured Constraint Sets Unstructured All Access Context NOTE Refer to the “FTAM Data Structures” chapter for detailed information on setting the FTAM-1 document type using the Ft_dt_ftam_1 structure. FTAM-1 Document Semantics The following semantics are mandatory for FTAM-1 document types. • FTAM-1 uses restrictions specified by the Unstructured constraint set.
Document Types and Constraint Sets Document Types If the class parameter is not present, the default is FT_CL_GENERAL_STRING. The character strings may contain characters from any of the characters sets registered for use as C0, C1, G0, G1, G2, or G3 sets, including SPACE. 1 Refer to the “Character Sets” chapter for this list of characters. • The string_length parameter determines the length of maximum number of octets in each data element. HP–UX responders accept an unlimited string_length.
Document Types and Constraint Sets Document Types Figure 11-3 FTAM-2 Document Type Structure Root FADU DU Text String DU Text String Node Descr. FADU A Node Descr. DU Text String FADU B DU Text String Node Descr. FADU n FTAM-2 uses the Sequential Flat constraint set to restrict the file model, and therefore uses either the Unstructured All or Flat All access context (Figure 11-4). Refer to the “Constraint Sets” and “Access Contexts” sections for detailed information.
Document Types and Constraint Sets Document Types Figure 11-4 FTAM-2 Document Type Restrictions FTAM-2 Document Type Sequential Flat Constraint Sets Unstructured All or Flat All Access Context NOTE Refer to the “FTAM Data Structures” chapter for detailed information on setting the FTAM-2 document type using the Ft_dt_ftam_2 structure. FTAM-2 Document Semantics The following semantics are mandatory for FTAM-2 document types.
Document Types and Constraint Sets Document Types • If the class parameter is not present, the default is FT_CL_GRAPHIC_STRING. The character strings may contain characters from any of the characters sets registered for use as G0, G1, G2, or G3 sets, including SPACE. 1 Refer to the “Character Sets” chapter for this list of characters. • The string_length parameter determines the maximum number of octets in each data element. HP–UX responders accept an unlimited string_length.
Document Types and Constraint Sets Document Types Figure 11-6 FTAM-3 Document Type Restrictions FTAM-3 Document Type Unstructured Constraint Sets Unstructured All Access Context NOTE Refer to the “FTAM Data Structures” chapter for detailed information on setting the FTAM-3 document type using the Ft_dt_ftam_3 structure. FTAM-3 Document Semantics The following semantics are mandatory for FTAM-3 document types. • FTAM-3 uses the constraints specified by the Unstructured constraint set.
Document Types and Constraint Sets Document Types • The string_significance parameter determines the exact significance of the character strings. Three values are supported: • FT_SS_NO_SIGNIFICANCE - the string or data element boundaries are not preserved across file transfers. For example, if you create a file using eight strings, you may or may not receive eight strings back when you read the file. Different FTAM implementations may break the file into strings in different ways.
Document Types and Constraint Sets Document Types INTAP-1 Document Semantics The following semantics are mandatory for INTAP-1 document types. • An INTAP-1 document consists of one file access data unit, which consists only of zero, one, or more records. The order of these records is significant. • Each record consists of octets of any value from 0 to 255. The meaning attached to these values is not constrained by the document type.
Document Types and Constraint Sets Document Types Figure 11-9 NBS-9 Document Type Restrictions NBS-9 Document Type Unstructured Constraint Set Unstructured All Access Context NOTE Refer to the “FTAM Data Structures” chapter for detailed information on setting the NBS-9 document type using the Ft_dt_nbs_9 structure. NBS-9 Document Semantics The following semantics are mandatory semantics for NBS–9 document types. • NBS-9 uses the Unstructured constraint set.
Document Types and Constraint Sets Document Types • The following table describes the legal operations on NBS-9 documents: Table 11-1 Legal Operations for the NBS-9 Document Type Standard (specified by the NIST agreements) select open read close deselect Chapter 11 HP-UX FTAM Supports these Additional Value-Added Operations create delete read attributes change attributes 441
Document Types and Constraint Sets Constraint Sets Constraint Sets Every application needs a specific set of file structures, and any real system is likely to support only a limited range of file types, with restrictions on the ways you can modify files. Constraint sets express these limitations by restricting the following items. • Range of allowable file structures • Ways in which basic access actions can modify the structure Constraint sets restrict (reduce) the file model.
Document Types and Constraint Sets Constraint Sets • Special semantics of specific file access actions • Allowable FADU identity forms for each of the file access actions Access Contexts Each constraint set contains a list of available access contexts which allow you to further restrict the file structure view during read operations. The Access Contexts are Unstructured All Data Units (UA) and Flat All Data Units (FA). For FTAM-1, FTAM-3, and INTAP-1, only the UA access context is available.
Document Types and Constraint Sets Constraint Sets Unstructured Constraint Set The unstructured constraint set applies to files that you can transfer or access in whole, or extend; partial access is not available. Refer to the following list for applicable basic constraints. Constraint Set Name Unstructured Constraint Set Identifier ISO Standard 8571 constraint-set (4) unstructured (1) (ASN.
Document Types and Constraint Sets Constraint Sets Additional constraints on the Unstructured constraint set are as follows. Structural Constraints All actions in the unstructured constraint set result in a structure with a root node that has a data unit (although this data unit may be empty). Action Constraints The FT_FA_ERASE action yields a root node with an empty data unit. Identity Constraints The FADU identity is always FT_FIRST. Use this form of FADU identity with all permitted file actions.
Document Types and Constraint Sets Constraint Sets End of File No node selected.
12 Character Sets 447
Character Sets Former Intro ... Change Former Intro ... Change This chapter defines the available character sets for the HP FTAM/9000 product. All numbers are in decimal notation. IA5String The characters available for the IA5String are all characters with ordinal values between 0 and 127, inclusive. The exceptions are the characters with ordinal values 14 and 15. GeneralString The characters available for the GeneralString are all characters with ordinal values between 0 and 255, inclusive.
Glossary Access Context A set of restrictions that dictates how the information in a file is accessed; you can specify access contexts only when reading a file. Activity Attributes Attributes that define the properties that exist only while a specific FTAM connection is being used; these attributes are not part of the file. Application Entity A uniquely identified component of your application program that associates it with OSI; may be an FTAM initiator or FTAM responder.
Glossary Data Element The smallest piece of data whose identity is preserved when transferred by the Presentation Service. A data element may convey file contents information or protocol control information. File Access The inspection, modification, replacement, or erasure of a file's contents or a portion of it. File Access Data Unit (FADU) Data Unit (DU) The file unit that contains the actual file contents; a data unit may contain file structuring information or data elements.
Glossary File Service User The portion of the application entity that invokes the FTAM service. File Transfer A function that moves a part or the whole of a file's contents between open systems. File Transfer, Access and Management An OSI layer seven protocol that allows peer-to-peer file transfer, record access, and file management. FTAM See File Transfer, Access and Management ftam_init The executable name for an HP–UX FTAM initiator; sends your request to an FTAM responder.
Glossary Low Level Service (LLS) A function that provides the lowest level of service for the MAP 3.0 application interface; a LLS does not contain a sequence of other calls. Open Systems Interconnection (OSI) A set of standards that define the seven layers of communication protocols for a network; ISO defines these standards. Manufacturing Automation Protocol (MAP) A seven layer communications specification; allows multivendor communication among factory automation equipment without custom links.
Glossary the rules (protocols) for the FTAM state machine. (For example, the Data Transfer regime allows reading or writing of the file.) Regimes are nested. Responder The entity that receives and services an initiator's request; if applicable, the responder returns a response; the responder interacts directly with the virtual filestore.
Glossary 454 Glossary
Index A Abort ft_abort( ), 266 ft_aereset( ), 264 ft_ireceive( ), 267 Indication, 267 Abort Connections, 266 Access Contexts, 40, 90, 443 Access Control, 92 Defined Constants, 94 Accessing FTAM Files, 272 action_result, 341 Activate AE, 254 Activity Attributes, 39 AE, 37 Ae_dir_name, 75 Ae_dir_name Example, 81 Ae_label, 83 Ae_title, 84 Ae_title_option, 85 API Tracing, 349, 350, 351, 352 Api_rc, 87 Application Entities Activate, 254 Deactivate, 256 Application Entities (AE), 37, 254 Asynchronous Operations,
Index Ft_file_actions, 138 Ft_file_lock, 111 Ft_file_passwords, 140 Ft_file_status, 141 Ft_filename, 143 Ft_functional_units, 144 Ft_initiator_identity, 147 Ft_node_descriptor, 123 Ft_output, 156 Ft_processing_mode, 148 Ft_qos, 149 Ft_service_class, 150 Ft_single_file_pw, 155 Ft_structure_id, 121 Ft_xxx_out_dcb, 157 Inout_dcb, 156 Input_dcb, 160 Local_event_name, 163 P_address, 164 Data Transfer Cancel, 328 End, 324, 326 ft_edata( ), 324 ft_etransfer( ), 326 Receive Cancel Indication, 330 Data Types, 70 Da
Index FPM Errors, 341 ft_ gperror( ), 198 ft_abort( ), 266 Ft_abort_in_dcb, 266 Ft_output, 266 Ft_access_context, 90 Ft_access_control, 92 Ft_access_control_element, 94 Ft_account, 97 ft_aeactivation( ), 254 Ft_aeactivation_in_dcb, 254 Ft_output, 255 ft_aedeactivation( ), 256 Ft_output, 256 ft_aereset( ), 264 Ft_output, 264 FT_AG Defined Constants, 100 FT_AN Defined Constants, 102 Ft_attribute_ groups, 98 Ft_attribute_names, 101, 105 Ft_attribute_values, 106 Ft_attributes, 103 ft_bgroup( ), 305 Ft_bgroup_o
Index Functions ft_open( ), 280 ft_open( ), 280 Ft_open_in_dcb, 280 Ft_open_out_dcb, 281 Ft_output, 156, 256, 264, 266 FT_PA Defined Constants, 106 FT_PM Defined Constants, 148 Ft_processing_mode, 148 Ft_qos, 149 ft_rattributes( ), 294 Ft_rattributes_in_dcb, 295 Ft_rattributes_out_dcb, 295 ft_rcancel( ), 330 Ft_rcancel_out_dcb, 330 ft_rdata( ), 315 Ft_rdata_out_dcb, 315 ft_rdataqos( ), 317 Ft_rdataqos_out_dcb, 318 ft_read( ), 313 Ft_read_out_dcb, 314 ft_rrequest( ), 263 Ft_relreq_in_dcb, 263 Ft_relreq_out_
Index input_dcb, 160 INTAP-1 Document Types, 39 INTAP-1 Document Types, 39, 118, 438 International Standards Organization (ISO), 28 K Kernel Group, 99 L Libraries, 46 Linking FTAM Libraries, 46 lint(1) Library, 46 LLS, 51 Local_event_name, 163 Locate FADU, 299 Logging Errors, 346 Logging Errors Example, 347 Low Level Service (LLS), 51 M Managing FTAM Connections, 250 Managing FTAM Files, 272 Manufacturing Automation Protocol (MAP) 3.0, 29 MAP 3.0, 29 MAP 3.0 FTAM Errors, 339 map.h, 68 mapftam.
Index Programming, 63 Recovery, Error, 149 Regimes, 34 Data Transfer, 50 File Open, 49 File Selection, 49 FTAM, 48 Functions Within, 52 Guidelines, 47 Release Requests, 263 Resources Available, 200 Responder, 36 result.return_code, 339 result.
