HP NonStop OSI/FTAM Programming Guide Abstract This manual describes how to use the Open Systems Interconnection/File Transfer, Access, and Management (OSI/FTAM) application programmatic interface (API). It provides background and task information for programmers writing FTAM applications that use the services of the NonStop initiator. Product Version OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06 Supported Release Version Updates (RVUs) This publication supports D43.
Document History Part Number Product Version Published 059365 OSI/FTAM C30, OSI/APLMGR C30 September 1992 528612-001 OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06 October 2004
HP NonStop OSI/FTAM Programming Guide Glossary Index What’s New in This Manual vii Manual Information vii New and Changed Information Examples Figures vii About This Manual ix Intended Audience ix How to Use This Manual ix Supported Standards x Related Manuals xi Notation Conventions xiii 1.
2. ISO FTAM Concepts (continued) Contents 2. ISO FTAM Concepts (continued) Access Context 2-23 File-Access Data Units 2-24 File-Access Actions 2-26 Configuration of Default Values for VFS Parameters Document Types 2-28 Object Identifiers 2-29 FTAM-1 Documents 2-29 FTAM-2 Documents 2-29 FTAM-3 Documents 2-31 Describing Document Contents 2-31 NBS-9 Documents 2-32 Attributes 2-33 Activity Attributes 2-35 File Attributes 2-37 OSI Addresses 2-42 2-26 3.
3. NonStop FTAM Programming (continued) Contents 3. NonStop FTAM Programming (continued) NonStop FTAM Initiator Errors 3-39 ISO-Defined FTAM Diagnostic Messages 3-41 NonStop FTAM Diagnostic Messages 3-44 Application-Generated Diagnostic Messages 3-45 Where to Go for More Error Information 3-45 4.
4. Using FTM Procedure Calls (continued) Contents 4. Using FTM Procedure Calls (continued) Generating Cancels 4-49 Handling P-Aborts and U-Aborts 4-51 Generating U-Aborts 4-52 Handling Errors 4-53 Errors in Request and Response Procedures 4-53 Errors in Indication and Confirm Procedures 4-55 5. NonStop FTAM Programming Examples Basic Illustrated Principles 5-1 Sample Program Structure 5-2 Reading a File: C Programming Example 5-3 Writing a File: TAL Programming Example 5-42 6.
Figures (continued) Contents Figures (continued) Figure 2-5. Figure 2-6. Figure 2-7. Figure 2-8. Figure 3-1. Figure 3-2. Figure 3-3. Figure 3-4. Figure 3-5. Figure 3-6. Figure 3-7. Figure 3-8. Figure 3-9. Figure 3-10. Figure 3-11. Figure 3-12. Figure 3-13. Figure 4-1. Figure 4-2. Figure 4-3. Figure 4-4. Figure 4-5.
Tables (continued) Contents Tables (continued) Table 2-10. Table 2-11. Table 2-12. Table 2-13. Table 2-14. Table 3-1. Table 3-2. Table 3-3. Table 3-4. Table 3-5. Table 3-6. Table 3-7. Table 3-8. Table 4-1. Table 4-2. Table 4-3. 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.
What’s New in This Manual Manual Information HP NonStop OSI/FTAM Programming Guide Abstract This manual describes how to use the Open Systems Interconnection/File Transfer, Access, and Management (OSI/FTAM) application programmatic interface (API). It provides background and task information for programmers writing FTAM applications that use the services of the NonStop initiator.
What’s New in This Manual • • • • • New and Changed Information Changed the encoded date limit from 7 KB to 16 KB on page 3-17. Added that the initiator does not check the length for unbounded string condition against the maximum-string-length value on page 3-19. Changed “maximum-string length” from a required parameter to an optional parameter under Setting Procedure Parameters on page 4-26. Deleted the “maximum-string length” component on page 4-30.
About This Manual This guide is a companion to the OSI/FTAM Programming Reference Manual and provides background information for writing application programs using HP NonStop™ OSI/File Transfer, Access, and Management (FTAM) application services.
Supported Standards About This Manual Section Title This section... 4 Using FTM Procedure Calls Describes how to use the FTAM application programmatic interface (API) to perform common operations in an FTAM application. 5 NonStop FTAM Programming Examples Describes two sample applications using the NonStop FTAM API. 6 FTAM Application Management Describes some of the tools you can use to manage NonStop OSI/FTAM and briefly discusses a few of the tasks you will perform by using those tools.
Related Manuals About This Manual Related Manuals Figure i on page -xii shows how the manual you are now reading is related to other HP manuals. The flowchart, read from the top down, indicates the order in which you might read the manuals. Manuals connected to this manual with a vertical brace provide additional support for FTAM programming, which you might not immediately need. HP suggests starting with the OSI/FTAM Programming Guide.
Related Manuals About This Manual Control Service Element (ACSE) of the Application Layer. These procedures are part of the NonStop OSI/AS data communications subsystem. Figure i. Documentation Road Map OSI/FTAM Programming Guide SCF Reference Manual for Tandem FTAM and APLMGR OSI/FTAM Config. and Mgmt.
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.
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.
Notation for Messages About This Manual 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). For example: CALL CHECKRESIZESEGMENT ( segment-id , error ) ; !i !o !i,o.
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.
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.
Change Bar Notation About This Manual HP NonStop OSI/FTAM Programming Guide—528612-001 xviii
1 Introduction to NonStop OSI/FTAM Networks that consist of equipment provided by different vendors and following different protocols are increasingly common, and in such networks, heterogeneous file transfer and access is one of the most important and obvious computing requirements. For instance: • • • • Many kinds of applications require batch transfer of files: a file produced by an application on one system is moved to another system for processing by an application there.
Introduction to NonStop OSI/FTAM Figure 1-1.
Introduction to NonStop OSI/FTAM The FTAM Application Environment defined in that standard and is consistent with the Government Open Systems Interconnection Profile (GOSIP), which means that it can interoperate with a large variety of other FTAM implementations. With NonStop FTAM, your applications can exchange and manage files across an OSI network, with record-level access to structured text files.
The NonStop OSI Services Introduction to NonStop OSI/FTAM Figure 1-2. FTAM Application Environment Application Program FTAM API Management Interface Tandem FTAM Guardian File System OSI/AS OSI/TS TLAM or X25AM Communications Network Remote FTAM Responder VST0102.vsd The NonStop OSI Services NonStop FTAM is built on the NonStop OSI services, which consist of several products, as shown in Figure 1-2.
Introduction to NonStop OSI/FTAM Developing Your Application The NonStop OSI services give your FTAM application several major advantages. One is that all NonStop OSI products support an abundance of configuration options; therefore, you can define configurations to work correctly with a wide range of other OSI equipment.
Introduction to NonStop OSI/FTAM FTAM in Online Transaction Processing Applications defined by the Guardian disk process; how to use the FTAM API procedures and files of predefined data structures; and what types of errors your application can receive through the FTAM API. Section 3, NonStop FTAM Programming covers those topics. • • • Programming concepts of the NonStop operating system, and features and operation of the NonStop C or TAL compiler and development tools.
Introduction to NonStop OSI/FTAM FTAM in Online Transaction Processing Applications The following guidelines will simplify the task of integrating your application with Pathway. Remember that, within the context of Pathway, your FTAM application is defined as a server: • • • Code each Pathway requester program so it always requests a complete, high-level application function, such as moving a file from one place to another, or updating a file.
Introduction to NonStop OSI/FTAM FTAM in Online Transaction Processing Applications HP NonStop OSI/FTAM Programming Guide—528612-001 1 -8
2 ISO FTAM Concepts This section presents basic FTAM concepts needed to understand how to write FTAM programs. The information in this section is based on ISO 8571. It also contains some information about which features NonStop FTAM supports, but because that information is also in the OSI/FTAM Programming Reference Manual, you do not need to read this section if you are already familiar with the ISO standard.
FTAM Protocol Example ISO FTAM Concepts • • • • • • Writing files (or parts of files) Erasing files (or parts of files) Creating files Deleting files Reading file attributes Changing file attributes FTAM users communicate with the FTAM service provider by way of primitives; an operation like any of those mentioned above requires the exchange of multiple primitives, which the FTAM software encodes as protocol data units (PDUs). These are terms you need to remember if you are new to ISO FTAM.
Section Contents ISO FTAM Concepts Section Contents This section consists of three parts.
Section Contents ISO FTAM Concepts Figure 2-1.
Services ISO FTAM Concepts Services The FTAM protocol consists of distinct services. These services, in turn, are made up of primitives, which are the smallest units of interaction between the FTAM user and the FTAM service provider. Services fall into two categories: confirmed and unconfirmed services. Confirmed Versus Unconfirmed Services In a confirmed service, the FTAM initiator sends a request to the FTAM responder.
FTAM External Services ISO FTAM Concepts Figure 2-2. Protocol Diagrams for Confirmed and Unconfirmed Services Confirmed Service Initiating Process Responding Process F-xxx request F-xxx indication F-xxx response F-xxx confirm Unconfirmed Service F-xxx request F-xxx indication VST0202.vsd FTAM External Services ISO defines two levels of FTAM services: external services and internal services.
FTAM External Services ISO FTAM Concepts Table 2-1. FTAM Services (page 1 of 3) Associated Primitive Confirmed Description of Function Establish FTAM regime F-INITIALIZE Yes Makes an association between the initiator and responder. Establishes FTAM regime. Is required before any other FTAM services can be performed. Terminate FTAM regime (orderly) F-TERMINATE Yes Terminates the FTAM association and the FTAM regime. Valid only in the FTAM regime.
FTAM External Services ISO FTAM Concepts Table 2-1. FTAM Services (page 2 of 3) Service Associated Primitive Confirmed Description of Function File deletion F-DELETE Yes Deletes the current file from the file storage system and deselects that file. Terminates the file-selection regime and returns to the FTAM regime. Read attribute F-READ-ATTRIB Yes Returns file-attribute values of the current file. Allowed in the file-selection regime only.
Regimes and Protocol ISO FTAM Concepts Table 2-1. FTAM Services (page 3 of 3) Associated Primitive Confirmed Description of Function End of data transfer F-DATA-END No Signifies that data transfer is complete. Allowed in the data-transfer regime only. End of transfer F-TRANSFER-END Yes Terminates the data-transfer regime and returns to the file-open regime.
Regimes and Protocol ISO FTAM Concepts Figure 2-3. Regime Hierarchy FTAM Regime File Selection Regime File Open Regime Data Transfer Regime VST0203.vsd An application program establishes the FTAM regime when it successfully initializes an association. For the given association, the application program establishes the file-selection regime after it successfully selects or creates a file.
Regimes and Protocol ISO FTAM Concepts Figure 2-4. Regime Hierarchy and Service Primitives F-INITIALIZE FTAM Regime F-SELECT F-CREATE File-Selection Regime F-READ-ATTRIB F-CHANGE-ATTRIB F-OPEN File-Open Regime F-READ F-WRITE F-LOCATE F-ERASE F-DATA F-DATA-END Data-Transfer Regime F-U-ABORT F-P-ABORT F-TRANSFER-END F-CANCEL F-CLOSE F-DESELECT F-DELETE F-TERMINATE VST0204.
Functional Units ISO FTAM Concepts Once the application program selects or creates a file, it establishes the file-selection regime, and in so doing causes the association to move from the FTAM regime to the file-selection regime. In the file-selection regime, the program can read or change attributes of the selected file (F-READ-ATTRIB or F-CHANGE-ATTRIB) or open the file (F-OPEN).
Functional Units ISO FTAM Concepts Table 2-2.
Service Classes ISO FTAM Concepts Service Classes In addition to functional units, ISO 8571 defines five service classes. Service classes are subsets of FTAM services defined as combinations of functional units and constraints on allowed protocol. ISO FTAM defines these five service classes: • • • • • File transfer File access File management File transfer and management Unconstrained class NonStop FTAM supports all ISO-defined service classes except for the unconstrained class.
Service Classes ISO FTAM Concepts Table 2-3.
Service Classes ISO FTAM Concepts Table 2-4 shows the relationships between FTAM functional units and service classes as defined in ISO 8571-3, Table 1. This table shows the services associated with each functional unit and whether a functional unit, with all its associated services, is mandatory, optional, or not permitted within a given service class. Table 2-4.
Service Classes ISO FTAM Concepts Table 2-4.
Service Class Constraints ISO FTAM Concepts Table 2-4. Relationship of Functional Units to Services and Service Classes (page 3 of 3) Service Classes Functional Units Services File Transfer File Access File Management File Transfer and Management Unconstrained Checkpointing Cancel data transfer (for recoverable errors) Key: M indicates that the functional unit is mandatory for the given service class. O indicates that the functional unit can be used optionally with the given service class.
Service Class Constraints ISO FTAM Concepts The file-transfer, file-management, and file-transfer-and-management service classes require you to use grouped services. The file-access service class permits you to use grouping but does not require it. File-Transfer Service Class To use the services in the file-transfer service class, you must perform these three consecutive tasks: 1. A single grouped service that establishes a file-open regime.
Service Class Constraints ISO FTAM Concepts Example 2-1. Sequence of primitives. One possible sequence of primitives based on these three tasks is outlined below. Other sequences of primitives are possible because you can use different combinations of the optional or alternate primitives specified in the task descriptions. 1. F-BEGIN-GROUP F-SELECT F-OPEN F-END-GROUP 2. F-READ F-DATA-IND (multiple calls as needed to complete the read) F-DATA-END F-TRANSFER-END request F-TRANSFER-END confirm 3.
Negotiation of Service Class and Functional Units ISO FTAM Concepts For the groupings specified in the file-management service class, the value of the threshold parameter must be equal to the number of primitives in the group, excluding F-BEGIN-GROUP and F-END-GROUP. For information about the threshold parameter, refer to Grouping Control on page 4-15.
Virtual Filestore ISO FTAM Concepts • Unconstrained service class If none of the proposed service classes is acceptable to the responder, the responder can reject the association. The responder also checks the list of proposed functional units and removes from the list any functional units that it does not support and any functional units not allowed by the selected service class.
Access Context ISO FTAM Concepts Figure 2-5. Hierarchical File-Access Structure Root NAME Level 0 DU A E NAME DU B C DU DU F Level 1 Level 2 D DU Preorder traversal sequence: Root, A, B, C, D, E, F VST0205.vsd The model defines the access structure of a file. You can access the nodes of the tree in order, starting from the root node and proceeding through the subtree under each child node from left to right.
File-Access Data Units ISO FTAM Concepts File-Access Data Units You access files by way of file-access data units (FADUs), which correspond to subtrees; that is, a FADU includes a node and all of its children. Figure 2-6 shows several examples of FADUs. The FADU corresponding to the entire tree (FADU 0) provides access to the entire file. Other FADUs provide access to parts of the file. Figure 2-6.
File-Access Data Units ISO FTAM Concepts Figure 2-7. NonStop FTAM FADU Structure of FTAM-1 and FTAM-3 Document Types ROOT FADU VST0207.vsd You can refer to individual FADUs by FADU identities. Table 2-5 lists the values that the FADU identity can assume. NonStop FTAM supports all values in the table, unless otherwise noted; many of the values in Table 2-5, however, apply only to the FTAM-2 document type. For further information on FADU identities that HP does not support, see ISO 8571-2, clause 7.6.
File-Access Actions ISO FTAM Concepts FADU identities are categorized into three groups according to the method of access to nodes in a file. Table 2-6 describes the FADU-identity groups, the FADU-identity values that you can use in each group, and the associated methods of access. Table 2-6. FADU-Identity Groups Group Name FADU-Identity Values Method of Access Traversal Begin, first, next, last, end. Sequential access permitting you to traverse the file from the first FADU to the last FADU.
Configuration of Default Values for VFS Parameters ISO FTAM Concepts FILCONF is a configuration interface for VFS, interacting with OSI/FTAM through a configuration file. This configuration file has entries for the filestore and the other attributes of the association. You can set these entries (within valid limits) to configure the Responder and Virtual Filestore for interoperation. FILCONF takes input from a file defined by FTAMCONF environment variable.
Document Types ISO FTAM Concepts Input Validation Every entry read from the FTAMCONF is validated for the permissible value of the parameters and the correlation between the FTAM document type and the Guardian file type as well as the File code. If any inconsistency is found, an EMS message is generated. The FILCONF selects the system defaults for the erroneous entry and continues the FTAMCONF processing.
Object Identifiers ISO FTAM Concepts Object Identifiers The list of numbers in braces ({}) under the document type names and constraint sets in Table 2-8 on page 2-28 are object identifier values. The object identifier uniquely identifies several types of different information including, but not limited to, document type names and constraint sets. Specific values for object identifiers are assigned by ISO and other organizations.
FTAM-2 Documents ISO FTAM Concepts child node that has no subsequent child node is considered a leaf node. None of the nodes has a node name. Each data unit consists of zero, one, or more character strings. Figure 2-8. Hierarchical Structure of FTAM-2 File Root Level 0 Level 1 A B C D DU DU DU DU X ... DU VST0208.vsd Your application can access the whole file through the FADU associated with the root node (FADU identity of begin).
FTAM-3 Documents ISO FTAM Concepts between nodes, for example—is lost if the whole file is transferred in UA access context. (The result is equivalent to an unstructured file.) Only the data contents of the file are transferred in this case. In the FA access context, structuring data elements in the form of node-descriptor data elements are transferred, along with file-contents data elements.
NBS-9 Documents ISO FTAM Concepts of variable, fixed, or not-significant. The value of variable indicates that all strings in the file are of variable length up to the value of the maximum-string-length parameter. The value of fixed indicates that all strings in the file are equal to the maximum-string-length parameter in length. The value of not significant indicates that the boundaries of strings in the file are not necessarily preserved in a data transfer.
Attributes ISO FTAM Concepts An NBS-9 file returns directory information about other FTAM files; the selection of attributes for which values are returned varies with the FTAM implementation and possibly with the individual NBS-9 file. As part of a directory request, your application passes a bit-string parameter that can identify up to 18 file attributes (the ones for which you would like to get values). The number after each parameter in this list indicates the parameter position in the bit-string.
Attributes ISO FTAM Concepts Kernel group attributes are available in all FTAM implementations. The other attribute groups are optional. Table 2-11 lists the FTAM activity attributes and file attributes by group. Each attribute is described following the table. NonStop FTAM supports all attributes unless the text following this table indicates otherwise. Table 2-11.
Activity Attributes ISO FTAM Concepts Activity Attributes Activity attributes relate to activity during an ISO FTAM association. These attributes are created and discarded during the life of an association. Activity attributes are particular to a single FTAM association and are not directly accessible through FTAM protocol. No permanent record of their values is kept.
Activity Attributes ISO FTAM Concepts • • • • • • • Insert Replace Extend Erase Read attribute Change attribute Delete file The file-access actions were defined in File-Access Actions on page 2-26. The current-initiator-identity attribute identifies the initiator to the responder when the application program establishes the FTAM regime. The FTAM regime establishment service (F-INITIALIZE) sets the value from the initiator-identity parameter. The scope of this attribute is the FTAM regime.
File Attributes ISO FTAM Concepts set from the account parameter of the FTAM-regime-establishment service, file-creation service, or file-selection service. The current-concurrency-control attribute specifies the restrictions on parallel access to a file requested by the initiator. The value for each element of current concurrency control corresponds to each of the file-access actions listed in the description of the current-access-request attribute, and is one of the four values given in Table 2-13.
File Attributes ISO FTAM Concepts Negotiating File Attributes File-attribute groups are negotiated when an FTAM association is established. On the F-INITIALIZE request primitive, the attribute-groups parameter proposes a list of the optional attribute groups (storage, security, or private) that you want available for the association. A remote responder can reduce the list to what it can support; it cannot add to the list you propose.
File Attributes ISO FTAM Concepts • • • • • • • Insert Replace Extend Erase Read attribute Change attribute Delete file Table 2-14.
File Attributes ISO FTAM Concepts Contents-type. The contents-type attribute indicates either of the following: • • Document type of a file (and, optionally, parameter values that further define the document type). Abstract syntax name/constraint set name pair. Abstract syntax is defined as an abstract representation of the way in which components of information are to be specified in a communication.
File Attributes ISO FTAM Concepts FTAM, this attribute is set to the value of the current-initiator-identity activity attribute. You cannot use the change-attribute action to change this attribute. Identity-of-last-modifier. The identity-of-last-modifier attribute identifies the entity that last modified the file. The responder updates this attribute whenever the file is closed after it has been opened for modification or extension.
OSI Addresses ISO FTAM Concepts Security Group Attributes The security group must be negotiated before these attributes are available. This section describes the security group attributes. Access-control. The access-control attribute specifies the conditions under which access to a file is allowed. The conditions are defined by these elements: action list, concurrency access, identity, passwords, and location. If at least the condition defined by action-list is satisfied, access to the file is permitted.
3 NonStop FTAM Programming This section presents programming concepts and tasks important to application development in the NonStop FTAM environment using the NonStop initiator. This section covers these topics: Topic Page Association Establishment Concepts 3-1 Data Transfer Concepts 3-11 FTAM API Concepts 3-31 Error-Handling Concepts 3-39 Association Establishment Concepts A connection between an FTAM initiator and a remote FTAM responder is an association.
NonStop FTAM Programming APLMGR Process Name Programmers familiar with Guardian programming concepts will find it useful to know that a CEPI is a file number, as defined by the NonStop operating system, but has a negative value. Note. An FTAM CEPI identifies associations with an initiator rather than with a TAPS process. As such, FTAM and OSI/AS CEPIs are not equivalent and should not be used in the same program. NonStop FTAM applications should not combine FTAM API and OSI/AS API procedures.
NonStop FTAM Programming Subdevices Control Facility (SCF) allows you to configure or modify a default common name for an initiator process; this common name must correspond to a specific OSI address registered in the management information base controlled by the OSI manager process. For information about the management information base controlled by the OSI manager, see the OSI/AS Configuration and Management Manual. The common name does not necessarily refer to a particular initiator.
Subdevices NonStop FTAM Programming determines the outgoing path of communication for the application, including the OSI processes underlying FTAM, the associated controller, and subnetwork. The number of subdevices present for a given initiator process equals the current number of active associations using that initiator. Figure 3-1. Dual-NSP Configuration FTAM Initiator TAPS TSP TLAM-Based NSP X25-AM-Based NSP Ethernet/802.3 LAN Controller General-Purpose Controller X.25 NET To 802.
NonStop FTAM Programming How an Association Is Established Although your application might never use subdevice names, those names can be useful in debugging. For example, you need to supply a subdevice name as input to the SCF STATUS SU command, which provides you with useful information about the association. (For an explanation of the information this command returns for initiator subdevices, see Section 6, FTAM Application Management.
How an Association Is Established NonStop FTAM Programming and remote common names or OSI addresses, provided by the local-appl and remote-appl parameters. If the application did not specify a local common name and/or address in the local-appl parameter, the initiator sends its configured default. 8. The OSI manager retrieves the necessary addressing information from its MIB. Figure 3-2.
NonStop FTAM Programming Wait and Nowait Modes 9. The OSI manager chooses a TAPS subdevice name and sends a request to the local TSP server process to add a subdevice using this name. This request includes the name of the local NSP server process. 10. The TSP process builds a TSP subdevice name from the TAPS subdevice name, adds the TSP subdevice, and responds to the OSI manager. 11. The OSI manager then sends a request to the local TAPS server process to add a subdevice, using the name chosen in Step 9.
Wait and Nowait Modes NonStop FTAM Programming Wait Mode Procedures called in wait mode wait for the completion or failure of an I/O request, signalled by the return of a status code from that procedure. When you call a procedure in wait mode, the procedure does not return control to your application until the action associated with that procedure has completed or has failed. In most cases, an FTAM request requires a confirm from the remote FTAM responder.
NonStop FTAM Programming Wait and Nowait Modes Using MFM_AWAITIOX_ The FTAM API invokes I/O operations on behalf of your application. Therefore, the NonStop operating system returns I/O completion information to the FTAM API instead of to your program. While in nowait mode, your program retrieves I/O completion information from the FTAM API by calling the MFM_AWAITIOX_ procedure. Typically, your application contains a mixture of file-system, APS general-support, and FTM protocol procedure calls.
NonStop FTAM Programming • Wait and Nowait Modes No more than one call to an FTM procedure that causes I/O operations (see Table 4-1 on page 4-2) You can call Guardian file-system procedures while you wait for an FTM procedure or APS procedure to complete. Canceling Nowait Operations You can cancel a pending nowait operation by calling the MFM_CANCELREQ_ procedure for the associated CEPI. Using the MFM_CANCELREQ_ procedure is similar to using the Guardian procedure CANCELREQ.
NonStop FTAM Programming Data Transfer Concepts To use the tag parameter, assign a unique 32-bit integer value to the variable you will use for the tag. When you call an FTAM request procedure in nowait mode, include the tag in the parameter list. After the requested service is performed, the MFM_AWAITIOX_ call returns the tag for this service, identifying which service was completed. For reference information on the MFM_AWAITIOX_ procedure, see the OSI/FTAM Programming Reference Manual.
Data-Value Parameter NonStop FTAM Programming class 27) character string before checking the length of the string against the negotiated maximum-string-length value. When sending data to a remote responder, the initiator does not remove escape sequences embedded in such character strings but does exclude them from the calculation of the character-string length. • Some files might contain multiple character sets.
NonStop FTAM Programming Data-Value Parameter respectively. For descriptions of both structures, see the OSI/FTAM Programming Reference Manual. The contents of data-value differs depending on the FTAM document type being transferred. The subsections on the individual document types later in this section describe how applications handle data for the various document types.
Data-Value Parameter NonStop FTAM Programming !---------------------------------------------------------------------! ! This procedure takes the data-value parameter returned by a call ! ! to FTM_DATA_IND_ and processes each data element in the buffer. ! !---------------------------------------------------------------------! proc process_data(data_value); string .ext data_value; ! the data_value parameter returned by the ! FTM_DATA_IND_ procedure call begin int .
NonStop FTAM Programming Data-Value Parameter Limits on Data-Value Sizes The calculation of the maximum size of the data-value parameter is based on the number and length of character strings in the encoded data and the associated data header information. Because the data-value parameter contains more overhead of data header information than the encoded data, it can be larger than the maximum size of the encoded data, which is 16 KB.
NonStop FTAM Programming Data-Value Parameter Where NS = number of data elements ZLENi= length in bytes of the ith character string PAD = pad byte following string; if string length is even, PAD = 0; otherwise, PAD = 1; for the purposes of these calculations, PAD = 1 ND = number of node descriptors FSL = FADU structure length (size of ZFTM-DDL-DE-FADU data structure, or 50 bytes) 50 = internal initiator header overhead 16 = maximum data-value data header overhead 26 = maximum data-value element-header ove
Data-Value Parameter NonStop FTAM Programming Where NE = number of data elements ZLENi= length in bytes of the ith character string PAD = pad byte following string; if string length is even, PAD = 0; otherwise, PAD = 1; for the purposes of these calculations, PAD = 1 ND = number of node descriptors FSL = FADU structure length (size of ZFTM-DDL-DE-FADU data structure, or 50 bytes) 16 = maximum data-value data header overhead 26 = maximum data-value element-header overhead per data element Data-value limit
NonStop FTAM Programming NS-1 ∑ i=0 FTAM-1 Files ZLENi + ((TAG + LEN) * NS) <= 16384 Encoded-data limit for transfers of FTAM-2 files with FA access context): NS-1 ∑ i=0 ZLENi + ((TAG + LEN) * NS) + (8 * ND)<= 16384 Note. When the NonStop initiator encodes data, the maximum encoded-data header overhead (TAG + LEN) is always 4 bytes per string. One way to determine the TAG and LEN values for encoded data from a remote responder is to examine a trace of the NonStop initiator process.
NonStop FTAM Programming FTAM-1 Files STRINGSIG-NOTSIG (not significant), ZFTM-VAL-STRINGSIG-VARIABLE (variable), and ZFTM-VAL-STRINGSIG-FIXED (fixed). For not-significant string-significance, it does not matter whether you place the data in one or multiple data elements because the boundaries of character strings do not necessarily contribute to a document’s semantics.
FTAM-1 Files NonStop FTAM Programming Figure 3-4 shows a typical FTAM-1 or FTAM-3 data-value parameter, where the string-significance parameter has the value ZFTM-VAL-STRINGSIG-NOTSIG. Although FTAM-1 and FTAM-3 files differ in contents type, they are both transferred whole and use similar data-value structures. ZAPS-DDL-DATA-HDR indicates the number of data elements in the data-value parameter, and ZAPS-DDL-DATA-ELEMENT-HDR, the length and type of data in the data element. Figure 3-4.
FTAM-1 Files NonStop FTAM Programming Figure 3-6 shows a typical FTAM-1 or FTAM-3 data-value parameter where the string-significance parameter has the value ZFTM-VAL-STRINGSIG-VARIABLE. Figure 3-6. FTAM-1 or FTAM-3 Data-Value Parameter With String-Significance = ZFTM-VAL-STRINGSIG-VARIABLE ZAPS-DDL-DATA-HDR ZAPS-DDL-DATA-ELEMENT-HDR (length <_ max string length) Data element ZAPS-DDL-DATA-ELEMENT-HDR (length <_ max string length) Data element . . .
FTAM-2 Files NonStop FTAM Programming The initiator checks the length of each string against the maximum-string-length value proposed in the contents-type parameter of the open request or returned in the open confirm, where the maximum value is 7148 bytes. If the string length is greater than the proposed maximum-string-length, the initiator issues a provider abort. Files on the NonStop System Compatible with FTAM-1 Documents The Guardian file type corresponding to an FTAM-1 file is a standard EDIT file.
FTAM-2 Files NonStop FTAM Programming FTM_WRITE_REQ_ procedure call. You can write only to the end of an FTAM-2 file. You can replace the contents of an FTAM-2 file by first erasing the file and then writing to the end of the file. However, you must first have negotiated the file-access service class to erase the file. For more information about erasing a file, see the example for the FTM_ERASE_REQ_ procedure call in the OSI/FTAM Programming Reference Manual.
FTAM-2 Files NonStop FTAM Programming You must set the fields in ZFTM-DDL-DE-FADU to the following values when writing to multiple nodes: ZFTM-DDL-DE-FADU Field Value ZTYPE ZFTM-VAL-DE-NODE-DESC ZNAMEISPRESENT ZAPS-VAL-ABSENT ZARCLENGTHISPRESENT ZAPS-VAL-ABSENT* ZDATAEXISTS ZAPS-VAL-TRUE** * When the application provides no arc length value, the value defaults to 1, the value required for FTAM-2 files. ** The ZDATAEXISTSISPRESENT field is ignored by the initiator. Figure 3-9.
NonStop FTAM Programming FTAM-2 Files You must use a separate data element for each string. String length must be less than or equal to the value of maximum-string-length proposed by the FTM_OPEN_REQ_ or FTM_FILE_OPEN_REQ_ procedure or returned in the contents-type parameter by the FTM_OPEN_CNF_ or FTM_FILE_OPEN_CNF_ procedure. If the string length is greater than the proposed maximum-string-length, the initiator returns an error to the application.
FTAM-2 Files NonStop FTAM Programming Files on the NonStop System Compatible with FTAM-2 Documents The Guardian file type corresponding to an FTAM-2 file is an Enscribe relative file or SQL table, Type R. Its structure is shown in Figure 3-10 on page 3-26. The record number in a relative file corresponds to an FTAM node descriptor, and a record corresponds to a node as defined by FTAM. Figure 3-10.
NonStop FTAM Programming • FTAM-3 Files Extent sizes and number of extents, which determine the size of the file, should be consistent with the requirements of your application, for instance, large enough to hold the data you expect to transfer into the file. The suggestion for record length given above is based on the fact that, in the NonStop FTAM implementation, each node of an FTAM-2 file contains exactly one string.
NonStop FTAM Programming FTAM-3 Files string-significance parameter value of ZFTM-VAL-STRINGSIG-VARIABLE, see Figure 3-6 on page 3-21. Reading FTAM-3 Files To read an FTAM-3 file, you must first open the file (using FTM_OPEN_REQ_ or FTM_FILE_OPEN_REQ_) with a process-mode (ZFTM-DDL-PROC-MODE) parameter value of read. A fadu-id (ZFTM-DDL-FADU-ID) parameter value of first must be used on the FTM_READ_REQ_ call. The entire file is then returned by successive F-DATA indication events.
NonStop FTAM Programming FTAM-3 Files Figure 3-11. Entry-Sequenced Files on the NonStop System 1st Record 2nd Record Data Data 5th Record 6th Record Data 10th Record Data 11th Record Data Data 3rd Record 4th Record Data Data 7th Record Data 12th Record Data 8th Record 9th Record Data Data 13th Record 14th Record Data Empty Unused Data Blocks Unused Unused Variable-Length Physical Records VST0311.
NonStop FTAM Programming NBS-9 Files Note. 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.
NonStop FTAM Programming FTAM API Concepts Figure 3-12. Structure of NBS-9 Data-Value Parameter ZAPS-DDL-DATA-HDR ZAPS-DDL-DATA-ELEMENT-HDR ZFTM-DDL-READ-ATTR ZAPS-DDL-DATA-ELEMENT-HDR ZFTM-DDL-READ-ATTR . . . ZAPS-DDL-DATA-ELEMENT-HDR ZFTM-DDL-READ-ATTR VST0312.vsd ZFTM-DDL-READ-ATTR is defined in the file ZFTMDDL. For a description of this structure, see the OSI/FTAM Programming Reference Manual.
NonStop FTAM Programming • Initializing the API ZAPSTAL and ZFTMTAL files for data definitions To access FTAM library files in the C language, include these source files: • • CEXTDECS file (as $SYSTEM.SYSTEM.CEXTDECS) for FTM, APS, and MFM procedures ZAPSC and ZFTMC files for data definitions The ZAPSTAL and ZAPSC files are located in the OSI/AS distribution subvolume, ZOSIAPS, and the ZFTMTAL and ZFTMC files are located on the FTAM distribution subvolume, ZOSIFTAM.
NonStop FTAM Programming Using Predefined Data Structures 2. Call the procedure. 3. After calling the procedure: • • • ° Check the status or error code returned by the procedure. A procedure that performs I/O operations returns a status code; a procedure that does not perform I/O operations returns an error code. ° If status is not equal to ZAPS-VAL-STATUS-OK (0), call APS_STATUS_ for error-code and error-subcode values.
NonStop FTAM Programming DEFINITION ZFTM-DDL-CNTNTS-TYPE. 02 ZID 02 ZCNTNTSTYPE Using Predefined Data Structures TYPE ZAPS-DDL-ENUM1. TYPE ZAPS-DDL-CHAR128. 02 ZDOCTYPE 03 ZDOCTYPENAME 03 ZUNIVERSALCLASSISPRESENT 03 ZUNIVERSALCLASS 03 ZMAXSTRINGLENISPRESENT 03 ZMAXSTRINGLEN 03 ZSTRINGSIGISPRESENT 03 ZSTRINGSIG 03 ZFILEATTRSISPRESENT 03 ZFILEATTRS REDEFINES ZCNTNTSTYPE. TYPE ZAPS-DDL-OBJ-ID. TYPE ZAPS-DDL-ISPRESENT. TYPE ZAPS-DDL-INT2. TYPE ZAPS-DDL-ISPRESENT. TYPE ZAPS-DDL-INT2.
NonStop FTAM Programming Using Predefined Data Structures C Example The file ZFTMC shows this C data structure for zfaps_ddl_cntnts_type_def (comments are omitted, and lines are renumbered): 1 #pragma section zftm_ddl_cntnts_type 2 typedef struct 3 { 4 zaps_ddl_enum1_def 5 union 6 { 7 zaps_ddl_char128_def 8 struct 9 { zid; zcntntstype; 10 zaps_ddl_obj_id_def zdoctypename; 11 zaps_ddl_ispresent_def zuniversalclassispresent; 12 zaps_ddl_int2_def zuniversalclass; 13 zaps_ddl_ispresent_de
NonStop FTAM Programming Using Predefined Data Structures union name, u_zcntntstype; on line 19, the name of the union structure containing the desired field, zdoctype; on line 10, the name of the field in zdoctype, zdoctypename. Line 10 also shows that zdoctypename is defined as zaps_ddl_obj_id_def, which is specified in the file ZAPSC. The zaps_ddl_obj_id structure corresponds to the ASN.
NonStop FTAM Programming Using Predefined Data Structures TAL Example To reference TAL data structures, you follow a similar procedure to the one outlined above. Consider the same example.
NonStop FTAM Programming Using Predefined Data Structures 36 INT ZLASTMOD; 37 INT ZLASTREADACCESS; 38 INT ZLASTATTRMOD; 39 INT ZCREATORID; 40 INT ZLASTMODID; 41 INT ZLASTREADERID; 42 INT ZLASTATTRMODID; 43 INT ZFILEAVLBLTY; 44 INT ZFILESIZE; 45 INT ZFUTUREFILESIZE; 46 INT ZACCESSCNTRL; 47 INT ZLEGALQUALIF; 48 INT ZPRIVATEUSE; 49 END; 50 51 END; STRUCT ZCNSTRNTSETANDABSSYN = ZCNTNTSTYPE; 52 BEGIN 53 STRUCT 54 BEGIN 55 INT ZNUM^ELEMENTS; 56 INT ZOBJ^ID[
NonStop FTAM Programming Error-Handling Concepts of the structure containing the desired field, ZDOCTYPE; on line 17, the name of the field in ZDOCTYPE, ZDOCTYPENAME; and on lines 19 and 20, the names of the subfields defining ZDOCTYPENAME, ZNUM^ELEMENTS, and ZOBJ^ID. Therefore, to set up the document type name for an FTAM-3 file, use these lines of TAL code: contents_type.zdoctype.zdoctypename.znum^elements := 5; contents_type.zdoctype.zdoctypename.zobj^id [0] := 1; contents_type.zdoctype.zdoctypename.
NonStop FTAM Programming NonStop FTAM Initiator Errors The return value from a NonStop FTAM procedure call can be the first indication of an error condition. NonStop FTAM procedures use two types of return values: status and error. Status return values are returned by procedures performing I/O operations, and error return values are returned by procedures that perform no I/O operations. Note. Guardian condition codes are not used with any of the FTAM procedures.
NonStop FTAM Programming ISO-Defined FTAM Diagnostic Messages immediately call the APS_STATUS_ procedure in your program. The error-code and error-subcode parameters of this call provide additional details on the error condition, and the original-error-info (ZAPS-DDL-ORIGINAL-ERROR) parameter provides details on the first error detected in the OSI/AS layers.
NonStop FTAM Programming ISO-Defined FTAM Diagnostic Messages messages are defined in ISO 8571 and apply generically to any FTAM implementation. Circumstances for each error can vary from implementation to implementation, so you might need to refer to the documentation for the responding implementation to determine the exact nature of the problem. Most indication and confirm procedures can return diagnostic messages.
NonStop FTAM Programming ISO-Defined FTAM Diagnostic Messages Table 3-5. FTAM Diagnostic Message Contents Information Type Description Error Type Indicates whether the error is informative, permanent, or transient: • • • An informative error does not require recovery and does not affect the current state of the operation being attempted; it provides information to qualify a successful action.
NonStop FTAM Programming NonStop FTAM Diagnostic Messages Table 3-6.
NonStop FTAM Programming Application-Generated Diagnostic Messages Application-Generated Diagnostic Messages Four FTM procedure calls provide an optional diagnostic input parameter allowing you to include informative diagnostic messages with your application’s cancel, data-end, and abort requests (or responses, in the case of FTM_CANCEL_RSP_) to the responding system.
NonStop FTAM Programming Where to Go for More Error Information Table 3-8. Where to Find Additional Error Information (page 2 of 2) (continued) For details on... go to...
NonStop FTAM Programming Where to Go for More Error Information Figure 3-13.
NonStop FTAM Programming Where to Go for More Error Information HP NonStop OSI/FTAM Programming Guide—528612-001 3- 48
4 Using FTM Procedure Calls This section provides instructions on how to use the FTAM procedures to perform operations common to many FTAM applications.
Using FTM Procedure Calls Programming Tasks Table 4-1.
Using FTM Procedure Calls Programming Tasks Table 4-1.
Using FTM Procedure Calls Initializing the API contains programming examples in TAL and C that demonstrate reading and writing FTAM files. Initializing the API When your application is running, but before it establishes its first FTAM association across the network, it must call the APS_INITIALIZE_ procedure. This procedure allocates an extended segment that the FTAM API can use to maintain the context information for all the FTAM associations your application establishes.
Using FTM Procedure Calls Establishing an Association Table 4-2. Procedure Sequence for Receiving an Event Step Action to Take Procedure(s) to Call 1 Get the event. APS_EVENT_RECEIVE_ 2 Check status: What is the event? Or, if APS_EVENT_RECEIVE_ returns a status other than ZAPS-VAL-STATUS-EVENT, is there an error? APS_STATUS_ 3 Retrieve indication or confirm information.
Using FTM Procedure Calls Procedure-Call Sequence Table 4-3. Calls for Establishing an Association Step Action to Take Procedure(s) to Call Initialize the API (before first association). APS_INITIALIZE_ Connect the initiator with the remote responder specified. FTM_INITIALIZE_REQ_ a. If error returned by FTM_INITIALIZE_REQ_, check status. APS_STATUS_ b. If nowait mode, await completion of FTM_INITIALIZE_REQ_. MFM_AWAITIOX_ c. If error returned by MFM_AWAITIOX_, check status.
Using FTM Procedure Calls Setting Procedure Parameters code, to obtain the details of an error at this stage, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. a. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the APS_EVENT_RECEIVE_ call and to obtain the status code. A status code of ZAPS-VAL-STATUS-EVENT means you have received an event. 3.
Using FTM Procedure Calls Setting Procedure Parameters addresses, the default common name might not be the address you want. For more information on specifying the address of the local application entity, see OSI Addresses and Common Names on page 3-2. 3. The wait-mode parameter sets the association to wait or nowait operating mode. Valid values are ZAPS-VAL-WAITED or ZAPS-VAL-NOWAITED. The default value is ZAPS-VAL-WAITED. 4.
Using FTM Procedure Calls Setting Procedure Parameters Functional Unit DDL Identifier Value Limited file management ZFILEMGMT TRUE Enhanced file management ZFILEMGMTENHANCED TRUE Grouping ZGROUP TRUE FADU locking ZFADULOCK FALSE Recovery ZRECOVERY FALSE Restart data transfer ZRESTART FALSE The default functional units are consistent with the default service class.
Using FTM Procedure Calls Terminating an Association Terminating an Association When you complete your communication over an association, use the FTM_TERMINATE_REQ_ procedure to release the association. Table 4-4 shows the sequence of procedures to call and describes the steps for the orderly release of an association. Sometimes you can omit a procedure call associated with a substep, depending on the context. The sequence of procedures is explained after the table. Table 4-4.
Using FTM Procedure Calls Creating Files 2. Next, to receive a terminate confirm event, call APS_EVENT_RECEIVE_. In wait mode, this procedure returns a status code of ZAPS-VAL-STATUS-EVENT when you receive an event. If APS_EVENT_RECEIVE_ returns a different status code, to obtain the details of an error at this stage, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. a.
Using FTM Procedure Calls Procedure-Call Sequence Table 4-5. Calls for Creating an FTAM File (page 2 of 2) Step Action to Take Procedure(s) to Call a. If nowait mode, await completion of APS_EVENT_RECEIVE_. MFM_AWAITIOX_ 3 Check status: Is the event a create confirm? Or, if APS_EVENT_RECEIVE_ returns a status other than ZAPS-VAL-STATUS-EVENT, is there an error? APS_STATUS_ 4 Retrieve service confirm information.
Using FTM Procedure Calls Setting Procedure Parameters If the state-result value is ZFTM-VAL-STATE-SUCCESS and the action-result value is ZFTM-VAL-ACTION-SUCCESS, the file was created and has been selected. If the state-result value is ZFTM-VAL-STATE-FAILURE and the action-result value is ZFTM-VAL-STATE-SUCCESS, the file was created, but not selected. Setting Procedure Parameters To provide details about the file you wish to create, use these parameters of the FTM_CREATE_REQ_ procedure: 1.
Using FTM Procedure Calls Setting Procedure Parameters 3. The create-password (ZAPS-DDL-CHAR32) is an optional parameter that you can use to verify that the user identified by the initiator-id parameter has permission to create files in the current file system. If the create-password parameter is not supplied, no password is sent to the remote responder. 4.
Using FTM Procedure Calls Grouping Control Grouping Control Grouping control allows your application to perform a series of confirmed services as one interaction between the initiator and responder. The request primitives for these services are bracketed with the F-BEGIN-GROUP and F-END-GROUP request primitives. The FTAM initiator concatenates the grouped FTAM primitives and sends them in a single request PDU.
Using FTM Procedure Calls Grouping Control bar separating services in parentheses indicates that either but not both of the enclosed services must be included in the sequence. The group letters A through E are used for consistency with those defined in ISO 8571. Table 4-6.
Using FTM Procedure Calls Sample Procedure-Call Sequence Sample Procedure-Call Sequence Table 4-8 presents a sample procedure-call sequence using two grouped services: F-SELECT and F-OPEN. A similar sequence is used for all grouped services. Table 4-8. Calls for Selecting and Opening FTAM Files Using Two Grouped Services (page 1 of 2) Step Action to Take Procedure(s) to Call 1 Begin grouped request. FTM_BEGIN_GROUP_REQ_ a. If error returned by FTM_BEGIN_GROUP_REQ_, check status. APS_STATUS_ b.
Using FTM Procedure Calls Sample Procedure-Call Sequence Table 4-8. Calls for Selecting and Opening FTAM Files Using Two Grouped Services (page 2 of 2) Step Action to Take Procedure(s) to Call 8 Check status: Is the event a select confirm? Or, if APS_EVENT_RECEIVE_ returns a status other than ZAPS-VAL-STATUS-EVENT, what is the error? APS_STATUS_ 9 Retrieve service confirm information. FTM_SELECT_CNF_ 10 Get the next event. APS_EVENT_RECEIVE_ a. If nowait mode, await completion.
Using FTM Procedure Calls Sample Procedure-Call Sequence 2. To select an FTAM file, call FTM_SELECT_REQ_, giving details about the file you wish to select. The parameters involved in selecting a file are discussed in Selecting Files on page 4-21. a. If the select procedure succeeds, it returns a status code of ZAPS-VALSTATUS-OK. If the procedure fails, it returns a different status code.
Using FTM Procedure Calls Sample Procedure-Call Sequence specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. a. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the APS_EVENT_RECEIVE_ call and to obtain the status code. A status code of ZAPS-VAL-STATUS-EVENT means you have received an event. 6. If you have received an event, call APS_STATUS_ to determine which event.
Using FTM Procedure Calls Setting the Threshold Parameter Setting the Threshold Parameter The threshold parameter specifies how many primitives (not including the F-BEGIN-GROUP and F-END-GROUP primitives) must succeed before the group can be considered successful. Success occurs when a primitive returns a state-result value other than ZFTM-VAL-STATE-FAILURE. If threshold is set to the total number of primitives in the group, the primitives in the group succeed or fail as a group.
Using FTM Procedure Calls Procedure-Call Sequence Table 4-9. Calls for Selecting an FTAM File Step Action to Take Procedure(s) to Call 1 Select a file in the current file system. FTM_SELECT_REQ_ a. If error returned by FTM_SELECT_REQ_, check status. APS_STATUS_ b. If nowait mode, await completion of FTM_SELECT_REQ_. MFM_AWAITIOX_ c. If error returned by MFM_AWAITIOX_, check status. APS_STATUS_ Get the next event. APS_EVENT_RECEIVE_ a. If nowait mode, await completion of APS_EVENT_RECEIVE_.
Using FTM Procedure Calls Setting Procedure Parameters a. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the APS_EVENT_RECEIVE_ call and to obtain the status code. A status code of ZAPS-VAL-STATUS-EVENT means you received an event. 3. If you received an event, call APS_STATUS_ to determine which event. If the event code is ZFTM-VAL-EVT-SELECT-CNF, you received a select confirm. 4. Next, call FTM_SELECT_CNF_ to retrieve the data sent by the confirm.
Using FTM Procedure Calls Opening Files file if the access passwords for the requested actions do not match the responder’s access passwords. If you do not supply the parameter, the initiator does not send passwords to the remote responder. 4. The account (ZAPS-DDL-CHAR32) parameter identifies the account to charge for any costs incurred in the regime being established. If you do not supply account, no account name will be supplied to the remote responder. Some responders require an account identifier.
Using FTM Procedure Calls The Open Procedure These steps explain the sequence of procedure calls given in Table 4-10 on page 4-24. 1. To open a file, call FTM_OPEN_REQ_, using the parameters of the procedure to provide details about the file you wish to open. For information on setting the procedure parameters, see the following subsection. a. If the procedure succeeds, it returns a status code of ZAPS-VAL-STATUS-OK. If the procedure fails, it returns a different status code.
Using FTM Procedure Calls The File Open Procedure perform. The process-mode must be a subset of the requested-access parameter specified during file selection. The process-mode parameter is a string of Boolean fields, and each Boolean field can take on the values ZAPS-VAL-TRUE or ZAPS-VAL-FALSE. The fields and default values for process-mode include: Field Name Associated Action Default Value ZREAD Read a FADU in the file. TRUE ZINSERT Insert data into the file.
Using FTM Procedure Calls The File Open Procedure Procedure-Call Sequence Table 4-11 shows the sequence of procedures to call and describes the steps to optionally create, select, and open an FTAM file, using FTM_FILE_OPEN_REQ_, a grouped procedure. Sometimes you can omit a procedure call associated with a substep, depending on the context. The sequence of procedures is explained after the table.
Using FTM Procedure Calls The File Open Procedure a. If the procedure succeeds, it returns a status code of ZAPS-VAL-STATUS-OK. If the procedure fails, it returns a different status code. To obtain the details of an error at this stage, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. b. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the FTM_FILE_OPEN_REQ_ call.
Using FTM Procedure Calls The File Open Procedure 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 initialattrib parameter. File is selected. ZFTM-VAL-FOPEN-REPLACE (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-FOPEN-RECREATE (3) New file is created.
Using FTM Procedure Calls The File Open Procedure FTM_INITIALIZE_REQ_ call. The remote responder will reject the file selection if the access passwords for the requested actions do not match the responder’s access passwords. If the parameter is not supplied, the initiator will not send any passwords to the remote responder. If the file-status parameter specifies creating a new file or recreating a file with new attributes, the access-passwords attribute only verifies any delete actions.
Using FTM Procedure Calls Closing Files Field Name Associated Action Default Value ZREAD Read a FADU in the file. TRUE ZINSERT Insert data into the file. FALSE ZREPLACE Replace information in the file. FALSE ZEXTEND Extend the file. FALSE ZERASE Erase some or all the contents of the file. FALSE 8. The contents-type (ZFTM-DDL-CNTNTS-TYPE) parameter allows you to specify the FTAM document type.
Using FTM Procedure Calls The Close Procedure Table 4-12. Calls for Closing an FTAM File Using FTM_CLOSE_REQ_ Step Action to Take Procedure(s) to Call 1 Close the previously opened file. FTM_CLOSE_REQ_ a. If error returned by FTM_CLOSE_REQ_, check status. APS_STATUS_ b. If nowait mode, await completion of FTM_CLOSE_REQ_. MFM_AWAITIOX_ c. If error returned by MFM_AWAITIOX_, check status. APS_STATUS_ Get the next event. APS_EVENT_RECEIVE_ a.
Using FTM Procedure Calls The File Close Procedure 3. If you received an event, call APS_STATUS_ to determine which event. If the event code is ZFTM-VAL-EVT-CLOSE-CNF, you received a close confirm. 4. Next, call FTM_CLOSE_CNF_ to retrieve the data sent by the confirm. Check the action-result output parameters. If the action-result value is ZFTM-VAL-ACTION-SUCCESS, the file has been closed.
Using FTM Procedure Calls The File Close Procedure This call can issue these FTAM primitives: F-BEGIN-GROUP request F-CLOSE request F-DESELECT request or F-DELETE request, depending on delete-action. F-END-GROUP request For a delete-action value of ZFTM-VAL-CLOSE-NODELETE, this procedure calls the F-DESELECT request primitive. For a delete-action value of ZFTM-VAL-CLOSE-DELETE, the procedure calls the F-DELETE request primitive. The default value for the delete-action parameter is ZFTM-VAL-CLOSE-NODELETE.
Using FTM Procedure Calls Deselecting Files Deselecting Files Table 4-14 shows the sequence of procedures to call and describes the steps to follow to deselect an FTAM file. Sometimes you can omit a procedure call associated with a substep, depending on the context. The sequence of procedures is explained after the table. The sequence of procedures is explained after the table. Table 4-14.
Using FTM Procedure Calls Deleting Files input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. a. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the APS_EVENT_RECEIVE_ call and to obtain the status code. A status code of ZAPS-VAL-STATUS-EVENT means you received an event. 3. If you received an event, call APS_STATUS_ to determine which event. If the event code is ZFTM-VAL-EVT-DESELECT-CNF, you received a deselect confirm. 4.
Using FTM Procedure Calls Deleting Files requested-access parameter of the FTM_SELECT_REQ_ procedure must be set to ZAPS-VAL-TRUE. Also, if the remote responder requires it, you need to enter the correct access-passwords parameter in the ZDELETEPASSWD field of requested-access. Note. For the remote responder to respond affirmatively to the delete primitive, the deletefile field of the permitted-actions attribute of this file must be set to ON. a.
Using FTM Procedure Calls Writing Files Writing Files This section describes the steps to follow to write to an FTAM file and gives details on how to set the parameters of the FTM_WRITE_REQ_ procedure. Procedure-Call Sequence Figure 4-2 shows the sequence of FTAM primitives used for writing data to a previously opened file on a remote system. For an overview of data transfer concepts of NonStop FTAM, see Section 3, NonStop FTAM Programming. Figure 4-2.
Using FTM Procedure Calls Procedure-Call Sequence Table 4-16. Calls for Writing an FTAM File Step Action to Take Procedure(s) to Call 1 Issue a write request. FTM_WRITE_REQ_ a. If error returned by FTM_WRITE_REQ_, check status. APS_STATUS_ b. If nowait mode, await completion of FTM_WRITE_REQ_. MFM_AWAITIOX_ c. If error returned by MFM_AWAITIOX_, check status. APS_STATUS_ Issue a data request. FTM_DATA_REQ_ a. If error returned by FTM_DATA_REQ_, check status. APS_STATUS_ b.
Using FTM Procedure Calls Procedure-Call Sequence These steps explain the sequence of procedure calls given in Table 4-16 on page 4-39. 1. To request a data transfer from the local NonStop system to a previously opened file on a remote system, call FTM_WRITE_REQ_, specifying details about the file to which you wish to write (for information on the parameters of this procedure, see the following subsection). a. If the procedure succeeds, it returns a status code of ZAPS-VAL-STATUS-OK.
Using FTM Procedure Calls Setting Procedure Parameters c. If you call MFM_AWAITIOX_ and the status code returned is not ZAPS-VALSTATUS-OK, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. 4. Call FTM_TRANSFER_END_REQ_ to signify that the application does not need to transfer any more data. a. If the transfer-end procedure fails, it returns a status code other than ZAPSVAL-STATUS-OK.
Using FTM Procedure Calls Setting Procedure Parameters a. ZFTM-VAL-FADU-OP-INSERT specifies that the responder will insert the data immediately before the FADU identified in fadu-id. This value is valid for FTAM-2 files only. b. ZFTM-VAL-FADU-OP-REPLACE specifies that the data will replace the FADU identified in fadu-id. This value is valid for FTAM-1 and FTAM-3 files only. c. ZFTM-VAL-FADU-OP-EXTEND specifies that the responder will append the data being sent to the end of the FADU indicated in fadu-id.
Using FTM Procedure Calls Reading Files Reading Files This section describes the steps to follow to read an FTAM file and gives details on how to set the parameters of the FTM_READ_REQ_ procedure. Procedure-Call Sequence Figure 4-3 shows the sequence of FTAM primitives used for reading a file from a remote responder. For an overview of data transfer concepts of NonStop FTAM, see Section 3, NonStop FTAM Programming. Figure 4-3.
Using FTM Procedure Calls Procedure-Call Sequence Table 4-17. Calls for Reading an FTAM File Step Action to Take Procedure(s) to Call 1 Issue a read request. FTM_READ_REQ_ a. If error returned by FTM_READ_REQ_, check status. APS_STATUS_ b. If nowait mode, await completion of FTM_READ_REQ_. MFM_AWAITIOX_ c. If error returned by MFM_AWAITIOX_, check status. APS_STATUS_ Get the next event. APS_EVENT_RECEIVE_ a. If nowait mode, await completion of APS_EVENT_RECEIVE_.
Using FTM Procedure Calls Procedure-Call Sequence These steps explain the sequence of procedure calls given in Table 4-17 on page 4-44. 1. To request the transfer of some or all the data from the previously opened file on a remote system, call FTM_READ_REQ_, specifying details about the file from which you wish to read (for information on the parameters of this procedure, see the following subsection). a. If the read procedure fails, it returns a status code other than ZAPS-VAL-STATUS-OK.
Using FTM Procedure Calls Procedure-Call Sequence more-data, see the description of FTM_DATA_IND_ in the OSI/FTAM Programming Reference Manual. 5. To receive the next event, call APS_EVENT_RECEIVE_. In wait mode, this procedure returns a status code of ZAPS-VAL-STATUS-EVENT when you receive an event.
Using FTM Procedure Calls Setting Procedure Parameters 11. Call FTM_TRANSFER_END_CNF_ to retrieve the data sent by the confirm. Check action-result. If the action-result value is ZFTM-VAL-ACTION-SUCCESS, the responder successfully read the file. Setting Procedure Parameters To provide your application with details about the file from which you wish to read, use these parameters of the FTM_READ_REQ_ procedure: 1.
Using FTM Procedure Calls Handling Cancel Indications Handling Cancel Indications Table 4-18 shows the sequence of procedures to call and describes the steps to handle a cancel indication. Sometimes you can omit a procedure call associated with a substep, depending on the context. The sequence of procedures is explained after the table. Table 4-18. Calls for Handling Cancel Indications Step Action to Take Procedure(s) to Call 1 Get the next event. APS_EVENT_RECEIVE_ a.
Using FTM Procedure Calls Generating Cancels an error at this stage, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association. b. If the association is in nowait mode, call MFM_AWAITIOX_ to wait for completion of the FTM_CANCEL_RSP_ procedure call. c. If you call MFM_AWAITIOX_ and the status code returned is not ZAPS-VAL-STATUS-OK, call APS_STATUS_, specifying as input the CEPI returned by the FTM_INITIALIZE_REQ_ procedure for this association.
Using FTM Procedure Calls Generating Cancels Table 4-19. Calls for Generating Cancels (page 2 of 2) Step Action to Take Procedure(s) to Call a. If nowait mode, await completion of APS_EVENT_RECEIVE_. MFM_AWAITIOX_ 3 Check status: is the event a cancel confirm? Or, if APS_EVENT_RECEIVE_ returns a status other than ZAPS-VAL-STATUS-EVENT, is there an error? APS_STATUS_ 4 Retrieve service confirm information.
Using FTM Procedure Calls Handling P-Aborts and U-Aborts If the action-result value is ZFTM-VAL-ACTION-SUCCESS, the data transfer has been cancelled. Handling P-Aborts and U-Aborts Two types of aborts can be generated: the provider abort (P-abort), and the user abort (U-abort). A P-abort is generated by any service provider in the OSI stack on the NonStop system or on the responding system.
Using FTM Procedure Calls Generating U-Aborts 3. If you received a P-abort indication, call FTM_P_ABORT_IND_; if you received a U-abort indication, call FTM_U_ABORT_IND_. 4. Call APS_DISCARD_ to discard the association context and release the CEPI. If a data transfer was in progress at the time of the abort, files are left in an unknown state.
Using FTM Procedure Calls Handling Errors association and repeat the data transfer, or also continue it if the application was reading an FTAM-2 file. Handling Errors This subsection outlines the steps to follow in diagnosing problems associated with errors returned by FTM procedures. Errors in Request and Response Procedures To handle errors encountered by request and response procedures: 1. Check status. If status is ZAPS-VAL-STATUS-OK (0), there is no error.
Using FTM Procedure Calls Errors in Request and Response Procedures b. If the error return value from the APS_STATUS_ procedure equals 0, the APS_STATUS_ call was successful. You can now check the error-code value returned by APS_STATUS_. c. If the error-code output parameter returned by the APS_STATUS_ procedure equals ZFTM-ERR-BAD-APS-STATUS (-6019), OSI/AS has sent an error, indicated in the original-error-info parameter.
Using FTM Procedure Calls Errors in Indication and Confirm Procedures Figure 4-4. Handling Errors in FTM Request and Response Procedures After call to FTM procedure in wait or nowait mode, and MFM_AWAITIOX_ procedure in nowait mode, check status. Yes status = 0? There was no error. No Call APS_STATUS_ No Look up error in Table B-2 APS_STATUS_ call returns error value. error = 0? Yes APS_STATUS_ call was successful. No Look up error-code and error-subcode in Appendix B.
Using FTM Procedure Calls Errors in Indication and Confirm Procedures APS_EVENT_RECEIVE_ procedure reveals that an indication or confirm event has been received. The indication or confirm procedure then retrieves the associated event information. To handle errors encountered by indication and confirm procedures: 1. Check status. In wait mode, status is returned from a call to APS_EVENT_RECEIVE_.
Using FTM Procedure Calls Errors in Indication and Confirm Procedures Manual. For details on the contents of diagnostic, see Tables 3-5 through 3-7. If diagnostic shows the source of the error as the responding file protocol machine (4), see the OSI/FTAM Programming Reference Manual for a complete list of ISO-defined diagnostic messages that a remote responder might generate.
Using FTM Procedure Calls Errors in Indication and Confirm Procedures Figure 4-5. Handling Errors in FTM Indication and Confirm Procedures After call to APS_EVENT_RECEIVE_ procedure in wait mode or MFM_AWAITIOX_ procedure in nowait mode, check status return value from call. status = 1? No No event was received; look up status in Table B-1. Yes Call APS_STATUS_ Look up error in Table B-2 No error = 0? APS_STATUS_ call returns error value and event-code.
5 NonStop FTAM Programming Examples This section includes two examples that illustrate fundamental FTAM programming concepts.
NonStop FTAM Programming Examples • • • Sample Program Structure How to operate on a more complex document type (FTAM-2) and perform more complex file operations (such as file updates) How to use nowait mode How to maintain multiple active associations Each example in the OSI/FTAM Programming Reference Manual is provided in both C and TAL.
NonStop FTAM Programming Examples • Reading a File: C Programming Example check_status checks for status return values, error codes, and subcodes; displays a message, deallocates the segment, and stops the program. Comments provide more detailed information about what each routine does and how you can modify the program to work differently, for instance, to use another document type.
NonStop FTAM Programming Examples Reading a File: C Programming Example 33 /* */ 34 /*********************************************************************/ 35 36 #pragma XMEM 37 #pragma NOLIST 38 #include 39 #include 40 #include 41 #include 42 #include 43 #include 44 #include 45 46 /*********************************************************************/ 47 /* Source in */ 48 /* - APS and FTAM structure definitions
NonStop FTAM Programming Examples Reading a File: C Programming Example 72 , FTM_TERMINATE_CNF_ \ 73 , FTM_P_ABORT_IND_ \ 74 , FTM_U_ABORT_IND_ \ 75 , FTM_U_ABORT_REQ_ \ 76 , FTM_CANCEL_IND_ \ 77 , FTM_CANCEL_RSP_ \ 78 , APS_INITIALIZE_ \ 79 , APS_STATUS_ \ 80 , APS_EVENT_RECEIVE_ \ 81 , APS_DISCARD_ \ 82 , CREATE \ 83 , OPEN \ 84 , WRITEX \ 85 , FILEINFO \ 86 , CLOSE )" 87 #pragma LIST 88 89 90 /*********************************************************************/ 91 /
NonStop FTAM Programming Examples Reading a File: C Programming Example 111 #define MANAGER_NAME "$APMGR " 112 #define LOCAL_FILE_NAME "$VOLUME.SUBVOL.LOCALF" 113 #define REMOTE_FILE_NAME "$VOLUME.SUBVOL.
NonStop FTAM Programming Examples Reading a File: C Programming Example 150 /* Variables used by the FTM procedures */ 151 /**********************************************************************/ 152 153 long state_result; /* Result of regime transition */ 154 long action_result; /* Result of requested service */ 155 long start_position; /* Used to step thru src. data */ 156 long more_data; /* More data left to be retrieved */ 157 long next_position; /* Used to step thru src.
NonStop FTAM Programming Examples Reading a File: C Programming Example 189 zaps_ddl_char32_def filestore_password; 190 zftm_ddl_diagnostic_def diag; 191 zaps_ddl_char128_def remote_file; 192 zaps_ddl_original_error_def original_error_info; 193 zftm_ddl_requested_access_def requested_access; 194 zftm_ddl_access_passwds_def access_passwords; 195 zftm_ddl_attr_names_def attrib_names; 196 zftm_ddl_proc_mode_def process_mode; 197 zftm_ddl_read_attr_def file_attrib; 198 zftm_ddl_cnt
NonStop FTAM Programming Examples Reading a File: C Programming Example 228 /*********************************************************************/ 229 /* 230 /* Name: 231 /* */ 232 /* Description: This application initiates and manages a simple */ 233 /* file transfer. This procedure creates and opens */ 234 /* a local file, and closes it after FTAM operations */ 235 /* are complete.
NonStop FTAM Programming Examples Reading a File: C Programming Example 267 268 printf ( "Remote file read successfully\n" ); 269 270 } /* main */ 271 272 273 #pragma PAGE "FTAM_REGIME" 274 /*********************************************************************/ 275 /* */ 276 /* Name: ftam_regime */ 277 /* */ 278 /* Description: This procedure initiates the association and */ 279 /* establishes the FTAM regime.
NonStop FTAM Programming Examples Reading a File: C Programming Example 306 /* Set the remote appl for the association. */ 307 /******************************************************************/ 308 309 responding_appl.zpsap.zpsel.zlen = 0; 310 responding_appl.zpsap.zssel.zlen = 0; 311 responding_appl.zpsap.ztsel.zlen = 0; 312 responding_appl.zpsap.znsap.zlen = 0; 313 314 responding_appl.zappl_name.zlen = strlen (RESPONDING_APPL_NAME); 315 memcpy ( responding_appl.zappl_name.u_zc.
NonStop FTAM Programming Examples Reading a File: C Programming Example 345 /******************************************************************/ 346 /* Set the remote AE title for the association. 347 /******************************************************************/ */ 348 349 remote_ae_title.zae_title_type = ZAPS_VAL_AE_TITLE_FORMAT2; 350 remote_ae_title.zae_title_format2.zae_qualifier_ispresent 351 352 = ZAPS_VAL_PRESENT; remote_ae_title.zae_title_format2.
NonStop FTAM Programming Examples Reading a File: C Programming Example 384 func_units.zwrite = ZAPS_VAL_FALSE; 385 func_units.zfileaccess = ZAPS_VAL_FALSE; 386 func_units.zfilemgmt = ZAPS_VAL_FALSE; 387 func_units.zfilemgmtenhanced = ZAPS_VAL_FALSE; 388 func_units.zgroup = ZAPS_VAL_TRUE; 389 func_units.zfadulock = ZAPS_VAL_FALSE; 390 func_units.zrecovery = ZAPS_VAL_FALSE; 391 func_units.
NonStop FTAM Programming Examples Reading a File: C Programming Example 423 424 filestore_password.zlen = strlen (FILESTORE_PW); 425memcpy (filestore_password.u_zc.zb, FILESTORE_PW, strlen (FILESTORE_PW) ); 426 427 /******************************************************************/ 428 /* Request the association.
NonStop FTAM Programming Examples Reading a File: C Programming Example 462 , (int *) &func_units 463 , (int *) &attr_groups 464 , (int *) &contents_type_list 465 , (int *) &diag ); 466 467 if ( error != ZAPS_ERR_OK ) 468 { 469 printf ( "FTM_INITIALIZE_CNF_ FAILED\n" ); 470 check_error (); 471 } 472 if ( state_result == ZFTM_VAL_STATE_FAILURE ) 473 { 474 printf ( "FTM_INITIALIZE_CNF_ FAILED\n" ); 475 check_state (); 476 } 477 if ( action_result == ZFTM_VAL_ACTION_FAILURE ) 47
NonStop FTAM Programming Examples Reading a File: C Programming Example 501 printf ( "FTM_U_ABORT_REQ_ FAILED\n" ); 502 check_status (); 503 } 504 505 APS_DISCARD_ ( cepi ); 506 exit (EXIT_SUCCESS); 507 } 508 509 510 file_selection_open_regime (); 511 512 513 /******************************************************************/ 514 /* Terminate the FTAM regime.
NonStop FTAM Programming Examples 540 Reading a File: C Programming Example check_error (); 541 } 542 543 /******************************************************************/ 544 /* Discard the API context information for the association.
NonStop FTAM Programming Examples Reading a File: C Programming Example 579 requested_access.zread = ZAPS_VAL_TRUE; 580 requested_access.zinsert = ZAPS_VAL_FALSE; 581 requested_access.zreplace = ZAPS_VAL_FALSE; 582 requested_access.zextend = ZAPS_VAL_FALSE; 583 requested_access.zerase = ZAPS_VAL_FALSE; 584 requested_access.zreadattr = ZAPS_VAL_FALSE; 585 requested_access.zchngattr = ZAPS_VAL_FALSE; 586 requested_access.
NonStop FTAM Programming Examples Reading a File: C Programming Example 618 if ( status != ZAPS_VAL_STATUS_OK ) 619 { 620 printf ( "FTM_SELECT_REQ_ FAILED\n" ); 621 622 check_status (); } 623 624 status = FTM_OPEN_REQ_ ( cepi 625 , (int *) &process_mode 626 , /* (int *) &contents_type */ ); 627 if ( status != ZAPS_VAL_STATUS_OK ) 628 { 629 printf ( "FTM_OPEN_REQ_ FAILED\n" ); 630 check_status (); 631 } 632 633 error = FTM_END_GROUP_REQ_ ( cepi ); 634 if ( error != ZAPS_ERR_OK )
NonStop FTAM Programming Examples 657 Reading a File: C Programming Example { 658 printf ( "FTM_SELECT_CNF_ FAILED\n" ); 659 check_error (); 660 } 661 if ( state_result == ZFTM_VAL_STATE_FAILURE ) 662 { 663 printf ( "FTM_SELECT_CNF_ FAILED\n" ); 664 check_state (); 665 } 666 if ( action_result == ZFTM_VAL_ACTION_FAILURE ) 667 { 668 printf ( "FTM_SELECT_CNF_ FAILED\n" ); 669 check_action (); 670 } 671 672 event = ZFTM_VAL_EVT_OPEN_CNF; 673 get_event ( &event ); 674 error =
NonStop FTAM Programming Examples 696 event = ZFTM_VAL_EVT_ENDGROUP_CNF; 697 get_event ( &event ); Reading a File: C Programming Example 698 699 700 data_transfer_regime (); 701 702 703 /******************************************************************/ 704 /* Terminate the file-selection and file-open regimes.
NonStop FTAM Programming Examples Reading a File: C Programming Example 735 if ( status != ZAPS_VAL_STATUS_OK ) 736 { 737 printf ( "FTM_DESELECT_REQ_ FAILED\n" ); 738 check_status (); 739 } 740 741 error = FTM_END_GROUP_REQ_ ( cepi ); 742 if ( error != ZAPS_ERR_OK ) 743 { 744 printf ( "FTM_END_GROUP_REQ_ FAILED\n" ); 745 check_error (); 746 } 747 748 /******************************************************************/ 749 /* Call the following procedures to process the confirms re
NonStop FTAM Programming Examples Reading a File: C Programming Example 774 event = ZFTM_VAL_EVT_DESELECT_CNF; 775 get_event ( &event ); 776 777 error = FTM_DESELECT_CNF_ ( cepi 778 , (long *) &action_result 779 , (int *) &charging 780 , (int *) &diag ); 781 if ( error != ZAPS_ERR_OK ) 782 { 783 printf ( "FTM_DESELECT_CNF_ FAILED\n" ); 784 check_error (); 785 } 786 if ( action_result == ZFTM_VAL_ACTION_FAILURE ) 787 { 788 printf ( "FTM_DESELECT_CNF_ FAILED\n" ); 789 check_acti
NonStop FTAM Programming Examples 813 Reading a File: C Programming Example create_open_local_file (); 814 815 /******************************************************************/ 816 /* Initialize parameters for the FTM_READ_REQ_ procedure */ 817 /* and initiate a read. */ 818 /*****************************************************************/ 819 820 fadu_id.zid = ZFTM_VAL_FADUID_FIRSTLAST; 821 fadu_id.u_zfaduid.zfirstlast = ZFTM_VAL_FADUID_FIRST; 822 823 access_context.
NonStop FTAM Programming Examples Reading a File: C Programming Example 852 /*************************************************************/ 853 /* Call FTM_DATA_IND_ to receive data from the remote system,*/ 854 /* and then write data to the local Guardian file. */ 855 /* The required number of calls to FTM_DATA_IND_ can be */ 856 /* reduced by increasing MAX_BUF.
NonStop FTAM Programming Examples Reading a File: C Programming Example 891 printf ("Write failed with error #%d\n", error); 892 exit (EXIT_SUCCESS); 893 } 894 895 if ( i < data_hdr->znum_elements ) 896 { 897 element_hdr = (zaps_ddl_data_element_hdr_def *) 898 ( (char *) data_ptr + data_len 899 + element_hdr->zlen % 2 ); 900 data_len = (int) element_hdr->zlen; 901 data_ptr = (char *) 902 ( (char *) element_hdr 903 ); + sizeof (zaps_ddl_data_element_hdr_def) 904 905 } 906 907 }
NonStop FTAM Programming Examples 930 Reading a File: C Programming Example { 931 printf ( "FTM_DATA_END_IND_ FAILED\n" ); 932 check_action (); 933 } 934 935 break; 936 937 case ZFTM_VAL_EVT_CANCEL_IND: 938 939 940 /*************************************************************/ 941 /* The remote system has cancelled the transfer. Call the 942 /*indication and response procedures in response to the cancel*/ 943 /* request. This action terminates the data-transfer regime.
NonStop FTAM Programming Examples 969 Reading a File: C Programming Example break; 970 971 default: 972 973 bad_event ( event ); 974 break; 975 976 } /* end of switch */ 977 978 } 979 while ( event == ZFTM_VAL_EVT_DATA_IND ); 980 981 982 /*******************************************************************/ 983 /* When a cancel occurs, the data-transfer regime is terminated. */ 984 /* Skip the next section if a cancel took place.
NonStop FTAM Programming Examples 1008 if ( error != ZAPS_ERR_OK ) 1009 { Reading a File: C Programming Example 1010 printf ( "FTM_TRANSFER_END_CNF_ FAILED\n" ); 1011 check_error (); 1012 } 1013 if ( action_result == ZFTM_VAL_ACTION_FAILURE ) 1014 { 1015 printf ( "FTM_TRANSFER_END_CNF_ FAILED\n" ); 1016 check_action (); 1017 } 1018 } 1019 1020 } /* data_transfer_regime */ 1021 1022 1023 #pragma PAGE "CREATE_OPEN_LOCAL_FILE" 1024/*****************************************************
NonStop FTAM Programming Examples Reading a File: C Programming Example 1047 /* the remote file. If string-significance is 0 (variable), */ 1048 /* a file with code 892 and type E (Enscribe entry-sequenced) */ 1049 /* is created. If it is 1 (fixed), a file with code 891 and type */ 1050 /* E is created.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1086 FILEINFO ( , (int *) &error, local_file ); 1087 printf ( "OPEN for local file failed with error # %d\n", error ); 1088 exit (EXIT_SUCCESS); 1089 } 1090 1091 } /* create_open_local_file */ 1092 1093 1094 #pragma PAGE "GET_EVENT" 1095 /*********************************************************************/ 1096 /* 1097 /* Name: 1098 /* 1099 /* Description: The get_event procedure gets an available event.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1125 1126 error = APS_STATUS_ ( cepi 1127 , (int *) &event_code ); 1128 if ( error != ZAPS_ERR_OK ) 1129 check_error (); 1130 1131 /******************************************************************/ 1132 /* Verify that the expected event was received. (If the expected */ 1133 /* event = ANYEVENT, then any event code is valid.
NonStop FTAM Programming Examples 1164 Reading a File: C Programming Example { 1165 /***************************************************************/ 1166 /* Retrieve the action result and diagnostic messages for the */ 1167 /* P-abort.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1203 if ( action_result == ZFTM_VAL_ACTION_FAILURE ) 1204 { 1205 printf ( "FTM_U_ABORT_IND_ RECEIVED\n" ); 1206 check_action (); 1207 } 1208 1209 } 1210 else 1211 if ( event == ZFTM_VAL_EVT_CANCEL_IND ) 1212 { 1213 /***************************************************************/ 1214 /* Retrieve the action result and diagnostic messages for the */ 1215 /* cancel from the responder.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1242 1243 /*******************************************************************/ 1244 /* If an association exists, discard it. 1245 /*******************************************************************/ */ 1246 1247 if ( cepi != NOCEPI ) 1248 APS_DISCARD_ ( cepi ); 1249 1250 /*******************************************************************/ 1251 /* Display a message on the terminal and exit the program.
NonStop FTAM Programming Examples 1281 Reading a File: C Programming Example /******************************************************************/ 1282 1283 printf ( "BAD ACTION # %d\n", action_result ); 1284 check_diag (); 1285 1286 } /* check_action */ 1287 1288 1289 #pragma PAGE "CHECK_STATE" 1290 /*********************************************************************/ 1291 /* 1292 /* Name: 1293 /* */ 1294 /* Description: The following procedure is called when an FTM */ 1295 /* co
NonStop FTAM Programming Examples Reading a File: C Programming Example 1320 /* Name: check_diag */ 1321 /* */ 1322 /* Description: The check_diag procedure displays */ 1323 /* the diagnostic message type and error ID for each */ 1324 /* diagnostic message element, discards the association*/ 1325 /* and ends the program. Additional application- */ 1326 /* specific error handling or recovery could be */ 1327 /* implemented if required by an application.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1359 APS_DISCARD_ ( cepi ); 1360 printf ( "Association discarded\n" ); 1361 exit (EXIT_SUCCESS); 1362 1363 } /* check_diag */ 1364 1365 1366 #pragma PAGE "CHECK_STATUS" 1367 /********************************************************************/ 1368 /* 1369 /* Name: 1370 /* */ 1371 /* Description: The check_status procedure checks the status */ 1372 /* returned by an FTAM or APS procedure call.
NonStop FTAM Programming Examples 1398 Reading a File: C Programming Example if ( error != ZAPS_ERR_OK ) 1399 check_error (); 1400 1401 /******************************************************************/ 1402 /* Perform error handling, depending on the status value */ 1403 /* returned. Additional application-specific error handling or */ 1404 /* recovery could be implemented depending on application */ 1405 /* requirements.
NonStop FTAM Programming Examples 1437 Reading a File: C Programming Example printf ( "ERROR SUBCODE : %d\n", error_subcode ); 1438 1439 /******************************************************************/ 1440 /* Display the original error code and error subcode. 1441 /******************************************************************/ */ 1442 1443 printf ("ORIGINAL ERROR INFO -\n"); 1444 printf (" SERVICE ID : %d\n", original_error_info.zerror.
NonStop FTAM Programming Examples Reading a File: C Programming Example 1476 1477 printf ( "ERROR # %d\n", error ); 1478 1479 /******************************************************************/ 1480 /* Discard the API context information for the association, */ 1481 /* and exit the program.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example Writing a File: TAL Programming Example 1 !----------------------------------------------------------------------! 2 ! ! 3 ! Example in TAL - Creating and writing to a remote FTAM-1 file ! 4 ! (in Wait Mode) ! 5 ! ! 6 !----------------------------------------------------------------------! 7 ! ! 8 ! Program Name: EXTWRIF1 ! 9 ! ! 10 ! Program Description: ! 11 ! ! 12 ! This program, in wait mode, crea
NonStop FTAM Programming Examples 38 Writing a File: TAL Programming Example ?NOCODE 39 40 !----------------------------------------------------------------------! 41 ! Global data declarations 42 !----------------------------------------------------------------------! ! 43 44 !----------------------------------------------------------------------! 45 ! Macro for word addressing 46 !----------------------------------------------------------------------! ! 47 48 DEFINE SADDR( x ) = (@x '<<
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 77 STRING .EXT init_id[0:5] := "initid"; 78 STRING .EXT filestore_pw[0:2] := "aaa"; 79 STRING .EXT acct[0:4] := "12345"; 80 STRING .EXT manager_name[0:23] := "$APMGR "; 81 STRING .EXT remote_file_name[0:21] := "$VOLUME.SUBVOL.REMOTEF"; 82 STRING local_file_name[0:20] := "$VOLUME.SUBVOL.LOCALF"; 83 84 INT .EXT ftam_doc_type[0:NUM_ELEM-1] := [1,0,8571,5,1]; 85 INT .
NonStop FTAM Programming Examples 116 INT error_subcode; Writing a File: TAL Programming Example ! Returns error subcodes ! 117 118 !---------------------------------------------------------------------! 119 ! Variables used by the FTM procedures 120 !---------------------------------------------------------------------! ! 121 122 INT(32) state_result; ! Result of regime transition ! 123 INT(32) action_result; ! Result of requested service ! 124 INT(32) fadu_op; ! Operation perform
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 155 STRUCT .EXT initiator_id ( ZAPS^DDL^CHAR32^DEF ); 156 STRUCT .EXT account ( ZAPS^DDL^CHAR32^DEF ); 157 STRUCT .EXT filestore_password ( ZAPS^DDL^CHAR32^DEF ); 158 STRUCT .EXT create_password ( ZAPS^DDL^CHAR32^DEF ); 159 STRUCT .EXT local_ae_title ( ZAPS^DDL^AE^TITLE^DEF ); 160 STRUCT .EXT remote_ae_title ( ZAPS^DDL^AE^TITLE^DEF ); 161 STRUCT .
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 194 ! Incorporate SIO definitions and literals. Allocate run-unit control ! 195 ! block space. Allocate file control block space for the local file. ! 196 ! Declare the record length, file code, buffer length, and file ! 197 ! pointer for the local file. ! 198 !---------------------------------------------------------------------! 199 200 ?nolist 201 ?source $system.system.
NonStop FTAM Programming Examples 233 ? , FTM_WRITE_REQ_ 234 ? , FTM_DATA_REQ_ 235 ? , FTM_DATA_END_REQ_ 236 ? , FTM_TRANSFER_END_REQ_ 237 ? , FTM_TRANSFER_END_CNF_ 238 ? , FTM_CLOSE_REQ_ 239 ? , FTM_CLOSE_CNF_ 240 ? , FTM_DESELECT_REQ_ 241 ? , FTM_DESELECT_CNF_ 242 ? , FTM_TERMINATE_REQ_ 243 ? , FTM_TERMINATE_CNF_ 244 ? , FTM_P_ABORT_IND_ 245 ? , FTM_U_ABORT_IND_ 246 ? , FTM_U_ABORT_REQ_ 247 ? , FTM_CANCEL_IND_ 248 ? , FTM_CANCEL_RSP_ 249 ? , APS_INITIALIZ
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 272 ! Forward declarations 273 !---------------------------------------------------------------------! 274 275 276 PROC ftam_regime; 277 FORWARD; 278 279 PROC file_selection_open_regime; 280 FORWARD; 281 282 PROC data_transfer_regime; 283 FORWARD; 284 285 PROC get_event ( expected_event ); 286 INT .EXT expected_event; 287 FORWARD; 288 289 PROC bad_event ( event ); 290 INT .
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 310 ?PAGE "MAIN" 311 !---------------------------------------------------------------------! 312 ! 313 ! Name: 314 ! 315 ! Description: This application initiates and manages a simple ! 316 ! file transfer. This procedure opens the terminal ! 317 ! and the local file, and prints a message to the ! 318 ! terminal when FTAM operations are complete.
NonStop FTAM Programming Examples 349 Writing a File: TAL Programming Example END; 350 351 CALL CLOSE ( fn ); 352 353 !---------------------------------------------------------------------! 354 !Allocate and initialize a segment used by the FTM and APS procedures.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 388 , ! next-record-pointer ! 389 , ! last-modtime ! 390 , ! filecode ! 391 , ! secondary-extent-size ! 392 , ! current-record-pointer ! 393 , ! open-flags ! 394 , ! subdevice ! 395 , ! owner ! 396 , ! security ! 397 , ! num-extents-allocated ! 398 , max_filesize ); 399 IF <> THEN 400 BEGIN 401 402 tempbuf ':=' "Operation on local file failed with error #" -> @text_ptr; @text_ptr := @text_ptr + DNUMOUT ( t
NonStop FTAM Programming Examples 427 Writing a File: TAL Programming Example tempbuf ':=' "Open^File for local file failed with error #" 428 -> @text_ptr; 429 @text_ptr := @text_ptr + DNUMOUT ( text_ptr 430 , $DBL (error) 431 , BASE ); 432 text_len := @text_ptr - @tempbuf; 433 CALL WRITE ( termnum, outbuf, text_len ); 434 CALL STOP; 435 END; 436 437 CALL ftam_regime; 438 439 !--------------------------------------------------------------------! 440 ! Display a message on the termin
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 466 !------------------------------------------------------------------! 467 ! The following sections initialize the various parameters ! 468 ! for the FTM_INITIALIZE_REQ_ procedure. ! 469 !------------------------------------------------------------------! 470 471 !------------------------------------------------------------------! 472 ! Set the wait mode for the association to wait.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 505 local_appl.zappl^name.zlen := $occurs(local_appl_name); 506 local_appl.zappl^name.zb ':=' local_appl_name FOR 507 local_appl.zappl^name.zlen BYTES; 508 509 !------------------------------------------------------------------! 510 ! Set the local AE title for the association. 511 !------------------------------------------------------------------! ! 512 513 local_ae_title.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 544 !-------------------------------------------------------------------! 545 ! Select the file attribute groups required. 546 !-------------------------------------------------------------------! ! 547 548 attr_groups.zstorage := ZAPS^VAL^TRUE; 549 attr_groups.zsecurity := ZAPS^VAL^TRUE; 550 attr_groups.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 583 initiator_id.zlen := $occurs(init_id); 584 initiator_id.zb ':=' init_id FOR initiator_id.zlen BYTES; 585 586 !------------------------------------------------------------------! 587 ! Set the account for the association. 588 !------------------------------------------------------------------! ! 589 590 account.zlen := $occurs(acct); 591 account.zb ':=' acct FOR account.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 622 text_len := @text_ptr - @tempbuf; 623 CALL WRITE ( termnum, outbuf, text_len ); 624 CALL check_status; 625 END; 626 627 event := ZFTM^VAL^EVT^INITIALIZE^CNF; 628 CALL get_event ( event ); 629 630 error := FTM_INITIALIZE_CNF_ ( cepi 631 , state_result 632 , action_result 633 , local_appl 634 , responding_appl 635 , remote_ae_title 636 , service_class 637 , func_units 638 , attr_groups 639 , contents
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 661 ! be implemented if required by an application. 662 !------------------------------------------------------------------! 663 IF ( func_units.zwrite <> ZAPS^VAL^TRUE OR 664 func_units.zfilemgmt <> ZAPS^VAL^TRUE OR 665 func_units.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 700 ! attributed to the account. This parameter should be used only if ! 701 ! the account parameter was used in the FTM_INITIALIZE_REQ_ call. ! 702 ! The information returned in the charging parameter is not used ! 703 ! in this example.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 739 ! Use the FTM procedures FTM_CREATE_REQ_ and FTM_OPEN_REQ_ ! 740 ! to create and open the remote file. These two requests ! 741 ! are processed as a group. ! 742 !------------------------------------------------------------------! 743 744 !------------------------------------------------------------------! 745 ! Initialize parameters for the FTM_CREATE_REQ_ procedure call.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 778 initial_attr.zpermittedactions.zreadattr := ZAPS^VAL^TRUE; 779 initial_attr.zpermittedactions.zchngattr := ZAPS^VAL^TRUE; 780 initial_attr.zpermittedactions.zdeletefile := ZAPS^VAL^TRUE; 781 initial_attr.zpermittedactions.ztraversal := ZAPS^VAL^FALSE; 782 initial_attr.zpermittedactions.zreversetraversal := ZAPS^VAL^FALSE; 783 initial_attr.zpermittedactions.zrandom 784 initial_attr.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 817 818 ZAPS^VAL^TRUE; initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zinsert := 819 ZAPS^VAL^FALSE; 820 initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zreplace := 821 ZAPS^VAL^TRUE; 822 initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zextend := 823 824 ZAPS^VAL^TRUE; initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zerase := 825 826 ZAPS^VAL^TRUE; initial_attr.zaccesscntrlattr.zaccesscntrl.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 856 create_password.zlen := filestore_password.zlen; 857 create_password.zb 858 ':=' filestore_password.zb FOR create_password.zlen BYTES; 859 860 !------------------------------------------------------------------! 861 ! Set the requested_access parameter to provide this application ! 862 ! with replace access on the remote file.
NonStop FTAM Programming Examples 895 Writing a File: TAL Programming Example threshold := 2D; 896 897 status := FTM_BEGIN_GROUP_REQ_ ( cepi, threshold ); 898 IF ( status <> ZAPS^VAL^STATUS^OK ) THEN 899 CALL check_status; 900 901 !------------------------------------------------------------------! 902 ! Create the file.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 934 935 event := ZFTM^VAL^EVT^BEGINGROUP^CNF; 936 CALL get_event ( event ); 937 938 event := ZFTM^VAL^EVT^CREATE^CNF; 939 CALL get_event ( event ); 940 error := FTM_CREATE_CNF_ ( cepi 941 , state_result 942 , action_result 943 , initial_attr 944 , diag ); 945 946 947 948 949 950 IF ( error <> ZAPS^ERR^OK ) THEN CALL check_error; IF ( state_result = ZFTM^VAL^STATE^FAILURE ) THEN CALL check_state; IF ( action_result
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 973 974 !------------------------------------------------------------------! 975 ! Terminate the file-selection and file-open regimes. 976 !------------------------------------------------------------------! ! 977 978 979 !------------------------------------------------------------------! 980 ! Issue a close request for the remote file.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1012 1013 event := ZFTM^VAL^EVT^BEGINGROUP^CNF; 1014 CALL get_event ( event ); 1015 1016 event := ZFTM^VAL^EVT^CLOSE^CNF; 1017 CALL get_event ( event ); 1018 error := FTM_CLOSE_CNF_ ( cepi 1019 , action_result 1020 , diag ); 1021 IF ( error <> ZAPS^ERR^OK ) THEN 1022 CALL check_error; 1023 IF ( action_result = ZFTM^VAL^ACTION^FAILURE ) THEN 1024 CALL check_action; 1025 1026 event := ZFTM^VAL^EVT^DESELECT^CNF;
NonStop FTAM Programming Examples 1051 Writing a File: TAL Programming Example !--------------------------------------------------------------------! 1052 1053 PROC data_transfer_regime; 1054 1055 BEGIN 1056 1057 !------------------------------------------------------------------! 1058 ! Initialize parameters for the FTM_WRITE_REQ_ procedure.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1090 1091 error := Read^File ( FTAMFLE, local_buf, local_buf_len, , MAX_REC ); 1092 IF ( error <> 0 ) THEN 1093 BEGIN 1094 IF ( error = 1 ) THEN 1095 1096 EOF_flag := 1 ELSE 1097 BEGIN 1098 tempbuf ':=' "Read^File for local file failed with error #" 1099 -> @text_ptr; 1100 @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1101 , $DBL (error) 1102 , BASE ); 1103 text_len := @text_ptr - @tempbuf; 1104 CALL WRITE ( t
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1129 1130 !-------------------------------------------------------------! 1131 ! Call FTM_DATA_REQ_ to transfer data to the remote system.
NonStop FTAM Programming Examples 1168 Writing a File: TAL Programming Example IF ( action_result = ZFTM^VAL^ACTION^FAILURE ) THEN 1169 CALL check_action; 1170 1171 1172 END; --- data_transfer_regime --- 1173 1174 1175 ?PAGE "GET_EVENT" 1176 !--------------------------------------------------------------------! 1177 ! 1178 ! Name: 1179 ! ! 1180 ! Description: The get_event procedure gets an available event.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1207 error := APS_STATUS_ ( cepi, event_code ); 1208 IF ( error <> ZAPS^ERR^OK ) THEN 1209 CALL check_error; 1210 1211 !-----------------------------------------------------------------! 1212 ! Verify that the expected event was received. (If the expected ! 1213 ! event = ANYEVENT, then any event code is valid.
NonStop FTAM Programming Examples 1246 Writing a File: TAL Programming Example IF ( event = ZFTM^VAL^EVT^PABORT^IND ) THEN 1247 BEGIN 1248 !--------------------------------------------------------------! 1249 ! Retrieve the action result and diagnostic messages for the ! 1250 ! P-abort.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1285 ! Retrieve the action result and diagnostic messages for the ! 1286 ! cancel from the responder.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1324 text_len := @text_ptr - @tempbuf; 1325 CALL WRITE ( termnum, outbuf, text_len ); 1326 1327 CALL STOP; 1328 1329 END; -- bad_event -- 1330 1331 1332 ?PAGE "CHECK_ACTION" 1333 !--------------------------------------------------------------------! 1334 ! 1335 ! Name: 1336 ! ! 1337 ! Description: The following procedure is called when an FTM ! 1338 ! confirm procedure returns a bad action_result.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1363 ?PAGE "CHECK_STATE" 1364 !--------------------------------------------------------------------! 1365 ! 1366 ! Name: 1367 ! ! 1368 ! Description: The following procedure is called when an FTM ! 1369 ! confirm procedure returns a bad state_result. The ! 1370 ! procedure displays an error message and calls ! 1371 ! check_diag for diagnostic messages.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1402 ! and ends the program. Additional application-specific ! 1403 ! error handling or recovery could be implemented if ! 1404 ! required by an application.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1441 , BASE ); 1442 text_len := text_len + width; 1443 CALL WRITE ( termnum, outbuf, text_len ); 1444 1445 tempbuf ':=' " Error ID: " -> @text_ptr; 1446 text_len := @text_ptr - @tempbuf; 1447 width := DNUMOUT ( tempbuf[text_len] 1448 , $DBL ( diag.zdiagelems[i].zerrorid ) 1449 , BASE ); 1450 text_len := text_len + width; 1451 CALL WRITE ( termnum, outbuf, text_len ); 1452 1453 IF (diag.zdiagelems[i].
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1480 ! ! 1481 ! Name: 1482 ! 1483 ! Description: The check_status procedure checks the status returned ! 1484 ! from an FTAM or APS procedure call. It checks for ! 1485 ! NORETRY, RETRYLATER, and DISCARD.
NonStop FTAM Programming Examples 1519 Writing a File: TAL Programming Example BEGIN 1520 1521 ZAPS^VAL^STATUS^NO^RETRY, 1522 ZAPS^VAL^STATUS^RETRY^LATER, 1523 ZAPS^VAL^STATUS^DISCARD -> 1524 BEGIN 1525 1526 !--------------------------------------------------------------! 1527 ! The status indicates an error was detected. This application ! 1528 ! discards the association and exits the program.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1558 1559 tempbuf ':=' "ERROR # " -> @text_ptr; 1560 IF (error_code < 0) THEN 1561 BEGIN 1562 error_code := -error_code; 1563 text_ptr ':=' "-" -> @text_ptr; 1564 1565 END; @text_ptr := @text_ptr + DNUMOUT ( text_ptr 1566 , $DBL ( error_code ) 1567 , BASE ); 1568 text_len := @text_ptr - @tempbuf; 1569 CALL WRITE ( termnum, outbuf, text_len ); 1570 1571 tempbuf ':=' "ERROR SUBCODE # " -> @text_ptr; 1572 IF (err
NonStop FTAM Programming Examples 1597 Writing a File: TAL Programming Example CALL WRITE ( termnum, outbuf, text_len ); 1598 1599 tempbuf ':=' " ERROR CODE # " -> @text_ptr; 1600 IF ( original_error_info.zerror.zerror^code < 0) THEN 1601 BEGIN 1602 original_error_info.zerror.zerror^code 1603 1604 := -original_error_info.zerror.zerror^code; text_ptr ':=' "-" -> @text_ptr; 1605 END; 1606 @text_ptr := @text_ptr 1607 + DNUMOUT ( text_ptr 1608 , $DBL ( original_error_info.zerror.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1636 ?PAGE "CHECK_ERROR" 1637 !--------------------------------------------------------------------! 1638 ! 1639 ! Name: 1640 ! 1641 ! Description: The check_error procedure checks error codes ! 1642 ! returned from FTM procedure calls. This ! 1643 ! procedure displays a message, then discards ! 1644 ! the association to the remote system, and ends ! 1645 ! the program.
NonStop FTAM Programming Examples Writing a File: TAL Programming Example 1675 tempbuf ':=' "Association discarded" -> @text_ptr; 1676 text_len := @text_ptr - @tempbuf; 1677 CALL WRITE ( termnum, outbuf, text_len ); 1678 CALL STOP; 1679 1680 1681 END; -- check_error -- HP NonStop OSI/FTAM Programming Guide—528612-001 5- 85
NonStop FTAM Programming Examples Writing a File: TAL Programming Example HP NonStop OSI/FTAM Programming Guide—528612-001 5- 86
6 FTAM Application Management HP provides several tools for setting up and managing a system including NonStop FTAM and related products. Complete details for configuring and managing NonStop initiator processes are found in the OSI/FTAM Configuration and Management Manual. This manual highlights aspects of FTAM configuration and management that are especially important to FTAM application designers and programmers.
FTAM Application Management Capacity Capacity FTAM initiator capacity is determined by at least three factors: the number of concurrent associations per process, the number of initiator processes running, and the PDU size. Multiple Associations An FTAM initiator process can handle up to 32 concurrent associations; depending on the workload of your application, you might want to set a lower limit.
FTAM Application Management Fault Tolerance PDU Sizes A PDU is the encoded message that is transferred across an OSI network between the initiator and responder. The sender (either initiator or responder) encodes the parameters associated with an FTAM primitive into an FTAM PDU (FPDU) for transfer across the network. The receiver decodes the FPDU back into a primitive after it is received at its destination.
FTAM Application Management Troubleshooting and Tuning associations and connections. Check and verify all previous work performed using the NonStop initiator, correct inappropriate file states left from the component failure, and proceed according to your application’s needs. The process of verifying work performed before a hardware or software component failure and recovering from unknown file states is different for every application.
FTAM Application Management A Few Words of Advice application programs as they run. For a full description of Inspect, refer to the Inspect Manual. The Subsystem Control Facility (SCF) is a tool for managing NonStop FTAM initiator processes, as well as other communications software on your NonStop system. You use SCF not only to set up your FTAM configuration, but also to monitor the performance of initiator and APLMGR processes.
FTAM Application Management Checking Association Status For more information on troubleshooting user applications and interoperability problems, refer to the OSI/FTAM Configuration and Management Manual. Checking Association Status The next several pages provide an example of how you can use SCF to get information about a specific association.
FTAM Application Management Checking Association Status Called Address field. If no association has been established, the Responding Address field contains no values. The other fields in the display provide the following information: State identifies the current state of the subdevice being used for the association. This field always displays the value STARTED, indicating that the subdevice is in use. Opens displays the number of associations that have this subdevice open.
FTAM Application Management Checking Association Status Example 6-1. STATUS SU Display for a NonStop FTAM Initiator OSIFTAM Detailed Status SU \NET.$FTINI1.#Z000001 State Opens Error Error ............ ............ ............ Subcode..... STARTED 1 0 0 CEPI ............. 0 TAPS SU .......... \NET.$TAPS1.#Z000009 FTAM Functional Units Selected Read LimitedFileMgmt Calling Address: Group (LOCAL) PSEL..... SSEL..... 8118 TSEL..... 85 NSAP..... 83 ComName Called Address: PSEL..... (REMOTE) SSEL....
FTAM Application Management • Checking Association Status The displayed values for error and error-subcode correspond to error-code and error-subcode values that APS_STATUS_ returns to the application. If the returned error value and error-subcode value (if any) are not equal to ZAPS-ERR-OK (0), an error has occurred. For detailed information on diagnosing and recovering from the error, refer to the OSI/FTAM Programming Reference Manual.
FTAM Application Management Checking Association Status HP NonStop OSI/FTAM Programming Guide—528612-001 6- 10
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.
Glossary API (application programmatic interface). API (application programmatic interface). A mechanism by which an application program interfaces with another piece of software. For NonStop FTAM, the API consists of FTM, APS, and MFM procedures used in FTAM programming. The NonStop FTAM API also includes the data definitions provided in the ZFTMDDL file and all language-specific files derived from ZFTMDDL. See also APS procedures, FTM procedures., and MFM (module file management) procedures.
Glossary arc. arc. A directed link between two nodes in a hierarchical file. arc length. The number of node levels in a file hierarchy from the root node to a given node. For example, the arc length of an FTAM-2 document is always 1. ASE (application service element). A set of functions to be performed—such as file transfer, mail service, or transaction processing—along with all the elements necessary to perform that type of work, to support a particular application. ASI (additional service information).
Glossary basic data types. basic data types. First-level and second-level DDL data types, which can either stand alone as data types or be used to create higher-level DDL structures. called address. The OSI address of the responder called by the initiator that supports an FTAM application. Contrast with calling address and responding address. calling address. The OSI address of the initiator that calls a responder in an FTAM application. Contrast with called address and responding address. calling user.
Glossary conformance. conformance. The satisfaction, by an implementation of an OSI standard, of both static and dynamic conformance requirements, consistent with the capabilities stated in the protocol implementation conformance statement (PICS). Static conformance requirements are constraints specified in the standards or related profiles to facilitate interworking.
Glossary DDL (Data Definition Language). DDL (Data Definition Language). A NonStop language for defining data. DDL builds a dictionary from the definitions, translates the definitions into File Utility Program (FUP) commands, and generates object-definition source code in a variety of programming languages. default user (DEFUSER).
Glossary end-of-file marker. end-of-file marker. See EOF (end of file). 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.
Glossary event. 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.
Glossary file-access functional unit. 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 fileaccess 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.
Glossary file-system request. 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.
Glossary FTAM-1 file. 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.
Glossary grouping control. 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.
Glossary indirect-process-name. 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.
Glossary IS (International Standard). 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.
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.
Glossary NIST (National Institute of Science and Technology). 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) An HP NonStop system that is part of an Expand network. node descriptor.
Glossary null object type. 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.
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).
Glossary PDU 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.
Glossary presentation context. 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.
Glossary profile. 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.
Glossary read functional unit. 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.
Glossary responder. 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.
Glossary SCF kernel. 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.
Glossary service user. 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).
Glossary state transition. 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.
Glossary subdevice. 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.
Glossary swap volume. 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.
Glossary Transport Layer. 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.
Glossary user abort. 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.
Glossary X.25 network. 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.
Glossary $process-name.
Index A Aborts See P-aborts and U-aborts Access level, file See requested-access parameter access-context parameter 2-23, 4-47 access-control attribute 2-42 access-passwords parameter 4-14, 4-23, 4-29, 4-37 account parameter 4-9, 4-14, 4-24 action-result parameter 3-42 action-result value 4-5 active-contents-type attribute 2-35 Activity attributes 2-33, 2-35/2-37 Addresses 2-42 See OSI Addresses AE qualifier See local-ae-title and remote-ae-title parameters AE title See local-ae-title and remote-ae-title pa
Index A Applications (continued) check error 5-84 check state 5-36 check status 5-38/5-40 compiler directives and global declarations 5-42/5-49 data-transfer regime 5-68/5-72 file selection and open regimes 5-60/5-68 FTAM regime 5-53/5-60 get event 5-72/5-73 main 5-50/5-53 example in TAL, writing FTAM-1 file check status 5-80 example program structure 5-2 OLTP 1-6 sample program structure 5-2 Application-generated diagnostic messages 3-45 APS procedures programming tasks 4-1, 4-4 See also Procedures and i
Index B Associations (continued) CEPIs 3-1/3-2 description 4-5 OSI addresses and common names 3-2/3-3 procedure-call sequence for 4-5/4-7 sequence of steps for 3-5/3-7 subdevices 3-3/3-5 wait and nowait modes 3-7/3-11 identifying See CEPIs programming tasks for 4-1 terminating, procedure-call sequence for 4-11 wait and nowait modes 3-7/3-11 Attributes activity 2-35/2-37 file 2-37/2-38 file and activity by group, table of 2-34 file by group, table of 2-39 ISO FTAM, classes and groups defined 2-33 programmi
Index D Configuration (continued) requirements for initiator 6-1/6-3 Confirm procedures, error handling 4-55/4-57 Confirmed services, ISO FTAM 2-5 Connection endpoint identifiers See CEPIs Connections See Associations Constraint sets object identifiers 2-29 table of 2-28 contents-type attribute 2-40 contents-type parameter 4-26, 5-61 contents-type-list parameter 4-9, 5-13, 5-56 Context-free Pathway relationships 1-6 Context-sensitive FTAM relationships 1-6 Control, grouping See Grouping control Conversion
Index E data-value parameter (continued) FTAM-2 structure for multiple nodes 3-24 FTAM-2 structure for single node 3-23 Diagnosing strategies programming example, in C 5-36 programming example, in TAL 5-77 Diagnostic messages application-generated 3-45 message contents, table of 3-43 message groups, table of 3-43 NonStop FTAM 3-44 sources and observer identifier values, table of 3-44 diagnostic parameter 3-42 DIRLIS file 3-30 Document types describing document contents 2-31 FTAM-1 documents 2-24, 2-29 FTA
Index F Event Management Service See EMS Events begin-group confirm 4-19 cancel confirm 4-50 close confirm 4-32 create confirm 4-12 data indication 4-45 data-end indication 4-46 delete confirm 4-37 deselect confirm 4-35 end-group confirm 4-20 file-close confirm 4-34 file-open confirm 4-28 initialize confirm 4-6 open confirm 4-20, 4-25 P-abort indication 4-51 select confirm 4-20, 4-22 terminate confirm 4-11 transfer-end confirm 4-41, 4-46 U-abort indication 4-51 Events, receiving description 4-4 procedure-
Index F Files (continued) opening using file-open, sequence for 4-26/4-29 opening using open, sequence for 4-24/4-25 programming tasks for 4-1 reading FTAM-1 3-21 reading FTAM-2 3-25 reading FTAM-3 3-28 reading NBS-9 3-30/3-31 reading, sequence for 4-43/4-47 reading, sequence of primitives 4-43 selecting, sequence for 4-21/4-23, 4-23/4-24 writing FTAM-1 3-18/3-21 writing FTAM-2 3-22/3-25 writing FTAM-3 3-27/3-28 writing, sequence for 4-38/4-41 writing, sequence of primitives 4-38 filesize attribute 2-41 f
Index F FTAM-1 files (continued) data-value parameter 3-18/3-21 definition 2-29 entry number, table of 2-28 FADU structure 2-24 identifying FADUs 4-42, 4-47 NonStop system file equivalent 2-29 programming example, in TAL bad event 5-73/5-76 check action 5-76 check diagnostics 5-77/5-79 check error 5-84/5-85 check state 5-77 check status 5-79/5-83 compiler directives and global declarations 5-42/5-49 data-transfer regime 5-68/5-72 file selection and open regimes 5-60/5-68 FTAM regime 5-53/5-60 get event 5-
Index F FTM_CLOSE_REQ_ procedure example, in C 5-21 example, in TAL 5-67 FTM_CREATE_REQ_ procedure example, in TAL 5-65 FTM_DATA_END_IND_ procedure example, in C 5-26 FTM_DATA_END_REQ_ procedure example, in TAL 5-71 FTM_DATA_IND_ procedure example, in C 5-25 FTM_DELETE_REQ_ procedure 4-36 FTM_DESELECT_CNF_ procedure example, in C 5-23 example, in TAL 5-68 using 4-36 FTM_DESELECT_REQ_ procedure example, in C 5-21 example, in TAL 5-67 using 4-35/4-36 FTM_END_GROUP_REQ_ procedure example, in C 5-22 example,
Index G FTM_TRANSFER_END_CNF_ procedure example, in C 5-28 example, in TAL 5-71 using 4-41, 4-47 FTM_TRANSFER_END_REQ_ procedure example, in C 5-28 example, in TAL 5-71 using 4-41, 4-46 FTM_U_ABORT_IND_ procedure example, in C 5-33 example, in TAL 5-74 when to use 4-52 FTM_U_ABORT_REQ_ procedure 4-52 FTM_WRITE_REQ_ setting procedure parameters 4-41 FTM_WRITE_REQ_ procedure example, in TAL 5-69 using 4-38 Functional units defaults 4-8/4-9 definition 2-12 ISO FTAM groupings, table of 2-13 negotiation of 2-2
Index K identity-of-last-attribute-modifier attribute 2-41 identity-of-last-modifier attribute 2-41 identity-of-last-reader attribute 2-41 Indication procedures error handling strategies 4-55/4-57 Indications, cancel procedure-call sequence for 4-48/4-49 programming tasks for 4-3 Initializing an association setting procedure parameters 4-7/4-9 Initializing the API description 4-4 programming tasks for 4-2 initial-attrib parameter 4-13, 4-30 Initiator as NonStop FTAM component 1-3 checking association stat
Index N maximum-string-length parameter ISO FTAM definition 2-31 limitations 3-11 opening files 4-26 reading FTAM-1 files 3-22 reading FTAM-2 files 3-25 reading FTAM-3 files 3-28 specification of the contents type 3-11 writing FTAM-1 files 3-19 writing FTAM-2 files 3-25 writing FTAM-3 files 3-27 MFM_AWAITIOX_ procedure 3-9/3-10 MFM_CANCELREQ_ procedure 3-10 MSL See maximum-string-length parameter N NAMES SU, SCF command 6-6 National Bureau of Standards (NBS) See NIST NBS-9 files definition 2-32 identifyi
Index P OSI address See also local-appl and remote-appl parameters OSI addresses concepts 3-2/3-3 ISO FTAM concepts 2-42 OSI manager process 3-5 OSI/AS subsystem API role in establishing associations 3-7 relationship to NonStop FTAM 1-4 source data-definition files 3-32 using API with FTAM API procedures 3-2 OSI/TS subsystem, relationship to NonStop FTAM 1-4 override parameter 4-13 P Pad bytes in data-value parameter 3-13/3-14 Passwords See access-passwords, create-password, filestore-password, initial-a
Index S Read functional unit (continued) services and service classes, table of 2-16 Reading attributes, tasks for 4-3 Reading files FTAM-1 3-21 FTAM-2 3-25 FTAM-3 3-28 NBS-9 3-30 procedure-call sequence for 4-43/4-47 programming tasks for 4-2 sequence of primitives 4-43 setting procedure parameters 4-47 Read-only directory files See NBS-9 files Receiving events description 4-4 procedure-call sequence for 4-5 programming tasks for 4-2 See also Events Recovery functional unit ISO FTAM 2-13 services and ser
Index T Service classes, ISO FTAM (continued) negotiation of 2-21/2-22 overview of types 2-14 Service ID 3-41 Service primitives See Primitives Services grouping description 4-15 procedure-call sequence for 4-17/4-20 grouping close and deselect services 4-33 grouping control limitations 4-16 grouping select and open services 4-27 groupings by ISO into functional units 2-12/2-13 grouping, ISO concept of 2-18/2-19 ISO FTAM confirmed vs unconfirmed 2-5 ISO FTAM external 2-6/2-9 relationship to functional uni
Index U Transferring data (continued) overview 2-2 primitives for 2-8 programming concepts data-value parameter 3-12/3-18 FTAM-1 files 3-18/3-22 FTAM-2 files 3-22/3-27 FTAM-3 files 3-27/3-30 general description 3-11 NBS-9 files 3-30/3-31 Transport selector See TSEL, OSI address component Troubleshooting 6-4/6-6 TSEL, OSI address component 3-2 TSP process, OSI/TS 3-3 U UA data units 2-29, 2-30, 2-31 Unconfirmed services, ISO FTAM 2-5 Unconstrained service class description 2-14 functional units, table of
Index X Writing files (continued) FTAM-3 3-27 programming tasks for 4-3 sequence of primitives 4-38/4-41 setting procedure parameters 4-41/4-42 X X25AM subsystem 1-4 Z ZAPS-DDLAE-TITLE 4-8 APPL-ADDR 4-7 CHAR128 4-23, 4-28 CHAR32 4-7, 4-9, 4-14, 4-24, 4-30 FILENAME 4-7 programming example 5-7, 5-45 ZAPS-VALNOWAITED 4-8 STATUS-EVENT 4-7 STATUS-xxx 3-40 WAITED 4-8 ZFADUNUMBER field, fadu-id values for 4-47 ZFIRSTLAST field, fadu-id values for 4-47 ZFTMC file 4-3 ZFTMDDL file 4-3 ZFTMTAL file 4-3 ZFTM-DDLAC
Index Z ZFTM-VAL- (continued) FOPEN-xxx 4-28 STRINGSIG-FIXED 3-19 STRINGSIG-NOTSIG 3-20 STRINGSIG-VARIABLE 3-19 ZFTM-VAL-ACTION-SUCCESS 4-25 ZFTM-VAL-STATE-SUCCESS 4-25 ZRELATIVE field, fadu-id values for 4-47 HP NonStop OSI/FTAM Programming Guide—528612-001 Index -18
