OSI/FTAM Programming Reference Manual

ManualsBrandsHP ManualsServerHP NonStop G-Series

HP NonStop OSI/FTAM

Programming

Reference Manual

Abstract

This manual describes the operation of the HP NonStop

™

Open Systems

Interconnection/File Transfer, Access, and Management (OSI/FTAM) application

programmatic interface (API). It is for programmers writing FTAM applications that use

the services of the NonStop FTAM initiator. The FTAM API allows applications to

perform file-handling and transfer tasks.

Product Version

OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06

Supported Release Version Updates (RVUs)

This publication supports D43.00 and all subsequent D-series RVUs and G06.01 and

all subsequent G-series RVUs until otherwise indicated by its replacement publication.

Part Number Published

528611-001 October 2004

Summary of content (604 pages)

PAGE 1
HP NonStop OSI/FTAM Programming Reference Manual Abstract This manual describes the operation of the HP NonStop™ Open Systems Interconnection/File Transfer, Access, and Management (OSI/FTAM) application programmatic interface (API). It is for programmers writing FTAM applications that use the services of the NonStop FTAM initiator. The FTAM API allows applications to perform file-handling and transfer tasks.
PAGE 2
Document History Part Number Product Version Published 030253 OSI/FTAM C30, OSI/APLMGR C30 September 1992 528611-001 OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06 October 2004
PAGE 3
HP NonStop OSI/FTAM Programming Reference Manual Glossary Index What’s New in This Manual ix Manual Information ix New and Changed Information About This Manual xi Who Should Read This Manual? What’s In This Manual? xi Related Manuals xiv Notation Conventions xvi Figures Tables ix xi 1.
PAGE 4
3. NonStop FTAM Initiator Contents 3. NonStop FTAM Initiator Initiator Structure 3-1 Initiator Data Flow 3-3 Types of Procedures in the FTAM API 3-4 How FTM Procedures Are Categorized 3-5 Request Procedures 3-5 Indication Procedures 3-5 Response Procedures 3-6 Confirm Procedures 3-6 Grouped Procedures 3-6 Mapping of Primitives to Procedures 3-6 Supported Functions 3-9 Service Classes 3-9 Functional Units 3-9 Attribute Groups 3-10 Attributes 3-10 Document Types 3-11 Accessing Local Information 3-11 4.
PAGE 5
4. FTM Procedures (continued) Contents 4.
PAGE 6
A. DDL Definitions (continued) Contents A. DDL Definitions (continued) Parameter Structures A-5 ZAPS Structures A-6 ZFTM Structures A-12 Named Values A-37 Procedure Call Cross Reference Table A-42 B. NonStop FTAM Initiator Error Messages Status Codes B-2 Error Codes B-4 APS Error Codes B-4 FTAM Initiator Error Codes B-19 C.
PAGE 7
G. NonStop FTAM Programming Examples Contents G.
PAGE 8
Tables (continued) Contents Tables (continued) Table 4-4. Table 4-5. Table 4-6. Table 4-7. Table 4-8. Table 4-9. Table 4-10. Table 4-11. Table 4-12. Table 4-13. Table 4-14. Table 4-15. Table 4-16. Table 4-17. Table 4-18. Table 4-19. Table 4-20. Table 4-21. Table 4-22. Table 4-23.
PAGE 9
Tables (continued) Contents Tables (continued) Table 4-24. Table 4-25. Table 4-26. Table 4-27. Table 4-28. Table 4-29. Table 4-30. Table 4-31. Table 4-32. Table 4-33. Table 4-34. Table 4-35. Table 4-36. Table 4-37. Table 4-38. Table 4-39. Table 4-40. Table 4-41. Table 4-42. Table 4-43.
PAGE 10
Tables (continued) Contents Tables (continued) Table 4-44. Table 4-45. Table 4-46. Table 4-47. Table A-1. Table A-2. Table B-1. Table B-2. Table B-3. Table B-4. Table B-5. Table B-6. Table B-7. Table B-8. Table B-9. Table B-10. Table B-11. Table B-12. Table B-13. Table B-14. Table C-1. Table C-2. Table C-3. Table C-4. Table C-5. Table C-6. Table C-7. Table C-8. Table C-9. Table D-1.
PAGE 11
What’s New in This Manual Manual Information HP NonStop OSI/FTAM Programming Reference Manual Abstract This manual describes the operation of the HP NonStop™ Open Systems Interconnection/File Transfer, Access, and Management (OSI/FTAM) application programmatic interface (API). It is for programmers writing FTAM applications that use the services of the NonStop FTAM initiator. The FTAM API allows applications to perform file-handling and transfer tasks.
PAGE 12
What’s New in This Manual • • • • • New and Changed Information Changed the size of the encoded data limit from 7 KB to 16 KB on pages 4-50, B-27, and B-27. Changed the size of the data value parameter that can be sent from 11 KB to 24 KB on page B-27. Changed the buffer size from 12 KB to 25 KB under Considerations on page 4-55. Removed maximum-string-length as a required component of the contents-type attribute in the value for initial-attrib when specifying values of file-status on page 4-85.
PAGE 13
About This Manual The OSI/FTAM Programming Reference Manual is the companion manual to the OSI/FTAM Programming Guide. It provides reference information about writing application programs that use NonStop OSI/File Transfer, Access and Management (FTAM) application services.
PAGE 14
What’s In This Manual? About This Manual Section Title This section... 2 Conformance and Interoperability Presents details about NonStop FTAM conformance testing and pointers on evaluating interoperability between NonStop FTAM and other FTAM implementations. 3 NonStop FTAM Initiator Describes the NonStop FTAM initiator process and how it provides the supported FTAM functions, and presents information about the FTAM API.
PAGE 15
Supported Standards About This Manual Supported Standards This manual and the other NonStop FTAM manuals are written on the assumption that you are familiar with the ISO standards and the National Institute of Standards and Technology (NIST) FTAM Phase 2 agreements to which NonStop FTAM and the underlying NonStop OSI products conform.
PAGE 16
Related Manuals About This Manual Related Manuals Figure i on page -xv shows how the manual you are now reading is related to other NonStop manuals. The flowchart, read from the top down, indicates the order in which you might read the manuals.
PAGE 17
Related Manuals About This Manual Figure i. Documentation Road Map OSI/FTAM Programming Guide Guardian Programmer’s Guide TAL Reference Manual OSI/FTAM Programming Reference Manual OSI/FTAM and OSI/ APLMGR SCF Reference Manual OSI/FTAM Config. and Mgmt. Manual C/C++ Programmer's Guide Guardian Procedure Calls Reference Manual Guardian Procedure Errors and Messages Manual OSI/AS Programming Manual VSTAB01.
PAGE 18
Notation Conventions About This Manual Notation Conventions Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Backup DAM Volumes and Physical Disk Drives on page 3-2. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS.
PAGE 19
General Syntax Notation About This Manual { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON | OFF } | Vertical Line.
PAGE 20
Notation for Messages About This Manual a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] LINE [ , attribute-spec ]… !i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data to the called procedure); the !o notation follows an output parameter (one that returns data to the calling program).
PAGE 21
Notation for Management Programming Interfaces About This Manual lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned. For example: p-register process-name [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed.
PAGE 22
Change Bar Notation About This Manual UPPERCASE LETTERS. Uppercase letters indicate names from definition files. Type these names exactly as shown. For example: ZCOM-TKN-SUBJ-SERV lowercase letters. Words in lowercase letters are words that are part of the notation, including Data Definition Language (DDL) keywords. For example: token-type !r. The !r notation following a token or field name indicates that the token or field is required. For example: ZCOM-TKN-OBJNAME !o. token-type ZSPI-TYP-STRING.
PAGE 23
1 Introduction to NonStop OSI/FTAM This manual describes the NonStop Open Systems Interconnection/File Transfer, Access and Management (OSI/FTAM) product used in developing FTAM applications. NonStop OSI/FTAM is the NonStop implementation of the FTAM standard ISO 8571, developed by the International Organization for Standardization (ISO).
PAGE 24
Introduction to NonStop OSI/FTAM NonStop FTAM Services encoded messages transferred across an OSI network between the initiator and responder. FTAM file handling is defined in terms of initiator and responder functions. The initiator provides application programs with access to the FTAM protocol so that you can request services to be performed by a responder across the network. The remote responder acts as a file server and performs the requested services.
PAGE 25
Introduction to NonStop OSI/FTAM Programming Capabilities systems. The information consists of details on the transactions that have taken place with the other banks, such as credits, checks cleared, debits, and so on. FTAM provides the necessary file-handling function among the different systems on the network. The OSI/FTAM Programming Guide also describes an FTAM application scenario. Programming Capabilities This manual focuses on the programmatic interface you use to develop applications.
PAGE 26
Management Interface Introduction to NonStop OSI/FTAM system receives these responses as confirms. Thus, four primitives—request, indication, response, and confirm—are used to complete most services, as shown in Figure 1-1. The OSI/FTAM Programming Guide provides details on the different types of primitives and how they effect programming. Section 3, NonStop FTAM Initiator identifies the FTAM services that the initiator supports. Figure 1-1.
PAGE 27
Introduction to NonStop OSI/FTAM Architectural Overview Tandem LAN access method (TLAM) or the X.25 access method (X25AM) to communicate with remote computer systems across a network. NonStop FTAM, the OSI/AS subsystem, the OSI/TS subsystem, and TLAM or X25AM must be configured and running on the NonStop system for your application to communicate with a remote system. For more information about OSI/AS, OSI/TS, TLAM, and X25AM, see Figure 1-6 on page 1-13 and the accompanying text.
PAGE 28
Architectural Overview Introduction to NonStop OSI/FTAM complete discussion of this interface, refer to the OSI/FTAM Configuration and Management Manual. Figure 1-2. NonStop FTAM Architectural Overview Application Programmatic Interface Management Interface Guardian File System NonStop FTAM OSI/AS OSI/TS TLAM or X25AM Communications Network Remote FTAM Initiator Remote FTAM Responder VST0102.vsd Figure 1-2 also shows the following architectural components: • • • The Guardian file system.
PAGE 29
Introduction to NonStop OSI/FTAM • • FTAM and APLMGR Subsystems Remote FTAM initiator on the network, which can communicate with the NonStop FTAM responder and the Guardian file system. Remote FTAM responder on the network, which services requests initiated by the NonStop FTAM initiator for information stored in a remote file storage system. Note. The initiator and responder functions of remote FTAM implementations are not necessarily performed by separate processes.
PAGE 30
NonStop FTAM and the Guardian File System Introduction to NonStop OSI/FTAM Figure 1-3. FTAM and APLMGR Subsystems Application Programmatic Interface NonStop FTAM APLMGR Subsystem FTAM Subsystem APLMGR Initiator Management Interface Guardian File System MIB Responder VFS OSI/AS OSI/TS TLAM or X25AM Communications Network Remote FTAM Initiator Remote FTAM Responder VST0103.
PAGE 31
Introduction to NonStop OSI/FTAM Application Programmatic Interface When a remote FTAM initiator needs access to the Guardian file system, the responder provides that service via its VFS component, mapping the FTAM requests into Guardian file requests and translating between FTAM and Guardian file structures and attributes. For more information on the VFS, refer to the OSI/FTAM Responder Manual.
PAGE 32
Distributed Systems Management (DSM) Interface Introduction to NonStop OSI/FTAM Figure 1-4. NonStop FTAM and the Application Programmatic Interface (API) Application Program FTAM API Management Interface NonStop FTAM OSI/AS Guardian File System 4 OSI/TS TLAM or X25AM Communications Network Remote FTAM Responder VST0104.vsd Distributed Systems Management (DSM) Interface Figure 1-5 on page 1-12 shows additional details of the NonStop Distributed Systems Management (DSM) interface.
PAGE 33
Introduction to NonStop OSI/FTAM • • Distributed Systems Management (DSM) Interface Subsystem Control Point (SCP), an intermediate management process that routes commands from SCF to the APLMGR, initiator, or responder process being managed. Event Management Service (EMS), a collection of processes, tools, and interfaces that provide event collection, event logging, and event distribution facilities for communications subsystems.
PAGE 34
Introduction to NonStop OSI/FTAM OSI/AS, OSI/TS, and TLAM or X25AM Subsystems Figure 1-5. NonStop FTAM and the DSM Interface DSM EMS Application Programmatic Interface SCF NonStop FTAM PTRACE Guardian File System SCP OSI/AS 4 OSI/TS TLAM or X25AM Communications Network Remote FTAM Initiator Remote FTAM Responder VST0105.vsd OSI/AS, OSI/TS, and TLAM or X25AM Subsystems Figure 1-6 on page 1-13 focuses on the NonStop OSI underlying services.
PAGE 35
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems Introduction to NonStop OSI/FTAM Figure 1-6. NonStop FTAM and OSI/AS, OSI/TS, and TLAM or X25AM Subsystems Application Programmatic Interface NonStop FTAM Management Interface OSI/AS OSI Manager Guardian File System SCF TAPS OSI/TS SCF TSP MIB TLAM or X25AM SCF NSP Communications Network Remote FTAM Initiator Remote FTAM Responder VST0106.
PAGE 36
Introduction to NonStop OSI/FTAM OSI/AS, OSI/TS, and TLAM or X25AM Subsystems When configuring these subsystems to support FTAM services, you must register each TAPS, TSP, and NSP process with the OSI manager process. You can configure more than one instance of each of these processes (TAPS, TSP, and NSP) to run at a given time, as well as multiple OSI manager processes managing separate subsystems. For more information on configuring, refer to the OSI/FTAM Configuration and Management Manual.
PAGE 37
2 Conformance and Interoperability This section presents information about the conformance to standards and the interoperability of the NonStop FTAM initiator. Conformance is the satisfaction of the requirements of the applicable standards, consistent with the capabilities stated in the protocol implementation conformance statement (PICS) for the implementation. Interoperability is the ability of an implementation of a standard to work with other implementations of the same standard to deliver services.
PAGE 38
Conformance and Interoperability Basic Characteristics of FTAM Implementations conformant to the ISO specification. For example, two systems cannot interoperate when each supports only an initiator, or when a document type supported by an initiator is not included among the document types supported by the responder. The NonStop FTAM product has been tested to conform with the standards and profiles mentioned in Conformance on page 2-1.
PAGE 39
Conformance and Interoperability Document Types and Related Parameters Underlying Services NonStop FTAM uses NonStop OSI/AS, which is an implementation of version 1 of the Association Control Service Element (ACSE), as stated in ISO IS 8649 and 8650; version 1 of the Presentation Layer, as stated in ISO IS 8822 and 8823; and version 2 of the Session Layer, as stated in ISO IS 8326 and 8327.
PAGE 40
Conformance and Interoperability Data Transfer Considerations NonStop FTAM supports unbounded strings for FTAM-1 (string-significance: not significant or variable) and FTAM-3 (string-significance: not significant). For string-significance, the initiator supports all three possible values for the FTAM-1, FTAM-2, and FTAM-3 document types: not-significant, fixed, and variable.
PAGE 41
Conformance and Interoperability Presentation Encoding of FTAM PDUs and Data For FTAM-3 files, remember that the native character sets (ASCII, EBCDIC, and so on) might be incompatible on the sending and receiving systems. For example, NonStop systems use the 7-bit ASCII character set, whereas some other vendors’ systems use 8-bit EBCDIC. If you decide to send or receive text characters as FTAM-3 binary data, some conversion of the native character set might be necessary.
PAGE 42
Conformance and Interoperability Presentation Encoding of FTAM PDUs and Data HP NonStop OSI/FTAM Programming Reference Manual—528611-001 2 -6
PAGE 43
3 NonStop FTAM Initiator The NonStop FTAM initiator allows applications running on a NonStop system to access FTAM protocol and to request services of a responder across the OSI network. It is responsible for initiating and managing the associations between NonStop FTAM applications and remote FTAM applications. The initiator communicates with application programs through the FTAM application programmatic interface (API). The OSI/AS API provides the initiator interface with the OSI/AS subsystem.
PAGE 44
Running H/F 2 Running H/F 1 Other elements depicted in Figure 3-1, such as the Guardian file system and the TAPS process, are addressed in more detail later in this section. The numbers indicated in the figure refer to the sequence of information flow to and from the FTAM initiator, as described in the next subsection. Figure 3-1.
PAGE 45
Running H/F 2 Running H/F 1 Initiator Data Flow An FTAM application can send FTAM requests and responses and receive confirms and indications, as outlined later in this section. This subsection specifically describes the flow of an FTAM request from the NonStop FTAM application to the responding system, and the flow of the remote responder’s response back to the NonStop FTAM application in the form of a confirm. The sequence of steps below assumes that you have already established an association.
PAGE 46
Running H/F 2 Running H/F 1 TSP, and NSP processes, see the OSI/AS Configuration and Management Manual. For information about establishing an association and the FTAM programming concepts that facilitate the flow of data between the FTAM application and the responding system, see the OSI/FTAM Programming Guide.
PAGE 47
Running H/F 2 Running H/F 1 How FTM Procedures Are Categorized FTM procedures are categorized according to the four types of FTAM primitives: request, indication, response, and confirm. FTM procedures typically send primitives that operate in request-indication and response-confirm pairs. The initiator typically generates requests locally, and a remote FTAM responder receives them as indications. The responder typically generates responses that the initiator receives as confirms.
PAGE 48
Running H/F 2 Running H/F 1 Response Procedures Response procedures have names in the form FTM_xxx_RSP_, where xxx refers to the specific FTAM primitive. While the responder is the sender of most responses to the initiator (in response to initiator requests), the initiator can also send a cancel response after receiving a cancel indication from the responder.
PAGE 49
Running H/F 2 Running H/F 1 Table 3-1.
PAGE 50
Running H/F 2 Running H/F 1 Table 3-1.
PAGE 51
Running H/F 2 Running H/F 1 Supported Functions The NonStop FTAM API provides parameters and defined values to allow your program to request the supported functions outlined in the following subsections. If you request an unsupported function in your application, the initiator returns an error. The functional scope of your FTAM application depends on which FTAM functions are supported both by the NonStop FTAM initiator and the remote responder with which the local initiator is interoperating.
PAGE 52
Running H/F 2 Running H/F 1 Attribute Groups Table 3-4. Attribute Groups Supported by the NonStop FTAM Initiator Attribute Group Initiator Support Kernel X Storage X Security X Private Attributes Table 3-5 identifies the attributes that the initiator supports. The table is organized according to the class of attribute (activity or file) and the supported attribute groups described above. Activity attributes pertain only to activity during an ISO FTAM association.
PAGE 53
Running H/F 2 Running H/F 1 The initiator does not support the current concurrency control or current locking style or the file attributes identity-of-last modifier and identity-of-last-reader activity attributes. Also, because NonStop FTAM does not support the private attribute group, the privateuse attribute of that group is not supported and is not reflected in the above table.
PAGE 54
Running H/F 2 Running H/F 1 HP NonStop OSI/FTAM Programming Reference Manual—528611-001 3- 12
PAGE 55
4 FTM Procedures This section provides detailed reference material for each FTM procedure. It includes the following topics: Topic Page Files Provided by HP 4-1 Procedure Names 4-2 Procedure Calls and Parameters 4-2 FTAM Protocol Dependencies 4-7 Procedure Call Descriptions 4-9 Files Provided by HP The external declarations for the current version of the FTM, APS, and MFM procedures are provided in the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL declarations) and $SYSTEM.SYSTEM.
PAGE 56
Procedure Names FTM Procedures Procedure Names The names of all NonStop FTAM procedures start with the characters “FTM_.” The FTM procedures fall into four major categories, identified by the last few characters in the procedure name: • • • • REQ procedures enable you to make requests to the service provider. An example is FTM_INITIALIZE_REQ_, which requests initiation of an association with an FTAM responder.
PAGE 57
Procedure Calls and Parameters FTM Procedures and diagnostic) provide information critical to understanding the outcome of a particular operation, and HP recommends that you allocate runtime data space for these output parameters. For conditional input parameters, your application must provide values only if a specific condition is met. Table 4-1.
PAGE 58
Procedure Calls and Parameters FTM Procedures Table 4-1.
PAGE 59
Procedure Calls and Parameters FTM Procedures Table 4-1.
PAGE 60
Procedure Calls and Parameters FTM Procedures Table 4-1.
PAGE 61
FTAM Protocol Dependencies FTM Procedures Table 4-1.
PAGE 62
FTAM Protocol Dependencies FTM Procedures Table 4-2.
PAGE 63
Procedure Call Descriptions FTM Procedures Table 4-2. FTM Procedure Regime Dependencies (page 3 of 3) Regime Requirement Procedure FTM_END_GROUP_REQ_ * FTM_P_ABORT_IND_ ** FTM_U_ABORT_IND_ ** FTM_U_ABORT_REQ_ ** * Must be in the FTAM, file-selection, or file-open regime. In addition, there are further constraints based on grouping. See the OSI/FTAM Programming Guide. ** Valid in any regime.
PAGE 64
Procedure Call Descriptions FTM Procedures Figure 4-1. Sample FTM Procedure Call Description 1 FTM_BEGIN_GROUP_REQ_ 2 This procedure allows you to request the start of a group of FTM procedures, which are then processed and responded to as a group. 3 4 5 status := FTM_BEGIN_GROUP_REQ_ ( cepi , threshold , [ tag ] ); 6 !I !I !I status return value INT indicates the outcome of the call . . . 7 cepi 8 input INT:value 9 is the connection endpoint identifier (CEPI) . . . ... 10 Considerations ...
PAGE 65
Procedure Call Descriptions FTM Procedures 5 You must enclose the list of parameters in parentheses. Use commas to separate multiple parameters. In the notation, optional parameters are enclosed in square brackets ( [ and ] ); these brackets must not appear in the program. If you omit optional parameters, a placeholder comma ( , ) must be present for each omitted parameter, except for parameters omitted from the end of the list. 6 The exclamation point indicates that a comment follows.
PAGE 66
FTM Procedures Procedure Call Descriptions 10 Considerations for using the procedure, including what to do in the case of specific abnormalities, are presented in this subsection. 11 FTAM initiator errors related to this procedure call are listed in a table in this subsection. Any of these or other errors with particular significance for the procedure call are described after the table.
PAGE 67
FTM_BEGIN_GROUP_REQ_ FTM Procedures FTM_BEGIN_GROUP_REQ_ This procedure allows you to request the start of a group of FTM procedures, which are then processed and responded to as a group. status := FTM_BEGIN_GROUP_REQ_ ( cepi , threshold , [ tag ] ); status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx status values, see Table B-1 on page B-2.
PAGE 68
FTM_BEGIN_GROUP_REQ_ FTM Procedures threshold is a required parameter. For additional information on setting the threshold value, see the OSI/FTAM Programming Guide. tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag parameter value, allowing your application to match the completion with the correct instance of the procedure call.
PAGE 69
FTM_BEGIN_GROUP_REQ_ FTM Procedures For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages. The following table lists common errors that can occur on the FTM_BEGIN_GROUP_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in a state in which a grouped request is allowed.
PAGE 70
FTM_CANCEL_REQ_ FTM Procedures FTM_CANCEL_REQ_ This procedure allows you to request cancellation of the data-transfer regime. If cancellation is successful, the results of any interrupted read or write operations are unknown and the data-transfer regime ends. The association moves to the file-open regime upon successful completion of the cancellation request. For a description of these regimes, see the OSI/FTAM Programming Guide.
PAGE 71
FTM_CANCEL_REQ_ FTM Procedures FTAM Diagnostic Messages. For more information on application-generated diagnostic messages, see the OSI/FTAM Programming Guide. diagnostic is an optional parameter. tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call.
PAGE 72
FTM_CANCEL_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_CANCEL_REQ_ procedure call. These error values... Error Code: Error Subcode: are returned if.... ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the datatransfer regime. Examples Examples of the FTM_CANCEL_REQ_ call in a program begin on line 1231 of the C version and line 1324 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 73
FTM_CANCEL_CNF_ FTM Procedures FTM_CANCEL_CNF_ This procedure allows you to retrieve the responder’s response to your FTM_CANCEL_REQ_ procedure call to cancel the data-transfer regime. For a description of the data-transfer regime, see the OSI/FTAM Programming Guide. error := FTM_CANCEL_CNF_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 74
FTM_CANCEL_CNF_ FTM Procedures diagnostic output INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC) provides information that qualifies the success or explains the failure of a requested action. For a complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic Messages. diagnostic is an optional parameter. Considerations • • To complete this procedure call successfully, the association must be in the data-transfer regime.
PAGE 75
FTM_CANCEL_IND_ FTM Procedures FTM_CANCEL_IND_ This procedure allows you to retrieve indication information on a responder request to cancel the data-transfer regime. The association is returned to the file-open regime. For a description of these regimes, see the OSI/FTAM Programming Guide. error := FTM_CANCEL_IND_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call.
PAGE 76
FTM_CANCEL_IND_ FTM Procedures diagnostic is an optional parameter. Considerations • • • To complete this procedure call successfully, the association must be in the data-transfer regime. You must call APS_EVENT_RECEIVE_ to receive the indication event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper indication procedure to use to retrieve the data. You must receive the ZFTM-VAL-EVT-CANCEL-IND event before calling FTM_CANCEL_IND_.
PAGE 77
FTM_CANCEL_RSP_ FTM Procedures FTM_CANCEL_RSP_ This procedure allows you to communicate the results of actions taken in response to the responder’s request to cancel the data-transfer regime. For a description of the data-transfer regime, see the OSI/FTAM Programming Guide. status := FTM_CANCEL_RSP_ ( , , , cepi [ action-result ] [ diagnostic ] [ tag ] ); status ! ! ! ! I I I I return value INT indicates the outcome of the call.
PAGE 78
FTM_CANCEL_RSP_ FTM Procedures diagnostic is an optional parameter. tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter.
PAGE 79
FTM_CANCEL_RSP_ FTM Procedures Table 4-7. Possible FTAM Initiator Errors for the FTM_CANCEL_RSP_ Procedure (page 2 of 2) Error Code FTAM Initiator Error - 6012 ZFTM-ERR-SERV-NOT-NEGOTIATED - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6019 ZFTM-ERR-BAD-APS-STATUS - 6022 ZFTM-ERR-CONNECTION-ABORTED - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 80
FTM_CHANGE_ATTRIB_REQ_ FTM Procedures FTM_CHANGE_ATTRIB_REQ_ This procedure allows you to request changes to the file attributes of the file previously selected. status := FTM_CHANGE_ATTRIB_REQ_ ( cepi , change-attrib , [ tag ] ) ; status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2. cepi input INT:value is the connection endpoint identifier (CEPI) used to identify the specific association.
PAGE 81
FTM_CHANGE_ATTRIB_REQ_ FTM Procedures • • • To complete this procedure call successfully, the association must be in the file-selection regime. For the remote responder to respond affirmatively to the change-attribute primitive, the change-attribute field of the permitted-actions attribute of this file must be set to ON. You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. Errors Table 4-8.
PAGE 82
FTM_CHANGE_ATTRIB_REQ_ FTM Procedures . These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-selection regime. Error Code: Error Subcode: ZFTM-ERR-FU-NOT-NEGOTIATED (-6002) ZFTM-ERR-FU-ENHANCED-MGMT (-5) The enhanced-filemanagement functional unit must be negotiated for this procedure call to be valid.
PAGE 83
FTM_CHANGE_ATTRIB_CNF_ FTM Procedures FTM_CHANGE_ATTRIB_CNF_ This procedure allows you to retrieve the remote responder’s response to the application’s request to change file attributes of the previously selected file. error := FTM_CHANGE_ATTRIB_CNF_ ( , , , error cepi [ action-result ] [ change-attrib ] [ diagnostic ] ) ; ! ! ! ! I O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 84
FTM_CHANGE_ATTRIB_CNF_ FTM Procedures shortens any attribute value that exceeds these limits. Therefore, when the responder returns a value for an access-control password that is greater than 32 characters, the initiator passes only the first 32 characters to the application, or in the case of a filename attribute, when the value is greater than 128, the initiator passes only the first 128 characters to the application. change-attrib is an optional parameter. diagnostic output INT .
PAGE 85
FTM_CHANGE_ATTRIB_CNF_ FTM Procedures Examples Examples of the FTM_CHANGE_ATTRIB_CNF_ call in a program begin on line 1384 of the C version and line 1472 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 86
FTM_CLOSE_REQ_ FTM Procedures FTM_CLOSE_REQ_ This procedure allows you to request closure of the previously opened file. It also terminates the file-open regime. Successful completion of the close request moves the association to the file-selection regime. For a description of these regimes, see the OSI/FTAM Programming Guide. status := FTM_CLOSE_REQ_ ( cepi , [ tag ] ) ; status ! I ! I return value INT indicates the outcome of the call.
PAGE 87
FTM_CLOSE_REQ_ FTM Procedures Errors Table 4-10. Possible FTAM Initiator Errors for the FTM_CLOSE_REQ_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6001 ZFTM-ERR-OUT-OF-SEQUENCE - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6019 ZFTM-ERR-BAD-APS-STATUS - 6022 ZFTM-ERR-CONNECTION-ABORTED - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 88
FTM_CLOSE_CNF_ FTM Procedures FTM_CLOSE_CNF_ This procedure allows you to retrieve the remote responder’s response to the application’s request to close the previously opened file. error := FTM_CLOSE_CNF_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 89
FTM_CLOSE_CNF_ FTM Procedures diagnostic is an optional parameter. Considerations • • To complete this procedure call successfully, the association must be in the fileopen regime. Before calling FTM_CLOSE_CNF_, you must call the following procedures: FTM_CLOSE_REQ_ APS_EVENT_RECEIVE_ APS_STATUS_ You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data.
PAGE 90
FTM_CREATE_REQ_ FTM Procedures FTM_CREATE_REQ_ This procedure allows you to request creation and selection of a file in the file storage system with which an association has been established. Successful completion of this procedure initiates the file-selection regime. For a description of the file-selection regime, see the OSI/FTAM Programming Guide.
PAGE 91
FTM_CREATE_REQ_ FTM Procedures Value Name and Code If file does not exist... If file exists... ZFTM-VAL-OVR-CREATE-FAIL (0) New file is created. Call fails. ZFTM-VAL-OVR-SELECT-OLD (1) New file is created. File is selected (the F-CREATE primitive is not called). ZFTM-VAL-OVR-CREATE-OLD (2) New file is created. File is deleted, and a new file having the same file attributes as the old file is created. ZFTM-VAL-OVR-CREATE-NEW (3) New file is created.
PAGE 92
FTM_CREATE_REQ_ FTM Procedures ZEXTEND Extend the file. FALSE ZERASE Erase some or all the contents of the file. FALSE ZREADATTR Read the attributes of the file. TRUE ZCHNGATTR Change the attributes of the file. FALSE ZDELETE Delete the file. FALSE requested-access is an optional parameter. access-passwords input INT .EXT:ref:(ZFTM-DDL-ACCESS-PASSWDS) authenticates the actions requested in the requested-access parameter.
PAGE 93
FTM_CREATE_REQ_ FTM Procedures • • You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. For any file attribute the remote responder requires and you do not specify in the initial-attrib parameter, the responder will supply a value that is appropriate for its file storage system. Errors Table 4-12.
PAGE 94
FTM_CREATE_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_CREATE_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the FTAM regime. Error Code: Error Subcode: ZFTM-ERR-FU-NOT-NEGOTIATED (-6002) ZFTM-ERR-FU-LMTD-MGMT (-5) The limited-filemanagement functional unit must be negotiated for this procedure call to be valid.
PAGE 95
FTM_CREATE_CNF_ FTM Procedures FTM_CREATE_CNF_ This procedure allows you to retrieve the remote responder’s response to the initiator request to create and select a file in a file storage system with which an association has been established. error := FTM_CREATE_CNF_ ( , , , , cepi [ state-result ] [ action-result ] [ initial-attrib ] [ diagnostic ] ) ; error ! ! ! ! ! I O O O O return value INT indicates the outcome of the call.
PAGE 96
FTM_CREATE_CNF_ FTM Procedures A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was successful. Even for a successful operation, the diagnostic parameter might include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is likely to contain one or more diagnostic messages. action-result is an optional parameter. initial-attrib output INT .
PAGE 97
FTM_CREATE_CNF_ FTM Procedures You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data. You must receive the ZFTM-VAL-EVT-CREATE-CNF event before calling FTM_CREATE_CNF_. • • • Initial attributes can vary from those requested. The responder might not fully support all the attributes requested.
PAGE 98
FTM_DATA_END_REQ_ FTM Procedures FTM_DATA_END_REQ_ This procedure allows you to request an end to a block data transfer initiated by the FTM_WRITE_REQ_ procedure. status := FTM_DATA_END_REQ_ ( , , , cepi [ action-result ] [ diagnostic ] [ tag ] ) ; status ! ! ! ! I I I I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 99
FTM_DATA_END_REQ_ FTM Procedures tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter.
PAGE 100
FTM_DATA_END_REQ_ FTM Procedures Examples Examples of the FTM_DATA_END_REQ_ call in a program begin on line 1293 of the C version and line 1404 of the TAL version of Example 1, and on line 1204 of the C version and line 1293 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 101
FTM_DATA_END_IND_ FTM Procedures FTM_DATA_END_IND_ This procedure allows you to retrieve information on a responder request to end a block data transfer initiated by the FTM_READ_REQ_ procedure. error := FTM_DATA_END_IND_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 102
FTM_DATA_END_IND_ FTM Procedures diagnostic is an optional parameter. Considerations • • • • To complete this procedure call successfully, the association must be in the datatransfer regime. You must call APS_EVENT_RECEIVE_ to receive the indication event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper indication procedure to use to retrieve the data. You must receive the ZFTM-VAL-EVT-DATAEND-IND event before calling FTM_DATA_END_IND_.
PAGE 103
FTM_DATA_REQ_ FTM Procedures FTM_DATA_REQ_ This procedure allows you to transfer, or write, a block of data to a previously opened file. The FTM_WRITE_REQ_ procedure must have been called to start the write transfer before this procedure is called. status := FTM_DATA_REQ_ ( cepi , data-value , [ tag ] ) ; status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 104
FTM_DATA_REQ_ FTM Procedures Considerations • • • • To complete this procedure call successfully, the association must be in the data-transfer regime. You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. The encoded PDU is limited to 16 KB. For more information on calculating the size of the encoded PDU, see the OSI/FTAM Programming Guide.
PAGE 105
FTM_DATA_REQ_ FTM Procedures values for the data element types (ZAPS-DDL-DATA-ELEMENT-HDR.ZTYPE) are listed below with descriptions of their structures: • ZFTM-VAL-DE-FADU (ZFTM-DDL-DE-FADU) Only FTAM-2 document types in the FA access context use this data element. It is used to represent a structuring data element, which can be either a node descriptor data element, an enter subtree data element, or an exit subtree data element. Node descriptor data element is the only type used.
PAGE 106
FTM_DATA_REQ_ FTM Procedures Errors Table 4-16.
PAGE 107
FTM_DATA_IND_ FTM Procedures FTM_DATA_IND_ This procedure allows you to receive, or read, a block of data from the previously opened file involved in a data transfer. error := FTM_DATA_IND_ ( , , , , , cepi buffer-size data-value [ more-data ] [ next-position ] [ start-position ] ) ; error return ! ! ! ! ! ! I I O O O I value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 108
FTM_DATA_IND_ FTM Procedures For further details on the structure of data-value, see the OSI/FTAM Programming Guide. data-value is a required parameter. more-data output INT(32) .EXT:ref:1 indicates that more data is available. The application should call FTM_DATA_IND_ again to obtain the remaining data. more-data specifies the size in bytes of the remaining data including all necessary headers.
PAGE 109
FTM_DATA_IND_ FTM Procedures Considerations • • • To complete this procedure call successfully, you must have previously called the FTM_READ_REQ_, and the association must be in the data-transfer regime. You must call APS_EVENT_RECEIVE_ to receive the indication event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper indication procedure to use to retrieve the data.
PAGE 110
FTM_DATA_IND_ FTM Procedures The structure of individual data elements specified in the data-value parameter varies, depending on the contents type of the file being transferred. The valid values for the data element types (ZAPS-DDL-DATA-ELEMENT-HDR.ZTYPE) are listed below with descriptions of their structures: ° ZFTM-VAL-DE-FADU (ZFTM-DDL-DE-FADU) This data element is used only by FTAM-2 document types in the FA access context.
PAGE 111
FTM_DATA_IND_ FTM Procedures The following table lists the common errors that can occur on the FTM_DATA_IND_ procedure call. These error values... Error Code: Error Subcode: are returned if.... ZFTM-ERR-DATA-VALUE-TOO-SMALL (-6037) Minimum number of bytes to retrieve at least one data element and its associated header information The buffer-size parameter is too small to contain the data header, data element header, and current data element.
PAGE 112
FTM_DELETE_REQ_ FTM Procedures FTM_DELETE_REQ_ This procedure allows you to request deletion of the currently selected file. The remote responder’s successful response to this request primitive terminates the file-selection regime and moves the association to the FTAM regime. For a description of these regimes, see the OSI/FTAM Programming Guide. status := FTM_DELETE_REQ_ ( cepi , [ tag ] ) ; status ! I ! I return value INT indicates the outcome of the call.
PAGE 113
FTM_DELETE_REQ_ FTM Procedures • You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. Errors Table 4-18.
PAGE 114
FTM_DELETE_CNF_ FTM Procedures FTM_DELETE_CNF_ This procedure allows you to retrieve the responder’s response to the application’s request to delete the currently selected file. error := FTM_DELETE_CNF_ ( , , , cepi [ action-result ] [ charging ] [ diagnostic ] ) ; error ! ! ! ! I O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 115
FTM_DELETE_CNF_ FTM Procedures conveys information on the costs attributed to the account during the regime being released. The charging parameter is present only if you provided the account parameter on the FTM_INITIALIZE_REQ_ call. charging is a list of triples, each of which contains a resource identifier, a charging unit, and a charge value.
PAGE 116
FTM_DELETE_CNF_ FTM Procedures For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages. Examples Examples of the FTM_DELETE_CNF_ call in a program begin on line 1474 of the C version and line 1562 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 117
FTM_DESELECT_REQ_ FTM Procedures FTM_DESELECT_REQ_ This procedure allows you to request an end to access to the file that was previously selected. Successful completion of this procedure terminates the file-selection regime and moves the association to the FTAM regime. For a description of these regimes, see the OSI/FTAM Programming Guide. status := FTM_DESELECT_REQ_ ( cepi , [ tag ] ) ; status ! I ! I return value INT indicates the outcome of the call.
PAGE 118
FTM_DESELECT_REQ_ FTM Procedures Errors Table 4-20. Possible FTAM Initiator Errors for the FTM_DESELECT_REQ_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6001 ZFTM-ERR-OUT-OF-SEQUENCE - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6019 ZFTM-ERR-BAD-APS-STATUS - 6022 ZFTM-ERR-CONNECTION-ABORTED - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 119
FTM_DESELECT_CNF_ FTM Procedures FTM_DESELECT_CNF_ This procedure allows you to retrieve the responder’s response to the application’s request to end access to the file that was previously selected. error := FTM_DESELECT_CNF_ ( , , , cepi [ action-result ] [ charging ] [ diagnostic ] ) ; error ! ! ! ! I O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 120
FTM_DESELECT_CNF_ FTM Procedures conveys information on the costs attributed to the account in the regime being released. The charging parameter is present only if you provided the account parameter on the FTM_SELECT_REQ_ call. charging is a list of triples, each of which contains a resource identifier, a charging unit, and a charge value.
PAGE 121
FTM_DESELECT_CNF_ FTM Procedures Errors Table 4-21. Possible FTAM Initiator Errors for the FTM_DESELECT_CNF_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 122
FTM_END_GROUP_REQ_ FTM Procedures FTM_END_GROUP_REQ_ This procedure allows you to signify the end of a group of FTAM requests. error := FTM_END_GROUP_REQ_ ( cepi , [ tag ] ) ; error ! I ! I return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages. cepi input INT:value is the connection endpoint identifier (CEPI) used to identify the specific association.
PAGE 123
FTM_END_GROUP_REQ_ FTM Procedures Errors Table 4-22. Possible FTAM Initiator Errors for the FTM_END_GROUP_REQ_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6001 ZFTM-ERR-OUT-OF-SEQUENCE - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6019 ZFTM-ERR-BAD-APS-STATUS - 6022 ZFTM-ERR-CONNECTION-ABORTED - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 124
FTM_ERASE_REQ_ FTM Procedures FTM_ERASE_REQ_ This procedure allows you to request erasure of the contents of the specified file-access data unit (FADU) in the previously selected and opened file. status := FTM_ERASE_REQ_ ( cepi , fadu-id , [ tag ] ) ; status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 125
FTM_ERASE_REQ_ FTM Procedures tag is an optional parameter. Considerations • • • • Before using this procedure, you must have negotiated the file-access functional unit and file-access service class on the FTM_INITIALIZE_REQ_ call. To complete this procedure call successfully, the association must be in the fileopen regime, and you must have set the ZERASE field of the process-mode parameter (ZFTM-DDL-PROC-MODE) of the open request to ON.
PAGE 126
FTM_ERASE_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_ERASE_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-open regime. Error Code: ZFTM-ERR-FADU-ID-INVALID (-6006) The FADU ID is inconsistent with the document type requested when the file was opened.
PAGE 127
FTM_ERASE_REQ_ FTM Procedures Example The following TAL program illustrates the use of the FTM_ERASE_REQ_ procedure call: 1. !-----------------------------------------------------------------------! 2. ! This example demonstrates how to erase the contents of an FTAM-2 ! 3. ! file. It assumes that the file has already been selected and ! 4. ! opened. ! 5. ! ! 6. ! This example abends on all error conditions. Additional application- ! 7.
PAGE 128
FTM_ERASE_REQ_ FTM Procedures 37. END; 38. !----------------------------------------------------------------------! 39. ! Call APS_EVENT_RECEIVE_ to receive the confirm for the erase service.! 40. !----------------------------------------------------------------------! 41. status := APS_EVENT_RECEIVE_ ( cepi, WAIT_FOREVER ); 42. IF ( status <> ZAPS^VAL^STATUS^EVENT ) THEN 43. BEGIN 44. CALL ABEND; 45. END; 46. !----------------------------------------------------------------------! 47.
PAGE 129
FTM_ERASE_CNF_ FTM Procedures FTM_ERASE_CNF_ This procedure allows you to retrieve the responder’s response to the application’s request to erase the specified FADU of the previously selected and opened file. error := FTM_ERASE_CNF_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 130
FTM_ERASE_CNF_ FTM Procedures diagnostic is an optional parameter. Considerations • • To successfully complete this procedure call, the association must be in the file-open regime. Before calling FTM_ERASE_CNF_, you must call the following procedures: FTM_ERASE_REQ_ APS_EVENT_RECEIVE_ APS_STATUS_ You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data.
PAGE 131
FTM_FILE_CLOSE_REQ_ FTM Procedures FTM_FILE_CLOSE_REQ_ This grouped procedure issues the primitives F-BEGIN-GROUP, F-CLOSE, either F-DESELECT or F-DELETE, and F-END-GROUP, allowing you to close and either deselect or delete a file in a single call. Successful completion of this procedure terminates the file-open and file-selection regimes and moves the association to the FTAM regime. For a description of these regimes, see the OSI/FTAM Programming Guide.
PAGE 132
FTM_FILE_CLOSE_REQ_ FTM Procedures with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter. Considerations • • • • • • Before calling FTM_FILE_CLOSE_REQ_, you must have negotiated a service class other than the file-management service class via the FTM_INITIALIZE_REQ_ call. You must also have negotiated the grouping functional unit and the read or write functional unit.
PAGE 133
FTM_FILE_CLOSE_REQ_ FTM Procedures Errors Table 4-25.
PAGE 134
FTM_FILE_CLOSE_CNF_ FTM Procedures FTM_FILE_CLOSE_CNF_ This procedure allows you to retrieve the remote responder’s response to the application’s request to close and either deselect or delete a file. error := FTM_FILE_CLOSE_CNF_ ( , , , cepi [ action-result ] [ charging ] [ diagnostic ] ) ; error ! ! ! ! I O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 135
FTM_FILE_CLOSE_CNF_ FTM Procedures conveys information on the costs attributed to the account in the regime being released. The charging parameter is present only if you provided the account parameter on the FTM_INITIALIZE_REQ_ call. charging is a list of triples, each of which contains a resource identifier, a charging unit, and a charge value.
PAGE 136
FTM_FILE_CLOSE_CNF_ FTM Procedures Errors Table 4-26. Possible FTAM Initiator Errors for the FTM_FILE_CLOSE_CNF_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 137
FTM_FILE_OPEN_REQ_ FTM Procedures FTM_FILE_OPEN_REQ_ This grouped procedure issues the primitives F-BEGIN-GROUP, F-SELECT or F-CREATE, F-OPEN, and F-END-GROUP, allowing you to select or create a file and then open it in a single procedure call. Successful completion of this procedure initiates the file-selection and file-open regimes and leaves the association in the file-open regime. For a description of these regimes, see the OSI/FTAM Programming Guide.
PAGE 138
FTM_FILE_OPEN_REQ_ FTM Procedures values except for ZFTM-VAL-FOPEN-OLD is the same as those defined for the override parameter of the create request. This table lists the valid values for this parameter and the corresponding actions taken. Value Name and Code If File Does Not Exist... If File Exists... ZFTM-VAL-FOPEN-NEW (0) New file is created. Call fails. ZFTM-VAL-FOPEN-UNKNOWN (1) File is created using the file attributes specified in the initial-attrib parameter. File is selected.
PAGE 139
FTM_FILE_OPEN_REQ_ FTM Procedures if the access passwords for the requested actions do not match the responder’s access passwords. access-passwords is an optional parameter. If you do not supply access-passwords, no passwords will be sent to the remote responder. initial-attrib input INT .EXT:ref:(ZFTM-DDL-CREATE-ATTR-GRP) defines the file attributes associated with the created file.
PAGE 140
FTM_FILE_OPEN_REQ_ FTM Procedures process-mode is an optional parameter. contents-type input INT .EXT:ref:(ZFTM-DDL-CNTNTS-TYPE) allows you to specify the abstract data type of the contents of the file, including the structuring information. The contents-type parameter must either match the contents type of the file being opened or be an allowed simplification of the document type. contents-type is an optional parameter.
PAGE 141
FTM_FILE_OPEN_REQ_ FTM Procedures is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter.
PAGE 142
FTM_FILE_OPEN_REQ_ FTM Procedures Errors Table 4-27.
PAGE 143
FTM_FILE_OPEN_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_FILE_OPEN_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the FTAM regime.
PAGE 144
FTM_FILE_OPEN_CNF_ FTM Procedures FTM_FILE_OPEN_CNF_ This procedure allows you to retrieve the remote responder’s response to the application’s request to select and open a file or optionally create and open a file. error := FTM_FILE_OPEN_CNF_ ( , , , , , , cepi [ state-result ] [ action-result ] [ filename ] [ initial-attrib ] [ contents-type ] [ diagnostic ] ) ; error ! ! ! ! ! ! ! I O O O O O O return value INT indicates the outcome of the call.
PAGE 145
FTM_FILE_OPEN_CNF_ FTM Procedures A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was successful. Even for a successful operation, the diagnostic parameter might include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is likely to contain one or more diagnostic messages. action-result is an optional parameter. filename output INT .
PAGE 146
FTM_FILE_OPEN_CNF_ FTM Procedures contents-type is an optional parameter. diagnostic output INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC) provides information that qualifies the success or explains the failure of a requested action. For a complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic Messages. The initiator can also return the informative diagnostic message ZFTM-DIAGCNTNTS-TYPE-SIMPLE (5037) on this call.
PAGE 147
FTM_INITIALIZE_REQ_ FTM Procedures FTM_INITIALIZE_REQ_ This procedure allows you to request initiation of an association with an FTAM responder. Successful completion of this procedure initializes the FTAM regime. For a description of the FTAM regime, see the OSI/FTAM Programming Guide.
PAGE 148
FTM_INITIALIZE_REQ_ FTM Procedures remote-appl input INT .EXT:ref:(ZAPS-DDL-APPL-ADDR) specifies the common name and/or OSI address of the called FTAM responder. remote-appl is a required parameter. wait-mode input INT:value sets the operating mode (wait mode or nowait mode) for the lifetime of the association. Valid values are as follows: ZAPS-VAL-WAITED ZAPS-VAL-NOWAITED The default mode is ZAPS-VAL-WAITED. wait-mode is an optional parameter. local-appl input INT .
PAGE 149
FTM_INITIALIZE_REQ_ FTM Procedures specifies the application entity (AE) title of the responding application entity. The AE title consists of an application process title and an AE qualifier. remote-ae-title is an optional parameter. If you omit remote-ae-title, the remote application entity title will be as specified in NIST, Stable Implementation Agreements for Open Systems Interconnection Protocols, Section 5.11.1.1.
PAGE 150
FTM_INITIALIZE_REQ_ FTM Procedures Note. The requested functional units must include all mandatory functional units for the service classes requested.
PAGE 151
FTM_INITIALIZE_REQ_ FTM Procedures initiator-id input INT .EXT:ref:(ZAPS-DDL-CHAR32) identifies the calling application to the responding application entity. initiator-id is an optional parameter. If you omit initiator-id, no initiator identity will be specified. Some responders require an initiator ID. For information on responder requirements for the initiator ID, refer to the responder documentation. account input INT .
PAGE 152
FTM_INITIALIZE_REQ_ FTM Procedures extended segment that the FTAM API uses to maintain the context information for all the FTAM associations your application establishes. • • • • • You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. The local-appl and remote-appl parameters each consist of the common name (OSI/AS application name) and the corresponding OSI address.
PAGE 153
FTM_INITIALIZE_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_INITIALIZE_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: Orig. Error Code: Orig. Subcode: ZFTM-ERR-BAD-APS-STATUS (-6019) 0 ZAPS-ERR-MGR-ERR (-126) ZAPS-ERR-MGR-LOCAL-NAME (101) The local application name is not configured in OSI/AS. Error Code: Error Subcode: Orig. Error Code: Orig.
PAGE 154
FTM_INITIALIZE_REQ_ FTM Procedures These error values... are returned if.... Error Code: Error Subcode: ZAPS-ERR-MGR-ERR (-126) -10 The NonStop FTAM initiator has been overloaded momentarily with ADD SU requests from the APLMGR process. The APLMGR process can handle only 16 outstanding register requests from the FTAM API at one time, but will continue processing until all associations are established.
PAGE 155
FTM_INITIALIZE_CNF_ FTM Procedures FTM_INITIALIZE_CNF_ This procedure allows you to retrieve remote responder’s response to the application’s request to establish an association with a remote responder.
PAGE 156
FTM_INITIALIZE_CNF_ FTM Procedures ZFTM-VAL-ACTION-SUCCESS ZFTM-VAL-ACTION-FAILURE A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was successful. Even for a successful operation, the diagnostic parameter might include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and the diagnostic parameter is likely to contain one or more diagnostic messages. action-result is an optional parameter. local-appl output INT .
PAGE 157
FTM_INITIALIZE_CNF_ FTM Procedures func-units output INT .EXT:ref:(ZFTM-DDL-FUNC-UNITS) returns the file service functional units requested by the initiator and negotiated by the remote responder. The negotiation process defines the functional units for the association. For a detailed explanation of functional units, see the OSI/FTAM Programming Guide. func-units is an optional parameter. attrib-groups output INT .
PAGE 158
FTM_INITIALIZE_CNF_ FTM Procedures Considerations • Before calling FTM_INITIALIZE_CNF_, you must call the following procedures: FTM_INITIALIZE_REQ_ APS_EVENT_RECEIVE_ APS_STATUS_ You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-INITIALIZE-CNF event before calling FTM_INITIALIZE_CNF_.
PAGE 159
FTM_INITIALIZE_CNF_ FTM Procedures Examples Examples of the FTM_INITIALIZE_CNF_ call in a program begin on line 893 of the C version and line 852 of the TAL version of Example 1, and on line 462 of the C version and line 556 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 160
FTM_LOCATE_REQ_ FTM Procedures FTM_LOCATE_REQ_ This procedure allows you to move a location pointer to a specified place in the previously opened file. The location pointer is used in read and write operations. status := FTM_LOCATE_REQ_ ( cepi , fadu-id , [ tag ] ) ; status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 161
FTM_LOCATE_REQ_ FTM Procedures tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter.
PAGE 162
FTM_LOCATE_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_LOCATE_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-open regime. Error Code: ZFTM-ERR-FADU-ID-INVALID (-6006) The FADU ID is inconsistent with the document type requested when the file was opened.
PAGE 163
FTM_LOCATE_REQ_ FTM Procedures Example The following TAL program illustrates the use of the FTM_LOCATE_REQ_ procedure call: 1. !-----------------------------------------------------------------------! 2. ! This example demonstrates how to locate a record of an FTAM-2 file. ! 3. ! It assumes that the file has already been selected and opened. ! 4. ! ! 5. ! This example abends on all error conditions. Additional application- ! 6. ! specific error handling or recovery could be implemented if ! 7.
PAGE 164
FTM_LOCATE_REQ_ FTM Procedures 37. IF ( status <> ZAPS-VAL-STATUS-EVENT ) THEN 38. BEGIN 39. CALL ABEND; 40. END; 41. !----------------------------------------------------------------------! 42. ! Call APS_STATUS_ to determine what event has been received. Verify ! 43. ! that the event is the locate confirm. ! 44. !----------------------------------------------------------------------! 45. error := APS_STATUS_ ( cepi, event_code ); 46. IF ( error <> ZAPS-ERR-OK ) OR 47.
PAGE 165
FTM_LOCATE_CNF_ FTM Procedures FTM_LOCATE_CNF_ This procedure allows you to retrieve the responder’s response to the application’s request to move the pointer to a specified location in the previously opened file. The location pointer is used in read and write operations. error := FTM_LOCATE_CNF_ ( cepi , [ action-result ] , [ fadu-id ] , [ diagnostic ] ) ; error ! ! ! ! I O O O return value INT indicates the outcome of the call.
PAGE 166
FTM_LOCATE_CNF_ FTM Procedures returns the FADU identity. For a full explanation of this parameter and its usage, see the OSI/FTAM Programming Guide. fadu-id is an optional parameter. diagnostic output INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC) provides information that qualifies the success or explains the failure of a requested action. For a complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic Messages. diagnostic is an optional parameter.
PAGE 167
FTM_OPEN_REQ_ FTM Procedures FTM_OPEN_REQ_ This procedure allows you to make the contents of the previously selected file available for access. This procedure initiates the file-open regime. For a description of the file-open regime, see the OSI/FTAM Programming Guide. status := FTM_OPEN_REQ_ ( cepi , [ process-mode ] , [ contents-type ] , [ tag ] ) ; status ! ! ! ! I I I I return value INT indicates the outcome of the call.
PAGE 168
FTM_OPEN_REQ_ FTM Procedures maximum-string-length). All the three are optional parameters; however, when you specify a value for maximum-string-length, it should be in the range of 1 through 7148. For a full description of contents-type and its usage, see the OSI/FTAM Programming Guide.
PAGE 169
FTM_OPEN_REQ_ FTM Procedures Errors Table 4-33.
PAGE 170
FTM_OPEN_REQ_ FTM Procedures Examples Examples of the FTM_OPEN_REQ_ call in a program begin on line 819 of the C version and line 917 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 171
FTM_OPEN_CNF_ FTM Procedures FTM_OPEN_CNF_ This procedure allows you to retrieve the remote responder’s response to the application’s request to open the previously selected file. error := FTM_OPEN_CNF_ ( , , , , cepi [ state-result ] [ action-result ] [ contents-type ] [ diagnostic ] ) ; error ! ! ! ! ! I O O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 172
FTM_OPEN_CNF_ FTM Procedures include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is likely to contain one or more diagnostic messages. action-result is an optional parameter. contents-type output INT.EXT:ref:(ZFTM-DDL-CNTNTS-TYPE) returns the document type with appropriate parameters.
PAGE 173
FTM_OPEN_CNF_ FTM Procedures You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-OPEN-CNF event before calling FTM_OPEN_CNF_. • The association stays in the file-selection regime if state-result indicates a failure, or moves to the file-open regime if state-result indicates a success. Errors Table 4-34.
PAGE 174
FTM_P_ABORT_IND_ FTM Procedures FTM_P_ABORT_IND_ This procedure allows you to retrieve information indicating that the association has been aborted somewhere in the OSI stack, either on the NonStop system or on the remote responding system. error := FTM_P_ABORT_IND_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error return ! I ! O ! O value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 175
FTM_P_ABORT_IND_ FTM Procedures provides information that qualifies the success or explains the failure of the requested action. This parameter might not contain any information, depending on where the provider abort was issued. For a complete list of possible diagnostic values that can be returned from the remote responder, see Appendix C, ISO FTAM Diagnostic Messages.
PAGE 176
FTM_READ_REQ_ FTM Procedures FTM_READ_REQ_ This procedure allows you to request the transfer of some or all the contents of the previously opened file. This procedure initiates the data-transfer regime. For a description of the data-transfer regime, see the OSI/FTAM Programming Guide. status := FTM_READ_REQ_ ( , , , cepi fadu-id access-context [ tag ] ) ; status ! ! ! ! I I I I return value INT indicates the outcome of the call.
PAGE 177
FTM_READ_REQ_ FTM Procedures Data Structure Field Possible Values ZFTM-VAL-FADUID-CURRENT ZFTM-VAL-FADUID-NEXT ZFADUNUMBER (specifies number of FADUs separating desired FADU from root FADU) For more information on the use of the above values, see the OSI/FTAM Programming Guide or ISO 8571, Part 2. fadu-id is a required parameter. access-context input INT .EXT:ref:(ZFTM-DDL-ACCESS-CNTXT) specifies the file access structure for transfers in the data-transfer regime.
PAGE 178
FTM_READ_REQ_ FTM Procedures • • You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call. Successful completion of the FTM_READ_REQ_ procedure call transfers the application to the data-transfer regime. Errors Table 4-36.
PAGE 179
FTM_READ_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_READ_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-open regime. Error Code: ZFTM-ERR-FADU-ID-INVALID (-6006) The FADU ID is inconsistent with the document type you requested when opening the file.
PAGE 180
FTM_READ_ATTRIB_REQ_ FTM Procedures FTM_READ_ATTRIB_REQ_ This procedure allows you to read the file attributes of the previously selected file. status := FTM_READ_ATTRIB_REQ_ ( cepi , attrib-names , [ tag ] ) ; status ! I ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2. cepi input INT:value is the connection endpoint identifier (CEPI) used to identify the specific association.
PAGE 181
FTM_READ_ATTRIB_REQ_ FTM Procedures • • • • To complete this procedure call successfully, you must have previously called FTM_SELECT_REQ_, and the association must be in the file-selection regime. For the remote responder to respond affirmatively to the read-attributes primitive, the read-attributes field of the permitted-actions attribute of this file must be set to ON.
PAGE 182
FTM_READ_ATTRIB_REQ_ FTM Procedures The following table lists common errors that can occur on the FTM_READ_ATTRIB_REQ_ procedure call. These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-selection regime.
PAGE 183
FTM_READ_ATTRIB_CNF_ FTM Procedures FTM_READ_ATTRIB_CNF_ This procedure allows you to retrieve the file attributes requested by the FTM_READ_ATTRIB_REQ_ request. error := FTM_READ_ATTRIB_CNF_ ( , , , cepi [ action-result ] [ file-attrib ] [ diagnostic ] ) ; error ! ! ! ! I O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 184
FTM_READ_ATTRIB_CNF_ FTM Procedures contains values of the attributes associated with the file, returned by the remote responder. For a description of these attributes, see the OSI/FTAM Programming Guide. The initiator limits the length of several of the file attributes and shortens any attribute value that exceeds these limits.
PAGE 185
FTM_READ_ATTRIB_CNF_ FTM Procedures Errors Table 4-38. Possible FTAM Initiator Errors for the FTM_READ_ATTRIB_CNF_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 186
FTM_SELECT_REQ_ FTM Procedures FTM_SELECT_REQ_ This procedure allows you to make a file available for access. You must have previously established an association with a remote responder. This procedure initiates the file-selection regime. For a description of the file-selection regime, see the OSI/FTAM Programming Guide.
PAGE 187
FTM_SELECT_REQ_ FTM Procedures access-passwords input INT .EXT:ref:(ZFTM-DDL-ACCESS-PASSWDS) authenticates the actions requested in the requested-access parameter. To successfully use this parameter, you must have first negotiated the security group on the FTM_INITIALIZE_REQ_ call. If the remote responder requires access passwords and the access passwords for the requested actions do not match the responder’s access passwords, the responder will reject the file selection.
PAGE 188
FTM_SELECT_REQ_ FTM Procedures Errors Table 4-39.
PAGE 189
FTM_SELECT_CNF_ FTM Procedures FTM_SELECT_CNF_ This procedure allows you to retrieve results of the application’s request to make a file available for access. error := FTM_SELECT_CNF_ ( , , , , cepi [ state-result ] [ action-result ] [ filename ] [ diagnostic ] ) ; error ! ! ! ! ! I O O O O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 190
FTM_SELECT_CNF_ FTM Procedures A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was successful. Even for a successful operation, the diagnostic parameter might include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is likely to contain one or more diagnostic messages. action-result is an optional parameter. filename output INT .
PAGE 191
FTM_SELECT_CNF_ FTM Procedures Errors Table 4-40. Possible FTAM Initiator Errors for the FTM_SELECT_CNF_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 192
FTM_TERMINATE_REQ_ FTM Procedures FTM_TERMINATE_REQ_ This procedure allows you to terminate an association with a remote responder. This procedure terminates the FTAM regime. For a description of the FTAM regime, see the OSI/FTAM Programming Guide. status := FTM_TERMINATE_REQ_ ( cepi , [ tag ] ) ; status ! I ! I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 193
FTM_TERMINATE_REQ_ FTM Procedures Errors Table 4-41. Possible FTAM Initiator Errors for the FTM_TERMINATE_REQ_ Procedure Error Code FTAM Initiator Error - 6000 ZFTM-ERR-INTERNAL - 6001 ZFTM-ERR-OUT-OF-SEQUENCE - 6017 ZFTM-ERR-INVALID-IF-VERSION - 6018 ZFTM-ERR-INVALID-FIELD-VERSION - 6019 ZFTM-ERR-BAD-APS-STATUS - 6022 ZFTM-ERR-CONNECTION-ABORTED - 6036 ZFTM-ERR-SU-ABORTED For cause, effect, and recovery information on these errors, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 194
FTM_TERMINATE_CNF_ FTM Procedures FTM_TERMINATE_CNF_ This procedure allows you to retrieve results of the application’s request to terminate an association with a remote responder. error := FTM_TERMINATE_CNF_ ( cepi , [ charging ] ) ; error ! I ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages. cepi input INT:value is the connection endpoint identifier (CEPI) used to identify the specific association.
PAGE 195
FTM_TERMINATE_CNF_ FTM Procedures You call APS_EVENT_RECEIVE_ to receive the confirm event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper confirm procedure to use to retrieve the data. You must receive the ZFTM-VAL-EVT-TERMINATE-CNF event before calling FTM_TERMINATE_CNF_. • You should call APS_DISCARD_ to discard the association context after the completion of the FTM_TERMINATE_CNF_ procedure call. Errors Table 4-42.
PAGE 196
FTM_TRANSFER_END_REQ_ FTM Procedures FTM_TRANSFER_END_REQ_ This procedure allows you to signify that no more data transfer is required. Before calling this procedure, you must call the FTM_DATA_END_REQ_ or FTM_DATA_END_IND_ procedure. This procedure terminates the data-transfer regime and moves the association to the file-open regime. For a description of these regimes, see the OSI/FTAM Programming Guide.
PAGE 197
FTM_TRANSFER_END_REQ_ FTM Procedures Errors Table 4-43.
PAGE 198
FTM_TRANSFER_END_CNF_ FTM Procedures FTM_TRANSFER_END_CNF_ This procedure allows you to retrieve the responder’s response to the application’s request to end the data-transfer regime. For a description of the data-transfer regime, see the OSI/FTAM Programming Guide. error := FTM_TRANSFER_END_CNF_ ( cepi , [ action-result ] , [ diagnostic ] ) ; ! I ! O ! O error return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages.
PAGE 199
FTM_TRANSFER_END_CNF_ FTM Procedures provides information that qualifies the success or explains the failure of a requested action. For a complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic Messages. diagnostic is an optional parameter. Considerations • • To complete this procedure call successfully, the association must be in the data-transfer regime.
PAGE 200
FTM_U_ABORT_REQ_ FTM Procedures FTM_U_ABORT_REQ_ This procedure allows you to make a request to abort the association with a remote responder. This procedure terminates all existing regimes. status := FTM_U_ABORT_REQ_ ( , , , cepi [ action-result ] [ diagnostic ] [ tag ] ) ; status ! ! ! ! I I I I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 201
FTM_U_ABORT_REQ_ FTM Procedures diagnostic is an optional parameter. tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call. When the operation is complete, the MFM_AWAITIOX_ procedure returns the tag value, allowing your application to match the completion with the correct instance of the procedure call. For details on the use of the tag parameter, see the OSI/FTAM Programming Guide. tag is an optional parameter.
PAGE 202
FTM Procedures FTM_U_ABORT_REQ_ version and line 2066 of the TAL version of Example 2 in Appendix G, NonStop FTAM Programming Examples.
PAGE 203
FTM_U_ABORT_IND_ FTM Procedures FTM_U_ABORT_IND_ This procedure allows you to retrieve information on the user abort generated by the remote responder. error := FTM_U_ABORT_IND_ ( cepi , [ action-result ] , [ diagnostic ] ) ; error ! I ! O ! O return value INT indicates the outcome of the call. For a list of defined values, see Appendix B, NonStop FTAM Initiator Error Messages. cepi input INT:value is the connection endpoint identifier (CEPI) used to identify the specific association.
PAGE 204
FTM_U_ABORT_IND_ FTM Procedures Considerations • • To successfully complete this procedure call, you must have successfully issued the F-INITIALIZE request and have a valid CEPI for the association. Before calling FTM_U_ABORT_IND_, you must call the following procedures: APS_EVENT_RECEIVE_ APS_STATUS_ You call APS_EVENT_RECEIVE_ to receive the indication event and APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the proper indication procedure to use to retrieve the data.
PAGE 205
FTM_WRITE_REQ_ FTM Procedures FTM_WRITE_REQ_ This procedure allows you to request transfer of data to the previously opened file. This procedure initiates the data-transfer regime. For a description of the data-transfer regime, see the OSI/FTAM Programming Guide. status := FTM_WRITE_REQ_ ( , , , cepi fadu-operation fadu-id [ tag ] ) ; status ! ! ! ! I I I I return value INT indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2.
PAGE 206
FTM_WRITE_REQ_ FTM Procedures ZFTM-VAL-FADUID-FIRST for the ZFIRSTLAST field. This value specifies the beginning of the first FADU after the root FADU and applies only to FTAM-1 and FTAM-3 document types. ZFTM-VAL-FADUID-END for the ZBEGINEND field. This value specifies the end of the last FADU and applies only to FTAM-2 document types. fadu-id is a required parameter. tag input INT(32):value is for use in nowait mode only. Specify a unique value to identify this instance of the procedure call.
PAGE 207
FTM_WRITE_REQ_ FTM Procedures Errors Table 4-47.
PAGE 208
FTM_WRITE_REQ_ FTM Procedures These error values... are returned if.... Error Code: Error Subcode: ZFTM-ERR-OUT-OF-SEQUENCE (-6001) ZFTM-ERR-OOS-STATE-MACHINE (1) The association is not in the file-open regime. Error Code: ZFTM-ERR-FADU-ID-INVALID (-6006) The FADU ID is inconsistent with the document type you requested when opening the file.
PAGE 209
A DDL Definitions This appendix describes the Data Definition Language (DDL) for the data structures used in parameters to the procedures described in Section 4, FTM Procedures. This appendix covers the following topics: Topic Page Types of DDL Definitions A-1 Locating DDL Definitions A-2 Basic Data Types A-3 Parameter Structures A-5 Named Values A-37 Procedure Call Cross Reference Table A-42 This appendix shows the information in DDL format.
PAGE 210
Locating DDL Definitions DDL Definitions • Named values Named values identify specific values or sets of values that can be assigned to parameters or parameter fields. Status codes, error codes, and error subcodes that the APS and FTM procedures return are defined in ZAPSDDL and ZFTMDDL. Appendix B, NonStop FTAM Initiator Error Messages describes these items.
PAGE 211
Basic Data Types DDL Definitions Basic Data Types Some DDL data types build upon simple ZAPS or ZFTM data types. First-level data types provide the lowest-level building blocks. Second-level data types are made from one or more first-level data types. First-Level Data Types First-level data types can stand alone as data types or you can use them to create more complex data-type levels. ZAPS-DDL-BOOLEAN defines the Boolean fields that the procedures use. DEFINITION ZAPS-DDL-BOOLEAN TYPE BINARY 16.
PAGE 212
Second-Level Data Types DDL Definitions Second-Level Data Types Second-level basic data types consist of one or more of the first-level data types described in the previous subsection. ZAPS-DDL-CHAR16 is a string of 16 ASCII characters. You can address them as a structure, as bytes, or as integers. DEFINITION ZAPS-DDL-CHAR16. 02 ZLEN 02 ZC 02 ZS REDEFINES ZC. 03 ZI 02 ZB REDEFINES ZC END TYPE ZAPS-DDL-INT1. PIC X(16). TYPE BINARY 16 OCCURS 8 TIMES.
PAGE 213
Parameter Structures DDL Definitions ZAPS-DDL-ISPRESENT indicates whether an optional parameter is present. DEFINITION ZAPS-DDL-ISPRESENT TYPE ZAPS-DDL-ENUM1. The valid values are: CONSTANT CONSTANT ZAPS-VAL-ABSENT ZAPS-VAL-PRESENT VALUE 0. VALUE 1. ZAPS-DDL-OBJ-ID is the ASN.1 object identifier used for the abstract syntax name, the transfer syntax name, and the application context name.
PAGE 214
ZAPS Structures DDL Definitions ZAPS Structures The first part of this subsection describes the APS data structures relevant to the ZFTM structures presented later in this subsection. All APS structures begin with ZAPS. The OSI/AS Programming Manual also documents these structures. ZAPS-DDL-ABSTRACT-SYN-NAME describes an ASN.1 abstract syntax. DEFINITION ZAPS-DDL-ABSTRACT-SYN-NAME TYPE ZAPS-DDL-OBJ-ID. ZAPS-DDL-AE-TITLE defines an ACSE application entity title (AE title).
PAGE 215
ZAPS Structures DDL Definitions when you establish an association. You can also use ZAPS-DDL-APPL-ADDR to return the responding address on the association. DEFINITION ZAPS-DDL-APPL-ADDR. 02 ZPSAP TYPE ZAPS-DDL-PSAP. 02 ZAPPL-NAME TYPE ZAPS-DDL-CHAR128. END ZPSAP is the OSI address of the application. ZAPPL-NAME is the locally assigned application name. ZAPS-DDL-APPL-CNTXT is an ACSE application context name.
PAGE 216
ZAPS Structures DDL Definitions data element headers, refer to the OSI/FTAM Programming Guide and ZAPS-DDLDATA-HDR in this subsection. DEFINITION ZAPS-DDL-DATA-ELEMENT-HDR. 02 ZLEN TYPE ZAPS-DDL-INT2. 02 ZTYPE TYPE ZAPS-DDL-ENUM1. *02 ZPCID TYPE ZAPS-DDL-PRES-CNTXT-ID. 02 FILLER PIC X(18).
PAGE 217
ZAPS Structures DDL Definitions The value of ZNUM-ELEMENTS specifies the number of data elements in the data parameter. ZAPS-DDL-DIAG-BUF is a diagnostic buffer that conveys additional information helpful in analyzing the problem being reported. The format of this structure is considered HP internal. DEFINITION ZAPS-DDL-DIAG-BUF. 02 ZC PIC X(64). 02 ZS REDEFINES ZC. 03 ZI TYPE BINARY 16 02 ZB REDEFINES ZC PIC X END OCCURS 32 TIMES. OCCURS 64 TIMES.
PAGE 218
ZAPS Structures DDL Definitions ZAPS-DDL-PSAP defines a presentation service access point address. It contains the OSI address of an application process. DEFINITION ZAPS-DDL-PSAP. 02 ZPSEL 02 ZSSEL 02 ZTSEL 02 ZNSAP END TYPE TYPE TYPE TYPE ZAPS-DDL-CHAR16. ZAPS-DDL-CHAR16. ZAPS-DDL-CHAR32. ZAPS-DDL-CHAR20. ZPSEL is the presentation selector address. ZSSEL is the session selector address. ZTSEL is the transport selector address. It defines a user of the Transport Layer service.
PAGE 219
ZAPS Structures DDL Definitions ZAPS-DDL-SWAP-VOLUME defines the name of a disk to be used as a swap volume for the API segment. DEFINITION ZAPS-DDL-SWAP-VOLUME. 02 ZC PIC X(8). END ZAPS-DDL-TRANSFER-SYN-NAME describes an ASN.1 transfer syntax. DEFINITION ZAPS-DDL-TRANSFER-SYN-NAME TYPE ZAPS-DDL-OBJ-ID.
PAGE 220
ZFTM Structures DDL Definitions ZFTM Structures The following subsection describes the FTAM structures that define reference parameters for FTAM procedures. All FTAM structures begin with ZFTM. ZFTM-DDL-ACCESS-CNTRL-ATTR is the file attribute that defines the conditions under which access to the file is allowed. DEFINITION ZFTM-DDL-ACCESS-CNTRL-ATTR. 02 ZID TYPE ZAPS-DDL-ENUM1. 02 ZACCESSCNTRL TYPE ZFTM-DDL-ACCESS-CNTRL-ELEM.
PAGE 221
ZFTM Structures DDL Definitions ZDELETEVALUES contains the access-control element values to be deleted. ZFTM-DDL-ACCESS-CNTRL-ELEM contains the information used to determine when an application can access a file. DEFINITION ZFTM-DDL-ACCESS-CNTRL-ELEM. 02 ZACTIONLIST TYPE ZFTM-DDL-REQUESTED-ACCESS. 02 ZCONCURRENCYISPRESENT TYPE ZAPS-DDL-ISPRESENT. 02 ZCONCURRENCYACCESS TYPE ZFTM-DDL-CONCURRENCY. 02 ZIDENTITYISPRESENT TYPE ZAPS-DDL-ISPRESENT. 02 ZIDENTITY TYPE ZAPS-DDL-CHAR32.
PAGE 222
ZFTM Structures DDL Definitions ZFTM-VAL-ACCESSCNTXT-FA, Flat All Data Units. According to this access context, Node-Descriptor-Data-Elements and File-Contents-Data-Elements from the addressed FADU are transferred. ZFTM-VAL-ACCESSCNTXT-UA, Unstructured All Data Units. According to this access context, only File-Contents-Data-Elements from the addressed FADU are transferred. ZLEVELNUMISPRESENT indicates if a level number value is present. The value of this field is always ZAPS-VAL-ABSENT.
PAGE 223
ZFTM Structures DDL Definitions ZFTM-DDL-ACCOUNT-ATTR defines a file attribute that identifies the account to be charged for FTAM use. DEFINITION ZFTM-DDL-ACCOUNT-ATTR. 02 ZID TYPE ZAPS-DDL-ENUM1. 02 ZACCOUNT TYPE ZAPS-DDL-CHAR32. END ZID indicates whether a ZACCOUNT value is available. The ZID field of this structure is not used in initiator requests and indications. ZID has two possible values: ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT. ZACCOUNT specifies the identity of the account.
PAGE 224
ZFTM Structures DDL Definitions ZPRIVATE specifies whether the private attribute group is available. Because NonStop FTAM does not support the private attribute group, always set this field to ZAPS-VAL-FALSE. ZFTM-DDL-ATTR-NAMES identifies the file attributes that you wish the responder to return when you issue an FTM_READ_ATTRIB_REQ_ procedure call. This structure is also used in NBS-9 operations to specify the file attributes of the contents-type (ZFILEATTRS field of ZDOCTYPE in ZFTM-DDL-CNTNTS-TYPE).
PAGE 225
ZFTM Structures DDL Definitions ZFILEAVLBLTY requests the file availability status. ZFILESIZE requests the file size. ZFUTUREFILESIZE requests the future file size. ZACCESSCNTRL requests the access control specifications. ZLEGALQUALIF requests the legal status of the file. ZPRIVATEUSE requests the private use attribute. This attribute is not used. ZFTM-DDL-CHANGE-ATTR specifies the attributes you wish to change, along with their new values, when you issue the FTM_CHANGE_ATTRIB_REQ_ procedure call.
PAGE 226
ZFTM Structures DDL Definitions ZSTORAGEACCOUNT identifies the storage account to be used for tracking FTAM-use charges. ZFILEAVLBLTYATTRISPRESENT indicates whether the file availability status is to be changed. ZFILEAVLBLTYATTR specifies immediate or deferred file availability. ZFUTUREFILESIZEISPRESENT indicates whether the future file size value is to be changed. ZFUTUREFILESIZE contains the future file size value. ZACCESSCNTRLISPRESENT indicates whether access control specifications are to be changed.
PAGE 227
ZFTM Structures DDL Definitions ZCHARGEUNIT specifies the units used for measuring charges. The unit depends on the implementation. If the responder returns a value for the unit of measurement that is greater than 16, the initiator passes only the first 16 characters to the application. ZCHARGEVALUE indicates how many of the units specified in ZCHARGEUNIT are to be charged. ZFTM-DDL-CNTNTS-LIST is the contents-type-list parameter.
PAGE 228
ZFTM Structures DDL Definitions ZASNAME is reserved, and application programs should not use it. ZFTM-DDL-CNTNTS-TYPE specifies the contents type of an abstract data type file when an application opens the file. DEFINITION ZFTM-DDL-CNTNTS-TYPE. 02 ZID 02 ZCNTNTSTYPE TYPE ZAPS-DDL-ENUM1. TYPE ZAPS-DDL-CHAR128.
PAGE 229
ZFTM Structures DDL Definitions ZFTM-VAL-CNTNTSTYPE-UNKNOWN indicates that the contents type is unknown. ZCNTNTSTYPE allocates space for the contents type information redefined by ZDOCTYPE; application programs do not need to access this structure. ZDOCTYPE contains the following document type parameters that an application can access: ZDOCTYPENAME specifies the document type name. ZUNIVERSALCLASSISPRESENT indicates whether a universal class value is present.
PAGE 230
ZFTM Structures DDL Definitions ZMAXSTRINGLEN is a required parameter for FTAM-1, FTAM-2, and FTAM-3 document types. This field indicates how long a data string can be. ZSTRINGSIGISPRESENT indicates whether a string significance value is present. ZSTRINGSIG indicates whether the length of the string used for transferring data is significant to the semantics of the file. If it is significant, it indicates whether the length is variable or fixed.
PAGE 231
ZFTM Structures DDL Definitions ZFTM-DDL-CONCURRENCY-KEY defines the levels of concurrency applied to various file activities in ZFTM-DDL-CONCURRENCY. DEFINITION ZFTM-DDL-CONCURRENCY-KEY. 02 ZNOTREQUIRED TYPE 02 ZSHARED TYPE 02 ZEXCLUSIVE TYPE 02 ZNOACCESS TYPE END ZAPS-DDL-BOOLEAN. ZAPS-DDL-BOOLEAN. ZAPS-DDL-BOOLEAN. ZAPS-DDL-BOOLEAN. ZNOTREQUIRED indicates that the primary user does not intend to perform the specified activity on the file.
PAGE 232
ZFTM Structures DDL Definitions ZCNTNTSTYPEVALUE specifies the contents type of the file. ZSTORAGEACCOUNTISPRESENT indicates whether a storage account has been specified. ZSTORAGEACCOUNT identifies the storage account to be charged for FTAM activity. ZFILEAVLBLTYATTRISPRESENT indicates whether file availability is specified. ZFILEAVLBLTYATTR contains the file availability status. ZFUTUREFILESIZEISPRESENT indicates whether a future file size has been specified.
PAGE 233
ZFTM Structures DDL Definitions ZCNTNTSTYPEVALUE specifies the contents type of the file. ZSTORAGEACCOUNTISPRESENT indicates whether a storage account has been specified. ZSTORAGEACCOUNT identifies the storage account to be charged for FTAM activity. ZFILEAVLBLTYATTRISPRESENT indicates whether file availability is specified for the file. ZFILEAVLBLTYATTR contains the file availability status. ZFUTUREFILESIZEISPRESENT indicates whether a future file size has been specified.
PAGE 234
ZFTM Structures DDL Definitions ZFTM-DDL-DE-FADU is the data type for an FTAM structuring data element. ZFTM-DDL-DE-FADU is not a valid data element for FTAM-1, FTAM-3, or NBS-9 document types. DEFINITION ZFTM-DDL-DE-FADU. 02 ZTYPE 02 ZNAMEISPRESENT 02 ZNAME 02 ZARCLENGTHISPRESENT 02 ZARCLENGTH 02 ZDATAEXISTSISPRESENT 02 ZDATAEXISTS END TYPE TYPE TYPE TYPE TYPE TYPE TYPE ZAPS-DDL-INT2. ZAPS-DDL-ISPRESENT. ZAPS-DDL-CHAR32. ZAPS-DDL-ISPRESENT. ZAPS-DDL-INT2. ZAPS-DDL-ISPRESENT. ZAPS-DDL-BOOLEAN.
PAGE 235
ZFTM Structures DDL Definitions ZFTM-DDL-DIAG-ELEM contains the information returned in a single FTAM diagnostic message. DEFINITION ZFTM-DDL-DIAG-ELEM. 02 ZDIAGTYPE 02 ZERRORID 02 ZERROROBSERVER 02 ZERRORSOURCE 02 ZSUGGESTEDDELAYISPRESENT 02 ZSUGGESTEDDELAY 02 ZFURTHERDETAILSISPRESENT 02 ZFURTHERDETAILS END TYPE TYPE TYPE TYPE TYPE TYPE TYPE TYPE ZAPS-DDL-INT2. ZAPS-DDL-INT2. ZFTM-DDL-ENTITY-REF. ZFTM-DDL-ENTITY-REF. ZAPS-DDL-ISPRESENT. ZAPS-DDL-INT2. ZAPS-DDL-ISPRESENT. ZFTM-DDL-CHAR256.
PAGE 236
ZFTM Structures DDL Definitions ZFTM-DDL-DIAGNOSTIC is the structure used by FTAM to return up to 10 diagnostic elements. DEFINITION ZFTM-DDL-DIAGNOSTIC. 02 ZDIAGCOUNT TYPE ZAPS-DDL-INT1. 02 ZDIAGELEMSISPRESENT TYPE ZAPS-DDL-ISPRESENT. 02 ZDIAGELEMS TYPE ZFTM-DDL-DIAG-ELEM OCCURS 10 TIMES. END ZDIAGCOUNT specifies how many diagnostic elements are present, if any. ZDIAGELEMSISPRESENT indicates whether diagnostic elements are present. ZDIAGELEMS contains up to 10 diagnostic elements.
PAGE 237
ZFTM Structures DDL Definitions ZFTM-DDL-FADU-ID identifies a specific file data access unit (FADU) in any one of five possible ways. Use this structure to locate FADUs on erase, locate, read, and write requests. DEFINITION ZFTM-DDL-FADU-ID. 02 ZID 02 ZFADUID 02 ZFIRSTLAST 02 ZRELATIVE 02 ZBEGINEND 02 ZFADUNUMBER TYPE ZAPS-DDL-ENUM1. TYPE ZAPS-DDL-INT2. REDEFINES ZFADUID TYPE ZAPS-DDL-INT2. REDEFINES ZFADUID TYPE ZAPS-DDL-INT2. REDEFINES ZFADUID TYPE ZAPS-DDL-INT2.
PAGE 238
ZFTM Structures DDL Definitions used at one time. The remaining fields in this structure identify the FADU according to that method. ZFIRSTLAST identifies the FADU as either of the following: ZFTM-VAL-FADUID-FIRST specifies the first FADU after the root FADU. ZFTM-VAL-FADUID-LAST specifies the last FADU. ZRELATIVE identifies the relative position of the FADU as one of the following: ZFTM-VAL-FADUID-PREVIOUS specifies the previous FADU. ZFTM-VAL-FADUID-CURRENT specifies the current FADU.
PAGE 239
ZFTM Structures DDL Definitions ZFTM-DDL-FILESIZE-ATTR specifies the file attribute that represents the size of the file in octets. DEFINITION ZFTM-DDL-FILESIZE-ATTR. 02 ZID TYPE ZAPS-DDL-ENUM1. 02 ZFILESIZE TYPE ZAPS-DDL-INT2. END ZID indicates whether there is a ZFILESIZE attribute available. The ZID field of this structure is not used in initiator requests and indications. ZID has two possible values: ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT. ZFILESIZE contains the size of the file.
PAGE 240
ZFTM Structures DDL Definitions ZFTM-DDL-LEGALQUALIF-ATTR defines the legal status of the file. DEFINITION ZFTM-DDL-LEGALQUALIF-ATTR. 02 ZID TYPE ZAPS-DDL-ENUM1. 02 ZLEGALQUALIF TYPE ZAPS-DDL-CHAR128. END ZID indicates whether there is a ZLEGALQUALIF attribute value for this file. The ZID field of this structure is not used in initiator requests and indications. ZID has two possible values: ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTRISPRESENT.
PAGE 241
ZFTM Structures DDL Definitions ZRANDOM specifies access that permits you to select any FADU by the FADU identity specified in a read, write, or locate request. ZFTM-DDL-PROC-MODE specifies the processing mode that defines the actions permitted on the FADUs of the file in the open regime. To allow multiple actions, set the corresponding fields in ZFTM-DDL-PROC-MODE to ZAPS-VAL-TRUE. DEFINITION ZFTM-DDL-PROC-MODE.
PAGE 242
ZFTM Structures DDL Definitions DEFINITION ZFTM-DDL-READ-ATTR.
PAGE 243
ZFTM Structures DDL Definitions ZCNTNTSTYPEVALUE indicates the contents type. ZSTORAGEACCOUNTISPRESENT indicates whether a storage account was returned. ZSTORAGEACCOUNT identifies the storage account. ZCREATIONISPRESENT indicates whether a file creation date was returned. ZCREATION returns the date and time that the file was created. ZLASTMODISPRESENT indicates whether the date and time of the last modification was returned. ZLASTMOD returns the date and time the file was last modified.
PAGE 244
ZFTM Structures DDL Definitions ZACCESSCNTRLATTRISPRESENT indicates whether the access control attribute was returned. ZACCESSCNTRLATTR returns the access control values. ZLEGALQUALIFISPRESENT indicates whether the legal qualification attribute was returned. ZLEGALQUALIFICATION returns a text string giving information about the legal status of the file. ZFTM-DDL-REQUESTED-ACCESS specifies the types of access that you want for a file you are selecting or creating. DEFINITION ZFTM-DDL-REQUESTED-ACCESS.
PAGE 245
Named Values DDL Definitions ZMGMT specifies the file-management class. ZTRANSFER specifies the file-transfer class. ZXFERMGMT specifies the file-transfer-management class. ZACCESS specifies the file-access class. ZFTM-DDL-USER-ID identifies the user identity responsible for various file activities including creating a file, reading it, modifying it, and reading and modifying its attributes. DEFINITION ZFTM-DDL-USER-ID. 02 ZID 02 ZUSERID END TYPE ZAPS-DDL-ENUM1. TYPE ZAPS-DDL-CHAR32.
PAGE 246
Named Values DDL Definitions ZAPS-VAL-TRUE indicates that the condition in the ZAPS-DDL-BOOLEAN data type is true. ZFTM-VAL-ACCESSCNTXT-xxx See ZFTM-DDL-ACCESS-CNTXT on page A-13. ZFTM-VAL-ACTION-xxx indicates the outcome of an action. The following values are returned on the FTM procedures: CONSTANT CONSTANT ZFTM-VAL-ACTION-SUCCESS ZFTM-VAL-ACTION-FAILURE VALUE 0 VALUE 2 TYPE BINARY 32. TYPE BINARY 32. ZFTM-VAL-ACTION-SUCCESS indicates that the action was a success.
PAGE 247
Named Values DDL Definitions ZFTM-VAL-DIAG-xxx provides diagnostic information returned by the FTAM responder. For a listing of possible messages, refer to Appendix C, ISO FTAM Diagnostic Messages. ZFTM-VAL-ENTITYREF-xxx See ZFTM-DDL-ENTITY-REF on page A-28. ZFTM-VAL-EVT-xxx tells you which event (a primitive or an error) has been received. The event values are listed in Table A-1. This table also lists the procedure to call to retrieve the event information, where applicable.
PAGE 248
Named Values DDL Definitions Table A-1.
PAGE 249
Named Values DDL Definitions ZFTM-VAL-FOPEN-RECREATE indicates that the existing file is to be deleted and a new file is to be created using the file attributes specified in the initial-attrib parameter. If the file does not exist, the new file is created and the call succeeds. ZFTM-VAL-FOPEN-OLD indicates that an existing file is selected. If the file does not exist, the call to open the file fails.
PAGE 250
Procedure Call Cross Reference Table DDL Definitions Procedure Call Cross Reference Table Table A-2.
PAGE 251
Procedure Call Cross Reference Table DDL Definitions Table A-2.
PAGE 252
DDL Definitions Procedure Call Cross Reference Table HP NonStop OSI/FTAM Programming Reference Manual—528611-001 A -44
PAGE 253
B NonStop FTAM Initiator Error Messages This appendix describes the following types of error messages that you might encounter in developing NonStop FTAM applications: • • APS error messages and subcodes Error messages and subcodes generated by the NonStop FTAM initiator or FTAM API This appendix covers the following topics: Topic Page Status Codes B-2 Error Codes B-4 The NonStop FTAM initiator also generates FTAM diagnostic messages, which are described in Appendix D, NonStop FTAM Initiator Diagno
PAGE 254
Status Codes NonStop FTAM Initiator Error Messages see the “Errors” subsections in the individual procedure descriptions in Section 4, FTM Procedures. For information about MFM and APS procedures, refer to Appendix E, MFM Procedures and Appendix F, APS Procedures, respectively.
PAGE 255
NonStop FTAM Initiator Error Messages Status Codes 0 ZAPS-VAL-STATUS-OK Effect. This code has two meanings. If you receive ZAPS-VAL-STATUS-OK (0) after a call to an FTM or APS procedure in wait mode or after MFM_AWAITIOX_ in nowait mode, the operation was successful. If you receive ZAPS-VAL-STATUS-OK (0) after a call to an FTM or APS procedure in nowait mode, the operation was successfully initiated. Recovery. None is required. 1 ZAPS-VAL-STATUS-EVENT Effect.
PAGE 256
Error Codes NonStop FTAM Initiator Error Messages 7 ZAPS-VAL-STATUS-DISCARD Effect. The operation you requested failed because of an aborted association or internal causes rendering the association useless (for example, the associated SU was aborted). Recovery. Discard the association context, as described in the OSI/FTAM Programming Guide.
PAGE 257
APS Error Codes NonStop FTAM Initiator Error Messages Table B-2.
PAGE 258
APS Error Codes NonStop FTAM Initiator Error Messages Table B-2. APS Error Codes for NonStop FTAM (page 3 of 3) Constant (ZAPS-ERR-) Code Meaning NONE-PENDING -135 No operation pending PARAM-MISSING* -136 Mandatory parameter(s) missing PARAM-BOUNDS* -137 Reference parameter(s) out of bounds PARAM-RANGE* -138 Value of parameter(s) outside range INVALID-SERVICE* -141 Unrecognized service ID * These are APS error codes redefined for use in NonStop FTAM.
PAGE 259
NonStop FTAM Initiator Error Messages APS Error Codes -104 ZAPS-ERR-INTERNAL Cause. An internal error has occurred. Subcodes. A number of undocumented subcodes internal to NonStop Kernel are possible. Recovery. Trace the TAPS process and note the error and subcode, if any. Follow the standard procedures at your site for contacting the appropriate support personnel. These procedures might involve contacting your local HP support analyst. -105 ZAPS-ERR-PARAMETER Cause.
PAGE 260
NonStop FTAM Initiator Error Messages APS Error Codes -107 ZAPS-ERR-STATE-MACHINE Cause. Cause. Your application attempted to invoke a primitive that was not valid in the current state. Subcodes. The possible subcodes are ZAPS-ERR-SM-BAD-STATE and ZAPS-ERRSM-BAD-EVENT. For more information, see the OSI/AS Programming Manual. Recovery. Check your application’s calling sequence against the situation you are encountering.
PAGE 261
NonStop FTAM Initiator Error Messages APS Error Codes 114 ZAPS-ERR-OPERATOR-ABORT Cause. The association has been aborted by the operator. Subcodes. None. Recovery. Call APS_DISCARD_ to discard the association context. -116 ZAPS-ERR-NO-DATA Cause. You requested data, but no data is available to satisfy the request. Possible causes for this error include: • • You requested data, but none was received with the incoming primitive. You specified a start position beyond the end of the data. Subcodes. None.
PAGE 262
NonStop FTAM Initiator Error Messages APS Error Codes -118 ZAPS-ERR-MFM-ERROR Cause. The Module File Management (MFM) software returned an unrecoverable error. Subcodes. The error subcodes are Guardian file-system error codes, indicating the error code returned from the MFM software. For descriptions of file-system errors, refer to the Guardian Procedure Errors and Messages Manual. Recovery. Abort the association or discard the association context.
PAGE 263
NonStop FTAM Initiator Error Messages APS Error Codes -121 ZAPS-ERR-SSNULL Cause. An SPI error was encountered during the execution of the SSNULL procedure. This is an internal error involving SPI buffer management. Subcodes. The subcode indicates the error returned by SSNULL. For descriptions of the SPI errors, refer to the Guardian Procedure Errors and Messages Manual. Recovery. Follow the standard procedures at your site for contacting the appropriate support personnel.
PAGE 264
APS Error Codes NonStop FTAM Initiator Error Messages -124 ZAPS-ERR-BAD-MGR Cause. You specified an invalid APLMGR process name in a call to the FTM_INITIALIZE_REQ_ procedure, or that the process specified is not an APLMGR process of the correct version. Subcodes. None. Recovery. Specify a valid APLMGR process name. -125 ZAPS-ERR-MGR-FS-ERROR Cause. The FTAM API encountered a file-system error while communicating with the APLMGR process. This error indicates that the connect sequence has failed.
PAGE 265
APS Error Codes NonStop FTAM Initiator Error Messages Table B-3. APLMGR Subcodes (page 2 of 2) Constant (ZFTM-ERR-MGR-) Value Meaning ASE-UNAVAIL 7004 FTAM process not available ASE-TBL-EMPTY 7005 FTAM process table empty, no processes defined, or APLMGR is in suspended state ASE-NOT-READY 7006 FTAM process not ready, no processes in started state Recovery. Recovery depends on the subcode received. For APLMGR-generated values 7000, 7001, and 7002, stop the program and rerun it.
PAGE 266
NonStop FTAM Initiator Error Messages APS Error Codes -129 ZAPS-ERR-NO-EVENT Cause. You set a time limit of 0D when calling APS_EVENT_RECEIVE_, but no event was received. Subcodes. None. Recovery. Continue with other processing. -131 ZAPS-ERR-NO-CONNECTION Cause. No association exists. Subcodes. None. Recovery. Call APS_DISCARD_ to discard the association context and release the CEPI. Then call FTM_INITIALIZE_REQ_ to reinitiate the association. -134 ZAPS-ERR-TAPS-FS-ERROR Cause.
PAGE 267
NonStop FTAM Initiator Error Messages APS Error Codes Recovery. Check the calling sequence used in your application. If you have issued an APS_EVENT_RECEIVE_, for example, make sure that you have first called the desired FTM request or response procedure that will cause a confirm or indication. If you have issued an MFM_AWAITIOX_ call, you should have first issued the appropriate FTM request or response nowaited procedure and that procedure should have returned a status value of ZAPS-VAL-STATUS-OK (0).
PAGE 268
APS Error Codes NonStop FTAM Initiator Error Messages Table B-4.
PAGE 269
APS Error Codes NonStop FTAM Initiator Error Messages Table B-4.
PAGE 270
APS Error Codes NonStop FTAM Initiator Error Messages Table B-4.
PAGE 271
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages -138 ZAPS-ERR-PARAM-RANGE Cause. One or more parameters were outside the permissible range of values. Subcodes. For FTM-procedure parameters, see Table B-4 on page B-16, and for APS-procedure parameters, the OSI/AS Programming Manual. Recovery. Correct your use of parameters, rebuild the application, and then retry the operation. -141 ZAPS-ERR-INVALID-SERVICE Cause.
PAGE 272
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages Table B-5.
PAGE 273
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages -6000 ZFTM-ERR-INTERNAL Cause. The FTAM API or the FTAM initiator detected an internal error. Subcodes. The subcode identifies the general location in the code where the error was detected. These subcodes are not documented in this manual. Effect. The initiator rejects your request. Files involved in a data transfer might be left in an unknown state. Recovery. Abort the association and call APS_DISCARD_ to discard the association context.
PAGE 274
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages Effect. The initiator rejects your request. Recovery. Issue a valid request, or retry with the procedures in proper sequence. For the procedure sequence for major FTAM tasks, refer to the OSI/FTAM Programming Guide. For protocol information, refer to Section 4, FTM Procedures and to the ISO 8571 standard.
PAGE 275
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages Table B-8. Functional Units Required for Create, Change-Attribute, and BeginGroup Services (page 2 of 2) Procedure Functional Unit Required FTM_FILE_OPEN_REQ_ Grouping, read, or write FTM_LOCATE_REQ_ File access FTM_OPEN_REQ_ Read or write FTM_READ_ATTRIB_REQ_ Limited file management -6003 ZFTM-ERR-ACCESS-INCNSTNT Cause.
PAGE 276
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages -6004 ZFTM-ERR-ACCESS-NOT-AVAIL Cause. You called the FTM_READ_ATTRIB_REQ_, FTM_CHANGE_ATTRIB_REQ_ or FTM_DELETE_REQ_ when requested-access on the FTM_SELECT_REQ_ or FTM_CREATE_REQ_ procedure call did not include the read-attribute, changeattribute, or delete-file action, respectively. Subcodes. For the required access, see Table B-9 on page B-23. Only the subcode of the file access first detected as missing is displayed. Effect.
PAGE 277
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes -6006 ZFTM-ERR-FADU-ID-INVALID Cause. On the FTM_LOCATE_REQ_, FTM_ERASE_REQ_, FTM_READ_REQ_, or FTM_WRITE_REQ_ procedure, you specified a file-access data unit (FADU) ID that was inconsistent with the document type requested when the file was opened. Subcodes. None. Effect. The initiator rejects your request. Recovery. Reissue the request using a FADU ID that is compatible with the document type.
PAGE 278
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages -6008 ZFTM-ERR-PROC-MODE-NOT-AVAIL Cause. You called FTM_READ_REQ_ or FTM_ERASE_REQ_ after opening the file with a processing mode that did not include the read or erase actions, respectively. Subcodes. To determine what processing mode was required, see Table B-10 on page B-24. Effect. The initiator rejects your request. Recovery. Close the file and reopen it specifying the correct processing mode.
PAGE 279
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages Table B-12.
PAGE 280
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages -6012 ZFTM-ERR-SERV-NOT-NEGOTIATED Cause. You have not negotiated the correct service class to perform the current task. This error message can be returned when you attempt to perform: • • • A task within a grouped request that is not supported by the negotiated service class An erase or locate action in a service class other than the file-access service class A read or write action in the management service class Subcodes.
PAGE 281
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes standard procedures at your site for contacting the appropriate support personnel. These procedures might involve contacting your local HP support analyst. -6018 ZFTM-ERR-INVALID-FIELD-VERSION Cause. The application is using a version of the FTM procedure module that is incompatible with the maximum field version of the FTAM initiator process. Subcodes. None. Effect. The program cannot run. Recovery.
PAGE 282
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes configuration, refer to the OSI/FTAM and OSI/APLMGR SCF Reference Manual and the OSI/AS SCF Reference Manual. -6021 ZFTM-ERR-RESRC-DCB-ALLOC Cause. The FTAM initiator has detected a memory allocation problem; it was unable to allocate sufficient memory to complete your request. Subcodes. None. Effect. The service fails, and any file in the process of being written is left in an unknown state. Recovery.
PAGE 283
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes -6024 ZFTM-ERR-ATTR-GRP-NOT-NEG Cause. In calling an FTM_READ_ATTRIB_REQ_ or FTM_CHANGE_ATTRIB_REQ_ procedure, you tried to use an attribute that is inconsistent with the attribute group negotiated when the association was established using the FTM_INITIALIZE_REQ_ procedure. Subcodes. None. Effect. The initiator rejects your request.
PAGE 284
FTAM Initiator Error Codes NonStop FTAM Initiator Error Messages FTM_LOCATE_REQ_. For information on functional units and procedures, refer to the OSI/FTAM Programming Guide. -6030 ZFTM-ERR-DATA-XFER-CANCELLED Cause. Before the initiator could act upon a data request from the FTAM application, it received a cancel request from the responder and was therefore unable to send the requested data. Subcodes. None. Effect. The data is not sent. Recovery.
PAGE 285
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes -6036 ZFTM-ERR-SU-ABORTED Cause. The SCF command ABORT SU has just been issued to a subdevice that your application is using. Subcodes. None. Effect. The association associated with the aborted SU is terminated. Recovery. Call the APS_DISCARD_ procedure to discard the association context. Determine what problem has caused the system management staff to abort the SU.
PAGE 286
NonStop FTAM Initiator Error Messages FTAM Initiator Error Codes -6039 ZFTM-ERR-EMPTY-ASSOC-CNF Cause. Cause. An internal ACSE confirm (A-ASSOCIATE) was received without user data. Normally, the user data of the A-ASSOCIATE confirm would contain the FINITIALIZE confirm. This error indicates a problem with the responding entity on the remote system. Subcodes. None. Effect. The initiator rejects your request. Recovery. Call the APS_DISCARD_ procedure to discard the association context.
PAGE 287
C ISO FTAM Diagnostic Messages The ISO FTAM diagnostic messages returned by remote responders can have a variety of meanings depending on their use in a particular FTAM implementation.
PAGE 288
ISO FTAM Diagnostic Messages Table C-1. Error Types Constant (ZFTM-VAL-DIAG-) Error Type Value INFORMATIVE 0 An error message that does not affect the current state of the file service and does not require any recovery. TRANSIENT 1 An error that indicates that the failure of the operation being performed cannot recur if the sequence is repeated.
PAGE 289
General FTAM Diagnostic Messages ISO FTAM Diagnostic Messages General FTAM Diagnostic Messages Table C-3.
PAGE 290
Association-Related Diagnostic Messages ISO FTAM Diagnostic Messages Table C-4.
PAGE 291
Selection-Related Diagnostic Messages ISO FTAM Diagnostic Messages Selection-Related Diagnostic Messages Table C-6.
PAGE 292
File-Management-Related Diagnostic Messages ISO FTAM Diagnostic Messages Table C-6. Selection-Related Diagnostic Messages (page 2 of 2) Constant (ZFTM-DIAG-) Value Meaning ACCESS-VIOLATES-PA 3028 Requested access violates permitted actions FU-UNAVAIL 3029 Functional unit not available for requested access CREATED-NOT-SELECTED 3030 File created but not selected File-Management-Related Diagnostic Messages Table C-7.
PAGE 293
Access-Related Diagnostic Messages ISO FTAM Diagnostic Messages Table C-8.
PAGE 294
Recovery-Related Diagnostic Messages ISO FTAM Diagnostic Messages Recovery-Related Diagnostic Messages Table C-9.
PAGE 295
D NonStop FTAM Initiator Diagnostic Messages The NonStop FTAM initiator diagnostic messages are returned on indication and confirm procedures when the NonStop FTAM initiator detects a problem either locally or on the remote responder. Because there are so few of these messages, they are not grouped in the same way that the ISO FTAM diagnostic messages in the previous appendix are grouped.
PAGE 296
NonStop FTAM Initiator Diagnostic Messages the remote responder might be too large for the initiator to properly decode. You need either to increase the size of the maximum-string-length parameter or have the responder send smaller PDUs. You can increase the size of the maximum-stringlength parameter only if the string-significance value is not-significant. Otherwise, the responder must send smaller PDUs. In all other error conditions, the application should retry the operation.
PAGE 297
NonStop FTAM Initiator Diagnostic Messages 1007 ZFTM-DIAG-PROTOCOL-ERROR Cause. The initiator has detected a protocol error. Effect. The initiator aborts the association. Recovery. This message might indicate an interoperability problem. Verify that the responder is making a valid response to the initiator. This can be done by tracing the initiator and verifying the protocol.
PAGE 298
NonStop FTAM Initiator Diagnostic Messages 5037 ZFTM-DIAG-CNTNTS-TYPE-SIMPLE Cause. The initiator included an informative diagnostic message in the open confirm because the responder had simplified the contents type from FTAM-2 to FTAM-1. Effect. This is an information-only diagnostic message. The file-open request is complete for an FTAM-1 contents type. Recovery. If the simplification to FTAM-1 is acceptable to you, no action is required, and you can continue your application. Otherwise, close the file.
PAGE 299
E MFM Procedures This appendix contains detailed reference information for the module file management (MFM) procedure calls: MFM_AWAITIOX_ and MFM_CANCELREQ_. These calls are provided for NonStop FTAM programs using associations established in nowait mode. Using MFM Procedure Calls The external declarations for the current version of the MFM procedures are provided in the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL declarations) and $SYSTEM.SYSTEM.CEXTDECS (C declarations).
PAGE 300
Procedure Descriptions MFM Procedures Procedure Descriptions The names of all MFM procedures start with the characters “MFM_.” Figure 4-1 on page 4-10 shows the syntax notation used to describe procedure calls in this manual. This notation gives the syntax for calling the procedures from C or TAL programs. This appendix provides the syntax and semantics of the MFM procedures, in alphabetic order.
PAGE 301
MFM_AWAITIOX_ MFM Procedures When you call this procedure, give the filenum parameter one of the following values: • • • -1, to show that you want information on the first completion of an FTM, APS, or file-system procedure. A CEPI, to show that you want information on the first completion of an FTM or APS procedure for a particular connection. A file-system file number, to show that you want information on the completion of a file-system call made on a particular file-system open.
PAGE 302
MFM_CANCELREQ_ MFM Procedures positive number and filenum is a CEPI, the call is rejected with a status value of ZAPS-VAL-STATUS-NO-RETRY. segment-id output INT .EXT:ref:1 displays the segment ID of the extended segment containing the buffer when the operation was initiated. For NonStop FTAM operations, this parameter is not relevant and has the value -1. Considerations • Perform error checking as follows: 1. Immediately after the call to MFM_AWAITIOX_, check the filenum returned. 2.
PAGE 303
MFM_CANCELREQ_ MFM Procedures pseudofn input INT:value is the pseudo file number for which you want to cancel an operation. For FTAM or APS procedures, this is the connection endpoint identifier (CEPI). tag input INT(32):value identifies the operation you wish to cancel. Considerations • • • The semantics of MFM_CANCELREQ_ are similar to those of the file-system procedure CANCELREQ. The condition code is undefined after a call to MFM_CANCELREQ_.
PAGE 304
MFM Procedures MFM_CANCELREQ_ HP NonStop OSI/FTAM Programming Reference Manual—528611-001 E- 6
PAGE 305
F APS Procedures This appendix contains detailed reference information on the general-support procedures provided with NonStop FTAM API, including APS_DISCARD_, APS_EVENT_RECEIVE_, APS_INITIALIZE_, and APS_STATUS_. You use these procedures mainly to allocate and deallocate buffer space for use by the FTAM API, or retrieve event and error information.
PAGE 306
Procedure Descriptions APS Procedures Procedure Descriptions The names of all APS procedures start with the characters “APS_.” Figure 4-1 on page 4-10 shows the syntax notation used to describe procedure calls in this manual. This notation gives the syntax for calling the procedures from C or TAL programs. This appendix provides the syntax and semantics of the APS procedures, in alphabetic order.
PAGE 307
APS_DISCARD_ APS Procedures APS_DISCARD_ This procedure allows you to delete the API context information for an association. After APS_DISCARD_ has completed successfully, you can no longer use the CEPI. In normal circumstances, call APS_DISCARD_ after the association has been released or aborted by your application, by the remote responder, or by the service provider. In exceptional circumstances, you can call APS_DISCARD_ without previously releasing or aborting the association.
PAGE 308
APS_EVENT_RECEIVE_ APS Procedures APS_EVENT_RECEIVE_ This procedure allows you to receive an event. In other words, it notifies you when an indication or confirm primitive becomes available to you. If the association is in nowait mode, complete this operation by calling MFM_AWAITIOX_ on page E-2. When you have received an event, call APS_STATUS_ to determine which event. For further information about the use of this procedure, see in the OSI/FTAM Programming Guide.
PAGE 309
APS_EVENT_RECEIVE_ APS Procedures procedure displays the tag value, allowing you to match the completion with the correct instance of the procedure call. block-size input INT:value is an optional parameter that determines how events are to be retrieved. In NonStop FTAM operations, this parameter is not used.
PAGE 310
APS_INITIALIZE_ APS Procedures APS_INITIALIZE_ This procedure allocates and initializes a segment that holds context information for all of your API associations. This procedure must be the first FTAM procedure you call in your program. Call it only once. error := APS_INITIALIZE_ ( [ swapvol ] ); error ! I returned value INT indicates the outcome of the call. This value can be either a negative APS error code or a positive file-system error number.
PAGE 311
APS_STATUS_ APS Procedures APS_STATUS_ This procedure allows you to obtain status information for an established association or an association attempt. Use it in the following circumstances: • • • After an error, to obtain the error code and other details. After an event, to obtain the event code. After the successful completion of an FTM_INITIALIZE_REQ_ procedure, if you wish to obtain the name of the subdevice (SU) created for the association.
PAGE 312
APS_STATUS_ APS Procedures device-name output INT .EXT:ref:(ZAPS-DDL-FILENAME) is the complete FTAM device name, including subdevice, of the association for the CEPI you specified. This parameter is available for the CEPI after an FTM_INITIALIZE_REQ_ procedure has completed successfully. For more information about subdevices (SUs), refer to the OSI/FTAM Programming Guide or the OSI/FTAM and OSI/APLMGR SCF Reference Manual. error-code output INT .
PAGE 313
APS_STATUS_ APS Procedures transport-substate output INT .EXT:ref:1 indicates the substate qualifying the current transport state, if applicable, for the specified CEPI. This parameter is not used in NonStop FTAM operations and returns a value of 0. Considerations • • • • Because this procedure does not perform any file-system I/O operations, the request is always completed immediately after the procedure call. Even in nowait mode, do not call MFM_AWAITIOX_ to complete this procedure.
PAGE 314
APS_STATUS_ APS Procedures HP NonStop OSI/FTAM Programming Reference Manual—528611-001 F- 10
PAGE 315
G NonStop FTAM Programming Examples This appendix covers the following topics: Topic Page Example Structure and Protocol G-2 Example 1 in C—Updating a Remote File (in Nowait Mode) G-12 Example 1 in TAL—Updating a Remote File (in Nowait Mode) G-56 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) G-106 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) G-161 Translation Application Example G-221 This appendix contains sample programs that illustrate th
PAGE 316
NonStop FTAM Programming Examples Example Structure and Protocol Note. Besides making changes to the environmental variables contained in the programming examples in this manual, you might need to modify the examples to exclude certain procedure calls, depending upon the FTAM implementation with which you are interoperating.
PAGE 317
NonStop FTAM Programming Examples Example 1—Updating a Remote File (in Nowait Mode) Example 1—Updating a Remote File (in Nowait Mode) This programming example illustrates selective updating of an FTAM-2 file. It implements the routines for writing a FADU to a file on a remote system. All the FTAM routines operate in nowait mode. Nowait mode provides the benefits of improved performance in that it allows the program to perform multiple I/O operations concurrently.
PAGE 318
NonStop FTAM Programming Examples Example 1—Updating a Remote File (in Nowait Mode) Figure G-1.
PAGE 319
NonStop FTAM Programming Examples Example 1—Updating a Remote File (in Nowait Mode) Figure G-1.
PAGE 320
NonStop FTAM Programming Examples Example 2—Moving a File Between Two Remote Systems (in Wait Mode) Example 2—Moving a File Between Two Remote Systems (in Wait Mode) This programming example illustrates moving a simple binary file. This example implements the routines for moving an FTAM-3 file from one remote system to another remote system on the network. The FTAM routines used in this example operate in wait mode. The example does the following: 1. Establishes an APS segment. 2.
PAGE 321
NonStop FTAM Programming Examples Example 2—Moving a File Between Two Remote Systems (in Wait Mode) 16. Deselects the destination file. 17. Closes the source file. 18. Deletes the source file. 19. Terminates the association with the source system. 20. Terminates the association with the destination system. 21. Discards the association with the source system. 22. Discards the association with the destination system.
PAGE 322
Example 2—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples Figure G-2.
PAGE 323
Example 2—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples Figure G-2.
PAGE 324
Example 2—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples Figure G-2.
PAGE 325
Example 2—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples Figure G-2.
PAGE 326
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) Example 1 in C—Updating a Remote File (in Nowait Mode) 1 /***********************************************************************/ 2 /* */ 3 /* Example 1 in C - Updating a Remote FTAM-2 File (in Nowait Mode) */ 4 /* */ 5 /***********************************************************************/ 6 /* */ 7 /* Program Name: EXCINSF2 */ 8 /* */ 9 /* Program Description: */ 10 /* */ 11 /* This pro
PAGE 327
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 37 /* response procedures, as well as the */ 38 /* I/O completions */ 39 /* 40 /* */ check_error A procedure that checks for errors */ 41 /* returned by FTM indication and */ 42 /* confirm procedures */ 43 /* 44 /* */ check_action_diag A procedure that checks the action */ 45 /* result and diagnostic messages */ 46 /* returned by an FTM procedure */ 47 /* 48 /* */ bad_state A procedure 49 /
PAGE 328
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 76 77 /***********************************************************************/ 78 /* Source in */ 79 /* - APS and FTM structure definitions and literals */ 80 /* - External function declarations for FTM, APS, MFM, */ 81 /* and Guardian procedures */ 82 /***********************************************************************/ 83 84 #include "zapsc" /* APS DDL */ 85 #include "zftmc" /* FTM DDL */ 86
PAGE 329
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 115 #pragma LIST 116 117 /**********************************************************************/ 118 /* Global data declarations */ 119/***********************************************************************/ 120 121 /***********************************************************************/ 122 /* Environment-specific fields */ 123 /* You will need to change these fields to reflect your FTAM */ 124 /* environmen
PAGE 330
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 154 /**********************************************************************/ 155 156 #define NOCEPI -1 /* Indicates no valid CEPI */ 157 #define NOWAIT 0 /* Indicates nowait mode */ 158 #define WAIT_FOREVER /* MFM_AWAITIOX_ wait value */ 159 #define FALSE 0 /* Boolean value for FALSE */ 160 #define TRUE 1 /* Boolean value for TRUE */ 161 #define MAX_RECORDS 5 /* Maximum number of records */
PAGE 331
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 193 long buffer_addr; /* Returned buffer address */ 194 int count_transferred; /* Number of bytes read */ 195 int buf_count_transferred; /* Holding place for # of bytes */ 196 197 /**********************************************************************/ 198 /* Variables used by the FTM procedures */ 199 /**********************************************************************/ 200 201 long file_status; /*
PAGE 332
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 232 zaps_ddl_data_element_hdr_def *element_hdr_ptr; 233 zaps_ddl_data_hdr_def *data_hdr_ptr; 234 zaps_ddl_filename_def aplmgr_name; 235 zaps_ddl_appl_addr_def responding_appl; 236 zaps_ddl_appl_addr_def local_appl; 237 zftm_ddl_func_units_def func_units; 238 zftm_ddl_service_class_def service_class; 239 zaps_ddl_char128_def remote_file; 240 zaps_ddl_original_error_def original_error_info; 24
PAGE 333
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 271 /* */ 272 /* Name: insert */ 273 /* */ 274 /* Description: The insert program, written in nowait mode, updates */ 275 /* a file on a remote system of an OSI network by */ 276 /* inserting five records in it. This application */ 277 /* initiates and manages the data transfer. It reads */ 278 /* the data transferred from a local Guardian file.
PAGE 334
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 310 /*******************************************************************/ 311 312 error = APS_INITIALIZE_ (/* swapvol */); 313 if ( error != ZAPS_ERR_OK ) 314 { 315 printf ("Initialization of the FTAM/APS segment failed\n"); 316 exit (EXIT_SUCCESS); 317 } 318 319 /******************************************************************/ 320 /* The following sections initialize the various parameters */ 32
PAGE 335
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 349 local_appl.zpsap.znsap.zlen = 0; 350 local_appl.zappl_name.zlen = strlen (local_appl_name); 351 memcpy (local_appl.zappl_name.u_zc.zb, local_appl_name, 352 local_appl.zappl_name.zlen); 353 354 /**********************************************************************/ 355 /* Select the service class/classes required. This application needs */ 356 /* only the file-access service class.
PAGE 336
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 388 /**********************************************************************/ 389 390 contents_type_list.zcount = 1; 391 contents_type_list.zcntnts_type_ispresent = ZAPS_VAL_PRESENT; 392 contents_type_list.zcntnts_type_list[0].zid= ZFTM_VAL_CNTNTSLIST_DOCNAME; 393 contents_type_list.zcntnts_type_list[0].u_zcntntstype.zcntntstype. 394 znum_elements = 5; 395 memcpy ( contents_type_list.zcntnts_type_list[0].u_zcntntstype.
PAGE 337
NonStop FTAM Programming Examples 427 { 428 check_status (); 429 exit (EXIT_SUCCESS); 430 Example 1 in C—Updating a Remote File (in Nowait Mode) } 431 432 /**********************************************************************/ 433 /* The main control loop continues processing until an abort or */ 434 /* discard condition occurs, or until the last data request is sent.
PAGE 338
NonStop FTAM Programming Examples 466 if ( count_transferred != -1 ) 467 { 468 469 Example 1 in C—Updating a Remote File (in Nowait Mode) buf_count_transferred = count_transferred; } 470 471 472 473 if ( filenum != local_filenum ) /* Process the I/O completion of an FTAM or APS procedure or event */ { 474 475 /****************************************************************/ 476 /* Determine whether an FTAM I/O operation completed or an */ 477 /* event was received.
PAGE 339
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 505 FILEINFO ( local_filenum, &error ); 506 printf ("Local file error %d\n", error); 507 APS_DISCARD_ ( cepi ); 508 exit (EXIT_SUCCESS); 509 } 510 511 /****************************************************************/ 512 /* Verify that the local I/O completion was for a file read.
PAGE 340
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 544 CLOSE ( local_filenum ); 545 546 /*********************************************************************/ 547 /* Display a message to the terminal that an error occurred or that */ 548 /* the program completed successfully.
PAGE 341
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 583 { 584 585 /*******************************************************************/ 586 /* The tag value represents the type of FTM request or response */ 587 /* procedure associated with this I/O completion. The tag value */ 588 /* comes from the MFM_AWAITIOX_ call.
PAGE 342
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 622 /****************************************************************/ 623 /* The remote system is now set up for writing. Read the first */ 624 /* record from the file into the local buffer. The file was */ 625 /* opened in nowait mode.
PAGE 343
NonStop FTAM Programming Examples 661 if ( local_read_io_cmplt ) 662 { 663 664 Example 1 in C—Updating a Remote File (in Nowait Mode) data_transfer (); } 665 666 break; 667 668 case DATAEND_TAG: 669 /****************************************************************/ 670 /* All records have been transferred. Terminate the */ 671 /* data-transfer regime now.
PAGE 344
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 700 701 } /* end of case */ 702 703 } /* ftam_io_cmpl */ 704 705 706 #pragma PAGE "FTAM_EVENT_RCVD" 707 /**********************************************************************/ 708 /* */ 709 /* Name: ftam_event_rcvd */ 710 /* */ 711 /* Description: This procedure is called whenever an FTAM event is */ 712 /* received. It calls APS_STATUS_ to determine which */ 713 /* FTAM event has been received.
PAGE 345
NonStop FTAM Programming Examples 739 Example 1 in C—Updating a Remote File (in Nowait Mode) /********************************************************************/ 740 741 switch ( event_code ) 742 { 743 744 case ZFTM_VAL_EVT_INITIALIZE_CNF: init_cnf_open_req (); 745 break; 746 case ZFTM_VAL_EVT_FILEOPEN_CNF: 747 open_cnf_write_req (); 748 break; 749 case ZFTM_VAL_EVT_TRANSEND_CNF: 750 transend_cnf_close_req (); 751 break; 752 case ZFTM_VAL_EVT_FILECLOSE_CNF: 753 close_cnf_termina
PAGE 346
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 778 /* the action result and display any diagnostic messages. Then */ 779 /* set the flag to indicate that the file update is complete.
PAGE 347
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 817 /* The remote system has cancelled the transfer. Call */ 818 /* FTM_CANCEL_IND_ to get the action result and diagnostic */ 819 /* messages and FTM_CANCEL_RSP_ to acknowledge the indication */ 820 /* from the remote system. This terminates the data-transfer */ 821 /* regime.
PAGE 348
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 857 status = APS_EVENT_RECEIVE_ ( cepi 858 , /* WAIT_FOREVER */ 859 , (long) EVENTREC_TAG ); 860 861 check_status (); 862 } 863 864 } /* ftam_event_rcvd */ 865 866 867 #pragma PAGE "INIT_CNF_OPEN_REQ" 868 /*********************************************************************/ 869 /* 870 /* Name: 871 /* */ 872 /* Description: This procedure is called when an initialize confirm */ 873 /* is r
PAGE 349
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 896 , (int *) &local_appl 897 , (int *) &responding_appl 898 , /* remote_ae_title */ 899 , (int *) &service_class 900 , (int *) &func_units 901 , /* attr_groups */ 902 , (int *) &contents_type_list 903 , (int *) &diag ); 904 905 check_error (); 906 907 /*********************************************************************/ 908 /* Check the state result and the action result.
PAGE 350
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 935 , (long) ABORT_TAG ); 936 937 /******************************************************************/ 938 /* If the above abort request is sent to the remote system, */ 939 /* calling the main procedure sets the remote_file_update_cmpl */ 940 /* flag, and the program is terminated. If the request is not */ 941 /* sent out, set the flag here and return to the main procedure.
PAGE 351
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 974 = (long) MAX_READ_COUNT; 975 contents_type.u_zcntntstype.zdoctype.zstringsigispresent 976 = ZAPS_VAL_PRESENT; 977 contents_type.u_zcntntstype.zdoctype.zstringsig 978 = ZFTM_VAL_STRINGSIG_NOTSIG; 979 contents_type.u_zcntntstype.zdoctype.
PAGE 352
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1013 /*******************************************************************/ 1014 /* Initialize the remote-file-name parameter. The remote-file-name */ 1015 /* format is dependent on the remote system. 1016 /*******************************************************************/ */ 1017 1018 remote_file.zlen = strlen (remote_file_name); 1019 memcpy (remote_file.u_zc.zb, remote_file_name, remote_file.
PAGE 353
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1052 1053 1054 /*******************************************************************/ 1055 /* Issue the file-open request.
PAGE 354
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1091 1092 void open_cnf_write_req () 1093 1094 { 1095 1096 /******************************************************************/ 1097 /* Retrieve the file-open confirm data.
PAGE 355
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1130 fadu_op = ZFTM_VAL_FADU_OP_INSERT; 1131 1132 /*******************************************************************/ 1133 /* Specify the target FADU identity. Records can be inserted only */ 1134 /* at the end of an FTAM-2 file. */ 1135 /*******************************************************************/ 1136 1137 fadu_id.zid = ZFTM_VAL_FADUID_BEGINEND; 1138 fadu_id.u_zfaduid.
PAGE 356
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1169 /*********************************************************************/ 1170 1171 void transend_cnf_close_req () 1172 1173 { 1174 1175 /*****************************************************************/ 1176 /* Retrieve the transfer-end confirm data.
PAGE 357
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1208 1209 #pragma PAGE "CLOSE_CNF_TERMINATE_REQ" 1210 /*********************************************************************/ 1211 /* */ 1212 /* Name: close_cnf_terminate_req */ 1213 /* */ 1214 /* Description: This procedure is called when a file-close confirm */ 1215 /* is received. It calls FTM_FILE_CLOSE_CNF_ and */ 1216 /* checks the error status and state result.
PAGE 358
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1247 /******************************************************************/ 1248 /* The file has been closed. The association can be terminated.
PAGE 359
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1286 if ( records == MAX_RECORDS && remote_io_cmplt ) 1287 { 1288 1289 /*****************************************************************/ 1290 /* Issue the data-end primitive.
PAGE 360
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1325 /***************************************************************/ 1326 /* Initialize a pointer to the data-element header. Then set */ 1327 /* the length of the data to be transferred and the type of */ 1328 /* data to be transferred. The data length is returned from */ 1329 /* the local file-system read. The data type is set to text */ 1330 /* in this example.
PAGE 361
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1364 /***************************************************************/ 1365 /* Update the number of records that have been read. If 1366 /* the maximum number of records has been read, then return to */ 1367 /* the main control loop and wait for an I/O operation or */ 1368 /* an FTAM event to complete. Otherwise, read another record */ 1369 /* from the local Guardian file.
PAGE 362
NonStop FTAM Programming Examples 1403 Example 1 in C—Updating a Remote File (in Nowait Mode) } /* data_transfer */ 1404 1405 1406 #pragma PAGE "CHECK_STATUS" 1407 /*********************************************************************/ 1408 /* */ 1409 /* Name: check_status */ 1410 /* */ 1411 /* Description: The following procedure checks status returned from */ 1412 /* a previous FTAM procedure call. It checks for */ 1413 /* NORETRY, RETRYLATER, or DISCARD.
PAGE 363
Example 1 in C—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1442 error = APS_STATUS_ ( cepi 1443 , /* event_code */ 1444 , /* device_name */ 1445 , &error_code 1446 , &error_subcode 1447 , /* service_id */ 1448 , /* diagnostic_buffer */ 1449 , (int *) &original_error_info ); 1450 1451 check_error (); 1452 1453 /*******************************************************************/ 1454 /* Display the status code, error code, and error subcode.
PAGE 364
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1481 1482 case ZAPS_VAL_STATUS_NO_RETRY: 1483 case ZAPS_VAL_STATUS_RETRY_LATER: 1484 1485 /****************************************************************/ 1486 /* The nowait I/O completion indicates an error was detected, */ 1487 /* and the association should be aborted. If an abort request */ 1488 /* is in progress, do not issue another abort request.
PAGE 365
NonStop FTAM Programming Examples 1520 Example 1 in C—Updating a Remote File (in Nowait Mode) /**************************************************************/ 1521 1522 remote_file_update_cmplt = TRUE; 1523 1524 break; 1525 1526 default: /* Unknown status value */ 1527 1528 printf ("Unknown Status\n"); 1529 APS_DISCARD_ ( cepi ); 1530 exit (EXIT_FAILURE); 1531 1532 break; 1533 1534 } /* end of case */ 1535 1536 } /* check_status */ 1537 1538 1539 #pragma PAGE "CHECK_ERROR" 1540 /******
PAGE 366
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1559 1560 { 1561 1562 /******************************************************************/ 1563 /* Check for an error condition and display the error code. 1564 /******************************************************************/ */ 1565 1566 if ( error != ZAPS_ERR_OK ) 1567 { 1568 /*****************************************************************/ 1569 /* Display the error code.
PAGE 367
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1598 /* specific error handling or recovery could be */ 1599 /* implemented if required by an application.
PAGE 368
NonStop FTAM Programming Examples 1637 Example 1 in C—Updating a Remote File (in Nowait Mode) diag.zdiagelems[i].zfurtherdetails.u_zc.zb ); 1638 } 1639 1640 /******************************************************************/ 1641 /* Discard the API context information for the association and */ 1642 /* exit the program.
PAGE 369
NonStop FTAM Programming Examples Example 1 in C—Updating a Remote File (in Nowait Mode) 1676 1677 /******************************************************************/ 1678 /* Display the invalid state-result error message. You might also */ 1679 /* want to print out the diagnostic field to obtain more */ 1680 /* information about the error condition.
PAGE 370
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1 !-----------------------------------------------------------------------! 2 ! ! 3 ! Example 1 in TAL - Updating a Remote FTAM-2 File (in Nowait Mode) ! 4 ! ! 5 !-----------------------------------------------------------------------! 6 ! ! 7 ! Program Name: EXTINSF2 ! 8 ! ! 9 ! Program Description: ! 10 ! ! 11 ! This program, in no
PAGE 371
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 37 ! confirm procedures 38 ! 39 ! ! ! check_status A procedure that checks status ! 40 ! returned by FTM request and ! 41 ! response procedures as well as the ! 42 ! I/O completions ! 43 ! 44 ! ! bad_state 45 ! A procedure that handles an invalid ! FTAM state result ! 46 ! 47 ! ! check_action_diag A procedure that checks the action ! 48 ! result and diagnostic messages ! 49 ! returned
PAGE 372
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 76 77 ?nolist, source zftmtal ! FTM DDL ! ! APS DDL ! 78 ?list 79 ?nolist, source zapstal 80 ?list 81 ?nocode 82 ?nomap 83 84 !-----------------------------------------------------------------------! 85 ! Global data declarations ! 86 !-----------------------------------------------------------------------! 87 88 !-----------------------------------------------------------------------! 89 ! Macro for word add
PAGE 373
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 115 LITERAL NOWAIT = 0D; ! Indicates nowait mode ! 116 LITERAL WAIT_FOREVER = -1D; ! MFM_AWAITIOX_ wait value ! 117 LITERAL FALSE = 0; ! Boolean value for FALSE ! 118 LITERAL TRUE = 1; ! Boolean value for TRUE ! 119 LITERAL MAX_RECORDS = 5; ! Maximum number of records ! 120 LITERAL BASE = 10; ! Used with DNUMOUT as base ! 121 LITERAL MAX_BUF = 250; ! Maximum bytes to send ! 122 LITERAL
PAGE 374
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 154 INT wait_mode; ! Wait or nowait I/O ! 155 INT condition_code; ! Condition code ! 156 INT width; ! Used for DNUMOUT calls ! 157 158 !----------------------------------------------------------------------! 159 ! Variables used by the MFM_AWAITIOX_ procedure ! 160 !----------------------------------------------------------------------! 161 162 INT filenum; ! Returned by MFM_AWAITIOX_ ! 163 INT(32) b
PAGE 375
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 193 INT error_subcode; ! Returns error subcodes ! 194 INT file_error; ! Local file I/O errors ! 195 196 !----------------------------------------------------------------------! 197 ! Local and remote buffer pointers ! 198 !----------------------------------------------------------------------! 199 200 STRING .EXT remote_buffer[0:MAX_BUF-1]; ! Used for FTM_DATA_REQ_ 201 STRING .
PAGE 376
NonStop FTAM Programming Examples 232 INT infile [0:11]; 233 INT outfile [0:11]; 234 STRING params [0:131]; 235 Example 1 in TAL—Updating a Remote File (in Nowait Mode) END; 236 237 INT .
PAGE 377
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 271 ? , FTM_TRANSFER_END_REQ_ 272 ? , FTM_TRANSFER_END_CNF_ 273 ? , FTM_TERMINATE_REQ_ 274 ? , FTM_TERMINATE_CNF_ 275 ? , FTM_P_ABORT_IND_ 276 ? , FTM_U_ABORT_IND_ 277 ? , FTM_U_ABORT_REQ_ 278 ? , FTM_CANCEL_IND_ 279 ? , FTM_CANCEL_RSP_ 280 ? , APS_INITIALIZE_ 281 ? , APS_STATUS_ 282 ? , APS_EVENT_RECEIVE_ 283 ? , APS_DISCARD_ 284 ? , MFM_AWAITIOX_ 285 ? , ABEND 286 ? ,
PAGE 378
NonStop FTAM Programming Examples 310 FORWARD; 311 PROC FTAM_EVENT_RCVD; 312 FORWARD; 313 PROC FTAM_IO_CMPL; 314 FORWARD; Example 1 in TAL—Updating a Remote File (in Nowait Mode) 315 316 317 318 ?PAGE "proc INSERT" 319 !----------------------------------------------------------------------! 320 ! ! 321 ! Name: insert ! 322 ! ! 323 ! Description: The insert program, written in nowait mode, updates ! 324 ! a file on a remote system of an OSI network by ! 325 ! inserting five records i
PAGE 379
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 349 BEGIN 350 tempbuf ':=' "$RECEIVE open error" -> @text_ptr; 351 text_len := @text_ptr - @tempbuf; 352 CALL WRITE ( termnum, outbuf, text_len ); 353 CALL STOP; 354 END; 355 356 CALL READ ( fn, startup, $len(startup)); 357 IF <> THEN 358 BEGIN 359 tempbuf ':=' "$RECEIVE read error" -> @text_ptr; 360 text_len := @text_ptr - @tempbuf; 361 CALL WRITE ( termnum, outbuf, text_len ); 362 CALL STO
PAGE 380
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 388 ! Allocate and initialize a segment used by the FTM and APS ! 389 ! procedures.
PAGE 381
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 427 responding_appl.zappl^name.zlen BYTES; 428 429 local_appl.zpsap.zpsel.zlen := 0; 430 local_appl.zpsap.zssel.zlen := 0; 431 local_appl.zpsap.ztsel.zlen := 0; 432 local_appl.zpsap.znsap.zlen := 0; 433 local_appl.zappl^name.zlen 434 local_appl.zappl^name.zb 435 := $occurs(local_appl_name); ':=' local_appl_name FOR local_appl.zappl^name.
PAGE 382
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 466 func_units.zrestart := ZAPS^VAL^FALSE; 467 468 !---------------------------------------------------------------------! 469 ! Set up the contents-type-list to request a document of ! 470 ! type FTAM-2. The object ID breaks down as follows: ! 471 ! 1 = ISO, 0 = Standard, 8571 = FTAM, 5 = document type, ! 472 ! 2 = FTAM-2.
PAGE 383
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 505 , ! initiator_id - defaults to spaces ! 506 , ! account - defaults to spaces ! 507 , ! filestore_password - defaults to spaces ! 508 , $dbl (INITIALIZE_TAG) ); 509 510 511 IF ( status <> ZAPS^VAL^STATUS^OK ) THEN BEGIN 512 CALL check_status; 513 CALL STOP; 514 END; 515 516 !---------------------------------------------------------------------! 517 ! The main control loop continues processing u
PAGE 384
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 544 545 546 547 !-----------------------------------------------------------------! 548 ! If an I/O completion for READX is received, save the value of ! 549 ! count_transferred in buf_count_transferred for later use.
PAGE 385
NonStop FTAM Programming Examples 583 Example 1 in TAL—Updating a Remote File (in Nowait Mode) CALL ABEND; 584 END; 585 END 586 ELSE ! Process the local file I/O completion. ! 587 BEGIN 588 589 !--------------------------------------------------------------! 590 ! Check the condition code to determine if the local file ! 591 ! I/O operation completed successfully.
PAGE 386
NonStop FTAM Programming Examples 622 Example 1 in TAL—Updating a Remote File (in Nowait Mode) BEGIN 623 tempbuf ':=' "Invalid TAG" -> @text_ptr; 624 text_len := @text_ptr - @tempbuf; 625 CALL WRITE ( termnum, outbuf, text_len ); 626 CALL APS_DISCARD_ ( cepi ); 627 CALL ABEND; ! Unknown tag value.
PAGE 387
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 661 END; --- End INSERT --662 663 664 ?PAGE "proc FTAM_IO_CMPL" 665 !---------------------------------------------------------------------! 666 ! 667 ! Name: 668 ! ! 669 ! Description: This procedure processes I/O completions for FTM ! 670 ! request and response procedures. It uses the tag ! 671 ! field to determine which FTM procedure completed.
PAGE 388
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 700 ! completes.
PAGE 389
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 739 , BASE ); 740 text_len := @text_ptr - @tempbuf; 741 CALL WRITE ( termnum, outbuf, text_len ); 742 CALL APS_DISCARD_ ( cepi ); 743 CALL STOP; 744 END; 745 746 !--------------------------------------------------------------! 747 ! Set flags to indicate that the remote I/O operation is com- ! 748 ! plete (this is to know that there are no outstanding I/O ! 749 ! operations) and that there is a
PAGE 390
NonStop FTAM Programming Examples 778 Example 1 in TAL—Updating a Remote File (in Nowait Mode) ABORT_TAG -> 779 !--------------------------------------------------------------! 780 ! If an abort I/O operation completes, exit the main control ! 781 ! loop after returning from this routine.
PAGE 391
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 817 ! Output: None ! 818 ! ! 819 !-----------------------------------------------------------------------! 820 821 PROC ftam_event_rcvd; 822 823 BEGIN 824 825 826 ?PAGE "subproc INIT_CNF_OPEN_REQ" 827 !----------------------------------------------------------------------! 828 ! ! 829 ! Name: init_cnf_open_req ! 830 ! ! 831 ! Description: This subprocedure is called when an initialize ! 832 ! confirm
PAGE 392
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 856 , responding_appl 857 , ! remote_ae_title ! 858 , service_class 859 , func_units 860 , ! attr_groups ! 861 , contents_type_list 862 , diag ); 863 864 CALL check_error; 865 866 !--------------------------------------------------------------------! 867 ! Check the state result and the action result.
PAGE 393
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 895 status := FTM_U_ABORT_REQ_( cepi 896 , action_result 897 , ! diagnostic ! 898 , $dbl (ABORT_TAG) ); 899 900 !----------------------------------------------------------------! 901 ! If the above abort request is sent to the remote system, then ! 902 ! the calling main procedure sets the remote_file_update_cmplt ! 903 ! flag, and the program is terminated.
PAGE 394
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 934 !------------------------------------------------------------------! 935 ! Set the remaining contents_type.zdoctype elements to ! 936 ! ZAPS^VAL^ABSENT. ! 937 !------------------------------------------------------------------! 938 contents_type.zdoctype.
PAGE 395
NonStop FTAM Programming Examples 973 Example 1 in TAL—Updating a Remote File (in Nowait Mode) !--------------------------------------------------------------------! 974 975 !--------------------------------------------------------------------! 976 ! Initialize the remote-file-name parameter. The remote-file-name ! 977 ! format is dependent on the remote system. ! 978 !--------------------------------------------------------------------! 979 980 remote_file.
PAGE 396
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1012 process_mode.zextend := ZAPS^VAL^FALSE; 1013 process_mode.zerase := ZAPS^VAL^FALSE; 1014 1015 !--------------------------------------------------------------------! 1016 ! Issue the file-open request.
PAGE 397
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1051 ! ! 1052 !---------------------------------------------------------------------! 1053 1054 SUBPROC open_cnf_write_req; 1055 1056 BEGIN 1057 1058 !------------------------------------------------------------------! 1059 ! Retrieve the file-open confirm data.
PAGE 398
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1090 !------------------------------------------------------------------! 1091 1092 fadu_op := ZFTM^VAL^FADU^OP^INSERT; 1093 1094 !-----------------------------------------------------------------! 1095 ! Specify the target FADU identity. Records can be inserted ! 1096 ! only at the end of an FTAM-2 file. ! 1097 !-----------------------------------------------------------------! 1098 1099 fadu_id.
PAGE 399
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1129 ! Output: File-deselect/close request to remote responder ! 1130 ! 1131 !--------------------------------------------------------------------! ! 1132 1133 SUBPROC transend_cnf_close_req; 1134 1135 BEGIN 1136 1137 !-----------------------------------------------------------------! 1138 ! Retrieve the transfer-end confirm data.
PAGE 400
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1168 END; --- transend_cnf_close_req --- 1169 1170 1171 1172 ?PAGE "subproc CLOSE_CNF_TERMINATE_REQ" 1173 !--------------------------------------------------------------------! 1174 ! 1175 ! Name: 1176 ! ! 1177 ! Description: This subprocedure is called when a file-close ! 1178 ! confirm is received. It calls FTM_FILE_CLOSE_CNF_ ! 1179 ! and checks the error status and state result.
PAGE 401
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1207 CALL check_action_diag; 1208 1209 !-------------------------------------------------------------------! 1210 ! The file has been closed. The association can be terminated.
PAGE 402
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1246 CALL open_cnf_write_req; 1247 1248 1249 ZFTM^VAL^EVT^TRANSEND^CNF -> CALL transend_cnf_close_req; 1250 1251 1252 ZFTM^VAL^EVT^FILECLOSE^CNF -> CALL close_cnf_terminate_req; 1253 1254 ZFTM^VAL^EVT^TERMINATE^CNF -> 1255 1256 !------------------------------------------------------------! 1257 ! Retrieve the terminate-confirm data.
PAGE 403
NonStop FTAM Programming Examples 1285 CALL check_error; 1286 CALL check_action_diag; Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1287 1288 tempbuf ':=' "The association has been aborted" -> @text_ptr; 1289 text_len := @text_ptr - @tempbuf; 1290 CALL WRITE ( termnum, outbuf, text_len ); 1291 1292 remote_file_update_cmplt := TRUE; 1293 1294 ZFTM^VAL^EVT^UABORT^IND -> 1295 1296 !------------------------------------------------------------! 1297 ! Retrieve the user-abort indicat
PAGE 404
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1324 error := FTM_CANCEL_IND_ ( cepi 1325 , action_result 1326 , diag ); 1327 1328 CALL check_error; 1329 CALL check_action_diag; 1330 1331 tempbuf ':=' "The data transfer has been cancelled" -> @text_ptr; 1332 text_len := @text_ptr - @tempbuf; 1333 CALL WRITE ( termnum, outbuf, text_len ); 1334 1335 status := FTM_CANCEL_RSP_ ( cepi 1336 , ! action_result ! 1337 , ! diag ! ); 1338 1339 CALL ch
PAGE 405
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1363 1364 CALL check_status; 1365 END; 1366 1367 END; --- ftam_event_rcvd --- 1368 1369 1370 ?PAGE "proc DATA_TRANSFER" 1371 !--------------------------------------------------------------------! 1372 ! 1373 ! Name: 1374 ! ! 1375 ! Description: This procedure is called when a Guardian read or ! 1376 ! FTM data request completes.
PAGE 406
NonStop FTAM Programming Examples 1402 Example 1 in TAL—Updating a Remote File (in Nowait Mode) !--------------------------------------------------------------! 1403 1404 status := FTM_DATA_END_REQ_ ( cepi 1405 , ! action_result ! 1406 , ! diag ! 1407 , $dbl (DATAEND_TAG) ); 1408 1409 CALL check_status; 1410 RETURN; 1411 END; 1412 1413 !----------------------------------------------------------------! 1414 ! Once both the local read from the file system and the previous ! 1415 ! FTM d
PAGE 407
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1441 !--------------------------------------------------------------! 1442 1443 @element_hdr_ptr := @data_hdr_ptr + $udbl ($len (data_hdr_ptr)); 1444 element_hdr_ptr.zlen := $dbl ( buf_count_transferred ); 1445 element_hdr_ptr.
PAGE 408
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1480 records := records + 1; 1481 IF ( records < MAX_RECORDS ) THEN 1482 BEGIN 1483 !------------------------------------------------------------! 1484 ! Read the next record from the file.
PAGE 409
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1519 !--------------------------------------------------------------------! 1520 ! 1521 ! Name: 1522 ! ! 1523 ! Description: The following procedure checks status returned from ! 1524 ! a previous FTAM procedure call. It checks for ! 1525 ! NORETRY, RETRYLATER, or DISCARD.
PAGE 410
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1558 , error_subcode 1559 , ! service_id ! 1560 , ! diagnostic_buffer ! 1561 , original_error_info ); 1562 1563 CALL check_error; 1564 1565 !----------------------------------------------------------------! 1566 ! Display the status code.
PAGE 411
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1597 tempbuf ':=' "ERROR SUBCODE # " -> @text_ptr; 1598 IF (error_subcode < 0) THEN 1599 BEGIN 1600 error_subcode := -error_subcode; 1601 text_ptr ':=' "-" -> @text_ptr; 1602 END; 1603 @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1604 , $DBL ( error_subcode ) 1605 , BASE ); 1606 text_len := @text_ptr - @tempbuf; 1607 CALL WRITE ( termnum, outbuf, text_len ); 1608 1609 !-------------------------
PAGE 412
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1636 text_len := @text_ptr - @tempbuf; 1637 CALL WRITE ( termnum, outbuf, text_len ); 1638 1639 tempbuf ':=' " ERROR SUBCODE # " -> @text_ptr; 1640 IF ( original_error_info.zerror.zerror^subcode < 0) THEN 1641 BEGIN 1642 original_error_info.zerror.zerror^subcode 1643 1644 := -original_error_info.zerror.
PAGE 413
NonStop FTAM Programming Examples 1675 1676 Example 1 in TAL—Updating a Remote File (in Nowait Mode) BEGIN status := FTM_U_ABORT_REQ_ ( cepi 1677 , ! action_result ! 1678 , ! diag ! 1679 , $dbl (ABORT_TAG) ); 1680 1681 !------------------------------------------------------------! 1682 ! If the above abort request is sent to the remote system, 1683 ! ! calling the main procedure sets the remote_file_update_cmplt flag,! 1684 ! and the program is terminated.
PAGE 414
NonStop FTAM Programming Examples 1714 CALL APS_DISCARD_ ( cepi ); 1715 CALL ABEND; Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1716 1717 END; 1718 1719 END; --- check_status --- 1720 1721 1722 ?PAGE "proc CHECK_ERROR" 1723 !--------------------------------------------------------------------! 1724 ! 1725 ! Name: 1726 ! ! 1727 ! Description: The following procedure checks the error code ! 1728 ! returned from an FTM or APS procedure.
PAGE 415
NonStop FTAM Programming Examples 1753 Example 1 in TAL—Updating a Remote File (in Nowait Mode) !-----------------------------------------------------------------! 1754 1755 tempbuf ':=' "ERROR # " -> @text_ptr; 1756 IF (error_code < 0) THEN 1757 BEGIN 1758 error_code := -error_code; 1759 text_ptr ':=' "-" -> @text_ptr; 1760 END; 1761 @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1762 , $DBL ( error_code ) 1763 , BASE ); 1764 text_len := @text_ptr - @tempbuf; 1765 CALL WRITE ( termnum
PAGE 416
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1792 ! diagnostic message and error ID for each diagnostic ! 1793 ! message element, discards the association, and the ! 1794 ! program exits normally. Additional application- ! 1795 ! specific error handling or recovery could be ! 1796 ! implemented if required by an application.
PAGE 417
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1831 ! Display the diagnostic message type and error ID for each ! 1832 ! diagnostic message. ! 1833 !--------------------------------------------------------------! 1834 1835 FOR i := 0 TO diag.zdiagcount-1 DO 1836 BEGIN 1837 tempbuf ':=' " Diagnostic Type: " -> @text_ptr; 1838 text_len := @text_ptr - @tempbuf; 1839 width := DNUMOUT ( tempbuf[text_len] 1840 , $DBL ( diag.zdiagelems[i].
PAGE 418
NonStop FTAM Programming Examples Example 1 in TAL—Updating a Remote File (in Nowait Mode) 1870 CALL APS_DISCARD_ ( cepi ); 1871 tempbuf ':=' "Association discarded" -> @text_ptr; 1872 text_len := @text_ptr - @tempbuf; 1873 CALL WRITE ( termnum, outbuf, text_len ); 1874 CALL STOP; 1875 1876 END; 1877 1878 END; --- check_action_diag --- 1879 1880 1881 ?PAGE "proc BAD_STATE" 1882 !---------------------------------------------------------------------! 1883 ! ! 1884 ! Name: bad_state ! 1885
PAGE 419
Example 1 in TAL—Updating a Remote File (in Nowait Mode) NonStop FTAM Programming Examples 1909 1910 tempbuf ':=' "BAD STATE # " -> @text_ptr; 1911 text_len := @text_ptr - @tempbuf; 1912 width := DNUMOUT ( tempbuf[text_len] 1913 , $DBL ( state_result ) 1914 , BASE ); 1915 tempbuf[text_len + width] ':=' " Association aborted" -> @text_ptr; 1916 text_len := @text_ptr - @tempbuf; 1917 CALL WRITE ( termnum, outbuf, text_len ); 1918 1919 !-------------------------------------------------------
PAGE 420
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1 /*************************************************************************/ 2 /* */ 3 /* Example 2 in C - Moving an FTAM-3 File Between Two Remote Systems */ 4 /* (in Wait Mode) */ 5 /* */ 6 /************************************************************************/ 7 /* */ 8 /* Program Name: EXCMOVF3 */ 9 /* */ 10 /*
PAGE 421
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 37 /* check_status 38 /* A procedure that checks status returned */ by FTM procedure calls. */ 39 /* 40 /* */ check_error 41 /* A procedure that checks for errors */ returned by FTM procedure calls. */ 42 /* 43 /* */ check_state 44 /* A procedure that handles a failed state */ in the remote FTAM regime.
PAGE 422
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 76 77 #pragma nolist 78 #include 79 #include 80 #include 81 #include 82 83 /***********************************************************************/ 84 /* Include */ 85 /* - APS and FTM structure definitions and literals */ 86 /* - External function declarations for FTM, APS, and Guardian */ 87 /********************************************************
PAGE 423
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 115 , FTM_DATA_END_REQ_ \ 116 , FTM_DATA_END_IND_ \ 117 , FTM_TRANSFER_END_REQ_ \ 118 , FTM_TRANSFER_END_CNF_ \ 119 , FTM_TERMINATE_REQ_ \ 120 , FTM_TERMINATE_CNF_ \ 121 , FTM_CANCEL_IND_ \ 122 , FTM_CANCEL_REQ_ \ 123 , FTM_CANCEL_RSP_ \ 124 , FTM_CANCEL_CNF_ \ 125 , FTM_P_ABORT_IND_ \ 126 , FTM_U_ABORT_IND_ \ 127 , FTM_U_ABORT_REQ_ \ 128 , APS_INITIALIZE_ \ 12
PAGE 424
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 154 #define dst_filename "$VOLUME.SUBVOL.
PAGE 425
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 193 int src_con_established = FALSE; /* Src association existence flag */ 194 int dst_con_established = FALSE; /* Dst association existence flag */ 195 196 /**********************************************************************/ 197 /* Error-handling variables */ 198 /**********************************************************************/ 199 200 int status; /* Used for I/O request calls */
PAGE 426
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 232 zaps_ddl_char32_def initiator_id; 233 zaps_ddl_char32_def account; 234 zaps_ddl_char32_def filestore_password; 235 zftm_ddl_func_units_def src_func_units; 236 zftm_ddl_func_units_def dst_func_units; 237 zftm_ddl_attr_groups_def src_attr_groups; 238 zftm_ddl_attr_groups_def dst_attr_groups; 239 zftm_ddl_cntnts_list_def src_contents_type_list; 240 zftm_ddl_cntnts_list_def dst_content
PAGE 427
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 271 void bad_event ( int event, int cepi ); 272 void check_action_diag (); 273 void abort_discard (); 274 275 276 #pragma PAGE "MOVEFILE" 277 /**********************************************************************/ 278 /* */ 279 /* Name: movefile */ 280 /* */ 281 /* Description: The movefile program, written in wait mode, moves a */ 282 /* file between two systems on an OSI network.
PAGE 428
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 310 311 /*******************************************************************/ 312 /* The following sections initialize the various parameters */ 313 /* for the FTM_INITIALIZE_REQ_ procedure.
PAGE 429
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 349 local_appl.zpsap.znsap.zlen = 0; 350 local_appl.zappl_name.zlen = strlen (local_appl_name); 351 memcpy (local_appl.zappl_name.u_zc.zb, local_appl_name, 352 local_appl.zappl_name.zlen); 353 354 355 /*******************************************************************/ 356 /* The ae_title and src_ae_title parameters are optional */ 357 /* parameters supplied for example only.
PAGE 430
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 388 func_units.zfilemgmtenhanced = ZAPS_VAL_FALSE; 389 func_units.zgroup = ZAPS_VAL_TRUE; 390 func_units.zfadulock = ZAPS_VAL_FALSE; 391 func_units.zrecovery = ZAPS_VAL_FALSE; 392 func_units.zrestart = ZAPS_VAL_FALSE; 393 394 /*******************************************************************/ 395 /* Select the required attribute groups.
PAGE 431
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 427 428 initiator_id.zlen = strlen (init_id); 429 memcpy ( initiator_id.u_zc.zb, init_id, initiator_id.zlen); 430 431 account.zlen = strlen (charge_account); 432 memcpy ( account.u_zc.zb, charge_account, account.
PAGE 432
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 466 , (int *) &src_appl 467 , (int *) &src_ae_title 468 , /* src_service_class */ 469 , (int *) &src_func_units 470 , (int *) &src_attr_groups 471 , (int *) &src_contents_type_list 472 , (int *) &diag ); 473 474 check_error (); 475 check_action_diag (); 476 check_state (); 477 478 /********************************************************************/ 479 /* The source association
PAGE 433
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 505 /* not available, then abort the association and exit. Additional */ 506 /* application-specific error handling or recovery could be */ 507 /* implemented if required by an application. */ 508 /*******************************************************************/ 509 510 if ( src_attr_groups.zstorage != ZAPS_VAL_TRUE || 511 src_attr_groups.
PAGE 434
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 544 func_units.zwrite = ZAPS_VAL_TRUE; 545 func_units.zfilemgmt 546 func_units.zfilemgmtenhanced = ZAPS_VAL_TRUE; 547 func_units.zgroup = ZAPS_VAL_TRUE; = ZAPS_VAL_TRUE; 548 549 /*******************************************************************/ 550 /* Set the wait mode for the association to waited.
PAGE 435
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 583 , (int *) &dst_attr_groups 584 , (int *) &dst_contents_type_list 585 , (int *) &diag ); 586 587 check_error (); 588 check_action_diag (); 589 check_state (); 590 591 /*******************************************************************/ 592 /* The destination association has been established.
PAGE 436
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 622 /* implemented if required by an application. 623 /*******************************************************************/ 624 if ( dst_attr_groups.zstorage != ZAPS_VAL_TRUE || 625 dst_attr_groups.
PAGE 437
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 661 /*******************************************************************/ 662 /* Establish the source-file file-selection and file-open regimes.
PAGE 438
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 700 /* Provide the access password for each action to be performed on */ 701 /* the file. */ 702 /*******************************************************************/ 703 704 access_passwords.zreadpasswd.zlen = strlen (password); 705 memcpy(access_passwords.zreadpasswd.u_zc.zb, password, 706 access_passwords.zreadpasswd.zlen); 707 access_passwords.zinsertpasswd.
PAGE 439
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 739 740 /*******************************************************************/ 741 /* Set file availability and future filesize to ZAPS_VAL_TRUE. 742 /*******************************************************************/ */ 743 744 attr_names.zfileavlblty = ZAPS_VAL_TRUE; 745 attr_names.
PAGE 440
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 778 attr_names.zprivateuse = ZAPS_VAL_FALSE; 779 780 /*******************************************************************/ 781 /* Initialize parameters for the to FTM_OPEN_REQ_ procedure call.
PAGE 441
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 817 check_status ( src_cepi ); 818 819 status = FTM_OPEN_REQ_ ( src_cepi 820 , (int *) &process_mode 821 , (int *) &contents_type ); 822 check_status ( src_cepi ); 823 824 status= FTM_END_GROUP_REQ_ ( src_cepi ); 825 check_status ( src_cepi ); 826 827 /*******************************************************************/ 828 /* Call the following procedures to process the confirms retur
PAGE 442
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 856 check_action_diag (); 857 858 event = ZFTM_VAL_EVT_OPEN_CNF; 859 get_event ( &event, src_cepi ); 860 error = FTM_OPEN_CNF_ ( src_cepi 861 , (long *) &state_result 862 , (long *) &action_result 863 , (int *) &contents_type 864 , (int *) &diag ); 865 check_error (); 866 check_action_diag (); 867 check_state (); 868 869 event = ZFTM_VAL_EVT_ENDGROUP_CNF; 870 get_event ( &event
PAGE 443
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 895 initial_attr.zfilename.zlen); 896 initial_attr.zcntntstypevalue.zid = ZFTM_VAL_CNTNTSTYPE_DOCTYPE; 897 initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.zdoctypename. 898 znum_elements = num_elem; 899 memcpy(initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.zdoctypename. 900 zobj_id, ftam_doc_type, sizeof (ftam_doc_type)); 901 902 903 904 905 initial_attr.zcntntstypevalue.
PAGE 444
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 934 935 /*Security group */ 936 initial_attr.zaccesscntrlattrispresent = ZAPS_VAL_PRESENT; 937 938 /*******************************************************************/ 939 /* Set the next two attributes to allow write and change- */ 940 /* attribute capabilities during the move.
PAGE 445
NonStop FTAM Programming Examples 973 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) /*******************************************************************/ 974 975 override = ZFTM_VAL_OVR_CREATE_NEW; 976 977 /*******************************************************************/ 978 /* Set the requested_access parameter to provide replace and */ 979 /* change-attribute access on the file.
PAGE 446
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1012 /* file. */ 1013 /*******************************************************************/ 1014 1015 process_mode.zread = ZAPS_VAL_FALSE; 1016 process_mode.zinsert = ZAPS_VAL_FALSE; 1017 process_mode.zreplace = ZAPS_VAL_TRUE; 1018 process_mode.zextend = ZAPS_VAL_FALSE; 1019 process_mode.
PAGE 447
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1051 /* Call the following procedures to process the confirms returned */ 1052 /* by each request. The begin-group and end-group requests do not */ 1053 /* have separate confirm functions but, if successful, they */ 1054 /* result in confirm events. Call a get_event for each.
PAGE 448
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1090 /*******************************************************************/ 1091 1092 /*******************************************************************/ 1093 /* Initialize parameters for the FTM_WRITE_REQ_ and FTM_READ_REQ_ */ 1094 /* procedures.
PAGE 449
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1129 , (int *) &src_fadu_id 1130 , (int *) &access_context ); 1131 check_status ( src_cepi ); 1132 1133 /*******************************************************************/ 1134 /* Wait for a data indication from the source association.
PAGE 450
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1168 1169 error = FTM_DATA_IND_ ( src_cepi 1170 , (long) MAX_BUF 1171 , (char *) &data_value 1172 , (long *) &src_more_data 1173 , (long *) &src_next_position 1174 , src_start_position ); 1175 check_error (); 1176 1177 /************************************************************/ 1178 /* Call FTM_DATA_REQ_ to write data to the remote system.
PAGE 451
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1207 break; 1208 1209 case ZFTM_VAL_EVT_CANCEL_IND : 1210 1211 /*************************************************************/ 1212 /* The source system has cancelled the transfer. Call the */ 1213 /* indication procedure to get the error and action result, */ 1214 /* and then send a response to the source system.
PAGE 452
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1246 1247 default : 1248 bad_event ( event, src_cepi ); 1249 } 1250 1251 } 1252 while ( event == ZFTM_VAL_EVT_DATA_IND ); 1253 1254 /*End of file transfer loop */ 1255 1256 1257 /*******************************************************************/ 1258 /* Issue an FTM_TRANSFER_END_REQ_ call to the source and */ 1259 /* destination systems and wait for the respective confirms.
PAGE 453
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1285 check_action_diag (); 1286 1287 /*****************************************************************/ 1288 /* Terminate the destination-file data-transfer regime.
PAGE 454
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1324 if ( file_attr.zaccesscntrlattrispresent == ZAPS_VAL_PRESENT ) 1325 { 1326 change_attr.zaccesscntrlispresent = ZAPS_VAL_PRESENT; 1327 change_attr.zaccesscntrl.zid = ZFTM_VAL_ATTR_ISPRESENT; 1328 change_attr.zaccesscntrl.zinsertispresent = ZAPS_VAL_PRESENT; 1329 change_attr.zaccesscntrl.zinsertvalues = file_attr. 1330 zaccesscntrlattr.
PAGE 455
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1363 /* in response to each request. The begin-group and end-group */ 1364 /* requests do not have separate confirm procedures but, if */ 1365 /* successful, they result in confirm events. Call get-event */ 1366 /* for each.
PAGE 456
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1402 error = FTM_DESELECT_CNF_ ( dst_cepi 1403 , (long *) &action_result 1404 , (int *) &dst_charging 1405 , (int *) &diag ); 1406 check_error (); 1407 check_action_diag (); 1408 1409 event = ZFTM_VAL_EVT_ENDGROUP_CNF; 1410 get_event ( &event, dst_cepi ); 1411 1412 1413 /*******************************************************************/ 1414 /* Terminate the source-file file-open a
PAGE 457
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1441 status = FTM_END_GROUP_REQ_ ( src_cepi ); 1442 check_status ( src_cepi ); 1443 1444 /*******************************************************************/ 1445 /* Call the following procedures to process the confirms returned */ 1446 /* in response to each request.
PAGE 458
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1480 1481 event = ZFTM_VAL_EVT_ENDGROUP_CNF; 1482 get_event ( &event, src_cepi ); 1483 1484 1485 /*******************************************************************/ 1486 /* Terminate the source-file FTAM regime.
PAGE 459
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1519 1520 check_error (); 1521 1522 /*******************************************************************/ 1523 /* Discard the API context information for the source association.
PAGE 460
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1558 /* Input: Expected_event, the event that the procedure */ 1559 /* expects to receive on the association */ 1560 /* */ 1561 /* CEPI identifying the association that carries the */ 1562 /* event */ 1563 /* */ 1564 /* Output: Expected_event, which contains the value of */ 1565 /* the received event */ 1566 /*********************************************************************/ 1
PAGE 461
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1597 check_error (); 1598 1599 /*****************************************************************/ 1600 /* Verify that the expected event was received. If the expected */ 1601 /* event = ANYEVENT, then any event code is valid.
PAGE 462
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1636 /* Output: Error messages to terminal 1637 /* */ */ 1638 /*********************************************************************/ 1639 1640 void check_status ( cepi ) 1641 1642 int cepi; 1643 1644 { 1645 1646 /*******************************************************************/ 1647 /* Check for a good status.
PAGE 463
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1675 1676 /*******************************************************************/ 1677 /* Display the error code and subcode.
PAGE 464
NonStop FTAM Programming Examples 1714 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) } 1715 1716 case ZAPS_VAL_STATUS_DISCARD: 1717 { 1718 /**************************************************************/ 1719 /* A status of DISCARD returned on an FTM request indicates */ 1720 /* that the association associated with that CEPI has been */ 1721 /* lost.
PAGE 465
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1753 /*********************************************************************/ 1754 /* */ 1755 /* Name: check_error */ 1756 /* */ 1757 /* Description: The check_error procedure checks error codes */ 1758 /* returned by FTM procedure calls.
PAGE 466
NonStop FTAM Programming Examples 1792 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) abort_discard (); 1793 1794 exit (EXIT_SUCCESS); 1795 1796 } 1797 1798 } /*** check_error ***/ 1799 1800 1801 #pragma PAGE "CHECK_STATE" 1802 /*********************************************************************/ 1803 /* */ 1804 /* Name: check_state */ 1805 /* */ 1806 /* Description: The check_state procedure checks for a state */ 1807 /* result of failure on an FTM confirm.
PAGE 467
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1831 1832 1833 #pragma PAGE "BAD_EVENT" 1834 /*********************************************************************/ 1835 /* */ 1836 /* Name: bad_event */ 1837 /* */ 1838 /* Description: The bad_event procedure is called when an */ 1839 /* unexpected event is received from one of the */ 1840 /* associations. The event can be an abort indication.
PAGE 468
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1870 /*****************************************************************/ 1871 /* Retrieve the action result and diagnostic messages for the */ 1872 /* P-abort.
PAGE 469
NonStop FTAM Programming Examples 1909 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) { 1910 status = FTM_U_ABORT_REQ_ ( src_cepi 1911 , /* action_result */ 1912 , /* diagnostics */ ); 1913 check_status ( src_cepi ); 1914 } 1915 if ( dst_con_established ) 1916 { 1917 status = FTM_U_ABORT_REQ_ ( dst_cepi 1918 , /* action_result */ 1919 , /* diagnostics */ ); 1920 check_status ( dst_cepi ); 1921 1922 } } 1923 1924 /******************************************
PAGE 470
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 1948 1949 1950 #pragma PAGE "CHECK_ACTION_DIAG" 1951 /*********************************************************************/ 1952 /* */ 1953 /* Name: check_action_diag */ 1954 /* */ 1955 /* Description: The check_action_diag procedure determines whether */ 1956 /* the action requested of a remote responder was */ 1957 /* successful or not.
PAGE 471
NonStop FTAM Programming Examples 1987 Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) { 1988 printf (" Diagnostic Type: %ld\n", diag.zdiagelems[i].zdiagtype ); 1989 printf (" Error ID: %ld\n", diag.zdiagelems[i].zerrorid ); 1990 if (diag.zdiagelems[i].zfurtherdetailsispresent == ZAPS_VAL_PRESENT) 1991 printf (" Details: %s\n", 1992 diag.zdiagelems[i].zfurtherdetails.u_zc.
PAGE 472
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 2026 /*******************************************************************/ 2027 /* Initialize the parameters for the U-abort request.
PAGE 473
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2065 , action_result 2066 , (int *) &diag ); 2067 if (status != ZAPS_VAL_STATUS_OK) 2068 { 2069 printf ("Abort of the source association failed\n"); 2070 } 2071 2072 } 2073 2074 /*******************************************************************/ 2075 /* Abort the destination association if it exists.
PAGE 474
NonStop FTAM Programming Examples Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode) 2104 } /*** abort_discard ***/ 2105 2106 HP NonStop OSI/FTAM Programming Reference Manual—528611-001 G - 160
PAGE 475
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1 !-----------------------------------------------------------------------! 2 ! ! 3 ! Example 2 in TAL - Moving an FTAM-3 File Between Two Remote Systems ! 4 ! (in Wait Mode) ! 5 ! ! 6 !-----------------------------------------------------------------------! 7 ! ! 8 ! Program Name : EXTMOVF3 ! 9 ! ! 10 !
PAGE 476
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 37 ! by FTM procedure calls. 38 ! 39 ! ! check_error 40 ! A procedure that checks for errors ! returned by FTM procedure calls. ! 41 ! 42 ! ! check_state 43 ! A procedure that handles a failed state ! in the remote FTAM regime. ! 44 ! 45 ! ! bad_event 46 ! A procedure that handles unexpected ! FTAM events.
PAGE 477
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 76 77 !-----------------------------------------------------------------------! 78 ! Source in the FTM and APS structure definitions and literals from ! 79 ! the appropriate volume and subvolume.
PAGE 478
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 115 ! You will need to change these fields to reflect your FTAM ! 116 ! environment. src_filename and dst_filename must be valid file ! 117 ! names for the respective source and remote systems. In this example, ! 118 ! src_file and dst_file are Guardian files.
PAGE 479
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 154 155 !----------------------------------------------------------------------! 156 ! Boolean control variables ! 157 !----------------------------------------------------------------------! 158 159 INT src_con_established := FALSE; ! Src association existence flag ! 160 INT dst_con_established := FALSE; ! Dst association existence flag ! 161 162 !----------------------------------------------
PAGE 480
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 193 STRUCT .EXT ae_title ( ZAPS^DDL^AE^TITLE^DEF ); 194 STRUCT .EXT src_ae_title ( ZAPS^DDL^AE^TITLE^DEF ); 195 STRUCT .EXT dst_ae_title ( ZAPS^DDL^AE^TITLE^DEF ); 196 STRUCT .EXT func_units ( ZFTM^DDL^FUNC^UNITS^DEF ); 197 STRUCT .EXT attr_groups ( ZFTM^DDL^ATTR^GROUPS^DEF ); 198 STRUCT .EXT contents_type_list ( ZFTM^DDL^CNTNTS^LIST^DEF ); 199 STRUCT .
PAGE 481
NonStop FTAM Programming Examples 232 INT msg_code; 233 INT default_vol [0:7]; 234 INT infile [0:11]; 235 INT outfile [0:11]; 236 STRING params [0:131]; 237 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) END; 238 239 INT .
PAGE 482
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 271 ? , FTM_DELETE_CNF_ 272 ? , FTM_CREATE_REQ_ 273 ? , FTM_CREATE_CNF_ 274 ? , FTM_CLOSE_REQ_ 275 ? , FTM_CLOSE_CNF_ 276 ? , FTM_BEGIN_GROUP_REQ_ 277 ? , FTM_END_GROUP_REQ_ 278 ? , FTM_READ_ATTRIB_REQ_ 279 ? , FTM_READ_ATTRIB_CNF_ 280 ? , FTM_CHANGE_ATTRIB_REQ_ 281 ? , FTM_CHANGE_ATTRIB_CNF_ 282 ? , FTM_WRITE_REQ_ 283 ? , FTM_READ_REQ_ 284 ? , FTM_DATA_IND_ 285 ? , FTM_D
PAGE 483
NonStop FTAM Programming Examples 310 ? Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) , DNUMOUT ) 311 ?list 312 313 !----------------------------------------------------------------------! 314 ! Forward declarations ! 315 !----------------------------------------------------------------------! 316 317 PROC get_event ( expected_event, cepi ); 318 INT .
PAGE 484
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 349 ! Description: The movefile program written in wait mode moves a ! 350 ! file between two systems on an OSI network. This ! 351 ! application initiates and manages the file transfer.
PAGE 485
NonStop FTAM Programming Examples 388 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) CALL CLOSE ( fn ); 389 390 !------------------------------------------------------------------! 391 ! Allocate and initialize a segment used by the FTM and APS ! 392 ! procedures.
PAGE 486
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 427 !------------------------------------------------------------------! 428 429 src_appl.zpsap.zpsel.zlen := 0; 430 src_appl.zpsap.zssel.zlen := 0; 431 src_appl.zpsap.ztsel.zlen := 0; 432 src_appl.zpsap.znsap.zlen := 0; 433 src_appl.zappl^name.zlen 434 src_appl.zappl^name.zb := $occurs(src_appl_name); ':=' src_appl_name FOR 435 src_appl.zappl^name.zlen BYTES; 436 437 dst_appl.
PAGE 487
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 466 src_ae_title.zae^title^type := zaps^val^ae^title^format2; 467 src_ae_title.zae^title^format2.zae^qualifier^ispresent := 468 ZAPS^VAL^PRESENT; 469 src_ae_title.zae^title^format2.zae^qualifier := src_ae_qualifier; 470 src_ae_title.zae^title^format2.zap^title.znum^elements := NUM_ELEM; 471 src_ae_title.zae^title^format2.zap^title.
PAGE 488
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 505 !------------------------------------------------------------------! 506 507 contents_type_list.zcount := 1; 508 contents_type_list.zcntnts^type^ispresent := ZAPS^VAL^PRESENT; 509contents_type_list.zcntnts^type^list[0].zid:= ZFTM^VAL^CNTNTSLIST^DOCNAME; 510 contents_type_list.zcntnts^type^list[0].zcntntstype.znum^elements 511 := NUM_ELEM; 512 contents_type_list.zcntnts^type^list[0].
PAGE 489
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 544 545 event := ZFTM^VAL^EVT^INITIALIZE^CNF; 546 CALL get_event ( event, src_cepi ); 547 548 !------------------------------------------------------------------! 549 ! The optional output parameters for local_appl, src_appl, and ! 550 ! src_ae_title are supplied to the confirm procedure for example ! 551 ! only.
PAGE 490
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 583 ! not available, discard the association and exit. Additional ! 584 ! application-specific error handling or recovery could be ! 585 ! implemented if required by an application. ! 586 !------------------------------------------------------------------! 587 IF ( src_func_units.zread <> ZAPS^VAL^TRUE OR 588 src_func_units.zfilemgmt <> ZAPS^VAL^TRUE OR 589 src_func_units.
PAGE 491
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 622 623 !------------------------------------------------------------------! 624 ! Set the optional parameter dst_ae_title. 625 !------------------------------------------------------------------! ! 626 627 dst_ae_title.zae^title^type := zaps^val^ae^title^format2; 628 dst_ae_title.zae^title^format2.zae^qualifier^ispresent := 629 ZAPS^VAL^PRESENT; 630 dst_ae_title.zae^title^format2.
PAGE 492
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 661 , dst_ae_title 662 , ! service_class defaults to transfer ! 663 , func_units 664 , attr_groups 665 , contents_type_list 666 , initiator_id 667 , account 668 , filestore_password ); 669 670 CALL check_status ( dst_cepi ); 671 672 event := ZFTM^VAL^EVT^INITIALIZE^CNF; 673 CALL get_event ( event, dst_cepi ); 674 675 error := FTM_INITIALIZE_CNF_ ( dst_cepi 676 , state_result
PAGE 493
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 700 ! Verify that the functional units have not been negotiated down ! 701 ! from what was requested. If the requested functional units are ! 702 ! not available, discard both associations and exit. Additional ! 703 ! application-specific error handling or recovery could be ! 704 ! implemented if required by an application.
PAGE 494
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 739 !------------------------------------------------------------------! 740 ! Set the document type in the contents_type structure to FTAM-3. 741 !------------------------------------------------------------------! 742 contents_type.zid := ZFTM^VAL^CNTNTSTYPE^DOCTYPE; 743 contents_type.zdoctype.zdoctypename.znum^elements := NUM_ELEM; 744 contents_type.zdoctype.zdoctypename.
PAGE 495
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 778 ! requirements. ! 779 !------------------------------------------------------------------! 780 781 src_file.zlen := $occurs ( src_filename ); 782 src_file.zb ':=' src_filename FOR src_file.
PAGE 496
NonStop FTAM Programming Examples 817 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) access_passwords.zdeletepasswd.zlen BYTES; 818 819 !------------------------------------------------------------------! 820 !Initialize parameters for the FTM_READ_ATTRIB_REQ_ procedure call.
PAGE 497
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 856 attr_names.zlastreaderid := ZAPS^VAL^FALSE; 857 attr_names.zlastattrmodid := ZAPS^VAL^FALSE; 858 attr_names.zfilesize := ZAPS^VAL^FALSE; 859 860 ! security group ! 861 !------------------------------------------------------------------! 862 ! Set access control to ZAPS^VAL^TRUE. 863 !------------------------------------------------------------------! ! 864 865 attr_names.
PAGE 498
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 895 ! be successful for the group to succeed.
PAGE 499
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 934 935 event := ZFTM^VAL^EVT^SELECT^CNF; 936 CALL get_event ( event, src_cepi ); 937 error := FTM_SELECT_CNF_ ( src_cepi 938 , state_result 939 , action_result 940 , src_file 941 , diag ); 942 CALL check_error; 943 CALL check_action_diag; 944 CALL check_state; 945 946 event := ZFTM^VAL^EVT^READATTR^CNF; 947 CALL get_event ( event, src_cepi ); 948 error := FTM_READ_ATTRIB_CNF
PAGE 500
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 973 974 !------------------------------------------------------------------! 975 ! Use the FTM_CREATE_REQ_ and FTM_OPEN_REQ_ procedure calls to ! 976 ! create and open the file on the destination system. Send these ! 977 ! two requests out as a group. Initialize all necessary parameters ! 978 ! for the create and open procedures.
PAGE 501
NonStop FTAM Programming Examples 1012 initial_attr.zcntntstypevalue.zdoctype.zstringsig 1013 := file_attr.zcntntstypevalue.zdoctype. 1014 1015 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) zstringsig; initial_attr.zcntntstypevalue.zdoctype.zfileattrsispresent 1016 := ZAPS^VAL^ABSENT; 1017 1018 ! Storage group ! 1019 initial_attr.zstorageaccountispresent := ZAPS^VAL^ABSENT; 1020 initial_attr.zfileavlbltyattrispresent := ZAPS^VAL^PRESENT; 1021 initial_attr.
PAGE 502
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1051 initial_attr.zaccesscntrlattr.zaccesscntrl.zpasswdsispresent := 1052 1053 ZAPS^VAL^ABSENT; initial_attr.zaccesscntrlattr.zaccesscntrl.zlocationispresent := 1054 1055 ZAPS^VAL^ABSENT; initial_attr.
PAGE 503
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1090 access_passwords.zchngattrpasswd.zlen := $occurs(password); 1091 access_passwords.zchngattrpasswd.zb ':=' password FOR 1092 1093 access_passwords.zchngattrpasswd.zlen BYTES; access_passwords.zdeletepasswd.zlen := 0; 1094 1095 !------------------------------------------------------------------! 1096 ! Initialize parameters for the FTM_OPEN_REQ_ procedure call.
PAGE 504
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1129 1130 status := FTM_OPEN_REQ_ ( dst_cepi 1131 , process_mode 1132 , contents_type ); 1133 CALL check_status ( dst_cepi ); 1134 1135 status := FTM_END_GROUP_REQ_ ( dst_cepi ); 1136 CALL check_status ( dst_cepi ); 1137 1138 !------------------------------------------------------------------! 1139 ! Call the following procedures to process the confirms ! 1140 ! returned by each req
PAGE 505
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1168 CALL check_action_diag; 1169 CALL check_state; 1170 1171 event := ZFTM^VAL^EVT^ENDGROUP^CNF; 1172 CALL get_event ( event, dst_cepi ); 1173 1174 !------------------------------------------------------------------! 1175 ! Establish the source-file and destination-file data-transfer ! 1176 ! regimes.
PAGE 506
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1207 access_context.zcntxt := ZFTM^VAL^ACCESSCNTXT^UA; 1208 access_context.
PAGE 507
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1246 1247 src_more_data := 1D; 1248 src_start_position := 0D; 1249 1250 WHILE ( src_more_data <> 0D ) DO 1251 BEGIN 1252 !--------------------------------------------------------------! 1253 ! Call FTM_DATA_IND_ to read data from the source system.
PAGE 508
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1285 !---------------------------------------------------------------! 1286 1287 error := FTM_DATA_END_IND_ ( src_cepi 1288 , action_result 1289 , diag ); 1290 CALL check_error; 1291 CALL check_action_diag; 1292 1293 status := FTM_DATA_END_REQ_ ( dst_cepi 1294 , action_result ); 1295 CALL check_status ( dst_cepi ); 1296 1297 1298 END 1299 1300 1301 ELSE IF ( event = ZFTM^VAL^EVT^
PAGE 509
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1324 status := FTM_CANCEL_REQ_ ( dst_cepi 1325 , action_result 1326 , diag ); 1327 CALL check_status ( dst_cepi ); 1328 1329 event := ZFTM^VAL^EVT^CANCEL^CNF; 1330 CALL get_event ( event, dst_cepi ); 1331 error := FTM_CANCEL_CNF_ ( dst_cepi 1332 , action_result 1333 , diag ); 1334 CALL check_error; 1335 CALL check_action_diag; 1336 1337 END 1338 1339 1340 ELSE 1341 BEGIN 1
PAGE 510
NonStop FTAM Programming Examples 1363 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) BEGIN 1364 1365 !------------------------------------------------------------------! 1366 ! Terminate the source-file data-transfer regime.
PAGE 511
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1402 !------------------------------------------------------------------! 1403 ! Close the file on the destination system, change the attributes, ! 1404 ! and then deselect the file. These three primitives must also ! 1405 ! be grouped since the file-transfer service class was negotiated ! 1406 ! for the association.
PAGE 512
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1441 status := FTM_CHANGE_ATTRIB_REQ_ ( dst_cepi 1442 1443 , change_attr ); CALL check_status ( dst_cepi ); 1444 1445 status := FTM_DESELECT_REQ_ ( dst_cepi ); 1446 CALL check_status ( dst_cepi ); 1447 1448 status := FTM_END_GROUP_REQ_ ( dst_cepi ); 1449 CALL check_status ( dst_cepi ); 1450 1451 1452 !------------------------------------------------------------------! 1453 ! Call the f
PAGE 513
NonStop FTAM Programming Examples 1480 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) CALL get_event ( event, dst_cepi ); 1481 1482 !------------------------------------------------------------------! 1483 ! The charging parameter is used to convey information about costs ! 1484 ! attributed to the account. This parameter should be used only ! 1485 ! if the account parameter was used in the FTM_CREATE_REQ_ call.
PAGE 514
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1519 1520 status := FTM_BEGIN_GROUP_REQ_ ( src_cepi 1521 1522 , threshold ); CALL check_status ( src_cepi ); 1523 1524 status := FTM_CLOSE_REQ_ ( src_cepi ); 1525 CALL check_status ( src_cepi ); 1526 1527 status := FTM_DELETE_REQ_ ( src_cepi ); 1528 CALL check_status ( src_cepi ); 1529 1530 status := FTM_END_GROUP_REQ_ ( src_cepi ); 1531 CALL check_status ( src_cepi ); 1532 1533 !---
PAGE 515
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1558 ! The information returned in the charging parameter is not used ! 1559 ! in this example.
PAGE 516
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1597 !------------------------------------------------------------------! 1598 1599 status := FTM_TERMINATE_REQ_ ( dst_cepi ); 1600 CALL check_status ( dst_cepi ); 1601 1602 event := ZFTM^VAL^EVT^TERMINATE^CNF; 1603 CALL get_event ( event, dst_cepi ); 1604 1605 error := FTM_TERMINATE_CNF_ ( dst_cepi 1606 , ! charging ! ); 1607 1608 CALL check_error; 1609 1610 !-----------------------
PAGE 517
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1636 ?PAGE "GET_EVENT" 1637 !---------------------------------------------------------------------! 1638 ! ! 1639 ! Name: get_event ! 1640 ! ! 1641 ! Description: The get_event procedure gets an available event. It ! 1642 ! verifies that the event is the expected event and ! 1643 ! that there are no errors associated with it.
PAGE 518
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1675 ! A bad status has been received. ! 1676 !----------------------------------------------------------------! 1677 1678 1679 CALL check_status ( cepi ); END; 1680 1681 !------------------------------------------------------------------! 1682 ! Get the event code.
PAGE 519
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1714 ! Description: The check_status procedure checks the status returned ! 1715 ! from an FTM or APS procedure call. It checks for ! 1716 ! NORETRY, RETRYLATER, and DISCARD. If status is OK, ! 1717 ! it returns control to the main program. If status ! 1718 ! is not OK, it displays a message, discards the ! 1719 ! associations and exits the program.
PAGE 520
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1753 , ! diagnostic_buffer ! 1754 , original_error_info ); 1755 1756 CALL check_error; 1757 1758 !------------------------------------------------------------------! 1759 ! Display the status code.
PAGE 521
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 1792 IF (error_subcode < 0) THEN 1793 BEGIN 1794 error_subcode := -error_subcode; 1795 text_ptr ':=' "-" -> @text_ptr; 1796 END; 1797 @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1798 , $DBL ( error_subcode ) 1799 , BASE ); 1800 text_len := @text_ptr - @tempbuf; 1801 CALL WRITE ( termnum, outbuf, text_len ); 1802 1803 !--------------------------------------------------------------
PAGE 522
NonStop FTAM Programming Examples 1831 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) CALL WRITE ( termnum, outbuf, text_len ); 1832 1833 tempbuf ':=' " ERROR SUBCODE # " -> @text_ptr; 1834 IF ( original_error_info.zerror.zerror^subcode < 0) THEN 1835 BEGIN 1836 original_error_info.zerror.zerror^subcode 1837 1838 := -original_error_info.zerror.
PAGE 523
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1870 1871 ZAPS^VAL^STATUS^DISCARD -> 1872 BEGIN 1873 !---------------------------------------------------------------! 1874 ! A status of DISCARD returned on an FTM request indicates ! 1875 ! that the association associated with that CEPI has been ! 1876 ! lost.
PAGE 524
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1909 ?PAGE "CHECK_ERROR" 1910 !---------------------------------------------------------------------! 1911 ! ! 1912 ! Name: check_error ! 1913 ! ! 1914 ! Description: The check_error procedure checks error codes ! 1915 ! returned by FTM procedure calls.
PAGE 525
NonStop FTAM Programming Examples 1948 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1949 , $DBL ( error_code ) 1950 , BASE ); 1951 text_len := @text_ptr - @tempbuf; 1952 CALL WRITE ( termnum, outbuf, text_len ); 1953 1954 tempbuf ':=' "Association discarded" 1955 -> @text_ptr; 1956 text_len := @text_ptr - @tempbuf; 1957 CALL WRITE ( termnum, outbuf, text_len ); 1958 1959 !--------------------------------------------
PAGE 526
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 1987 1988 PROC check_state; 1989 1990 BEGIN 1991 1992 !------------------------------------------------------------------! 1993 ! Check the state-result parameter for a failure.
PAGE 527
NonStop FTAM Programming Examples 2026 ! Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) CEPI identifying the association that carried the 2027 ! event ! ! 2028 ! ! 2029 ! Output: Error messages to terminal 2030 ! ! ! 2031 !---------------------------------------------------------------------! 2032 2033 PROC bad_event ( event, cepi ); 2034 2035 INT .
PAGE 528
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2065 2066 status := FTM_U_ABORT_REQ_ ( dst_cepi 2067 , !action_result! 2068 , !diagnostics!); 2069 CALL check_status ( dst_cepi ); 2070 2071 END 2072 ELSE IF ( cepi = dst_cepi AND src_con_established ) THEN 2073 BEGIN 2074 status := FTM_U_ABORT_REQ_ ( src_cepi 2075 , !action_result! 2076 , !diagnostics!); 2077 CALL check_status ( src_cepi ); 2078 END; 2079 END 2080 ELSE 20
PAGE 529
NonStop FTAM Programming Examples Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) 2104 !------------------------------------------------------------------! 2105 ! Verify that a CEPI exists, and if it does, discard it.
PAGE 530
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2143 ! the diagnostic message type and error ID for each ! 2144 ! diagnostic message element, calls abort_discard, and ! 2145 ! ends the program. Additional application-specific ! 2146 ! error handling or recovery could be implemented if ! 2147 ! required by an application.
PAGE 531
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2182 FOR i := 0 TO diag.zdiagcount - 1 DO 2183 BEGIN 2184 tempbuf ':=' " Diagnostic Type: " -> @text_ptr; 2185 text_len := @text_ptr - @tempbuf; 2186 width := DNUMOUT ( tempbuf[text_len] 2187 , $DBL ( diag.zdiagelems[i].
PAGE 532
NonStop FTAM Programming Examples 2221 Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) CALL STOP; 2222 2223 END; 2224 2225 END; --- check_action_diag --2226 2227 2228 ?PAGE "ABORT_DISCARD" 2229 !---------------------------------------------------------------------! 2230 ! ! 2231 ! Name: abort_discard ! 2232 ! ! 2233 ! Description: The abort_discard procedure discards established ! 2234 ! ! associations.
PAGE 533
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2260 ! for an FTM_U_ABORT_REQ_ call. The diagnostic values set here are ! 2261 ! for example only; a real application might be more specific, for ! 2262 ! instance, in the error code. Here, type is set to "permanent"; ! 2263 ! error code is set to "no reason"; observer of error is this ! 2264 ! application, and source of error is not categorized.
PAGE 534
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode) NonStop FTAM Programming Examples 2299 status := FTM_U_ABORT_REQ_ ( dst_cepi 2300 , action_result 2301 , diag); 2302 2303 IF (status <> ZAPS^VAL^STATUS^OK) THEN 2304 BEGIN 2305 tempbuf ':=' "Abort of the destination association failed" 2306 ->@text_ptr; 2307 text_len := @text_ptr - @tempbuf; 2308 CALL WRITE ( termnum, outbuf, text_len ); 2309 2310 END; END; 2311 2312 !---------------------------------------------
PAGE 535
NonStop FTAM Programming Examples Translation Application Example Translation Application Example The following example program opens the responder and issues the Enable Translation command. It then reads its $RECEIVE and processes all translation requests.
PAGE 536
Translation Application Example NonStop FTAM Programming Examples 1 /***********************************************************************/ 2 /* */ 3 /* Test Translation Application for D42 Changes to FTAM */ 4 /* */ 5 /***********************************************************************/ 6 /* */ 7 /* */ 8 /* Program Name: exctran1 */ 9 /* */ 10 /* Program Description: */ 11 /* */ 12 /* This program opens the Responder file and issues ‘enable */ 13 /* translation’ comma
PAGE 537
Translation Application Example NonStop FTAM Programming Examples 39 #pragma SSV2 "$d43rsc.zosiaps" /* Look for OSI files here */ 40 #pragma SSV3 "$d43rsc.zspidef" /* Look for other SPI files */ 41 #pragma SSV4 "$d43rsc.
PAGE 538
Translation Application Example NonStop FTAM Programming Examples 79 , FILE_GETRECEIVEINFO_ \ 78 , FILE_OPEN_ \ 80 , FILENAME_TO_OLDFILENAME_ \ 81 , FILENAME_TO_PROCESSHANDLE_ \ 82 , FNAMETOFNAME32 \ 83 , OPENER_LOST_ \ 84 , PROCESSHANDLE_COMPARE_ \ 85 , PROCESSHANDLE_NULLIT_ \ 86 , READUPDATEX \ 87 , REPLYX \ 88 , SIGNALTIMEOUT \ 90 , SSINIT \ 91 , SSGETTKN \ 92 , SSPUTTKN \ 93 , STRING_UPSHIFT, \ 94 , TEXTTOSSID \ 95 , WRITEREADX )" nolist \ 96 /***********************
PAGE 539
Translation Application Example NonStop FTAM Programming Examples 118 zspi_ddl_error_def spi_error; 119 120 typedef short BOOL; 121 #define TRUE -1 122 #define FALSE 0 123 #pragma PAGE "OpenRcvFile" 124 /**********************************************************************/ 125 /* */ 126 /* Name: OpenRcvFile */ 127 /* */ 128 /* Desc: Opens the $RECEIVE file. Failure returns FALSE.
PAGE 540
Translation Application Example NonStop FTAM Programming Examples 157 { 158 zResponderParam = getenv (RESPONDER_PARAM); 159 if (!zResponderParam )/* If not already open, open it */ 160 { 161 printf ("Required parameter ’%s’ missing.
PAGE 541
NonStop FTAM Programming Examples Translation Application Example 204 FILE_GETINFO_ (sSpiFnum, (short *) &sLastError); 205 if (sLastError) 206 { 207 printf ("Error sending SPI command: %d\n", sLastError); 208 FILE_CLOSE_ (sSpiFnum); 209 sSpiFnum = -1; 210 return FALSE; 211 } 212 /* Check the results to make sure we were accepted */ 213 SSPUTTKN (saSpiBuffer, ZSPI_TKN_RESET_BUFFER, (char *) &sLen); 214 SSGETTKN (saSpiBuffer, ZSPI_TKN_DATALIST); 215 SSGETTKN (saSpiBuffer, ZSPI_TKN_ERR
PAGE 542
Translation Application Example NonStop FTAM Programming Examples 242 /**********************************************************************/ 243 void HandleSysMsg (short sLen) 244 { 245 zsys_ddl_smsg_open_def *OpenMsg; 246 zsys_ddl_receiveinformation_def ReceiveInfo; 247 short sIndex = -1, 248 sError = 0; 249 switch (saSpiBuffer [0]) 250 { 251 /*No close message if processor failed.
PAGE 543
Translation Application Example NonStop FTAM Programming Examples 280 printf ("Opener Backup Gone! Reestablished with " Primary.\n"); 281 else 282 /* The second call to OpenResponderFile() tries to reopen*/ 283 /* the responder. If open works, it will enable as well */ 284 if (OpenResponderFile()) /* Try to open once */ 285 printf ("Opener Backup Gone! Reestablished Open" 286 " with Primary.\n") 287 else 288 { 289 printf ("Opener Lost! Attempting to reopen" 290 "every %d seconds.
PAGE 544
Translation Application Example NonStop FTAM Programming Examples 319 OpenMsg = (zsys_ddl_smsg_open_def *) saSpiBuffer; 320 /* Only allow #ZSPI openers */ 321 if ((OpenMsg->z_qualifier_len != 5) || 322 !memcmp (OpenMsg->u_z_data.z_qualifier + 323 OpenMsg->z_opener_name.zlen, 324 325 "#ZSPI", 5)) { 326 REPLYX (, , , , 2); /* Don’t allow open! */ 327 return; 328 } 329 FILE_GETRECEIVEINFO_ ((short *) &ReceiveInfo); 330 if (PROCESSHANDLE_COMPARE_ ((short *) &ReceiveInfo.
PAGE 545
Translation Application Example NonStop FTAM Programming Examples 358 /* the responder. If open works, it will enable as well 359 if (OpenResponderFile()) /* Try to open once */ 360 printf ("Opener Backup Gone! Reestablished Open" 361 "with Primary.\n"); 362 else 363 { 364 printf ("Opener Gone! Attempting to reopen every %d" 365 " seconds.
PAGE 546
NonStop FTAM Programming Examples 397 charzName [16]; 398 }sUser; 399 shortsaOldName [12]; 400 zspi_ddl_fname32_defsXltFname; 401 zosf_ddl_xlate_action_type_defeXlateAct; 402 char zFilename [ZFTM_VAL_REQ_FILENAME_LEN], 403 404 Translation Application Example *zParam; READUPDATEX (sRcvFnum, (char *) saSpiBuffer, 405 (short) sizeof (saSpiBuffer), &sLen); 406 FILE_GETINFO_ (sRcvFnum, (short *) &sLastError); 407 if (sLastError == 6) 408 { 409 /* System messages are handled here.
PAGE 547
Translation Application Example NonStop FTAM Programming Examples 436 memcpy (zFilename, sReqFname.zName, sReqFname.sSize); 437 zFilename [sReqFname.sSize] = ’\0’; 438 439 /*For this sample program, use filename (upshifted) to look up param*/ STRING_UPSHIFT_ (zFilename, sReqFname.sSize, zFilename, 440 sReqFname.sSize); 441 zParam = getenv (zFilename); 442 if (!zParam) /* No translation...*/ 443 sXltErr = 3021; 444 else 445 { 446 /* Try to convert to a fname32.
PAGE 548
NonStop FTAM Programming Examples 475 Translation Application Example printf ("Fail, err %d\n", sXltErr); 476 else 477 printf ("Succeed: ’%s’\n", zParam); 478 /* Build the response */ 479 SSINIT (saSpiBuffer, ZOSA_VAL_MIN_BUFLEN, 480 (short *) &zosf_val_ssid, ZSPI_VAL_CMDHDR, 481 ZOSF_CMD_FILENAME_TRANSLATE, ZCOM_OBJ_PROCESS); 482 if (sXltErr == 0) /* Filename if no error */ 483 SSPUTTKN (saSpiBuffer, ZOSF_TKN_XLATED_FNAME, 484 (char *) &sXltFname); 485 else 486 { 487 /* Error tok
PAGE 549
NonStop FTAM Programming Examples 524 /* Open $Receive, and the Responder*/ 525 if (OpenRcvFile() && OpenResponderFile()) 526 527 528 Translation Application Example /* Get and process messages forever.
PAGE 550
NonStop FTAM Programming Examples Translation Application Example HP NonStop OSI/FTAM Programming Reference Manual—528611-001 G - 236
PAGE 551
Glossary The following glossary defines terms used both in this manual and in the other NonStop FTAM manuals. Not all terms listed here are used in this particular manual. abstract syntax. A standardized method of describing data structures that is independent of the way they are represented in data transmission. An abstract syntax uses a set of primitive elements defined by an abstract syntax notation such as ASN.
PAGE 552
Glossary API (application programmatic interface). API (application programmatic interface). A set of services (such as programming language functions or procedures) that are called by an application program to communicate with other software components. For example, an application program in the form of a client might use an API to communicate with a server program. For NonStop FTAM, the API consists of FTM, APS, and MFM procedures used in FTAM programming.
PAGE 553
Glossary APS (application, presentation, and session) procedures. APS (application, presentation, and session) procedures. A set of procedure calls, provided by NonStop as part of the OSI/AS subsystem, providing application programs with access to the services of ACSE (in the Application Layer), the Presentation Layer, and the Session Layer. The names of the APS procedures all begin with the letters APS. The APS procedures are defined in the EXTDECS0 and CEXTDECS files.
PAGE 554
backup opener. Glossary backup opener. The backup process that has an open to an FTAM initiator or responder process. See backup process. backup process. In a NonStop system, a process that is identical to the primary process and is created at the same time as the primary process. These two processes act as a process pair. The backup process takes over if the primary process fails. See primary process. basic data types.
PAGE 555
confirm procedure. Glossary confirm procedure. A procedure called to retrieve the confirm data after a confirm primitive has been received. See confirm primitive. confirmed service. A service in which the initiating application sends a request, and the responding application entity (for example, an FTAM responder) returns a response that is received as a confirm primitive by the initiating application. The confirm primitive acknowledges the success or failure of the requested action.
PAGE 556
Data Link Layer. Glossary Data Link Layer. Layer 2 in the OSI Reference Model. This layer packages data for transmission across the network and ensures that the data arrives at the next layer without any errors. data-transfer regime. The regime established after successfully gaining read or write access to an FTAM file. In the data-transfer regime, you can send or receive data, and you can abort the association. See also FTAM regime., file-selection regime., and fileopen regime.
PAGE 557
Glossary enhanced-file-management functional unit. enhanced-file-management functional unit. A functional unit that adds the modification of file attributes to the capabilities of the limited-file-management functional unit. See limited-file-management functional unit. Enscribe. The NonStop database file-management software provided as part of the Guardian file system. The Enscribe software provides access to—and manipulation of—records in a database on a NonStop system.
PAGE 558
event. Glossary event. (1) In NonStop OSI terms, an indication or confirm primitive that an application using the FTAM or OSI/AS API retrieves by calling the APS_EVENT_RECEIVE_ procedure. See also indication primitive. or confirm primitive. (2) In DSM terms, a significant change in some condition in the system or network. Events can be operational errors, notifications of limits exceeded, requests for action needed, and so on. See also EMS (Event Management Service). and event message.
PAGE 559
file-access functional unit. Glossary file-access functional unit. A functional unit that provides for access to an individual FADU in the file-access structure and allows the FADU to be manipulated within the file-access structure. file-access service class. The service class that allows access to remote files, and includes data manipulation and file management capabilities. file-attribute group. See attribute group. file attributes.
PAGE 560
file-system request. Glossary file-system request. A request to the Guardian file system by or on behalf of a process. Several different file-system requests are monitored for a process. You can view the number of these requests that have occurred by issuing the SCF STATS PROCESS command. file storage system. An organized collection of files, including attributes and names, residing on a computer system. On NonStop systems, the file storage system used is the Guardian file system.
PAGE 561
FTAM-1 file. Glossary FTAM-1 file. An unstructured text file that can be accessed only as a single data unit. See also document type. FTAM-2 file. A sequential text file that can be accessed either as a single data unit or as multiple data units. See also document type. FTAM-3 file. An unstructured binary file that can be accessed only as a single data unit. See also document type. FTM procedures.
PAGE 562
grouping control. Glossary grouping control. A mode of operation that allows your application to perform a sequence of confirmed services in one FTAM event. The request primitives for these services are bracketed with the F-BEGIN-GROUP and F-END-GROUP request primitives. The grouped request primitives are concatenated and sent in a single request PDU. The responder analyzes and retains its response to each of these requests until the group is complete or until a state failure occurs.
PAGE 563
indirect-process-name. Glossary indirect-process-name. A variable that represents the name of a NonStop initiator or responder process as it is known to APLMGR. It consists of three parts: $appl-mgrname, #proc-type, and internal-name, which are separated by periods (.). An SCF command that uses this form of process name is sent to the APLMGR process, which looks up the specified process in its MIB and then routes the command to the process. Contrast with $process-name. informative message.
PAGE 564
IS (International Standard). Glossary IS (International Standard). A final specification standard issued by ISO. ISO (International Organization for Standardization). A worldwide federation of national standards bodies established to promote the development of standards to facilitate the international exchange of goods and services, and to develop mutual cooperation in areas of intellectual, scientific, technological, and economic activity. ISO FTAM. Generic FTAM as specified in the ISO 8571 standard.
PAGE 565
Glossary maximum-string-length parameter. maximum-string-length parameter. An optional parameter of contents-type that indicates the maximum number of octets (excluding escape-sequence octets) that can be transmitted in a character string during the data-transfer regime. See also contentstype parameter. MFM (module file management) procedures.
PAGE 566
NIST (National Institute of Science and Technology). Glossary NIST (National Institute of Science and Technology). A U.S. government institution, formerly known as the National Bureau of Standards (NBS), that sets standards and promotes their acceptance. node. (1) The basic building block of the FTAM hierarchical file structure. (2) A NonStop system that is part of an Expand network. node descriptor.
PAGE 567
null object type. Glossary null object type. A NonStop term used to represent the absence of an object type in an SCF command. If a command supports the null object type, you can issue it without specifying an object type. For NonStop FTAM, the NAMES and VERSION commands support the null object type. The NAMES null command refers to a collection of object types; for the VERSION null command, the object type is irrelevant. object.
PAGE 568
Glossary OSI (Open Systems Interconnection). OSI (Open Systems Interconnection). A set of standards used for the interconnection of heterogeneous computer systems designed for universal connectivity. OSI address. The address of an object on an OSI network. An OSI address consists of four components: the transport selector (TSEL), session selector (SSEL), presentation selector (PSEL), and network service access point (NSAP). OSI/AS (Application Services).
PAGE 569
PDU Glossary PDU. The encoded message transferred across the OSI network between peer entities—for example, between an FTAM initiator and responder. Data, such as a block of information being transferred or a protocol primitive, is encoded into a PDU for transfer across the network. The PDU is decoded when it arrives at its destination.
PAGE 570
presentation context. Glossary presentation context. The combination of an abstract syntax and a transfer syntax on a Presentation Layer connection. In NonStop FTAM, you have programmatic control over the choice of presentation context related to document types, but not over the required abstract syntaxes associated with the protocol control information (PCI) for FTAM, ACSE, and the Presentation Layer. Presentation Layer. Layer 6 in the OSI Reference Model.
PAGE 571
profile. Glossary profile. (1) A complete set of self-consistent parameters specifying which options in one or more OSI standards will be supported by a group of implementations for a particular purpose. For example, the U.S. Government Open Systems Interconnection Profile (GOSIP) is a profile to which implementations must conform to be eligible for certain government contracts.
PAGE 572
read functional unit. Glossary read functional unit. A functional unit that allows the following activities on an association: • • • Establishing the file-open regime Transferring data from the responder to the initiator Releasing the file-open regime receiver. The entity that receives a communication from a remote sender. recovery functional unit. An ISO FTAM functional unit that allows the initiator process to recreate a previously destroyed regime. regime.
PAGE 573
responder. Glossary responder. The file-service user that accepts an initiator’s request to establish an FTAM regime. In NonStop FTAM, the responder is a process that services FTAM requests initiated from remote systems on an OSI network. The NonStop responder acts as an FTAM file server, mapping FTAM requests into Guardian file operations and providing a translation between Guardian file structures and FTAM file structures. The NonStop responder has no programmatic interface. Contrast with initiator.
PAGE 574
SCF kernel. Glossary SCF kernel. The part of the SCF software that provides subsystem-independent functions, such as accepting user input commands. SCP (Subsystem Control Point). The process used to provide the focal point for all NonStop data communications subsystems. There can be several instances of this process.
PAGE 575
service user. Glossary service user. An entity that uses services provided to it by a lower-layer entity. For example, the FTAM initiator is a service user of ACSE and presentation services provided by OSI/AS. Contrast service provider. session address. See SSAP (session service access point). Session Layer. Layer 5 in the OSI Reference Model. This layer allows the setup and termination of communication sessions between systems on the network. session selector. See SSEL (session selector).
PAGE 576
state transition. Glossary state transition. In DSM, a condition that exists when a process is in transition from one state to another. State transitions for PROCESS objects include ABORTING, STARTING, STOPPING, and SUSPENDING. Also called summary-state transition. status. A NonStop procedure completion code that indicates the outcome of a call. This code can assume one of nine values. storage group. File attributes that provide information about a file and the data stored in it.
PAGE 577
subdevice. Glossary subdevice. A logical entity maintained by a NonStop subsystem to provide access to a physical connection—that is, to a communications line. There might be one or many subdevices associated with a given line or process. Exactly what constitutes a subdevice differs depending on the subsystem.
PAGE 578
swap volume. Glossary swap volume. An optional disk volume used as an additional memory source during the operation of any process under the NonStop operating system. TACL. See HP Tandem Advanced Command Language (TACL). tag parameter. An optional procedure-call parameter you can use in nowait applications on NonStop systems to match nowait I/O requests with completions. If there are multiple I/O requests outstanding in your application, the tag indicates which one has completed.
PAGE 579
Transport Layer. Glossary Transport Layer. Layer 4 in the OSI Reference Model. This layer provides reliable data transfer. transport selector. See TSEL (transport selector). transport service access point. See TSAP (transport service access point). transport service provider. See TSP (transport service provider) process. traversal. An ordering of the nodes in a tree such that each node occurs only once, and which is determined by an algorithm applicable to all possible trees. tree.
PAGE 580
user abort. Glossary user abort. An association abort initiated by the application. An abort leaves the status of any interrupted operations undefined. FTAM provides the F-U-ABORT service to allow applications to request a user abort. Contrast with provider abort. VFS (virtual filestore). A virtual interface for FTAM requests to a file storage system. The NonStop FTAM responder implements a VFS that translates requests into Guardian file-system operations.
PAGE 581
X.25 network. Glossary X.25 network. Any network or subnetwork linked using X.25 standards. X.25 standards are CCITT standards that define packet-switching carrier communication in the Network Layer over wide area networks (WANs). $process-name. A variable that represents the Guardian process name of a NonStop initiator or responder process. An SCF command that uses this form of process name is sent directly to the specified initiator or responder process, rather than to the APLMGR process.
PAGE 582
$process-name.
PAGE 583
Index A API Aborting associations requesting 4-147/4-149 retrieving indication information 4-121/4-122, 4-150/4-151 See also FTM_P_ABORT_xxx procedures See also FTM_U_ABORT_xxx procedures Access, file context A-13 control A-12 determining A-13 error subcodes B-23 ISO FTAM diagnostic messages C-6/C-7 passwords A-14 See also Selecting files access-context parameter 4-3, 4-124 access-passwords parameter associated procedures 4-3 description 4-38, 4-84, 4-134 examples G-124, G-131, G-181, G-188 Account charge
PAGE 584
B Index APS procedures (continued) using F-1 APS_DISCARD_ procedure description F-3 examples, in C G-29, G-54, G-145 examples, in TAL G-76, G-104, G-202 APS_EVENT_RECEIVE_ procedure description F-4 examples, in C G-27, G-34, G-146 examples, in TAL G-74, G-90, G-203 APS_INITIALIZE_ procedure description F-6 examples, in C G-20, G-113 examples, in TAL G-66, G-171 APS_STATUS_ procedure description F-7 examples, in C G-30, G-49, G-146, G-148 examples, in TAL G-87, G-95, G-204, G-205 Architecture APLMGR subsys
PAGE 585
C Index C C declarations file See CEXTDECS file and ZOSIFTAM file C declarations files See CEXTDECS file and ZFTMC file Cancelling a data transfer regime requesting 4-16/4-18 responding 4-23/4-25 retrieving indication information 4-21/4-22 retrieving response information 4-19/4-20 Cancelling nowait operation E-4 CANCELREQ procedure E-4 cepi parameter 4-4 CEXTDECS file 4-1, E-1, F-1 change-attrib parameter 4-4, 4-26, 4-29 Changing access control values A-14 Changing file attributes DDL structure A-17 reque
PAGE 586
D Index Data (continued) parameter header A-8 Data encoding 2-5 Data structures related to error messages B-2 Data transfer ending requesting 4-143/4-144 retrieving response 4-145/4-146 ending a block requesting 4-44/4-46 retrieving request information 4-47/4-48 Data transfer block receiving 4-53/4-56 transferring 4-49/4-52 Data types first-level A-3 for each procedure, table of A-42/A-43 for FTAM structuring data element A-26 second-level A-4 Data-transfer regime cancelling confirming 4-19/4-20 requestin
PAGE 587
E Index Diagnostic messages (continued) structure of elements A-28 diagnostics parameter 4-4 diagnostic-buffer parameter F-8 Discarding API context information for associations F-3 Distributed Systems Management See DSM Document types access context, table of B-26 available for negotiating presentation context A-20 interoperability 2-3/2-4 supported by initiator 3-11 supported by NonStop FTAM 1-2 Documentation road map -xv Documentation, other -xiv DSM 1-4, 1-10/1-12 E EMS 1-11 Encoding data 2-5 Ending g
PAGE 588
F Index Files (continued) creating and selecting requesting 4-36/4-39 retrieving response 4-41/4-43 deleting requesting 4-58/4-59 retrieving response information 4-60/4-62 deselecting requesting 4-63/4-64 retrieving response 4-65/4-67 determining access A-14 erasing FADUs requesting 4-70/4-74 retrieving response 4-75/4-76 FTAM procedures, for 4-2 legal status A-32 managing, ISO FTAM messages C-6 permitted actions A-32 selecting ISO FTAM diagnostic messages C-5/C-6 requesting 4-133/4-135 retrieving respons
PAGE 589
F Index FTM procedures (continued) parameters and associated calls, table of 4-3/4-7 Programming Example 1 example structure and protocol G-3/G-5 example, in C G-12/G-55 example, in TAL G-56/G-105 Programming Example 2 example structure and protocol G-6/G-11 example, in C G-106/G-160 example, in TAL G-161/G-235 regime requirements, table of 4-7/4-9 request types 3-5 response types 3-6 FTM_BEGIN_GROUP_REQ_ procedure considerations 4-14 description 4-13/4-14 errors returned 4-14 examples in C G-126, G-132,
PAGE 590
F Index FTM_CLOSE_REQ_ procedure (continued) examples in C G-140, G-142 in TAL G-197, G-200 FTM_CREATE_CNF_ procedure considerations 4-42/4-43 description 4-41/4-42 errors returned 4-43 examples in C G-133 in TAL G-190 list of 4-43 FTM_CREATE_REQ_ procedure considerations 4-38 description 4-36/4-38 errors returned 4-39 examples in C G-132 in TAL G-189 list of 4-40 FTM_DATA_END_IND_ procedure considerations 4-48 description 4-47 errors returned 4-48 examples in C G-136 in TAL G-194 FTM_DATA_END_REQ_ proced
PAGE 591
F Index FTM_DESELECT_REQ_ procedure (continued) in C G-140 in TAL G-198 list of 4-64 FTM_END_GROUP_REQ_ procedure considerations 4-68 description 4-68 errors returned 4-69 examples in C G-127, G-132, G-140, G-143 in TAL G-184, G-190, G-198, G-200 list of 4-69 FTM_ERASE_CNF_ procedure considerations 4-76 description 4-75 errors returned 4-76 FTM_ERASE_REQ_ procedure considerations 4-71 description 4-70 errors returned 4-71/4-72 examples 4-73/4-74 FTM_FILE_CLOSE_CNF_ procedure considerations 4-81 descriptio
PAGE 592
F Index FTM_OPEN_CNF_ procedure considerations 4-119/4-120 description 4-118/4-119 errors returned 4-120 examples in C G-128, G-133 in TAL G-185, G-190 FTM_OPEN_REQ_ procedure considerations 4-115 description 4-114/4-115 errors returned 4-116 examples in C G-127, G-132 in TAL G-184, G-190 FTM_P_ABORT_IND_ procedure considerations 4-122 description 4-121/4-122 errors returned 4-122 examples in C G-32, G-154 in TAL G-88, G-213 FTM_READ_ATTRIB_CNF_ procedure considerations 4-131 description 4-130/4-131 error
PAGE 593
G Index FTM_TRANSFER_END_CNF_ procedure (continued) examples in C G-42, G-138 in TAL G-85, G-196 FTM_TRANSFER_END_REQ_ procedure considerations 4-143 description 4-143 errors returned 4-144 examples in C G-29, G-138 in TAL G-75, G-196 list of 4-144 FTM_U_ABORT_IND_ procedure considerations 4-151 description 4-150 errors returned 4-151 examples in C G-32 in TAL G-89 FTM_U_ABORT_REQ_ procedure considerations 4-148 description 4-147/4-148 errors returned 4-148 examples in C G-35, G-50, G-80, G-154, G-159 in
PAGE 594
K Index Initiating regimes data-transfer 4-123/4-126, 4-152/4-155 file-open 4-114/4-117 file-selection 4-133/4-135 file-selection and file-open 4-83/4-89 FTAM regime 4-93/4-100 Initiating system, definition of 1-5 Initiator Data Flow 3-3 Initiator Structure 3-1 Initiator, NonStop FTAM architectural overview 1-5/1-7 data flow to and from 3-3/3-4 error codes returned by descriptions B-21/B-34 table of B-19/B-20 error messages returned by overview B-3/B-4 status codes B-2/B-4 FTAM API, support for 3-4 FTM pr
PAGE 595
N Index Manuals, related -xiv maximum-string-length parameter 2-3 MFM procedures definition 3-4 overview 1-9 using E-1 MFM_AWAITIOX_ procedure considerations E-4 description E-2/E-4 examples in C G-23 in TAL G-69 MFM_CANCELREQ_ procedure considerations E-5 description E-4 MIB, OSI manager 1-13, 1-14 Module file management See MFM procedures E-1 more-data parameter 4-6, 4-54 Moving files, programming example example structure and protocol G-6/G-11 example, in C G-106/G-160 example, in TAL G-161/G-235 Movin
PAGE 596
P Index original-error-info parameter F-8 OSI address examples, in C G-20, G-114 examples, in TAL G-66, G-171 specifying A-6 OSI Reference Model, HP NonStop products for 1-5, 1-12/1-14 OSI/AS subsystem API 3-4 interaction with 1-4, 1-12/1-14 interoperability 2-1 OSI/FTAM Programming Guide A-24 OSI/TS subsystem 1-4, 1-12/1-14 override parameter 4-6, 4-36, A-41 P Parameter structures general A-5 ZAPS A-6/A-11 ZFTM A-12/A-37 Parameters See also individual parameter names Passwords, file attributes A-14 PDUs
PAGE 597
S Index Regimes requirements for each FTM procedure, table of 4-7/4-9 transition outcome A-41 remote-ae-title parameter 4-6, 4-94 remote-appl parameter 4-6, 4-94 Request procedures 3-5 requested-access parameter associated procedures 4-6 description 4-37, 4-84, 4-133 examples G-123, G-181 requested_access parameter G-131, G-188 Responder, NonStop FTAM architectural overview 1-5/1-7 functional overview 1-1 Responder, NonStop FTAM, interoperability 2-2 Responding system, definition of 1-5 responding-ae-titl
PAGE 598
U Index Terminating associations requesting 4-139/4-140 retrieving response 4-141/4-142 Terminating files See Closing files Terminating regimes all existing 4-147/4-149 data-transfer 4-16/4-18, 4-143/4-144 file-open 4-32/4-33 file-open and file-selection 4-77/4-79 file-selection 4-63/4-64 FTAM regime 4-141/4-142 Testing for conformance 2-1 threshold parameter 4-7, 4-13 timelimit parameter E-3 Time, generalized A-25 time-limit parameter F-4 TLAM subsystem 1-5, 1-12/1-14 TRACE command, SCF 1-11 Transferring
PAGE 599
Z Index ZAPS-DDL- data type identifiers BOOLEAN A-3 CHAR128 A-4 CHAR16 A-4 CHAR20 A-4 CHAR256 A-5 CHAR32 A-4 ENUM1 A-3 INT1 A-3 INT2 A-3 ISPRESENT A-5 OBJ-ID A-5 ZAPS-DDL- parameter structure identifiers ABSTRACT-AE-TITLE A-6 ABSTRACT-SYN-NAME A-6 AE-TITLE A-6 APPL-ADDR A-6 APPL-CNTXT A-7 cross-referenced by procedure call A-42/A-43 CURRENT-ERROR A-7 DATA-ELEMENT-HDR A-7 DATA-HDR A-8 DIAG-BUF A-9 ERROR-CODE A-9 FILENAME A-9 ORIGINAL-ERROR A-9 PSAP A-10 SERVICE-ID A-10 SWAP-VOLUME A-11 TRANSFER-SYN-NAME A-
PAGE 600
Z Index ZCHNGATTRPASSWD field A-14 ZCNTNTSTYPE field A-19, A-20, A-21 ZCNTNTSTYPEVALUE field A-24, A-25, A-35 ZCNTNTSTYPEVALUEISPRESENT field A-34 ZCNTNTS-TYPE-ISPRESENT field A-19 ZCNTNTS-TYPE-LIST A-19 ZCNTXT field A-13 ZCONCURRENCYACCESS field A-13 ZCONCURRENCYISPRESENT field A-13 ZCONSTRAINTSETASNAME field A-20, A-22 ZCOUNT field A-19 ZCREATION field A-16, A-35 ZCREATIONISPRESENT field A-35 ZCREATORID field A-16, A-35 ZCREATORIDISPRESENT field A-35 ZDATAEXISTS field A-26 ZDATAEXISTSISPRESENT field A-2
PAGE 601
Z Index ZFTM-DDL- parameter structure identifiers (continued) DE-FADU A-26 DIAGNOSTIC A-28 DIAG-ELEM A-27 ENTITY-REF A-28 FADU-ID A-29 FILEAVLBLTY-ATTR A-30 FILESIZE-ATTR A-31 FUNC-UNITS A-31 LEGALQUALIF-ATTR A-32 PERMITTED-ACTIONS A-32 PROC-MODE A-33 READ-ATTR A-33 REQUESTED-ACCESS A-36 SERVICE-CLASS A-36 USER-ID A-37 ZFTM-DDL-CHAR256 A-5 ZFTM-ERR- error code identifiers ACCESS-CNTXT-INVALID (-6009) B-26 ACCESS-INCNSTNT (-6003) B-23 ACCESS-NOT-AVAIL (-6004) B-24 ACSE-FAILURE (-6032) B-32 API-FS-ERROR (-6
PAGE 602
Z Index ZFTM-VAL- named values (continued) FILEAVLBLTY-xxx A-39 OVR-xxx A-41 STATE-xxx A-41 STRINGSIG-xxx A-41 UC-xxx A-41 ZFURTHERDETAILS field A-27 ZFURTHERDETAILSISPRESENT field A-27 ZFUTUREFILESIZE field A-17, A-18, A-24, A-25, A-35 ZFUTUREFILESIZEISPRESENT field A-18, A-24, A-25, A-35 ZGROUP field A-31 ZID field A-12, A-15, A-19, A-20, A-25, A-29, A-30, A-31, A-32, A-37 ZIDENTITY field A-13 ZIDENTITYISPRESENT field A-13 ZINSERT field A-22, A-32, A-33, A-36 ZINSERTISPRESENT field A-12 ZINSERTPASSWD fi
PAGE 603
Z Index ZSTORAGEACCOUNTISPRESENT field A-17, A-24, A-25, A-35 ZSTRINGSIG field A-22 ZSTRINGSIGISPRESENT field A-22 ZSUGGESTEDDELAY field A-27 ZSUGGESTEDDELAYISPRESENT field A-27 ZTRANSFER field A-37 ZTRAVERSAL field A-32 ZTSEL field A-10 ZTYPE field A-8, A-26 ZUNCONSTRAINED field A-36 ZUNIVERSALCLASS field A-21 ZUNIVERSALCLASSISPRESENTfield A-21 ZUSERID field A-37 ZWRITE field A-31 ZXFERMGMT field A-37 HP NonStop OSI/FTAM Programming Reference Manual—528611-001 Index -21
PAGE 604
Z Index HP NonStop OSI/FTAM Programming Reference Manual—528611-001 Index -22