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. A copy of the specific warranty terms applicable to your Hewlett- Packard product and replacement parts can be obtained from your local Sales and Service Office. Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 for other agencies. HEWLETT-PACKARD COMPANY 3000 Hanover Street Palo Alto, California 94304 U.S.A. Use of this manual and flexible disk(s) or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited. Copyright Notices. ©copyright 1983-97 Hewlett-Packard Company, all rights reserved. Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws. ©copyright 1979, 1980, 1983, 1985-93 Regents of the University of California This software is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California. 2 ©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. ©copyright 1990, 1991, 1992 Cornell University ©copyright 1989-1991 The University of Maryland ©copyright 1988 Carnegie Mellon University Trademark Notices UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. X Window System is a trademark of the Massachusetts Institute of Technology. MS-DOS and Microsoft are U.S. registered trademarks of Microsoft Corporation. OSF/Motif is a trademark of the Open Software Foundation, Inc. in the U.S. and other countries. 3 4 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. See your HP sales representative for details. First Edition: April 1991 (HP-UX Release 8.0) Second Edition: November 1992 (HP-UX Release 9.0) Third Edition: January 1995 (HP-UX Release 10.x) Fourth Edition: March 1997 (HP-UX Release 10.10) Fifth Edition: May 1997 (HP-UX Release 10.30) 5 6 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. Scope The HP FTAM/9000 Programmer's Guide explains basic FTAM concepts and thoroughly explains each FTAM data structure. This guide also describes the FTAM functions and their parameters. HP FTAM/9000 runs on HP OTS/9000, an HP network product that provides a lower-level OSI protocol “stack,” in conjunction with an 802.3 network link. 7 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. Additionally, it provides general recommendations for programming with FTAM. Chapter 3 HP FTAM/9000 Data StructuresThis chapter describes the structures used by FTAM. Additionally, the chapter describes header files, setting bits with defined constants, and basic data types. Chapter 4 Using Support FunctionsThis chapter describes the support functions used throughout most applications. For example, some support functions help you manage memory and translate error codes to printable character strings. Chapter 5 Using High Level, Context Free FunctionsThis chapter describes high level, context free (HLCF) functions. High level means you can use one function instead of several other functions (low level). Context free means they are not dependent on the use of other functions for their success. Chapter 6 Managing HP FTAM/9000 ConnectionsThis chapter describes functions used to establish and release FTAM connections. Chapter 7 Managing and Accessing HP FTAM/9000 FilesThis chapter describes the functions used to manage and access FTAM files after you established connections. 8 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. Chapter11 Document Types and Constraint SetsThis appendix contains describes the file representations supported by the various document types and constraint sets. Chapter 12 Character SetsThis appendix describes the available character sets for the HP–UX implementation of FTAM. Glossary The glossary defines terms used throughout the manual. Index The index lists information by topics so that you locate necessary information. Documentation Guide For More Read Information Installing and Installing and Administering HP Configuring HP FTAM/9000 (B1033-90034) FTAM/9000 Troubleshooting HP OSI Troubleshooting Guide (32070-90020) FTAM/9000 FTAM Programming HP FTAM/9000 Reference Manual (B1033-90004) 9 FTAM Protocol ISO 8571, Information Processing Systems – Specifications Open Systems Interconnection – File Transfer, Access and Management International ISO 8571, Information Processing Systems – Standards ISO 8571 Open Systems Interconnection – File Transfer, Access and Management MAP 3.0 Interface MAP 3.0 Application Interface Specification Specifications NBS Phase III Implementation Agreements for Open Systems Interconnection Protocols from the NBS Workshop for Implementors of Open Systems Interconnection ACSE ISO 8649, Information Processing Systems – Open Systems Interconnection – Service Definition for the Association Control Service Element ASN.1 ISO 8824, Information Processing Systems – Open Systems Interconnection – Specification of Abstract Syntax Notation One (ASN.1) BER ISO 8825, Information Processing Systems – Open Systems Interconnection – Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1) 10 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. .29 NBS (NIST) Implementors Agreements . .29 Protocol Implementation Conformance Statement (PICS) . .30 Overview of FTAM Concepts. .31 The Virtual Filestore (VFS) . .31 FTAM Shadow Files . .33 Regimes. .34 FTAM Communication. .35 Initiators and Responders . .36 Application Entities (AEs) . .37 Synchronous and Asynchronous Operations . .38 File Attributes . .39 Document Types . .39 Constraint Sets . .40 Access Contexts . .40 FTAM File Structure Model. .41 2. Using HP FTAM/9000 Chapter Overview . .44 Starting and Stopping the FTAM System . .45 Generating FTAM Programs . .46 Header Files . .46 libmapftam.a Library . .46 lint(1) Library . .46 11 Contents Using Regimes . 47 Regime Guidelines . 47 Using the FTAM Regime. 48 Using the File Selection Regime . 49 Using the File Open Regime . 49 Using the Data Transfer Regime . 50 Using Functions . 51 High Level Services (HLS) and Low Level Services (LLS). 51 Context Free (CF) and Context Sensitive (CS) Functions . 52 Available Functions . 52 Typical Applications . 59 Using Parameters. 60 Parameter Order . 60 Data Control Blocks . 61 input_dcb . 61 inout_dcb . 61 General Recommendations . 63 Handling Strings, HP-UX Lines, and FTAM-1 Lines . 64 3. HP FTAM/9000 Data Structures Chapter Overview . 67 Header Files . 68 Using Defined Constants To Set Bits . 69 EXAMPLE . 69 Basic Data Types . 70 Object_id . 70 Octet_string. 71 12 Contents Directory Services Data Structures . .72 Organizing Directory Services. .72 Using Directory Services . .74 Ae_dir_name . .75 Dir_dn . .76 EXAMPLE . .76 Dir_rdn . .77 EXAMPLE . .77 Dir_ava . .79 Setting Ae_dir_name Example . ..