Table 4-1. - HPE Support Center

Table 4-1. - HPE Support Center
HP NonStop OSI/FTAM
Programming
Reference Manual
Abstract
This manual describes the operation of the HP NonStop™ Open Systems
Interconnection/File Transfer, Access, and Management (OSI/FTAM) application
programmatic interface (API). It is for programmers writing FTAM applications that use
the services of the NonStop FTAM initiator. The FTAM API allows applications to
perform file-handling and transfer tasks.
Product Version
OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06
Supported Release Version Updates (RVUs)
This publication supports D43.00 and all subsequent D-series RVUs and G06.01 and
all subsequent G-series RVUs until otherwise indicated by its replacement publication.
Part Number
Published
528611-001
October 2004
Document History
Part Number
Product Version
Published
030253
OSI/FTAM C30, OSI/APLMGR C30
September 1992
528611-001
OSI/FTAM D43 and G06, OSI/APLMGR
D43 and G06
October 2004
HP NonStop OSI/FTAM
Programming Reference Manual
Glossary
Index
What’s New in This Manual ix
Manual Information ix
New and Changed Information
About This Manual xi
Who Should Read This Manual?
What’s In This Manual? xi
Related Manuals xiv
Notation Conventions xvi
Figures
Tables
ix
xi
1. Introduction to NonStop OSI/FTAM
Functional Overview 1-1
NonStop FTAM Services 1-2
NonStop FTAM Application Examples 1-2
Programming Capabilities 1-3
Programmatic Interface 1-3
Management Interface 1-4
Interaction With Other NonStop Subsystems 1-4
Architectural Overview 1-5
FTAM and APLMGR Subsystems 1-7
NonStop FTAM and the Guardian File System 1-8
Application Programmatic Interface 1-9
Distributed Systems Management (DSM) Interface 1-10
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems 1-12
2. Conformance and Interoperability
Conformance 2-1
Interoperability 2-1
Basic Characteristics of FTAM Implementations 2-2
Document Types and Related Parameters 2-3
Data Transfer Considerations 2-4
Presentation Encoding of FTAM PDUs and Data 2-5
Hewlett-Packard Company—528611-001
i
3. NonStop FTAM Initiator
Contents
3. NonStop FTAM Initiator
Initiator Structure 3-1
Initiator Data Flow 3-3
Types of Procedures in the FTAM API 3-4
How FTM Procedures Are Categorized 3-5
Request Procedures 3-5
Indication Procedures 3-5
Response Procedures 3-6
Confirm Procedures 3-6
Grouped Procedures 3-6
Mapping of Primitives to Procedures 3-6
Supported Functions 3-9
Service Classes 3-9
Functional Units 3-9
Attribute Groups 3-10
Attributes 3-10
Document Types 3-11
Accessing Local Information 3-11
4. FTM Procedures
Files Provided by HP 4-1
Procedure Names 4-2
Procedure Calls and Parameters 4-2
FTAM Protocol Dependencies 4-7
Procedure Call Descriptions 4-9
FTM_BEGIN_GROUP_REQ_ 4-13
FTM_CANCEL_REQ_ 4-16
FTM_CANCEL_CNF_ 4-19
FTM_CANCEL_IND_ 4-21
FTM_CANCEL_RSP_ 4-23
FTM_CHANGE_ATTRIB_REQ_ 4-26
FTM_CHANGE_ATTRIB_CNF_ 4-29
FTM_CLOSE_REQ_ 4-32
FTM_CLOSE_CNF_ 4-34
FTM_CREATE_REQ_ 4-36
FTM_CREATE_CNF_ 4-41
FTM_DATA_END_REQ_ 4-44
FTM_DATA_END_IND_ 4-47
FTM_DATA_REQ_ 4-49
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
ii
4. FTM Procedures (continued)
Contents
4. FTM Procedures (continued)
FTM_DATA_IND_ 4-53
FTM_DELETE_REQ_ 4-58
FTM_DELETE_CNF_ 4-60
FTM_DESELECT_REQ_ 4-63
FTM_DESELECT_CNF_ 4-65
FTM_END_GROUP_REQ_ 4-68
FTM_ERASE_REQ_ 4-70
FTM_ERASE_CNF_ 4-75
FTM_FILE_CLOSE_REQ_ 4-77
FTM_FILE_CLOSE_CNF_ 4-80
FTM_FILE_OPEN_REQ_ 4-83
FTM_FILE_OPEN_CNF_ 4-90
FTM_INITIALIZE_REQ_ 4-93
FTM_INITIALIZE_CNF_ 4-101
FTM_LOCATE_REQ_ 4-106
FTM_LOCATE_CNF_ 4-111
FTM_OPEN_REQ_ 4-114
FTM_OPEN_CNF_ 4-118
FTM_P_ABORT_IND_ 4-121
FTM_READ_REQ_ 4-123
FTM_READ_ATTRIB_REQ_ 4-127
FTM_READ_ATTRIB_CNF_ 4-130
FTM_SELECT_REQ_ 4-133
FTM_SELECT_CNF_ 4-136
FTM_TERMINATE_REQ_ 4-139
FTM_TERMINATE_CNF_ 4-141
FTM_TRANSFER_END_REQ_ 4-143
FTM_TRANSFER_END_CNF_ 4-145
FTM_U_ABORT_REQ_ 4-147
FTM_U_ABORT_IND_ 4-150
FTM_WRITE_REQ_ 4-152
A. DDL Definitions
Types of DDL Definitions A-1
Locating DDL Definitions A-2
Basic Data Types A-3
First-Level Data Types A-3
Second-Level Data Types A-4
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
iii
A. DDL Definitions (continued)
Contents
A. DDL Definitions (continued)
Parameter Structures A-5
ZAPS Structures A-6
ZFTM Structures A-12
Named Values A-37
Procedure Call Cross Reference Table
A-42
B. NonStop FTAM Initiator Error Messages
Status Codes B-2
Error Codes B-4
APS Error Codes B-4
FTAM Initiator Error Codes
B-19
C. ISO FTAM Diagnostic Messages
General FTAM Diagnostic Messages C-3
Protocol and Supporting Service-Related Diagnostic Messages
Association-Related Diagnostic Messages C-4
Selection-Related Diagnostic Messages C-5
File-Management-Related Diagnostic Messages C-6
Access-Related Diagnostic Messages C-6
Recovery-Related Diagnostic Messages C-8
C-3
D. NonStop FTAM Initiator Diagnostic Messages
E. MFM Procedures
Using MFM Procedure Calls E-1
Procedure Descriptions E-2
MFM_AWAITIOX_ E-2
MFM_CANCELREQ_ E-4
F. APS Procedures
Using APS Procedure Calls F-1
Procedure Descriptions F-2
APS_DISCARD_ F-3
APS_EVENT_RECEIVE_ F-4
APS_INITIALIZE_ F-6
APS_STATUS_ F-7
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
iv
G. NonStop FTAM Programming Examples
Contents
G. NonStop FTAM Programming Examples
Example Structure and Protocol G-2
Example 1—Updating a Remote File (in Nowait Mode) G-3
Example 2—Moving a File Between Two Remote Systems (in Wait Mode)
Example 1 in C—Updating a Remote File (in Nowait Mode) G-12
Example 1 in TAL—Updating a Remote File (in Nowait Mode) G-56
Example 2 in C—Moving a File Between Two Remote Systems (in Wait
Mode) G-106
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait
Mode) G-161
Translation Application Example G-221
G-6
Glossary
Index
Figures
Figure i.
Figure 1-1.
Figure 1-2.
Figure 1-3.
Figure 1-4.
Figure 1-5.
Figure 1-6.
Figure 3-1.
Figure 4-1.
Figure 4-2.
Figure G-1.
Figure G-2.
Documentation Road Map xv
An FTAM Service Using Four Primitives 1-4
NonStop FTAM Architectural Overview 1-6
FTAM and APLMGR Subsystems 1-8
NonStop FTAM and the Application Programmatic Interface (API)
NonStop FTAM and the DSM Interface 1-12
NonStop FTAM and OSI/AS, OSI/TS, and TLAM or X25AM
Subsystems 1-13
NonStop FTAM Initiator Process 3-2
Sample FTM Procedure Call Description 4-10
Structure of the Data-Value Parameter 4-50
Protocol Diagram for Programming Example 1 G-4
Protocol Diagram for Programming Example 2 G-8
Tables
Table 3-1.
Table 3-2.
Table 3-3.
Table 3-4.
Table 3-5.
Table 4-1.
Table 4-2.
Table 4-3.
FTAM Service Primitives and Related FTAM Procedures 3-7
Service Classes Supported by the NonStop FTAM Initiator 3-9
Functional Units Supported by the NonStop FTAM Initiator 3-9
Attribute Groups Supported by the NonStop FTAM Initiator 3-10
FTAM Attributes 3-10
FTM Procedure Parameters and Associated Calls 4-3
FTM Procedure Regime Dependencies 4-7
Possible FTAM Initiator Errors for the FTM_BEGIN_GROUP_REQ_
Procedure 4-14
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
v
1-10
Tables (continued)
Contents
Tables (continued)
Table 4-4.
Table 4-5.
Table 4-6.
Table 4-7.
Table 4-8.
Table 4-9.
Table 4-10.
Table 4-11.
Table 4-12.
Table 4-13.
Table 4-14.
Table 4-15.
Table 4-16.
Table 4-17.
Table 4-18.
Table 4-19.
Table 4-20.
Table 4-21.
Table 4-22.
Table 4-23.
Possible FTAM Initiator Errors for the FTM_CANCEL_REQ_
Procedure 4-17
Possible FTAM Initiator Errors for the FTM_CANCEL_CNF_
Procedure 4-20
Possible FTAM Initiator Errors for the FTM_CANCEL_IND_
Procedure 4-22
Possible FTAM Initiator Errors for the FTM_CANCEL_RSP_
Procedure 4-24
Possible FTAM Initiator Errors for the FTM_CHANGE_ATTRIB_REQ_
Procedure 4-27
Possible FTAM Initiator Errors for the FTM_CHANGE_ATTRIB_CNF_
Procedure 4-30
Possible FTAM Initiator Errors for the FTM_CLOSE_REQ_
Procedure 4-33
Possible FTAM Initiator Errors for the FTM_CLOSE_CNF_
Procedure 4-35
Possible FTAM Initiator Errors for the FTM_CREATE_REQ_
Procedure 4-39
Possible FTAM Initiator Errors for the FTM_CREATE_CNF_
Procedure 4-43
Possible FTAM Initiator Errors for the FTM_DATA_END_REQ_
Procedure 4-45
Possible FTAM Initiator Errors for the FTM_DATA_END_IND_
Procedure 4-48
Possible FTAM Initiator Errors for the FTM_DATA_REQ_
Procedure 4-52
Possible FTAM Initiator Errors for the FTM_DATA_IND_
Procedure 4-56
Possible FTAM Initiator Errors for the FTM_DELETE_REQ_
Procedure 4-59
Possible FTAM Initiator Errors for the FTM_DELETE_CNF_
Procedure 4-61
Possible FTAM Initiator Errors for the FTM_DESELECT_REQ_
Procedure 4-64
Possible FTAM Initiator Errors for the FTM_DESELECT_CNF_
Procedure 4-67
Possible FTAM Initiator Errors for the FTM_END_GROUP_REQ_
Procedure 4-69
Possible FTAM Initiator Errors for the FTM_ERASE_REQ_
Procedure 4-71
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
vi
Tables (continued)
Contents
Tables (continued)
Table 4-24.
Table 4-25.
Table 4-26.
Table 4-27.
Table 4-28.
Table 4-29.
Table 4-30.
Table 4-31.
Table 4-32.
Table 4-33.
Table 4-34.
Table 4-35.
Table 4-36.
Table 4-37.
Table 4-38.
Table 4-39.
Table 4-40.
Table 4-41.
Table 4-42.
Table 4-43.
Possible FTAM Initiator Errors for the FTM_ERASE_CNF_
Procedure 4-76
Possible FTAM Initiator Errors for the FTM_FILE_CLOSE_REQ_
Procedure 4-79
Possible FTAM Initiator Errors for the FTM_FILE_CLOSE_CNF_
Procedure 4-82
Possible FTAM Initiator Errors for the FTM_FILE_OPEN_REQ_
Procedure 4-88
Possible FTAM Initiator Errors for the FTM_FILE_OPEN_CNF_
Procedure 4-92
Possible FTAM Initiator Errors for the FTM_INITIALIZE_REQ_
Procedure 4-98
Possible FTAM Initiator Errors for the FTM_INITIALIZE_CNF_
Procedure 4-104
Possible FTAM Initiator Errors for the FTM_LOCATE_REQ_
Procedure 4-107
Possible FTAM Initiator Errors for the FTM_LOCATE_CNF_
Procedure 4-112
Possible FTAM Initiator Errors for the FTM_OPEN_REQ_
Procedure 4-116
Possible FTAM Initiator Errors for the FTM_OPEN_CNF_
Procedure 4-120
Possible FTAM Initiator Errors for the FTM_P_ABORT_IND_
Procedure 4-122
Possible FTAM Initiator Errors for the FTM_READ_REQ_
Procedure 4-125
Possible FTAM Initiator Errors for the FTM_READ_ATTRIB_REQ_
Procedure 4-128
Possible FTAM Initiator Errors for the FTM_READ_ATTRIB_CNF_
Procedure 4-132
Possible FTAM Initiator Errors for the FTM_SELECT_REQ_
Procedure 4-135
Possible FTAM Initiator Errors for the FTM_SELECT_CNF_
Procedure 4-138
Possible FTAM Initiator Errors for the FTM_TERMINATE_REQ_
Procedure 4-140
Possible FTAM Initiator Errors for the FTM_TERMINATE_CNF_
Procedure 4-142
Possible FTAM Initiator Errors for the FTM_TRANSFER_END_REQ_
Procedure 4-144
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
vii
Tables (continued)
Contents
Tables (continued)
Table 4-44.
Table 4-45.
Table 4-46.
Table 4-47.
Table A-1.
Table A-2.
Table B-1.
Table B-2.
Table B-3.
Table B-4.
Table B-5.
Table B-6.
Table B-7.
Table B-8.
Table B-9.
Table B-10.
Table B-11.
Table B-12.
Table B-13.
Table B-14.
Table C-1.
Table C-2.
Table C-3.
Table C-4.
Table C-5.
Table C-6.
Table C-7.
Table C-8.
Table C-9.
Table D-1.
Possible FTAM Initiator Errors for the FTM_TRANSFER_END_CNF_
Procedure 4-146
Possible FTAM Initiator Errors for the FTM_U_ABORT_REQ_
Procedure 4-148
Possible FTAM Initiator Errors for the FTM_U_ABORT_IND_
Procedure 4-151
Possible FTAM Initiator Errors for the FTM_WRITE_REQ_
Procedure 4-154
Event Code Values and Their Primitives A-39
Data Types Used by Procedure Calls A-42
Status Code Values B-2
APS Error Codes for NonStop FTAM B-4
APLMGR Subcodes B-12
FTM-Procedure Parameter Subcodes B-16
FTAM Initiator Error Codes B-19
Out-Of-Sequence Subcodes B-21
FTAM Functional-Unit Subcodes B-22
Functional Units Required for Create, Change-Attribute, and BeginGroup Services B-22
File-Access Subcodes B-23
Processing-Mode Subcodes B-24
Access Contexts by Document Type B-26
Invalid-Data Subcodes B-27
Service-Class Subcodes B-28
Association-Rejection Error Types B-32
Error Types C-2
Observers and Sources of Errors C-2
General FTAM Diagnostic Messages C-3
Protocol and Supporting Service-Related Diagnostic Messages C-3
Association-Related Diagnostic Messages C-4
Selection-Related Diagnostic Messages C-5
File-Management-Related Diagnostic Messages C-6
Access-Related Diagnostic Messages C-6
Recovery-Related Diagnostic Messages C-8
NonStop FTAM Initiator Diagnostic Messages D-1
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
viii
What’s New in This Manual
Manual Information
HP NonStop OSI/FTAM Programming Reference Manual
Abstract
This manual describes the operation of the HP NonStop™ Open Systems
Interconnection/File Transfer, Access, and Management (OSI/FTAM) application
programmatic interface (API). It is for programmers writing FTAM applications that use
the services of the NonStop FTAM initiator. The FTAM API allows applications to
perform file-handling and transfer tasks.
Product Version
OSI/FTAM D43 and G06, OSI/APLMGR D43 and G06
Supported Release Version Updates (RVUs)
This publication supports D43.00 and all subsequent D-series RVUs and G06.01 and
all subsequent G-series RVUs until otherwise indicated by its replacement publication.
Part Number
Published
528611-001
October 2004
Document History
Part Number
Product Version
Published
030253
OSI/FTAM C30, OSI/APLMGR C30
September 1992
528611-001
OSI/FTAM D43 and G06, OSI/APLMGR
D43 and G06
October 2004
New and Changed Information
This edition contains the following changes:
•
•
•
•
Clarified that NonStop FTAM supports unbounded character strings, under
Document Types and Related Parameters on page 2-4.
Removed maximum-string-length as a required component of the
contents-type attribute in the initial-attrib parameter for the
FTM_CREATE_REQ_ procedure on page 4-36.
Changed the third consideration for the FTM_CREATE_REQ procedure call to
clarify that a parameter value of ZFTM-VAL-CNTNTSTYPE-UNKNOWN is now
allowed under Considerations on page 4-38.
Removed “Error code: ZAPS-ERR-PARAM-MISSING (-136)” and “Subcode:
ZFTM-ERR-MAX-STRING-LEN (155)” from the list of errors on pages 4-40, 4-89,
and 4-115.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
ix
What’s New in This Manual
•
•
•
•
•
New and Changed Information
Changed the size of the encoded data limit from 7 KB to 16 KB on pages 4-50,
B-27, and B-27.
Changed the size of the data value parameter that can be sent from 11 KB to
24 KB on page B-27.
Changed the buffer size from 12 KB to 25 KB under Considerations on page 4-55.
Removed maximum-string-length as a required component of the
contents-type attribute in the value for initial-attrib when specifying
values of file-status on page 4-85.
Changed maximum-string-length from a required parameter to an optional
parameter under FTM_FILE_OPEN_REQ_ contents-type on 4-86 and
FTM_OPEN_REQ_ contents-type on page 4-113.
Added the following section from the OSI/FTAM Programming Supplement:
•
Added “Translation Application Example” on page G-221.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
x
About This Manual
The OSI/FTAM Programming Reference Manual is the companion manual to the
OSI/FTAM Programming Guide. It provides reference information about writing
application programs that use NonStop OSI/File Transfer, Access and Management
(FTAM) application services. This manual has the following objectives:
•
•
•
•
Introduce NonStop FTAM
Describe conformance and interoperability issues for NonStop FTAM
Provide information on the NonStop FTAM application programmatic interface
(API) and FTAM initiator process
Describe the procedures contained in the FTAM API and used to develop FTAM
applications
Who Should Read This Manual?
This manual is designed for programmers developing applications that use the
NonStop FTAM initiator. Programmers communicating with the initiator using the FTAM
API must be familiar with the ISO FTAM specification and FTAM protocol.
This manual provides a detailed description of the NonStop FTAM API and initiator. For
a review of basic FTAM concepts and details about NonStop FTAM programming and
the FTAM procedures, see OSI/FTAM Programming Guide.
What’s In This Manual?
Section
Title
This section...
1
Introduction to NonStop
OSI/FTAM
Provides a general introduction to FTAM for
programmers who use the initiator to develop
FTAM programs. It includes general
information about FTAM procedures and
interfaces and provides an explanation of
FTAM architecture. In addition, this section
describes the hardware and software needed
to run FTAM on an HP NonStop system.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xi
What’s In This Manual?
About This Manual
Section
Title
This section...
2
Conformance and
Interoperability
Presents details about NonStop FTAM
conformance testing and pointers on
evaluating interoperability between NonStop
FTAM and other FTAM implementations.
3
NonStop FTAM Initiator
Describes the NonStop FTAM initiator
process and how it provides the supported
FTAM functions, and presents information
about the FTAM API.
4
FTM Procedures
Provides reference information about the
FTM procedures that programmers use to
develop FTAM applications.
Appendix
Title
This section...
A
DDL Definitions
Defines all data types, parameter structures,
and named values provided by HP for use in
NonStop FTAM applications.
B
NonStop FTAM Initiator Error
Messages
Provides cause, effect, and recovery
information for all error messages that
originate in the NonStop initiator.
C
ISO FTAM Diagnostic
Messages
Lists the FTAM diagnostic messages defined
in the ISO 8571 standard and includes the
NonStop constants defined for them.
D
NonStop FTAM Initiator
Diagnostic Messages
Provides cause, effect, and recovery
information for all diagnostic messages that
originate in the initiator.
E
MFM Procedures
Provides reference information about MFM
procedures contained in the FTAM API.
F
APS Procedures
Provides reference information about the
subset of APS procedure calls contained in
the FTAM API.
G
NonStop FTAM Programming
Examples
Presents two sample programs, each one
provided in both C and TAL, that illustrate
how to develop an application that use
FTAM API procedures.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xii
Supported Standards
About This Manual
Supported Standards
This manual and the other NonStop FTAM manuals are written on the assumption that
you are familiar with the ISO standards and the National Institute of Standards and
Technology (NIST) FTAM Phase 2 agreements to which NonStop FTAM and the
underlying NonStop OSI products conform. These standards include the following:
Standard Number
Standard Name
ISO 8326
Basic Connection Oriented Session Service Definition
ISO 8327
Basic Connection Oriented Session Protocol Specification
ISO 8571-1
File Transfer, Access and Management—Part 1: General Introduction
ISO 8571-2
File Transfer, Access and Management—Part 2: Virtual Filestore
Definition
ISO 8571-3
File Transfer, Access and Management—Part 3: File Service
Definition
ISO 8571-4
File Transfer, Access and Management—Part 4: File Protocol
Specification
ISO 8571-5
File Transfer, Access and Management—Part 5: Protocol
Implementation Conformance Statement
ISO 8649
Service Definition for the Association Control Service Element
ISO 8650
Protocol Specification for the Association Control Service Element
ISO 8822
Connection Oriented Presentation Service Definition
ISO 8823
Connection Oriented Presentation Protocol Specification
ISO 8824
Specification of Abstract Syntax Notation One (ASN.1)
ISO 8825
Specification of Basic Encoding Rules for Abstract Syntax Notation
One (ASN.1)
ISO/IEC ISP 10607
Information Technology—International Standardized Profiles AFTnn—
File Transfer, Access and Management, Parts 1-6
NIST 500-162
Stable Implementation Agreements for Open Systems
Interconnection Protocols (Special Publication), Part 9—FTAM Phase
2
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xiii
Related Manuals
About This Manual
Related Manuals
Figure i on page -xv shows how the manual you are now reading is related to other
NonStop manuals. The flowchart, read from the top down, indicates the order in which
you might read the manuals. Before reading this manual, you should read or be
familiar with the following HP manuals:
•
•
•
OSI/FTAM Programming Guide explains important programming concepts
pertaining to the NonStop OSI/FTAM implementation and describes sequences of
procedure calls to use to perform common FTAM programming operations. This
manual also provides an overview of FTAM concepts for those who have not
recently read the ISO 8571 specification.
Guardian Programmer’s Guide describes how to use the NonStop procedure calls,
including the file-system procedures.
TAL Reference Manual describes how to use the Transaction Application
Language (TAL), and the C/C++ Programmer’s Guide describes HP C for NonStop
systems. You only need to be familiar with the information for the programming
language you are using.
The following manuals provide additional information to which you might need to refer
while using this manual:
•
•
Guardian Procedure Calls Reference Manual gives the syntax and programming
considerations for all the NonStop operating system procedures.
Guardian Procedure Errors and Messages Manual describes the file-system
messages that might be returned as error subcodes in NonStop FTAM error
conditions.
The following manuals provide additional information that might be of interest:
•
•
•
OSI/FTAM and OSI/APLMGR SCF Reference Manual describes how to use SCF
commands to configure, monitor, and control FTAM.
OSI/FTAM Configuration and Management Manual provides task-oriented
information necessary for the installation and management of NonStop FTAM
services including an explanation of the configuration and control of the initiator
and responder processes and the associated APLMGR process. This manual
includes information on monitoring and adjusting your subsystem to optimize
performance and on diagnosing and fixing problems.
OSI/AS Programming Manual describes the APS (application, presentation, and
session) procedures, which enable application programs to establish and use OSI
connections that use the Session Layer, the Presentation Layer, and the
Association Control Service Element (ACSE) of the Application Layer. These
procedures are part of the HP OSI/AS data communications subsystem.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xiv
Related Manuals
About This Manual
Figure i. Documentation Road Map
OSI/FTAM
Programming
Guide
Guardian
Programmer’s
Guide
TAL
Reference
Manual
OSI/FTAM
Programming
Reference
Manual
OSI/FTAM
and OSI/
APLMGR
SCF
Reference
Manual
OSI/FTAM
Config. and
Mgmt.
Manual
C/C++
Programmer's
Guide
Guardian
Procedure
Calls
Reference
Manual
Guardian
Procedure
Errors and
Messages
Manual
OSI/AS
Programming
Manual
VSTAB01.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xv
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. Uppercase letters indicate keywords and reserved words. Type
these items exactly as shown. Items not enclosed in brackets are required. For
example:
MAXATTACH
lowercase italic letters. Lowercase italic letters indicate variable items that you supply.
Items not enclosed in brackets are required. For example:
file-name
computer type. Computer type letters within text indicate C and Open System Services
(OSS) keywords and reserved words. Type these items exactly as shown. Items not
enclosed in brackets are required. For example:
myfile.c
italic computer type. Italic computer type letters within text indicate C and Open
System Services (OSS) variable items that you supply. Items not enclosed in brackets
are required. For example:
pathname
[ ] Brackets. Brackets enclose optional syntax items. For example:
TERM [\system-name.]$terminal-name
INT[ERRUPTS]
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list can be arranged either vertically, with aligned brackets on
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
FC [ num ]
[ -num ]
[ text ]
K [ X | D ] address
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xvi
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. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }
… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address [ , new-value ]…
[ - ] {0|1|2|3|4|5|6|7|8|9}…
An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:
"s-char…"
Punctuation. Parentheses, commas, semicolons, and other symbols not previously
described must be typed as shown. For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must type as shown. For example:
"[" repetition-constant-list "]"
Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In this example, no
spaces are permitted between the period and any other items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line, each
continuation line is indented three spaces and is separated from the preceding line by
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xvii
Notation for Messages
About This Manual
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:
ALTER [ / OUT file-spec / ] LINE
[ , attribute-spec ]…
!i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data
to the called procedure); the !o notation follows an output parameter (one that returns
data to the calling program). For example:
CALL CHECKRESIZESEGMENT (
segment-id
, error
) ;
!i
!o
!i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both
passes data to the called procedure and returns data to the calling program). For
example:
error := COMPRESSEDIT ( filenum ) ;
!i:i.
!i,o
In procedure calls, the !i:i notation follows an input string parameter that has a
corresponding parameter specifying the length of the string in bytes. For example:
error := FILENAME_COMPARE_ (
filename1:length
, filename2:length ) ;
!i:i
!i:i
!o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a
corresponding input parameter specifying the maximum length of the output buffer in
bytes. For example:
error := FILE_GETINFO_ (
filenum
, [ filename:maxlen ] ) ;
!i
!o:i
Notation for Messages
This list summarizes the notation conventions for the presentation of displayed
messages in this manual.
Bold Text. Bold text in an example indicates user input typed at the terminal. For example:
ENTER RUN CODE
?123
CODE RECEIVED:
123.00
The user must press the Return key after typing the input.
Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or
returned exactly as shown. For example:
Backup Up.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xviii
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. For
example:
Event number = number [ Subject = first-subject-value ]
A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none might actually be displayed. The items in the list can
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:
proc-name trapped [ in SQL | in SQL file system ]
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be
displayed, of which one is actually displayed. 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:
obj-type obj-name state changed to state, caused by
{ Object | Operator | Service }
process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown.
}
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
Transfer status: { OK | Failed }
% Percent Sign. A percent sign precedes a number that is not in decimal notation. The
% notation precedes an octal number. The %B notation precedes a binary number.
The %H notation precedes a hexadecimal number. For example:
%005400
%B101111
%H2F
P=%p-register E=%e-register
Notation for Management Programming Interfaces
This list summarizes the notation conventions used in the boxed descriptions of
programmatic commands, event messages, and error lists in this manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xix
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.
!r
The !o notation following a token or field name indicates that the token or field is
optional. For example:
ZSPI-TKN-MANAGER
token-type ZSPI-TYP-FNAME32.
!o
Change Bar Notation
Change bars are used to indicate substantive differences between this manual and its
preceding version. Change bars are vertical rules placed in the right margin of changed
portions of text, figures, tables, examples, and so on. Change bars highlight new or
revised information. For example:
The message types specified in the REPORT clause are different in the COBOL85
environment and the Common Run-Time Environment (CRE).
The CRE has many new message types and some new message type codes for
old message types. In the CRE, the message type SYSTEM includes all messages
except LOGICAL-CLOSE and LOGICAL-OPEN.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
xx
1
Introduction to NonStop OSI/FTAM
This manual describes the NonStop Open Systems Interconnection/File Transfer,
Access and Management (OSI/FTAM) product used in developing FTAM applications.
NonStop OSI/FTAM is the NonStop implementation of the FTAM standard ISO 8571,
developed by the International Organization for Standardization (ISO).
File Transfer, Access and Management (FTAM) is a set of Application Layer services
and an Application Layer protocol to support file handling on Open Systems
Interconnection (OSI) networks. Using this standard FTAM protocol across an OSI
network, different computer systems can transmit and receive file contents and
file-management-related messages.
While this manual is designed to be as complete as possible with regard to the
NonStop FTAM implementation, it is not intended to duplicate or replace the ISO
standards and National Institute of Science and Technology (NIST) FTAM Phase 2
agreements. About This Manual lists the relevant ISO and NIST documents that you
might want to review.
In this manual, ISO FTAM refers to the FTAM specification as defined in ISO 8571, and
NonStop FTAM refers to the NonStop OSI/FTAM product.
This section covers the following topics:
Topic
Page
Functional Overview
1-1
Architectural Overview
1-5
Functional Overview
ISO FTAM provides the following file-handling functions across the network:
•
•
•
•
•
•
•
Creating files
Deleting files
Erasing part or all the contents of files
Reading from files
Writing to files
Reading file attributes
Changing file attributes
FTAM users communicate with the FTAM service provider by way of primitives, the
smallest units of interaction between the FTAM user and the FTAM service provider. An
operation like any of those mentioned above requires the exchange of multiple
primitives, which the FTAM software encodes as protocol data units (PDUs), the
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -1
Introduction to NonStop OSI/FTAM
NonStop FTAM Services
encoded messages transferred across an OSI network between the initiator and
responder.
FTAM file handling is defined in terms of initiator and responder functions. The initiator
provides application programs with access to the FTAM protocol so that you can
request services to be performed by a responder across the network. The remote
responder acts as a file server and performs the requested services.
NonStop FTAM Services
NonStop FTAM provides most of the FTAM services specified in ISO 8571. The
NonStop FTAM implementation separates the initiator and responder functions into two
processes. The NonStop FTAM initiator process implements the initiator function, while
the NonStop FTAM responder process implements the responder function.
The initiator and responder processes provide the FTAM functions required for your
applications. These processes manage the FTAM communications among your
application and other FTAM applications on the local or remote computer systems on
an OSI network. Your application communicates with the initiator process through
system procedure calls, and with the NonStop operating system through Guardian
procedure calls.
NonStop FTAM can handle the following types of files, where the corresponding FTAM
document types are listed parenthetically:
•
•
•
•
Unstructured text files (FTAM-1)
Structured text files (FTAM-2)
Unstructured binary files (FTAM-3)
Directory files (NBS-9)
NonStop FTAM Application Examples
The following examples illustrate how NonStop FTAM services might be used to
develop an application:
•
•
•
An application that analyzes daily sales statistics uses FTAM procedures to access
one of the Sales division’s remote computers to retrieve summary reports at the
end of each day. FTAM provides the remote file-access link to the remote computer
in the Sales division.
An application distributes manufacturing schedules to different assembly areas
within a large manufacturing facility. The schedules are received as files on a
variety of computer systems at these assembly areas. FTAM provides the file
transfer capability across the OSI network to allow this distribution to take place
between the central NonStop computer (which distributes the manufacturing
schedules) and the other systems.
NonStop FTAM is used in a banking network to send information on the transfer of
funds from one bank (a NonStop system) to other banks that do not use NonStop
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -2
Introduction to NonStop OSI/FTAM
Programming Capabilities
systems. The information consists of details on the transactions that have taken
place with the other banks, such as credits, checks cleared, debits, and so on.
FTAM provides the necessary file-handling function among the different systems
on the network.
The OSI/FTAM Programming Guide also describes an FTAM application scenario.
Programming Capabilities
This manual focuses on the programmatic interface you use to develop applications.
To develop an application using the ISO FTAM protocol, use the NonStop FTAM
procedures to initiate file-handling tasks across an OSI network, and Guardian
procedure calls to perform local file handling. The FTAM programming capabilities
apply only to the initiator. There is no programmatic interface to the responder, and this
manual does not describe the responder process in detail. For detailed information on
the responder, refer to the OSI/FTAM Responder Manual.
ISO FTAM protocol defines a common model of the file system (the virtual filestore),
which allows all computer systems on an open network to share the same file handling
conventions. Since each FTAM responder implementation manages its own local file
system, you do not need to learn how to program file handling for each unique system
on your network. Programmers writing FTAM applications use the standard FTAM file
handling conventions to perform remote file-handling tasks. To handle local files in the
Guardian file system, a programmer developing FTAM applications on a NonStop
system uses Guardian file-system procedures.
Programmatic Interface
The NonStop FTAM application programmatic interface (API) is a set of procedures
that interact with the initiator process. Your application accesses the initiator by way of
the FTAM API. The initiator in turn sends requests to perform file-handling services to
remote responders.
The FTAM programmatic interface consists of the following types of procedures,
described in greater detail in Section 3, NonStop FTAM Initiator: FTAM protocol
procedures, general-support procedures, and module file management procedures.
Section 4, FTM Procedures includes reference information about FTAM protocol
procedures. The OSI/FTAM Programming Guide describes how to use FTAM API
procedures to perform basic FTAM programming tasks.
NonStop FTAM procedures are designed to easily integrate into application programs
written in either the C or TAL programming languages. Appendix G, NonStop FTAM
Programming Examples provides FTAM programming examples in both of these
languages. Each FTAM service, or file operation, can require that multiple FTAM
protocol procedures be called to complete the service. For example, to open a file, an
FTAM application must first call the initialize-request procedure and then a file-selectrequest and a file-open-request procedure to send the requests to the responding
system in the communication. The responding system receives the requests as
indications and sends responses back to the requesting system. The requesting
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -3
Management Interface
Introduction to NonStop OSI/FTAM
system receives these responses as confirms. Thus, four primitives—request,
indication, response, and confirm—are used to complete most services, as shown in
Figure 1-1. The OSI/FTAM Programming Guide provides details on the different types
of primitives and how they effect programming. Section 3, NonStop FTAM Initiator
identifies the FTAM services that the initiator supports.
Figure 1-1. An FTAM Service Using Four Primitives
Initiating Process
Responding Process
F-XXX request
F-XXX indication
F-XXX request
F-XXX confirm
VST0101.vsd
The ISO standard provides flexibility in the level of FTAM function that must be
implemented in an ISO-conformant system. This flexibility implies that, as you write
and test your application, you need to consider the specifications for the other FTAM
implementations with which your application will interoperate. For information about the
factors to consider in assessing the interoperability of the NonStop FTAM product with
other FTAM implementations, refer to Section 2, Conformance and Interoperability.
Management Interface
In addition to the programmatic interface, NonStop FTAM includes the Distributed
Systems Management (DSM) interface.
Three management utilities support the DSM interface to NonStop FTAM:
•
•
•
Subsystem Control Facility (SCF)
PTrace
Operator message facility of the Event Management Service (EMS)
These management utilities are described in greater detail in Distributed Systems
Management (DSM) Interface on page 1-10.
Note. The programmatic interfaces to the NonStop management products, SPI and EMS, are
not available for customer use with NonStop FTAM.
Interaction With Other NonStop Subsystems
NonStop OSI/Application Services (OSI/AS) manages the communication of messages
between a local NonStop system and a remote system on a network. NonStop FTAM
uses OSI/AS, which in turn uses OSI/Transport Services (OSI/TS) and either the HP
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -4
Introduction to NonStop OSI/FTAM
Architectural Overview
Tandem LAN access method (TLAM) or the X.25 access method (X25AM) to
communicate with remote computer systems across a network.
NonStop FTAM, the OSI/AS subsystem, the OSI/TS subsystem, and TLAM or X25AM
must be configured and running on the NonStop system for your application to
communicate with a remote system. For more information about OSI/AS, OSI/TS,
TLAM, and X25AM, see Figure 1-6 on page 1-13 and the accompanying text.
The OSI/FTAM Programming Guide provides more information on system
configuration requirements for running applications using FTAM. For details on
NonStop FTAM configuration and the services underlying NonStop FTAM, refer to the
OSI/FTAM Configuration and Management Manual.
Architectural Overview
FTAM services facilitate communication between different computer systems on an
OSI network. The communication link (at the FTAM level) created between two
systems is called an association. Each system is further defined in terms of its function
in the association. The system that creates and controls the association is called the
initiating system. The system that responds to the initiating system is called the
responding system. In NonStop FTAM, the initiating and responding functions are
performed by two processes: the initiator process and the responder process.
Note. The term “association” denotes a communication link between entities of the Application
Layer of the OSI Reference Model (specifically the Association Control Service Element, or
ACSE), and a “connection” is a communication link between entities of the six OSI layers below
the Application Layer. Because this manual focuses primarily on associations at the Application
Layer, it seldom uses the term “connection,” used extensively in the OSI/AS Programming
Manual.
The initiator allows NonStop FTAM applications to access FTAM protocol and request
services of a remote responder. The NonStop FTAM application programmatic
interface (API) is a set of procedures that interact with the initiator process. An
application uses these procedures to perform FTAM services, such as accessing files
on a remote computer system that supports FTAM.
The NonStop FTAM responder services FTAM requests initiated from remote systems
on the network. The 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 responder has no programmatic interface.
Figure 1-2 on page 1-6 provides an overview of the NonStop FTAM architecture.
NonStop FTAM provides two user interfaces:
•
•
NonStop FTAM application programmatic interface (API), which is the interface
between the FTAM application and the initiator. For details on the NonStop FTAM
API, refer to Section 3, NonStop FTAM Initiator.
Distributed Systems Management (DSM) interactive interface, which is used to
configure and control NonStop initiator, responder, and APLMGR processes. For a
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -5
Architectural Overview
Introduction to NonStop OSI/FTAM
complete discussion of this interface, refer to the OSI/FTAM Configuration and
Management Manual.
Figure 1-2. NonStop FTAM Architectural Overview
Application
Programmatic
Interface
Management
Interface
Guardian
File System
NonStop FTAM
OSI/AS
OSI/TS
TLAM or X25AM
Communications Network
Remote
FTAM
Initiator
Remote
FTAM
Responder
VST0102.vsd
Figure 1-2 also shows the following architectural components:
•
•
•
The Guardian file system. The files to be accessed on the local NonStop system
reside here.
OSI underlying services, including OSI/AS, OSI/TS, and TLAM or X25AM.
Together, these underlying subsystems provide the necessary protocol to
communicate with remote computer systems across an OSI network.
The OSI communications network, which interfaces with either the HP TLAM or
X25AM software. TLAM implements the 802.3 communications protocol for an OSI
network. The X25AM product implements the X.25 communications protocol.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -6
Introduction to NonStop OSI/FTAM
•
•
FTAM and APLMGR Subsystems
Remote FTAM initiator on the network, which can communicate with the NonStop
FTAM responder and the Guardian file system.
Remote FTAM responder on the network, which services requests initiated by the
NonStop FTAM initiator for information stored in a remote file storage system.
Note. The initiator and responder functions of remote FTAM implementations are not
necessarily performed by separate processes.
FTAM and APLMGR Subsystems
For the purposes of configuration and management, the NonStop FTAM software
consists of two subsystems: FTAM and APLMGR. Figure 1-3 on page 1-8 illustrates
the major components of these subsystems.
The FTAM subsystem consists of the initiator and responder processes and the objects
representing associations between those processes and FTAM implementations in
remote systems. You can configure multiple initiator or responder processes, or both,
as needed.
The virtual filestore (VFS) acts as an interface to the Guardian file system. Files
accessible via the Guardian file system can also be accessed via the VFS component
of the responder. This includes all files on the system on which the responder process
is running, as well as all files on the Expand network to which that system belongs. The
responder uses the VFS to access the Guardian file system in servicing requests from
a remote FTAM initiator.
The APLMGR subsystem—also called simply APLMGR—manages NonStop FTAM.
Through the APLMGR subsystem, you can configure and control initiator and
responder processes. The APLMGR subsystem comprises the APLMGR process and
its management information base, or MIB. (The APLMGR MIB stores the configuration
information for the APLMGR, initiator, and responder processes, while the OSI
manager MIB that is part of OSI/AS stores configuration information for the OSI
underlying services.)
The APLMGR process uses the information stored in the APLMGR MIB to create the
initiator and responder processes. For a complete discussion of the SCF commands
used to manage the initiator and responder processes, refer to the OSI/FTAM and
OSI/APLMGR SCF Reference Manual. For information on using the SCF commands to
configure and control NonStop FTAM, refer to the OSI/FTAM Configuration and
Management Manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -7
NonStop FTAM and the Guardian File System
Introduction to NonStop OSI/FTAM
Figure 1-3. FTAM and APLMGR Subsystems
Application
Programmatic
Interface
NonStop
FTAM
APLMGR
Subsystem
FTAM
Subsystem
APLMGR
Initiator
Management
Interface
Guardian
File System
MIB
Responder
VFS
OSI/AS
OSI/TS
TLAM or X25AM
Communications Network
Remote
FTAM
Initiator
Remote
FTAM
Responder
VST0103.vsd
NonStop FTAM and the Guardian File System
To access local files on NonStop systems, FTAM applications need to communicate
with the Guardian file system using Guardian system procedures. To develop NonStop
FTAM applications, you should be familiar with using FTAM procedures with Guardian
procedures for effective FTAM file transfer. For more information about using the
Guardian system procedures in FTAM applications, refer to the OSI/FTAM
Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -8
Introduction to NonStop OSI/FTAM
Application Programmatic Interface
When a remote FTAM initiator needs access to the Guardian file system, the
responder provides that service via its VFS component, mapping the FTAM requests
into Guardian file requests and translating between FTAM and Guardian file structures
and attributes. For more information on the VFS, refer to the OSI/FTAM Responder
Manual.
Application Programmatic Interface
Figure 1-4 on page 1-10 shows that your FTAM application program uses the NonStop
FTAM application programmatic interface (FTAM API). This interface consists of
NonStop FTM, APS, and MFM procedures and associated definition files. The FTM
procedures are the NonStop FTAM protocol procedures described in Section 4, FTM
Procedures. The APS procedures are a small subset of the APS procedures used in
the application programmatic interface to OSI/AS. This subset of general-support
procedures is used primarily for managing FTAM API buffer space and retrieving event
and error information. For a full description of the APS procedures included in the
FTAM API, see Appendix F, APS Procedures. The MFM procedures are the module file
management procedures used in FTAM programming for nowait I/O operations. These
procedures are described in Appendix E, MFM Procedures. The FTM, APS, and MFM
procedures give you access to the functions of the initiator process.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1 -9
Distributed Systems Management (DSM) Interface
Introduction to NonStop OSI/FTAM
Figure 1-4. NonStop FTAM and the Application Programmatic Interface (API)
Application
Program
FTAM API
Management
Interface
NonStop FTAM
OSI/AS
Guardian
File System
4
OSI/TS
TLAM or X25AM
Communications Network
Remote
FTAM
Responder
VST0104.vsd
Distributed Systems Management (DSM) Interface
Figure 1-5 on page 1-12 shows additional details of the NonStop Distributed Systems
Management (DSM) interface. DSM is a group of NonStop products that work together
to manage systems and networks. The major components of DSM are:
•
Subsystem Control Facility (SCF), a common management interface for a variety
of NonStop data communications products including NonStop FTAM, OSI/AS, and
others. This interface allows you to configure and manage NonStop FTAM. The
OSI/FTAM and OSI/APLMGR SCF Reference Manual describes the SCF
commands you use to configure and control the NonStop FTAM and APLMGR
processes, to monitor the initiator and responder processes, and to control the
connections from those processes to FTAM implementations on remote systems.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1-10
Introduction to NonStop OSI/FTAM
•
•
Distributed Systems Management (DSM) Interface
Subsystem Control Point (SCP), an intermediate management process that routes
commands from SCF to the APLMGR, initiator, or responder process being
managed.
Event Management Service (EMS), a collection of processes, tools, and interfaces
that provide event collection, event logging, and event distribution facilities for
communications subsystems. All OSI subsystems—such as APLMGR, FTAM,
OSI/AS, and others—report significant events in the form of event messages to an
EMS collector, which logs the messages. These event messages can then be
retrieved interactively from an EMS distributor process. You can use information
retrieved from EMS to monitor the activity of NonStop FTAM and recognize
operational problems on the network.
For more information about EMS, refer to the EMS Manual. For more information
about APLMGR and FTAM operator messages, refer to the Operator Messages
Manual.
•
PTrace (print trace), a utility that selects, formats, and displays trace data. You
collect trace data by issuing the SCF TRACE command to an APLMGR, initiator, or
responder process. For information about the SCF TRACE command and PTrace,
refer to the OSI/FTAM Configuration and Management Manual, the PTrace
Reference Manual, and the OSI/FTAM and OSI/APLMGR SCF Reference Manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1-11
Introduction to NonStop OSI/FTAM
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems
Figure 1-5. NonStop FTAM and the DSM Interface
DSM
EMS
Application
Programmatic
Interface
SCF
NonStop FTAM
PTRACE
Guardian
File System
SCP
OSI/AS
4
OSI/TS
TLAM or X25AM
Communications Network
Remote
FTAM
Initiator
Remote
FTAM
Responder
VST0105.vsd
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems
Figure 1-6 on page 1-13 focuses on the NonStop OSI underlying services. To
communicate over OSI networks, NonStop FTAM uses the services of the NonStop
OSI/AS and OSI/TS subsystems, and either the HP Tandem LAN Access Method
(TLAM) or the X.25 Access Method (X25AM), as shown.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1-12
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems
Introduction to NonStop OSI/FTAM
Figure 1-6. NonStop FTAM and OSI/AS, OSI/TS, and TLAM or X25AM
Subsystems
Application
Programmatic
Interface
NonStop FTAM
Management Interface
OSI/AS
OSI Manager
Guardian
File System
SCF
TAPS
OSI/TS
SCF
TSP
MIB
TLAM
or
X25AM
SCF
NSP
Communications Network
Remote
FTAM
Initiator
Remote
FTAM
Responder
VST0106.vsd
To communicate with remote computer systems across an OSI network, you must
configure NonStop FTAM to operate with these subsystems. The OSI/AS subsystem
consists of NonStop application, presentation, and session service provider (TAPS)
processes; the OSI/TS subsystem consists of transport service provider (TSP)
processes; and the TLAM and X25AM subsystems each consist of network service
provider (NSP) processes. All these subsystems are managed by the OSI manager
process, which maintains its own management information base (MIB).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1-13
Introduction to NonStop OSI/FTAM
OSI/AS, OSI/TS, and TLAM or X25AM Subsystems
When configuring these subsystems to support FTAM services, you must register each
TAPS, TSP, and NSP process with the OSI manager process. You can configure more
than one instance of each of these processes (TAPS, TSP, and NSP) to run at a given
time, as well as multiple OSI manager processes managing separate subsystems. For
more information on configuring, refer to the OSI/FTAM Configuration and
Management Manual.
The OSI manager MIB stores the common name and corresponding addresses for all
OSI processes. In addition to the address information for the TAPS, TSP, and NSP
processes, you must add either the common name or address associated with each
initiator or responder process to the OSI manager MIB. For more information on OSI
addressing, refer to the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
1-14
2
Conformance and Interoperability
This section presents information about the conformance to standards and the
interoperability of the NonStop FTAM initiator.
Conformance is the satisfaction of the requirements of the applicable standards,
consistent with the capabilities stated in the protocol implementation conformance
statement (PICS) for the implementation. Interoperability is the ability of an
implementation of a standard to work with other implementations of the same standard
to deliver services.
A list of the international standards and agreements that apply to NonStop FTAM is
provided in About This Manual.
These topics are covered in this section:
Topic
Page
Conformance
2-1
Interoperability
2-1
Conformance
To be ISO FTAM-conformant, an FTAM implementation must comply with the
International Organization for Standardization (ISO) FTAM standard for communication
between different FTAM implementations. Conformance to the ISO FTAM standard is
tested in the areas of the support of services, functional units, service classes, and file
attributes.
Conformance testing increases the probability that an implementation can work with
other implementations. Two or more implementations are more likely to work together
when they conform to the same set of standards.
The NonStop OSI/FTAM product has been tested to conform with ISO 8571, NIST
Special Publication 500-162 (Stable Implementation Agreements for Open Systems
Interconnection Protocols), Part 9–FTAM Phase 2, and US GOSIP version 1.0.
Interoperability
Interoperability, or interworking, is the ability of two implementations to communicate
using FTAM primitives in a useful and meaningful way. While conformance to ISO
FTAM is necessary, it does not by itself guarantee that two implementations will
interwork. Even if the two implementations conform to the same OSI protocol standard,
they might be incapable of interworking with each other for reasons outside the scope
of that standard (see ISO IS 9646-1, section 5.7.2).
In addition, the FTAM standard is very complex. Two implementations might contain
disjoint subsets of the standard that do not allow for interoperability but are fully
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -1
Conformance and Interoperability
Basic Characteristics of FTAM Implementations
conformant to the ISO specification. For example, two systems cannot interoperate
when each supports only an initiator, or when a document type supported by an
initiator is not included among the document types supported by the responder.
The NonStop FTAM product has been tested to conform with the standards and
profiles mentioned in Conformance on page 2-1. It has also been tested to interoperate
with a number of other vendors according to the NISTIR 4435 document, “FTAM
Interoperability Tests,” which most vendors use as a basis for writing FTAM
interoperability tests.
When evaluating interoperability between NonStop FTAM and another FTAM
implementation, consider the following aspects in which FTAM implementations can
vary. The NonStop FTAM manual set provides you with the information about the
NonStop FTAM implementation that you need to determine whether another
implementation can interoperate with the NonStop FTAM product. You can find more
information about the following interoperability considerations in the sections or
manuals noted.
Basic Characteristics of FTAM Implementations
To determine whether another FTAM implementation can interoperate with NonStop
FTAM, you must first consider the following basic characteristics of the two
implementations.
Roles of Initiator and Responder
Initiator and responder roles must be compatible to interoperate successfully. For two
implementations to interoperate, there must be an initiator and a responder that can
send and receive data between the two. For more information on the NonStop FTAM
initiator, see Section 3, NonStop FTAM Initiator.
Roles of Sender and Receiver
The sender is the entity that sends data. The receiver is the entity receiving data. In
NonStop FTAM, both the initiator and the responder have sender and receiver
capabilities. For example, an initiator sending a read request is the receiver, and an
initiator sending a write request is the sender.
Service Classes Supported
The service classes supported are defined in terms of combinations of functional units.
At least one common service class must be supported for two implementations to
interoperate. NonStop FTAM supports four service classes: file transfer, file
management, file transfer and management, and file access. For a complete
description of these service classes, see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -2
Conformance and Interoperability
Document Types and Related Parameters
Underlying Services
NonStop FTAM uses NonStop OSI/AS, which is an implementation of version 1 of the
Association Control Service Element (ACSE), as stated in ISO IS 8649 and 8650;
version 1 of the Presentation Layer, as stated in ISO IS 8822 and 8823; and version 2
of the Session Layer, as stated in ISO IS 8326 and 8327. To interoperate with NonStop
FTAM, other FTAM implementations must support compatible versions of ACSE,
Presentation, and Session Layers, as well as the services underlying the Session
Layer.
For a complete list of the ISO standards and NIST agreements to which the NonStop
OSI/FTAM software conforms, see Supported Standards on page -xiii.
Functional Units
Both implementations must support the functional units required for any services the
pair will perform together. NonStop FTAM supports seven functional units: kernel, read,
write, file access, limited file management, enhanced file management, and grouping.
For more information on functional units, see the OSI/FTAM Programming Guide.
Attributes
Aspects of attributes that can affect interoperability include the optional groups of
attributes, the level of support for each individual attribute and its optional components,
and the range of values supported for each attribute. The NonStop FTAM
implementation supports three attribute groups: kernel, storage, and security. For more
information on attributes and attribute support in the NonStop FTAM initiator, see
Section 3, NonStop FTAM Initiator and the OSI/FTAM Programming Guide.
FTAM Parameters
Concerns related to FTAM parameters include the supported optional parameters and
the range of values for all parameters. If both implementations are to interoperate, they
must support all parameters and ranges required by the services to be performed. For
more information on the optional parameters supported by NonStop FTAM and the
parameter value ranges, see Section 4, FTM Procedures.
Document Types and Related Parameters
Both implementations must support one or more common document types to
interoperate. NonStop FTAM supports the following document types: FTAM-1, FTAM-2,
FTAM-3, and NBS-9. In addition, users of both implementations must be aware of how
the parameters associated with the FTAM-1, FTAM-2, and FTAM-3 document types
(maximum-string-length, string-significance, and universal-class) are
used in the FTAM software with which they wish to interoperate. (Document-type
parameters do not apply to the NBS-9 document type, which allows reading of
directory information using an attribute bit string.)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -3
Conformance and Interoperability
Data Transfer Considerations
NonStop FTAM supports unbounded strings for FTAM-1 (string-significance: not
significant or variable) and FTAM-3 (string-significance: not significant).
For string-significance, the initiator supports all three possible values for the FTAM-1,
FTAM-2, and FTAM-3 document types: not-significant, fixed, and variable.
For the universal-class parameter associated with FTAM-1 and FTAM-2
document types (the concept of universal-class does not apply to FTAM-3 documents),
the initiator supports the universal-class values specified in Tables 19 and 20 of ISO
8571, Part 2. If no universal-class value is proposed in an initiator open request or
returned in an open confirm, the NonStop FTAM initiator assumes that the responder is
sending GraphicString data, in compliance with the ISO 8571 default for the universalclass parameter value.
For more information on NonStop FTAM document types and their associated
parameters, see the OSI/FTAM Programming Guide.
Data Transfer Considerations
This subsection briefly describes the aspects of NonStop FTAM data handling that
might affect interoperability between the NonStop FTAM initiator and another FTAM
implementation. For complete information, see the OSI/FTAM Programming Guide.
Handling of Escape Sequences
In enforcing maximum-string-length, when the initiator receives data from a remote
responder, it strips out all escape sequences embedded in character strings with a
negotiated universal-class of 25 (GraphicString) or 27 (GeneralString). Any escape
sequences invoking different character sets that the file might have originally contained
are eliminated from the data before it is passed up to the local FTAM application.
Use of Format Effectors
Format effectors are characters such as carriage returns and line feeds, which control
the formatting of information on character-imaging devices. To interoperate
successfully, application programmers must understand what an implementation
expects as an end-of-line symbol and how it interprets format effectors. For example,
some implementations use the FTAM-1 document type to transfer binary data as
opposed to text. Some implementations recognize carriage returns and line feeds as
format effectors and discard them when binary data, not text, is being transferred;
others see the format effectors as data and transfer them as such.
Character Sets
The NonStop FTAM initiator does no character-set verification. For FTAM-1 and
FTAM-2 files, to ensure that the file being transferred contains the correct character
string type as specified in the universal-class parameter, your application should
verify characters as it sends or receives the data. For more information, see ISO 8824,
which defines character-string types.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -4
Conformance and Interoperability
Presentation Encoding of FTAM PDUs and Data
For FTAM-3 files, remember that the native character sets (ASCII, EBCDIC, and so on)
might be incompatible on the sending and receiving systems. For example, NonStop
systems use the 7-bit ASCII character set, whereas some other vendors’ systems use
8-bit EBCDIC. If you decide to send or receive text characters as FTAM-3 binary data,
some conversion of the native character set might be necessary.
Presentation Encoding of FTAM PDUs and Data
As described in ISO 8823, clause 8, there are several options for encoding
presentation data for FTAM. Presentation data is encoded as SEQUENCE OF
PDV-list. Each PDV list in turn can encode data as single-ASN1-type, octet-aligned, or
arbitrary. If only a single ASN.1 data element is to be encoded, then a single PDV list
encoded as single-ASN1-type must be used. However, when multiple ASN.1 data
elements are to be encoded (as with grouped requests and most F-DATA requests),
there are several options:
•
•
•
Place the data in a single PDV list encoded as octet-aligned.
Place the data in multiple PDV lists, each containing one ASN.1 data element,
encoded as single-ASN1-type.
Place the data in multiple PDV lists, some containing multiple data elements
encoded as octet-aligned and others containing a single data element encoded as
single-ASN1-type.
Any of these three options is valid when all data elements have the same presentation
context. If different presentation contexts are used (as would be the case with FTAM-2
data using FA access context), a separate PDV list must be used for each different
presentation context.
When receiving PDUs, NonStop FTAM supports all three options. When sending
PDUs, NonStop FTAM follows these rules:
•
•
•
If single FTAM PDUs are to be sent, they are placed in a single PDV list encoded
as single-ASN1-type.
If multiple FTAM PDUs are to be sent (grouped requests or responses), they are
sent in a single PDV list encoded as single-ASN1-type.
When F-DATA requests are sent by the initiator, the method of encoding depends
on the number of data elements to be encoded. If only a single data element is
provided, it is placed in a single PDV list encoded as single-ASN1-type; when more
than one data element is provided, the data elements are placed in a single PDV
list, encoded as octet-aligned.
For FTAM-2 files, node-descriptor data elements are placed in their own PDV lists
as single-ASN1-type; consecutive file-contents data elements are placed in a
single PDV list as single-ASN1-type or octet-aligned, depending on whether one or
more consecutive data elements exist.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -5
Conformance and Interoperability
Presentation Encoding of FTAM PDUs and Data
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
2 -6
3
NonStop FTAM Initiator
The NonStop FTAM initiator allows applications running on a NonStop system to
access FTAM protocol and to request services of a responder across the OSI network.
It is responsible for initiating and managing the associations between NonStop FTAM
applications and remote FTAM applications. The initiator communicates with
application programs through the FTAM application programmatic interface (API). The
OSI/AS API provides the initiator interface with the OSI/AS subsystem.
This section covers the following topics:
Topic
Page
Initiator Structure
3-1
Initiator Data Flow
3-3
Types of Procedures in the FTAM API
3-4
How FTM Procedures Are Categorized
3-5
Supported Functions
3-9
Accessing Local Information
3-11
This information is intended for programmers writing applications for NonStop systems
that will interact with FTAM responders on remote systems.
Initiator Structure
The initiator can be broken down into two main components that provide FTAM
functions to the FTAM application. These components process FTAM requests,
perform the requested operations, and communicate with the requesting application
processes.
Figure 3-1 on page 3-2 focuses on the initiator components essential to programming
and does not reflect the parts of the initiator that format data or process management
messages, for example. For diagrams reflecting the global system architecture of
NonStop FTAM, see Section 1, Introduction to NonStop OSI/FTAM.
Figure 3-1 on page 3-2 shows the following initiator components:
•
The protocol state machine receives FTAM requests from the FTAM API. It checks
the validity of the FTAM requests, translates them into the appropriate FTAM
primitives (generally requests or responses), and sends them through the OSI/AS
API to the TAPS process of the OSI/AS subsystem.
The protocol state machine also checks the validity of confirms and indications as
they come in from the TAPS process.
•
The OSI/AS API is the programmatic interface between the initiator and the
OSI/AS subsystem. The initiator communicates with underlying NonStop OSI/AS
processes through this interface.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -1
Running H/F 2
Running H/F 1
Other elements depicted in Figure 3-1, such as the Guardian file system and the TAPS
process, are addressed in more detail later in this section. The numbers indicated in
the figure refer to the sequence of information flow to and from the FTAM initiator, as
described in the next subsection.
Figure 3-1. NonStop FTAM Initiator Process
1
Application
Program
Guardian
File System
FTAM API
2
3
Protocol
State Machine
OSI/AS API
4
TAPS
5
TSP
6
NSP
7
Communications Network
8
Remote
FTAM
Responder
VST0301.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -2
Running H/F 2
Running H/F 1
Initiator Data Flow
An FTAM application can send FTAM requests and responses and receive confirms
and indications, as outlined later in this section. This subsection specifically describes
the flow of an FTAM request from the NonStop FTAM application to the responding
system, and the flow of the remote responder’s response back to the NonStop FTAM
application in the form of a confirm.
The sequence of steps below assumes that you have already established an
association. The numbers shown in Figure 3-1 on page 3-2 correspond to the
sequence of steps outlined below.
1. The FTAM application issues a procedure call through the FTAM API, which
performs some verification and, if necessary, rejects the call with the appropriate
error.
2. If the FTAM API verifies the procedure call to be valid, it sends the appropriate
FTAM request primitive to the FTAM initiator.
3. When the initiator receives the service request, it sends the request directly to the
protocol state machine, where it is processed. The protocol state machine does
some limited error checking, and when it detects an FTAM protocol error or other
error, it sends an error message to the application through the FTAM API and
discontinues processing the request.
4. If the FTAM request is valid, the protocol state machine sends the request through
the OSI/AS API to the TAPS process of the OSI/AS subsystem.
5. The TAPS process receives the FTAM request protocol data unit (PDU), formats it
as an appropriate protocol data unit, and forwards it to the appropriate TSP
process.
6. The TSP process, in turn, processes the information received from TAPS, formats
it as a transport protocol data unit (TPDU), and forwards it to the NSP process.
7. The NSP process formats the PDU and, depending on the network protocol that
the NSP process supports (TLAM or X25AM, for example), forwards it via the
appropriate controller over the network to the responding system, where it is
received as an indication.
8. The responding system processes the indication and sends back a response.
The NonStop initiating system then receives the response as a confirm and sends it up
through the NSP, TSP, and TAPS processes for processing. After processing it, the
TAPS process sends the confirm information through the OSI/AS API to the FTAM
initiator. Once in the FTAM initiator, the protocol state machine verifies, processes, and
sends it to the application via the FTAM API.
The configuration of NonStop FTAM and OSI/AS determines the selection of the TAPS,
TSP, and NSP processes to be used for an association. For more information on
configuration, see the OSI/FTAM Configuration and Management Manual. For
additional details on the upward and downward flow of information between TAPS,
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -3
Running H/F 2
Running H/F 1
TSP, and NSP processes, see the OSI/AS Configuration and Management Manual.
For information about establishing an association and the FTAM programming
concepts that facilitate the flow of data between the FTAM application and the
responding system, see the OSI/FTAM Programming Guide.
The following subsections describe the FTAM API in greater detail, outline the FTAM
functions it supports, and explain how it enables you to transfer, access, and manage
files in an OSI environment.
Types of Procedures in the FTAM API
The initiator supports the FTAM API, which is a collection of system procedures your
program can call to perform FTAM services, such as accessing files on a remote
system that supports FTAM. The FTAM API consists of three types of procedures:
•
FTAM protocol procedures, which begin with the prefix “FTM” and enable the
application to make FTAM service requests of remote responders.
The FTM procedures are sensitive to context: to avoid protocol violations, the
application program must maintain the context in which each call is made. The
FTAM API does not keep track of the procedure-call sequence or the state
changes that occur within the FTAM initiator.
How FTM Procedures Are Categorized on page 3-5, describes these procedures in
greater detail.
•
•
Several general-support procedures, which begin with the prefix “APS.” These
procedures allocate and deallocate buffer space in the FTAM API and retrieve
event and error information.
Module file management procedures, which begin with the prefix “MFM.” If your
program operates in nowait mode, you use the module file management
procedures to receive completion information for I/O requests. For details on
operating in nowait mode, see the OSI/FTAM Programming Guide.
Note. If you are familiar with the OSI/AS API, you might recognize the APS procedures
contained in the FTAM API, which are a small subset of the APS procedures that make up the
OSI/AS API. You might also recognize the MFM procedures. The APS and MFM procedures
that are part of the FTAM API perform functions equivalent to procedures by the same name
that also are part of the OSI/AS API.
Appendix E, MFM Procedures and Appendix F, APS Procedures provide detailed
information on the MFM and APS procedures included in the FTAM API.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -4
Running H/F 2
Running H/F 1
How FTM Procedures Are Categorized
FTM procedures are categorized according to the four types of FTAM primitives:
request, indication, response, and confirm. FTM procedures typically send primitives
that operate in request-indication and response-confirm pairs. The initiator typically
generates requests locally, and a remote FTAM responder receives them as
indications. The responder typically generates responses that the initiator receives as
confirms.
For example, to establish an association, you call the FTM_INITIALIZE_REQ_
procedure and generate a request primitive. The initiator sends the request primitive
across the network as an encoded message, or FTAM protocol data unit (FPDU), to
the remote responder, which receives the request as a corresponding indication. The
responder establishes an association with the initiator and sends back a response to
the initiator. The initiator receives the response as a corresponding confirm. The
following subsections describe these four categories of FTM procedures and their
relationships during an association. A fifth subsection describes the FTAM API grouped
procedures, which allow an application to perform several file operations as a grouped
service.
Request Procedures
Request procedures have names in the form FTM_xxx_REQ_, where xxx refers to
the specific FTAM primitive. When you call a request procedure, the initiator validates
the request and, when it detects an error, it returns an error message to your
application. If the initiator finds no protocol error, the initiator encodes the
corresponding FPDU to send across the network. The initiator then forwards the FPDU
to the remote responder to ask for the specified service. The responder receives the
FPDU as the corresponding indication. For a more detailed description of FPDUs, see
the OSI/FTAM Programming Guide.
For further information on using request procedures, refer to the appropriate procedure
call information in the OSI/FTAM Programming Guide and in Section 4, FTM
Procedures.
Indication Procedures
Indication procedures have names in the form FTM_xxx_IND_, where xxx refers to
the specific FTAM primitive. While the responder is the recipient of most indications (as
a result of initiator requests), the initiator can also receive indications. The abort,
cancel, and data-transfer services allow the initiator to receive indications from the
remote responder.
For further information on using indication procedures, refer to the appropriate
procedure call information in the OSI/FTAM Programming Guide and in Section 4, FTM
Procedures.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -5
Running H/F 2
Running H/F 1
Response Procedures
Response procedures have names in the form FTM_xxx_RSP_, where xxx refers to
the specific FTAM primitive. While the responder is the sender of most responses to
the initiator (in response to initiator requests), the initiator can also send a cancel
response after receiving a cancel indication from the responder.
For further information on using the cancel response procedure, refer to the
information about the FTM_CANCEL_RSP_ procedure call in the OSI/FTAM
Programming Guide and in Section 4, FTM Procedures.
Confirm Procedures
Confirm procedures have names in the form FTM_xxx_CNF_, where xxx refers to the
specific FTAM primitive. The initiator receives confirm primitives as a result of
responses sent by the responder. Confirm procedures allow your application to extract
from the confirm primitive the results of the responder’s attempts to perform requested
services.
For further information on using confirm procedures, refer to the appropriate procedure
call information in the OSI/FTAM Programming Guide and in Section 4, FTM
Procedures.
Grouped Procedures
Most of the FTM procedures are associated with a single FTAM primitive. For example,
the FTM_INITIALIZE_REQ_ procedure issues only the F-INITIALIZE primitive.
However, two FTM procedures, called grouped procedures, issue several primitives:
FTM_FILE_OPEN_REQ_ and FTM_FILE_CLOSE_REQ_.
The grouped procedure FTM_FILE_OPEN_REQ_, for example, issues the primitives
F-SELECT or F-CREATE, and F-OPEN, which allows you to select or create a file and
then open it in a single procedure call. The grouped procedure
FTM_FILE_CLOSE_REQ_ issues the primitives F-CLOSE and either F-DESELECT or
F-DELETE, allowing you to close and either deselect or delete a file in a single
procedure call. The request primitives for both the file-open and file-close services are
bracketed with the F-BEGIN-GROUP and F-END-GROUP primitives.
Two confirm procedures, FTM_FILE_OPEN_CNF_ and FTM_FILE_CLOSE_CNF_,
complete the request-confirm pairings of the file-open and file-close operations, as
shown in the table in the following subsection.
Mapping of Primitives to Procedures
Table 3-1 on page 3-7 lists the ISO FTAM service primitives and the corresponding
NonStop FTAM procedures. The F-BEGIN-GROUP and F-END-GROUP confirms do
not use an FTM_xxx_CNF_ procedure call. Because no parameters are passed in the
two primitives, a confirm procedure to retrieve data is unnecessary.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -6
Running H/F 2
Running H/F 1
Table 3-1. FTAM Service Primitives and Related FTAM Procedures
(page 1 of 2)
ISO FTAM Service Primitives
NonStop FTAM Procedures
F-BEGIN-GROUP request
FTM_BEGIN_GROUP_REQ_
F-BEGIN-GROUP confirm
Not Applicable
F-CANCEL request
FTM_CANCEL_REQ_
F-CANCEL indication
FTM_CANCEL_IND_
F-CANCEL response
FTM_CANCEL_RSP_
F-CANCEL confirm
FTM_CANCEL_CNF_
F-CHANGE-ATTRIB request
FTM_CHANGE_ATTRIB_REQ_
F-CHANGE-ATTRIB confirm
FTM_CHANGE_ATTRIB_CNF_
F-CLOSE request
FTM_CLOSE_REQ_
F-CLOSE confirm
FTM_CLOSE_CNF_
F-CREATE request
FTM_CREATE_REQ_
F-CREATE confirm
FTM_CREATE_CNF_
F-DATA request
FTM_DATA_REQ_
F-DATA indication
FTM_DATA_IND_
F-DATA-END request
FTM_DATA_END_REQ_
F-DATA-END indication
FTM_DATA_END_IND_
F-DELETE request
FTM_DELETE_REQ_
F-DELETE confirm
FTM_DELETE_CNF_
F-DESELECT request
FTM_DESELECT_REQ_
F-DESELECT confirm
FTM_DESELECT_CNF_
F-END-GROUP request
FTM_END_GROUP_REQ_
F-END-GROUP confirm
Not Applicable
F-ERASE request
FTM_ERASE_REQ_
F-ERASE confirm
FTM_ERASE_CNF_
Grouped request:
FTM_FILE_CLOSE_REQ_
F-BEGIN-GROUP request
F-CLOSE request
F-DESELECT request or F-DELETE request
F-END-GROUP request
Grouped confirm:
FTM_FILE_CLOSE_CNF_
F-BEGIN-GROUP confirm
F-CLOSE confirm
F-DESELECT confirm or F-DELETE confirm
F-END-GROUP confirm
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -7
Running H/F 2
Running H/F 1
Table 3-1. FTAM Service Primitives and Related FTAM Procedures
(page 2 of 2)
ISO FTAM Service Primitives
NonStop FTAM Procedures
Grouped request:
FTM_FILE_OPEN_REQ_
F-BEGIN-GROUP request
F-SELECT request or F-CREATE request
F-OPEN request
F-END-GROUP request
Grouped confirm:
FTM_FILE_OPEN_CNF_
F-BEGIN-GROUP confirm
F-SELECT confirm or F-CREATE confirm
F-OPEN confirm
F-END-GROUP confirm
F-INITIALIZE request
FTM_INITIALIZE_REQ_
F-INITIALIZE confirm
FTM_INITIALIZE_CNF_
F-LOCATE request
FTM_LOCATE_REQ_
F-LOCATE confirm
FTM_LOCATE_CNF_
F-OPEN request
FTM_OPEN_REQ_
F-OPEN confirm
FTM_OPEN_CNF_
F-P-ABORT indication
FTM_P_ABORT_IND_
F-READ request
FTM_READ_REQ_
F-READ-ATTRIB request
FTM_READ_ATTRIB_REQ_
F-READ-ATTRIB confirm
FTM_READ_ATTRIB_CNF_
F-SELECT request
FTM_SELECT_REQ_
F-SELECT confirm
FTM_SELECT_CNF_
F-TERMINATE request
FTM_TERMINATE_REQ_
F-TERMINATE confirm
FTM_TERMINATE_CNF_
F-TRANSFER-END request
FTM_TRANSFER_END_REQ_
F-TRANSFER-END confirm
FTM_TRANSFER_END_CNF_
F-U-ABORT request
FTM_U_ABORT_REQ_
F-U-ABORT indication
FTM_U_ABORT_IND_
F-WRITE request
FTM_WRITE_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -8
Running H/F 2
Running H/F 1
Supported Functions
The NonStop FTAM API provides parameters and defined values to allow your
program to request the supported functions outlined in the following subsections. If you
request an unsupported function in your application, the initiator returns an error. The
functional scope of your FTAM application depends on which FTAM functions are
supported both by the NonStop FTAM initiator and the remote responder with which
the local initiator is interoperating.
The following subsections identify the FTAM service classes, functional units, attribute
groups, attributes, and document types that the initiator supports—that is, that it can
encode in an outgoing protocol data unit (PDU). For a listing and explanation of these
FTAM concepts as specified by ISO, refer to the OSI/FTAM Programming Guide, or to
ISO 8571, Parts 2 and 3.
Service Classes
Table 3-2. Service Classes Supported by the NonStop FTAM Initiator
Service Class
Initiator Support
File transfer
X
File access
X
File management
X
File transfer and management
X
Unconstrained
Functional Units
Table 3-3. Functional Units Supported by the NonStop FTAM Initiator
Functional Unit
Initiator Support
Kernel
X
Read
X
Write
X
File access
X
Limited file management
X
Enhanced file management
X
Grouping
X
FADU locking
Recovery
Restart data transfer
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3 -9
Running H/F 2
Running H/F 1
Attribute Groups
Table 3-4. Attribute Groups Supported by the NonStop FTAM Initiator
Attribute Group
Initiator Support
Kernel
X
Storage
X
Security
X
Private
Attributes
Table 3-5 identifies the attributes that the initiator supports. The table is organized
according to the class of attribute (activity or file) and the supported attribute groups
described above. Activity attributes pertain only to activity during an ISO FTAM
association. File attributes are characteristics of a file in a file storage system.
Table 3-5. FTAM Attributes
Kernel Group
Storage Group
Security Group
Activity
Attributes
Active contents type
Current access
request
Current initiator
identity
Current location
Current processing
mode
Current calling
application entity
title
Current responding
application entity
title
Current account
Current access passwords
Active legal qualification
File
Attributes
Filename
Permitted actions
Contents type
Storage account
Date and time of creation
Date and time of last
modification
Date and time of last read
access
Date and time of last
attribute modification
Identity of creator
Identity of last
attribute modifier
File availability
Filesize
Future filesize
Access control
Legal qualifications
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3- 10
Running H/F 2
Running H/F 1
The initiator does not support the current concurrency control or current locking style or
the file attributes identity-of-last modifier and identity-of-last-reader activity attributes.
Also, because NonStop FTAM does not support the private attribute group, the privateuse attribute of that group is not supported and is not reflected in the above table.
Document Types
The initiator supports the following FTAM document types:
•
•
•
•
FTAM-1
FTAM-2
FTAM-3
NBS-9
Accessing Local Information
To access local files, your application programs communicate directly with the
Guardian file system. To transfer files to or from the local system, application programs
must manage local file access using Guardian file-system calls such as OPEN, READ,
WRITE, and CLOSE. Security is controlled by the NonStop operating system. The first
programming example in Appendix G, NonStop FTAM Programming Examples
illustrates how to use Guardian procedures in a NonStop FTAM application.
The NonStop FTAM procedures provide for the transfer of files in three different
directions. Typically, you transfer files from a local file system to a remote file system,
or from remote to local, as illustrated in the programming examples in the OSI/FTAM
Programming Guide. In addition, remote-to-remote file transfers are also possible, as
illustrated in the second programming example in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3- 11
Running H/F 2
Running H/F 1
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
3- 12
4
FTM Procedures
This section provides detailed reference material for each FTM procedure. It includes
the following topics:
Topic
Page
Files Provided by HP
4-1
Procedure Names
4-2
Procedure Calls and Parameters
4-2
FTAM Protocol Dependencies
4-7
Procedure Call Descriptions
4-9
Files Provided by HP
The external declarations for the current version of the FTM, APS, and MFM
procedures are provided in the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL
declarations) and $SYSTEM.SYSTEM.CEXTDECS (C declarations). For applications
coded in TAL, you must use the ?SOURCE directive for EXTDECS0 at the beginning of
the external procedures section of your program. For applications coded in C, you
must include CEXTDECS in your program before making any calls to the procedures.
The NonStop FTAM distribution subvolume ZOSIFTAM supplies three files containing
NonStop FTAM data declarations:
•
•
•
ZFTMTAL contains TAL declarations for NonStop FTAM data structures. You can
use the ?SOURCE directive to include these declarations in your TAL application
programs.
ZFTMC contains the C declarations for NonStop FTAM data structures. You can
use the #include directive to include them in C programs.
ZFTMDDL is the NonStop FTAM DDL source from which the ZFTMTAL and
ZFTMC declarations were produced.
The NonStop OSI/AS distribution subvolume ZOSIAPS supplies three files containing
OSI/AS data declarations:
•
•
•
ZAPSTAL contains TAL declarations for OSI/AS data structures used in
parameters of the procedure calls.
ZAPSC contains the C declarations for OSI/AS data structures used in parameters
to the procedure calls.
ZAPSDDL is the OSI/AS DDL source from which the ZAPSTAL and ZAPSC
declarations were produced.
For a detailed description of pertinent structures in ZAPSDDL and ZFTMDDL, see
Appendix A, DDL Definitions. For a description of all structures in ZAPSDDL, refer to
the OSI/AS Programming Manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -1
Procedure Names
FTM Procedures
Procedure Names
The names of all NonStop FTAM procedures start with the characters “FTM_.” The
FTM procedures fall into four major categories, identified by the last few characters in
the procedure name:
•
•
•
•
REQ procedures enable you to make requests to the service provider. An example
is FTM_INITIALIZE_REQ_, which requests initiation of an association with an
FTAM responder.
IND procedures enable you to retrieve indication data as a result of service
requests sent by a remote entity. An example is FTM_CANCEL_IND_, which
allows you to retrieve indication information on a responder request to cancel the
data-transfer regime.
RSP procedures enable you to respond to an incoming indication primitive. An
example is FTM_CANCEL_RSP_, which allows you to communicate the results of
actions taken in response to a responder’s request to cancel the data-transfer
regime.
CNF procedures enable you to retrieve confirm information as a result of
responses sent by a remote application entity. An example is
FTM_INITIALIZE_CNF_, which reads the parameters returned to the initiator from
a responder following an initialize request sent from the initiator to the responder.
The middle word or words of a procedure name further identify the functionality
provided by the procedure. For examples, see the brief descriptions of the
FTM_INITIALIZE_REQ_ and FTM_CANCEL_IND_ procedures presented above.
Procedure Calls and Parameters
The parameters, and the procedures in which they can or must, appear are listed in
Table 4-1 on page 4-3. The data type for each parameter is the same for all procedures
in which it is used and is described in more detail in Appendix A, DDL Definitions.
Parameters are categorized into three types: required, optional, and conditional.
For the required input parameters noted in Table 4-1 on page 4-3 and the procedure
descriptions that follow, your application must provide values. If your application does
not, the NonStop initiator will not perform the service.
For the optional input parameters, your application does not need to provide values.
However, this does not necessarily mean that no value is assigned to these
parameters. In some cases, the NonStop initiator provides default values for optional
parameters in the PDU it sends across the network to the remote responder. In other
cases, the NonStop FTAM initiator sends no value for a particular parameter, and the
remote FTAM responder is free to provide its own default values.
Output parameters are generally considered optional. However, several of the output
parameters described in this section (for example, state-result, action-result,
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -2
Procedure Calls and Parameters
FTM Procedures
and diagnostic) provide information critical to understanding the outcome of a
particular operation, and HP recommends that you allocate runtime data space for
these output parameters.
For conditional input parameters, your application must provide values only if a specific
condition is met.
Table 4-1. FTM Procedure Parameters and Associated Calls (page 1 of 5)
Parameter
Procedure Calls
Input
or
Output
accesscontext
FTM_READ_REQ_
accesspasswords
account
actionresult
Data Type
Parameter
Input
ZFTM-DDL-ACCESSCNTXT
Required
FTM_CREATE_REQ_
Input
ZFTM-DDL-ACCESSPASSWDS
Optional
FTM_FILE_OPEN_REQ_
Input
Optional
FTM_SELECT_REQ_
Input
Optional
FTM_CREATE_REQ_
Input
FTM_FILE_OPEN_REQ_
Input
Optional
FTM_INITIALIZE_REQ_
Input
Optional
FTM_SELECT_REQ_
Input
Optional
FTM_CANCEL_REQ_
Input
FTM_CANCEL_RSP_
Input
Optional
FTM_DATA_END_REQ_
Input
Optional
FTM_CANCEL_CNF_
Output
Optional
FTM_CANCEL_IND_
Output
Optional
FTM_CHANGE_ATTRIB_CNF_
Output
Optional
FTM_CHANGE_ATTRIB_REQ_
Output
Optional
FTM_CLOSE_CNF_
Output
Optional
FTM_CREATE_CNF_
Output
Optional
FTM_DATA_END_IND_
Output
Optional
FTM_DATA_END_REQ_
Input
Optional
FTM_DELETE_CNF_
Output
Optional
FTM_DESELECT_CNF_
Output
Optional
FTM_ERASE_CNF_
Output
Optional
FTM_FILE_CLOSE_CNF_
Output
Optional
FTM_FILE_OPEN_CNF_
Output
Optional
FTM_INITIALIZE_CNF_
Output
Optional
FTM_LOCATE_CNF_
Output
Optional
FTM_OPEN_CNF_
Output
Optional
FTM_P_ABORT_IND_
Output
Optional
ZAPS-DDL-CHAR32
INT(32)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -3
Optional
Required
Procedure Calls and Parameters
FTM Procedures
Table 4-1. FTM Procedure Parameters and Associated Calls (page 2 of 5)
Procedure Calls
Input
or
Output
FTM_READ_ATTRIB_CNF_
Output
Optional
FTM_SELECT_CNF_
Output
Optional
FTM_TRANSFER_END_CNF_
Output
Optional
FTM_U_ABORT_IND_
Output
Optional
FTM_U_ABORT_REQ_
Input
Optional
aplmgrname
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-FILENAME
Required
attribgroups
FTM_INITIALIZE_CNF_
Output
ZFTM-DDL-ATTRGROUPS
Optional
FTM_INITIALIZE_REQ_
Input
attribnames
FTM_READ_ATTRIB_REQ_
Input
ZFTM-DDL-ATTRNAMES
Required
buffersize
FTM_DATA_IND_
Input
INT(32)
Required
cepi
FTM_INITIALIZE_REQ_
Output
INT
Required
All other procedures
Input
FTM_CHANGE_ATTRIB_CNF_
Output
FTM_CHANGE_ATTRIB_REQ_
Input
FTM_DELETE_CNF_
Output
FTM_DESELECT_CNF_
Output
Optional
FTM_FILE_CLOSE_CNF_
Output
Optional
FTM_TERMINATE_CNF_
Output
Optional
FTM_FILE_OPEN_CNF_
Output
FTM_FILE_OPEN_REQ_
Input
Optional
FTM_OPEN_CNF_
Output
Optional
FTM_OPEN_REQ_
Input
Optional
FTM_INITIALIZE_CNF_
Output
FTM_INITIALIZE_REQ_
Input
createpassword
FTM_CREATE_REQ_
Input
ZAPS-DDL-CHAR32
Optional
deleteaction
FTM_FILE_CLOSE_REQ_
Input
INT(32)
Optional
diagnostic
FTM_CANCEL_REQ_
Input
ZFTM-DDLDIAGNOSTIC
Optional
FTM_CANCEL_RSP_
Input
Parameter
changeattrib
charging
contentstype
contentstype-list
Data Type
Parameter
Optional
Required
ZFTM-DDL-CHANGEATTR
Optional
Optional
ZFTM-DDL-CHARGING
ZFTM-DDL-CNTNTSTYPE
ZFTM-DDL-CNTNTSLIST
Optional
Optional
Optional
Optional
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -4
Optional
Procedure Calls and Parameters
FTM Procedures
Table 4-1. FTM Procedure Parameters and Associated Calls (page 3 of 5)
Procedure Calls
Input
or
Output
FTM_CANCEL_CNF_
Output
Optional
FTM_CANCEL_IND_
Output
Optional
FTM_CHANGE_ATTRIB_CNF_
Output
Optional
FTM_CHANGE_ATTRIB_REQ_
Output
Optional
FTM_CLOSE_CNF_
Output
Optional
FTM_CREATE_CNF_
Output
Optional
FTM_DATA_END_IND_
Output
Optional
FTM_DATA_END_REQ_
Input
Optional
FTM_DELETE_CNF_
Output
Optional
FTM_DESELECT_CNF_
Output
Optional
FTM_ERASE_CNF_
Output
Optional
FTM_FILE_CLOSE_CNF_
Output
FTM_FILE_OPEN_CNF_
Output
Optional
FTM_INITIALIZE_CNF_
Output
Optional
FTM_LOCATE_CNF_
Output
Optional
FTM_OPEN_CNF_
Output
Optional
FTM_P_ABORT_IND_
Output
Optional
FTM_READ_ATTRIB_CNF_
Output
Optional
FTM_SELECT_CNF_
Output
Optional
FTM_TRANSFER_END_CNF_
Output
Optional
FTM_U_ABORT_IND_
Output
Optional
FTM_U_ABORT_REQ_
Input
Optional
FTM_ERASE_REQ_
Input
FTM_LOCATE_REQ_
Input
Required
FTM_READ_REQ_
Input
Required
FTM_WRITE_REQ_
Input
Required
FTM_LOCATE_CNF_
Output
Optional
faduoperation
FTM_WRITE_REQ_
Input
INT(32)
Required
fileattrib
FTM_READ_ATTRIB_CNF_
Output
ZFTM-DDL-READ-ATTR
Optional
filename
FTM_FILE_OPEN_REQ_
Input
ZAPS-DDL-CHAR128
Required
FTM_SELECT_REQ_
Input
Required
FTM_FILE_OPEN_CNF_
Output
Optional
FTM_SELECT_CNF_
Output
Optional
Parameter
fadu-id
Data Type
ZFTM-DDLDIAGNOSTIC
ZFTM-DDL-FADU-ID
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -5
Parameter
Optional
Required
Procedure Calls and Parameters
FTM Procedures
Table 4-1. FTM Procedure Parameters and Associated Calls (page 4 of 5)
Parameter
Procedure Calls
Input
or
Output
filestatus
FTM_FILE_OPEN_REQ_
Input
INT(32)
Optional
filestorepassword
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-CHAR32
Optional
func-units
FTM_INITIALIZE_CNF_
Output
ZFTM-DDL-FUNCUNITS
Optional
FTM_INITIALIZE_REQ_
Input
FTM_CREATE_REQ_
Input
FTM_CREATE_CNF_
Output
FTM_FILE_OPEN_CNF_
Output
FTM_FILE_OPEN_REQ_
Input
initiatorid
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-CHAR32
Optional
local-aetitle
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-AE-TITLE
Optional
local-appl
FTM_INITIALIZE_CNF_
Output
ZAPS-DDL-APPL-ADDR
Optional
FTM_INITIALIZE_REQ_
Input
more-data
FTM_DATA_IND_
Output
INT(32)
Optional
nextposition
FTM_DATA_IND_
Output
INT(32)
Optional
override
FTM_CREATE_REQ_
Input
INT(32)
Optional
processmode
FTM_FILE_OPEN_REQ_
Input
ZFTM-DDL-PROCMODE
Optional
FTM_OPEN_REQ_
Input
remote-aetitle
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-AE-TITLE
Optional
remoteappl
FTM_INITIALIZE_REQ_
Input
ZAPS-DDL-APPL-ADDR
Required
requestedaccess
FTM_CREATE_REQ_
Input
ZFTM-DDLREQUESTED-ACCESS
Optional
FTM_FILE_OPEN_REQ_
Input
Optional
FTM_SELECT_REQ_
Input
Optional
responding
-ae-title
FTM_INITIALIZE_CNF_
Output
ZAPS-DDL-AE-TITLE
Optional
responding
-appl
FTM_INITIALIZE_CNF_
Output
ZAPS-DDL-APPL-ADDR
Optional
initialattrib
Data Type
Parameter
Optional
ZFTM-DDL-CREATEATTR
Required
Optional
ZFTM-DDL-CREATEATTR-GRP
Optional
Conditional
Optional
Optional
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -6
FTAM Protocol Dependencies
FTM Procedures
Table 4-1. FTM Procedure Parameters and Associated Calls (page 5 of 5)
Parameter
Procedure Calls
Input
or
Output
serviceclass
FTM_INITIALIZE_CNF_
Output
FTM_INITIALIZE_REQ_
Input
startposition
FTM_DATA_IND_
Input
INT(32)
Optional
stateresult
FTM_CREATE_CNF_
Output
INT(32)
Optional
FTM_FILE_OPEN_CNF_
Output
Optional
FTM_INITIALIZE_CNF_
Output
Optional
FTM_OPEN_CNF_
Output
Optional
FTM_SELECT_CNF_
Output
Optional
tag
All request and response
procedures
Input
INT(32)
Optional
threshold
FTM_BEGIN_GROUP_REQ_
Input
INT(32)
Required
wait-mode
FTM_INITIALIZE_REQ_
Input
INT
Optional
Data Type
Parameter
ZFTM-DDL-SERVICECLASS
Optional
Optional
Every FTAM procedure uses cepi, and all request procedures made in nowait mode
can optionally use tag. Most indication and confirm procedures can but do not have to
use the diagnostic and action-result parameters.
FTAM Protocol Dependencies
FTAM protocol requires that you call most FTM procedures only when the association
is within a particular FTAM regime. Table 4-2 summarizes these regime requirements
for calling the FTM procedures. The table does not reflect regime transitions caused by
the issuing of individual calls or the grouping of confirmed services. For example,
grouped procedures, such as FTM_FILE_OPEN_REQ_ and
FTM_FILE_CLOSE_REQ_, allow an association to move through several regimes at
the same time.
Table 4-2. FTM Procedure Regime Dependencies (page 1 of 3)
Regime Requirement
Procedure
Prior to Association Establishment
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Must be in FTAM regime
FTM_CREATE_CNF_
FTM_CREATE_REQ_
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -7
FTAM Protocol Dependencies
FTM Procedures
Table 4-2. FTM Procedure Regime Dependencies (page 2 of 3)
Regime Requirement
Procedure
FTM_SELECT_CNF_
FTM_SELECT_REQ_
FTM_TERMINATE_CNF_
FTM_TERMINATE_REQ_
Must be in file-selection regime
FTM_CHANGE_ATTRIB_CNF_
FTM_CHANGE_ATTRIB_REQ_
FTM_DELETE_REQ_
FTM_DESELECT_CNF_
FTM_DESELECT_REQ_
FTM_OPEN_CNF_
FTM_OPEN_REQ_
FTM_READ_ATTRIB_CNF_
FTM_READ_ATTRIB_REQ_
Must be in file-open regime
FTM_CLOSE_CNF_
FTM_CLOSE_REQ_
FTM_ERASE_CNF_
FTM_ERASE_REQ_
FTM_FILE_CLOSE_CNF_
FTM_FILE_CLOSE_REQ_
FTM_LOCATE_CNF_
FTM_LOCATE_REQ_
FTM_READ_REQ_
FTM_WRITE_REQ_
Must be in data-transfer regime
FTM_CANCEL_CNF_
FTM_CANCEL_IND_
FTM_CANCEL_REQ_
FTM_CANCEL_RSP_
FTM_DATA_END_IND_
FTM_DATA_END_REQ_
FTM_DATA_IND_
FTM_DATA_REQ_
FTM_TRANSFER_END_CNF_
FTM_TRANSFER_END_REQ_
Other
FTM_BEGIN_GROUP_REQ_ *
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -8
Procedure Call Descriptions
FTM Procedures
Table 4-2. FTM Procedure Regime Dependencies (page 3 of 3)
Regime Requirement
Procedure
FTM_END_GROUP_REQ_ *
FTM_P_ABORT_IND_ **
FTM_U_ABORT_IND_ **
FTM_U_ABORT_REQ_ **
*
Must be in the FTAM, file-selection, or file-open regime. In addition, there are further constraints based on
grouping. See the OSI/FTAM Programming Guide.
** Valid in any regime.
Procedure Call Descriptions
Figure 4-1 on page 4-10 shows the syntax notation used to describe procedure calls in
this manual. This notation gives the syntax for calling the procedures from TAL
programs. For information about calling procedures from C programs, refer to the
C/C++ Programmer’s Guide. Figure 4-1 on page 4-10, the remainder of this section
provides the syntax and semantics of all the FTM procedures.
The procedure descriptions are first organized alphabetically according to the middle
word or words identifying the main function of the procedure. For example, the
FTM_CANCEL _xxx procedures are described before the FTM_CREATE_xxx
procedures, and the FTM_FILE_CLOSE_xxx procedures, before the
FTM_FILE_OPEN_xxx procedures. A group of procedures with the same main
function are then arranged in the order in which an application would typically call
them: REQ procedures, CNF procedures, IND procedures, and RSP procedures. Only
for the cancel function does the FTAM API provide procedures from all four categories
of procedures; most of the FTAM API functions require only request and confirm
procedures.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -9
Procedure Call Descriptions
FTM Procedures
Figure 4-1. Sample FTM Procedure Call Description
1 FTM_BEGIN_GROUP_REQ_
2 This procedure allows you to request the start of a group of FTM procedures, which are then
processed and responded to as a group.
3
4
5
status := FTM_BEGIN_GROUP_REQ_ ( cepi
, threshold
, [ tag ] );
6
!I
!I
!I
status
return value
INT
indicates the outcome of the call . . .
7 cepi
8
input
INT:value
9
is the connection endpoint identifier (CEPI) . . .
...
10 Considerations
...
11 Errors
...
12 Examples
...
VST0401.vsd
Legend
1
Procedure call name.
2
Description of procedure function.
Items 3 through 6 illustrate the syntax of the procedure, including all required and optional
parameters.
3
This indicates the type of value that the procedure returns. For the FTM
procedures, the variable type is always either “status” or “error.” HP notation for the
variable is either status or error. Possible ZAPS-VAL-STATUS-xxx values for
status are listed in Table B-1 on page B-2; possible ZAPS-ERR-xxx and
ZFTM-ERR-xxx error values are listed in Table B-2 on page B-4 and Table B-5
on page B-19.
4
This is the name of the procedure. It must appear in your program exactly as
shown, including the underscore characters. In C programming, all letters in the
name must be in uppercase.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 10
Procedure Call Descriptions
FTM Procedures
5
You must enclose the list of parameters in parentheses. Use commas to separate
multiple parameters. In the notation, optional parameters are enclosed in square
brackets ( [ and ] ); these brackets must not appear in the program. If you omit
optional parameters, a placeholder comma ( , ) must be present for each omitted
parameter, except for parameters omitted from the end of the list.
6
The exclamation point indicates that a comment follows. The comment is either I
or O (or both), indicating that the parameter is either an input (I) or an output (O)
parameter (or both). Input parameters are those passing data to the called
procedure; output parameters are those that return data to the calling program.
Input-and-output parameters both pass data to the called procedure and return data
to the program.
7
This line indicates whether the parameter is an input or an output parameter (or
both).
8
This line indicates the parameter type, which begins with one of the following:
INT
integer (one word)
INT(32)
doubleword integer (two words)
STRING
character string (one or more bytes)
Next, the following notation can appear:
.EXT
means that the parameter is a reference parameter accessed
by an extended pointer.
For all parameters except returned values, the parameter
type (and .EXT, if present) is followed by a colon. Additional
information after the colon includes:
9
value
means that the actual value or contents of the parameter are
passed.
ref:1
means that this is a reference parameter; that is, the address
of the parameter is passed. (The statements within the
program body must access the actual parameter contents
indirectly through the parameter location.) 1 indicates that
the parameter contains one element.
ref:( ddlname)
means that this is a reference parameter and that the
information contained at this address is accessed according
to the data type ddlname. For more information on data
types and structures, refer to Appendix A, DDL Definitions.
ref:*
means that this is a reference parameter; the number of
elements returned varies according to the number of
elements requested.
This line describes the information passed or returned in the parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 11
FTM Procedures
Procedure Call Descriptions
10
Considerations for using the procedure, including what to do in the case of specific
abnormalities, are presented in this subsection.
11
FTAM initiator errors related to this procedure call are listed in a table in this
subsection. Any of these or other errors with particular significance for the
procedure call are described after the table. Error descriptions include specifics
about the subcodes associated with a particular error, as well as original error
codes and subcodes and the reasons that they are returned (using
APS_STATUS_).
12
References to the lines in which procedure calls appear in the programming
examples in Appendix G, NonStop FTAM Programming Examples, or program
segments illustrating the use of the procedure call are presented in this subsection.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 12
FTM_BEGIN_GROUP_REQ_
FTM Procedures
FTM_BEGIN_GROUP_REQ_
This procedure allows you to request the start of a group of FTM procedures, which
are then processed and responded to as a group.
status := FTM_BEGIN_GROUP_REQ_ ( cepi
, threshold
, [ tag ] );
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
status values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
threshold
input
INT(32):value
specifies how many primitives (not including begin-group and end-group) within a
grouped service must succeed before the group can be considered successful. A
primitive is categorized as successful or unsuccessful on the basis of its
state-result parameter. Success occurs when a primitive returns a
state-result value other than ZFTM-VAL-STATE-FAILURE. Primitives that
have no state-result parameter are considered successful for the purposes of
the threshold count.
If the threshold parameter is set to the total number of primitives in the group,
the primitives in the group succeed or fail as a group; when a single primitive fails,
the entire group fails. If a grouped request fails, no change in state occurs, and the
association remains in the regime in which it was when you initiated the grouped
request.
For transfer service class, management service class, or transfer-andmanagement service class, you must set threshold to the total number of
required and optional primitives you plan for the group. This limitation on the
threshold value does not apply to the file-access service class, for which greater
flexibility is provided. For the file-access service class, you can set the threshold
parameter to a value less than the total number of required and optional primitives
to include in the group.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 13
FTM_BEGIN_GROUP_REQ_
FTM Procedures
threshold is a required parameter.
For additional information on setting the threshold value, see the OSI/FTAM
Programming Guide.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag parameter value, allowing your application to match the
completion with the correct instance of the procedure call. For details on the use of
the tag parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
Before calling FTM_BEGIN_GROUP_REQ_, you must have negotiated the
grouping functional unit on the FTM_INITIALIZE_REQ_ call.
Because no values are returned in the F-BEGIN-GROUP response, no confirm
procedure is needed to retrieve data. You must, however, verify the success of the
F-BEGIN-GROUP primitive by calling APS_STATUS_ and determining that the
begin-group confirm has been received. If the value of the event-code parameter
is ZFTM-VAL-EVT-BEGINGROUP-CNF, the begin group confirm has been
received.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation
when you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-3. Possible FTAM Initiator Errors for the FTM_BEGIN_GROUP_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 14
FTM_BEGIN_GROUP_REQ_
FTM Procedures
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_BEGIN_GROUP_REQ_ procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in a
state in which a grouped
request is allowed. Grouped
requests are allowed only in
selected regimes,
depending on the service
class. For example, in the
file-transfer service class,
grouped requests are
allowed only in the FTAM
regime and file-open
regimes. For more
information on FTAM
protocol, see the OSI/FTAM
Programming Guide.
Error Code:
Error Subcode:
ZFTM-ERR-FU-NOT-NEGOTIATED (-6002)
ZFTM-ERR-FU-GROUPING (-6)
The grouping functional unit
was not negotiated. The
grouping functional unit
must be negotiated for this
procedure to be valid.
Examples
Examples of the FTM_BEGIN_GROUP_REQ_ call in a program begin on line 803 in
the C version and line 900 of the TAL version of Example 2 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 15
FTM_CANCEL_REQ_
FTM Procedures
FTM_CANCEL_REQ_
This procedure allows you to request cancellation of the data-transfer regime. If
cancellation is successful, the results of any interrupted read or write operations are
unknown and the data-transfer regime ends. The association moves to the file-open
regime upon successful completion of the cancellation request. For a description of
these regimes, see the OSI/FTAM Programming Guide.
status := FTM_CANCEL_REQ_ (
,
,
,
cepi
[ action-result ]
[ diagnostic ]
[ tag ] );
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
input
INT(32):value
allows you to summarize the type of information contained in the diagnostic
parameter. The action-result value is never less severe than the most severe
diagnostic value. The following are the valid values:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
action-result is an optional parameter. If you do not supply this parameter, it
defaults to ZFTM-VAL-ACTION-SUCCESS, indicating that the diagnostic
parameter contains only informative diagnostic information.
diagnostic
input
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
allows you to provide user information that explains the reason for termination of
activities. For a complete list of possible diagnostic values, see Appendix C, ISO
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 16
FTM_CANCEL_REQ_
FTM Procedures
FTAM Diagnostic Messages. For more information on application-generated
diagnostic messages, see the OSI/FTAM Programming Guide.
diagnostic is an optional parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
To successfully complete this procedure call, you must have negotiated any
service class other than the file-management service class, as well as the read or
write functional unit, on the FTM_INITIALIZE_REQ_ call.
To complete this procedure call successfully, the association must be in the
data-transfer regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-4. Possible FTAM Initiator Errors for the FTM_CANCEL_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 17
FTM_CANCEL_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_CANCEL_REQ_
procedure call.
These error values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is
not in the datatransfer regime.
Examples
Examples of the FTM_CANCEL_REQ_ call in a program begin on line 1231 of the C
version and line 1324 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 18
FTM_CANCEL_CNF_
FTM Procedures
FTM_CANCEL_CNF_
This procedure allows you to retrieve the responder’s response to your
FTM_CANCEL_REQ_ procedure call to cancel the data-transfer regime. For a
description of the data-transfer regime, see the OSI/FTAM Programming Guide.
error := FTM_CANCEL_CNF_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the cancel-request
operation was successful. Even for a successful operation, the diagnostic
parameter might include one or more informative messages. A value of
ZFTM-VAL-ACTION-FAILURE indicates that the operation was not successful, and
diagnostic is likely to contain one or more diagnostic messages.
action-result is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 19
FTM_CANCEL_CNF_
FTM Procedures
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
data-transfer regime.
Before calling FTM_CANCEL_CNF_, you must call the following procedures:
FTM_CANCEL_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CANCEL- CNF event before calling FTM_CANCEL_CNF_.
•
•
Results of the data-transfer regime are not known.
Receipt of the ZFTM-VAL-EVT-CANCEL-CNF event returns the association to the
file-open regime. The application can either call the read or write operation in
progress at the time of the cancel, or close and deselect the file previously
selected and opened for the transfer and terminate the association.
Errors
Table 4-5. Possible FTAM Initiator Errors for the FTM_CANCEL_CNF_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_CANCEL_CNF_ call in a program begin on line 1239 of the C
version and line 1331 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 20
FTM_CANCEL_IND_
FTM Procedures
FTM_CANCEL_IND_
This procedure allows you to retrieve indication information on a responder request
to cancel the data-transfer regime. The association is returned to the file-open
regime. For a description of these regimes, see the OSI/FTAM Programming Guide.
error := FTM_CANCEL_IND_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
Even for a successful operation, the diagnostic parameter might include one or
more informative messages. A value of ZFTM-VAL-ACTION-FAILURE indicates
that the operation was not successful, and diagnostic is likely to contain one or
more permanent diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 21
FTM_CANCEL_IND_
FTM Procedures
diagnostic is an optional parameter.
Considerations
•
•
•
To complete this procedure call successfully, the association must be in the
data-transfer regime.
You must call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CANCEL-IND event before calling FTM_CANCEL_IND_.
You should call the FTM_CANCEL_RSP_ call after the FTM_CANCEL_IND_
procedure. Once you successfully call FTM_CANCEL_RSP_, the results of any
interrupted read or write operations will be unknown, and the data-transfer regime
will be terminated.
Errors
Table 4-6. Possible FTAM Initiator Errors for the FTM_CANCEL_IND_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B,
NonStop FTAM Initiator Error Messages.
Examples
Examples of the FTM_CANCEL_IND_ call in a program begin on line 824 of the C
version and line 1324 of the TAL version of Example 1 and on line 1221 of the C
version and line 1314 of the TAL version of Example 2 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 22
FTM_CANCEL_RSP_
FTM Procedures
FTM_CANCEL_RSP_
This procedure allows you to communicate the results of actions taken in response
to the responder’s request to cancel the data-transfer regime. For a description of
the data-transfer regime, see the OSI/FTAM Programming Guide.
status := FTM_CANCEL_RSP_ (
,
,
,
cepi
[ action-result ]
[ diagnostic ]
[ tag ] );
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
input
INT(32):value
allows you to provide information on the success of the remote responder’s cancel
request. The action-result value is never less severe than the most severe
diagnostic value. These are the valid values:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
action-result is an optional parameter. If you do not supply this parameter, it
defaults to ZFTM-VAL-ACTION-SUCCESS.
diagnostic
input
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
allows you to provide further information on the results of actions taken to cancel
the data-transfer regime. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages. For more information on
application-generated diagnostic messages, see the OSI/FTAM Programming
Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 23
FTM_CANCEL_RSP_
FTM Procedures
diagnostic is an optional parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, you must have negotiated, via the
FTM_INITIALIZE_REQ_ call, any service class other than the file-management
service class, as well as the read or write functional unit. The association must also
be in the data-transfer regime.
Before calling FTM_CANCEL_RSP_, you must call the following procedures:
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CANCEL_IND_
You call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CANCEL-IND event before calling FTM_CANCEL_IND_.
FTM_CANCEL_IND_ retrieves the indication information on the responder request
to cancel the data-transfer regime.
•
•
•
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Results of the data-transfer regime are not known.
Once the FTM_CANCEL_RSP_ call is successfully completed, the association
returns to the file-open regime.
Errors
Table 4-7. Possible FTAM Initiator Errors for the FTM_CANCEL_RSP_
Procedure (page 1 of 2)
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 24
FTM_CANCEL_RSP_
FTM Procedures
Table 4-7. Possible FTAM Initiator Errors for the FTM_CANCEL_RSP_
Procedure (page 2 of 2)
Error Code
FTAM Initiator Error
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_CANCEL_RSP_
procedure call.
These error values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
An F-CANCEL
indication was not
received on the
association. The
association must
have previously
received the ZFTMVAL-EVT-CANCELIND event before
calling this
procedure.
Examples
Examples of the FTM_CANCEL_RSP_ call in a program begin on line 833 of the C
version and line 1335 of the TAL version of Example 1 and on line 1227 of the C
version and line 1320 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 25
FTM_CHANGE_ATTRIB_REQ_
FTM Procedures
FTM_CHANGE_ATTRIB_REQ_
This procedure allows you to request changes to the file attributes of the file previously
selected.
status := FTM_CHANGE_ATTRIB_REQ_ ( cepi
, change-attrib
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
change-attrib
input
INT .EXT:ref:(ZFTM-DDL-CHANGE-ATTR)
contains the file attributes to be changed and the new values for the attributes.
change-attrib is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
Before calling this procedure, you must have negotiated the enhanced-filemanagement functional unit and the appropriate attribute groups on the
FTM_INITIALIZE_REQ_ call. You must also have set the ZCHNGATTR field of the
requested-access parameter of the select request to ON.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 26
FTM_CHANGE_ATTRIB_REQ_
FTM Procedures
•
•
•
To complete this procedure call successfully, the association must be in the
file-selection regime.
For the remote responder to respond affirmatively to the change-attribute primitive,
the change-attribute field of the permitted-actions attribute of this file must be set to
ON.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-8. Possible FTAM Initiator Errors for the FTM_CHANGE_ATTRIB_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6004
ZFTM-ERR-ACCESS-NOT-AVAIL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6024
ZFTM-ERR-ATTR-GRP-NOT-NEG
- 6025
ZFTM-ERR-PRIVATE-USE-NOT-SUPP
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_CHANGE_ATTRIB_REQ_ procedure call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 27
FTM_CHANGE_ATTRIB_REQ_
FTM Procedures
.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-selection regime.
Error Code:
Error Subcode:
ZFTM-ERR-FU-NOT-NEGOTIATED (-6002)
ZFTM-ERR-FU-ENHANCED-MGMT (-5)
The enhanced-filemanagement functional
unit must be negotiated for
this procedure call to be
valid.
Error Code:
Error Subcode:
ZFTM-ERR-ACCESS-NOT-AVAIL (-6004)
ZFTM-ERR-ACCESS-CHNG-ATTR (-7)
The requested-access
parameter on the previous
FTM_CREATE_REQ_ or
FTM_SELECT_REQ_ call
for this association did not
have the ZCHNGATTR
field set to ZAPSVAL-TRUE. You must
request change attribute
access when selecting the
file.
Error Code:
ZFTM-ERR-ATTR-GRP-NOT-NEG (-6024)
You attempted to change
an attribute that is in an
attribute group that was
not negotiated.
Examples
Examples of the FTM_CHANGE_ATTRIB_REQ_ call in a program begin on line 1351
of the C version and line 1441 of the TAL version of Example 2 in Appendix G,
NonStop FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 28
FTM_CHANGE_ATTRIB_CNF_
FTM Procedures
FTM_CHANGE_ATTRIB_CNF_
This procedure allows you to retrieve the remote responder’s response to the
application’s request to change file attributes of the previously selected file.
error := FTM_CHANGE_ATTRIB_CNF_ (
,
,
,
error
cepi
[ action-result ]
[ change-attrib ]
[ diagnostic ] ) ;
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
change-attrib
output
INT .EXT:ref:(ZFTM-DDL-CHANGE-ATTR)
contains the new values for the file attributes that were changed by the remote
responder. The initiator limits the length of several of the file attributes and
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 29
FTM_CHANGE_ATTRIB_CNF_
FTM Procedures
shortens any attribute value that exceeds these limits. Therefore, when the
responder returns a value for an access-control password that is greater than 32
characters, the initiator passes only the first 32 characters to the application, or in
the case of a filename attribute, when the value is greater than 128, the initiator
passes only the first 128 characters to the application.
change-attrib is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
file-selection regime.
Before calling this procedure, you must call the following procedures:
FTM_CHANGE_ATTRIB_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CHANGEATTR- CNF event before calling
FTM_CHANGE_ATTRIB_CNF_.
Errors
Table 4-9. Possible FTAM Initiator Errors for the FTM_CHANGE_ATTRIB_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 30
FTM_CHANGE_ATTRIB_CNF_
FTM Procedures
Examples
Examples of the FTM_CHANGE_ATTRIB_CNF_ call in a program begin on line 1384
of the C version and line 1472 of the TAL version of Example 2 in Appendix G,
NonStop FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 31
FTM_CLOSE_REQ_
FTM Procedures
FTM_CLOSE_REQ_
This procedure allows you to request closure of the previously opened file. It also
terminates the file-open regime. Successful completion of the close request moves the
association to the file-selection regime. For a description of these regimes, see the
OSI/FTAM Programming Guide.
status := FTM_CLOSE_REQ_ ( cepi
, [ tag ] ) ;
status
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
file-open regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 32
FTM_CLOSE_REQ_
FTM Procedures
Errors
Table 4-10. Possible FTAM Initiator Errors for the FTM_CLOSE_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_CLOSE_REQ_
procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-selection regime.
Examples
Examples of the FTM_CLOSE_REQ_ call in a program begin on line 1348 of the C
version and line 1438 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 33
FTM_CLOSE_CNF_
FTM Procedures
FTM_CLOSE_CNF_
This procedure allows you to retrieve the remote responder’s response to the
application’s request to close the previously opened file.
error := FTM_CLOSE_CNF_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 34
FTM_CLOSE_CNF_
FTM Procedures
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the fileopen regime.
Before calling FTM_CLOSE_CNF_, you must call the following procedures:
FTM_CLOSE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CLOSE- CNF event before calling FTM_CLOSE_CNF_.
•
The association returns to the file-selection regime when the application receives
the ZFTM-VAL-EVT-CLOSE-CNF event and the value of the action-result
parameter is ZFTM-VAL-ACTION-SUCCESS.
Errors
Table 4-11. Possible FTAM Initiator Errors for the FTM_CLOSE_CNF_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_CLOSE_CNF_ call in a program begin on line 1375 of the C
version and line 1464 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 35
FTM_CREATE_REQ_
FTM Procedures
FTM_CREATE_REQ_
This procedure allows you to request creation and selection of a file in the file storage
system with which an association has been established. Successful completion of this
procedure initiates the file-selection regime. For a description of the file-selection
regime, see the OSI/FTAM Programming Guide.
status := FTM_CREATE_REQ_ (
,
,
,
,
,
,
,
cepi
initial-attrib
[ override ]
[ create-password ]
[ requested-access ]
[ access-passwords ]
[ account ]
[ tag ] );
status
!
!
!
!
!
!
!
!
I
I
I
I
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
initial-attrib
input
INT .EXT:ref:(ZFTM-DDL-CREATE-ATTR)
defines the file attributes associated with the created file. For an attribute to be
defined at file creation, you must have negotiated the appropriate attribute group
on the FTM_INITIALIZE_REQ_ call.
initial-attrib is a required parameter. You must specify at least the filename
attribute and the document type component of the contents-type attribute in this
parameter.
override
input
INT(32):value
specifies the action to be taken if the named file already exists. Valid values are
defined below. The default override value is ZFTM-VAL-OVR-CREATE-FAIL.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 36
FTM_CREATE_REQ_
FTM Procedures
Value Name and Code
If file does not exist...
If file exists...
ZFTM-VAL-OVR-CREATE-FAIL (0)
New file is created.
Call fails.
ZFTM-VAL-OVR-SELECT-OLD (1)
New file is created.
File is selected (the
F-CREATE primitive
is not called).
ZFTM-VAL-OVR-CREATE-OLD (2)
New file is created.
File is deleted, and
a new file having the
same file attributes
as the old file is
created.
ZFTM-VAL-OVR-CREATE-NEW (3)
New file is created.
File is deleted, and
a new file is created
using the file
attributes specified
in the initialattrib parameter.
override is an optional parameter.
create-password
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
is an optional parameter that can be used to verify that the user identified by the
initiator ID has permission to create files.
create-password is an optional parameter. If you do not supply
create-password, no password is sent to the remote responder.
requested-access
input
INT .EXT:ref:(ZFTM-DDL-REQUESTED-ACCESS)
following the file creation, this parameter specifies the level of access to the file
you are requesting. The requested access does not need to reflect full file-action
capabilities as specified in the permitted-actions field of the initial-attrib
parameter, but it must be a subset of these capabilities. If the
requested-access parameter is incompatible with the newly created file, the file
selection will fail, although the file was created.
The requested-access 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 requested-access include:
Field Name
Task Associated With Access
Default Value
ZREAD
Read the file.
TRUE
ZINSERT
Insert information into the file.
FALSE
ZREPLACE
Replace some or all the contents of the file.
FALSE
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 37
FTM_CREATE_REQ_
FTM Procedures
ZEXTEND
Extend the file.
FALSE
ZERASE
Erase some or all the contents of the file.
FALSE
ZREADATTR
Read the attributes of the file.
TRUE
ZCHNGATTR
Change the attributes of the file.
FALSE
ZDELETE
Delete the file.
FALSE
requested-access is an optional parameter.
access-passwords
input
INT .EXT:ref:(ZFTM-DDL-ACCESS-PASSWDS) authenticates the actions
requested in the requested-access parameter. To use this parameter, you must
have selected the security group on the FTM_INITIALIZE_REQ_ call. The remote
responder will reject the subsequent file selection if the access passwords for the
requested actions do not match the responder’s access passwords.
access-passwords is an optional parameter. If you do not supply
access-passwords, no passwords are sent to the remote responder.
account
input
INT .EXT:ref:(ZAPS-DDL-CHAR32) identifies the account to be charged for costs
that are incurred during the file-selection regime.
account is an optional parameter. If you omit account, no account name will be
supplied to the remote responder.
Some responders require an account name. For information on responder
requirements for the account name, refer to the responder documentation.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
Before calling FTM_CREATE_REQ_, you must have negotiated the
limited-file-management functional unit. A parameter value of ZFTM-VALCNTNTSTYPE-UNKNOWN is allowed for the contents type specified in intialattrib. Maximum-string-length must be in the range of 1 through 7148.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 38
FTM_CREATE_REQ_
FTM Procedures
•
•
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
For any file attribute the remote responder requires and you do not specify in the
initial-attrib parameter, the responder will supply a value that is appropriate
for its file storage system.
Errors
Table 4-12. Possible FTAM Initiator Errors for the FTM_CREATE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6003
ZFTM-ERR-ACCESS-INCNSTNT
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 39
FTM_CREATE_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_CREATE_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the FTAM regime.
Error Code:
Error Subcode:
ZFTM-ERR-FU-NOT-NEGOTIATED (-6002)
ZFTM-ERR-FU-LMTD-MGMT (-5)
The limited-filemanagement functional
unit must be negotiated
for this procedure call to
be valid.
Error Code:
ZFTM-ERR-ACCESS-INCNSTNT (-6003)
The requestedaccess parameter
values are inconsistent
with the negotiated
functional units or
inconsistent with the
contents-type of the
document being created.
The error subcode
shows which file access
capability was
inconsistent.
Error Code:
Error Subcode:
ZAPS-ERR-PARAM-RANGE (-138)
ZFTM-ERR-MAX-STRING-LEN (155)
The maximum-stringlength parameter
specified as part of the
contents-type
parameter was too large.
The maximum value for
maximum-stringlength is 7148.
Examples
Examples of the FTM_CREATE_REQ_ call in a program begin on line 1033 of the C
version and line 1121 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 40
FTM_CREATE_CNF_
FTM Procedures
FTM_CREATE_CNF_
This procedure allows you to retrieve the remote responder’s response to the initiator
request to create and select a file in a file storage system with which an association
has been established.
error := FTM_CREATE_CNF_ (
,
,
,
,
cepi
[ state-result ]
[ action-result ]
[ initial-attrib ]
[ diagnostic ] ) ;
error
!
!
!
!
!
I
O
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
state-result
output
INT(32) . EXT:ref:1
indicates if the responder established the file-selection regime as requested. Valid
values are as follows:
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
state-result is an optional parameter.
action-result output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 41
FTM_CREATE_CNF_
FTM Procedures
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
initial-attrib
output
INT .EXT:ref:(ZFTM-DDL-CREATE-ATTR)
defines the file attributes associated with the created file. The remote responder
can respond that no value is available for a proposed attribute if it does not support
the attribute, except for the filename and permitted-actions attributes to which
values must be assigned. To these two attributes, the remote responder can assign
a different value from the one proposed by the initiator. For all other file attributes,
the remote responder must either accept the proposed value or respond that no
value is available. If the initiator proposes no value for this parameter, the remote
responder can supply its own default value for this parameter. The appropriate
attribute group must be negotiated on the FTM_INITIALIZE_REQ_ call for an
attribute to be defined at file creation.
If the application specified a value of ZFTM-VAL-OVR-CREATE-FAIL (0) or
ZFTM-VAL-OVR-CREATE-NEW (3) for the override parameter on the
FTM_CREATE_REQ_, the maximum-string-length value returned as part of
the contents-type attribute in this parameter must match the value proposed on the
FTM_CREATE_REQ_ call.
initial-attrib is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
Before calling FTM_CREATE_CNF_, you must call the following procedures:
FTM_CREATE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 42
FTM_CREATE_CNF_
FTM Procedures
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-CREATE-CNF event before calling FTM_CREATE_CNF_.
•
•
•
Initial attributes can vary from those requested. The responder might not fully
support all the attributes requested. In such a case, the responder will respond that
no value is available for those attributes not fully supported.
The association remains in the FTAM regime if state-result indicates a failure,
or moves to the file-selection regime if state-result indicates success.
The following regime transitions occur as a result of these different action results:
°
°
If the file creation fails, the association remains in the FTAM regime.
°
In the case of file selection only, where the value of the override parameter
of the FTM_CREATE_REQ_ procedure is ZFTM-VAL-OVR-SELECT-OLD, the
association moves to the file-selection regime.
°
If the file was created and selected, the association moves to the file-selection
regime.
If the file was created, but the selection of the file failed, the association returns
to the FTAM regime.
Errors
Table 4-13. Possible FTAM Initiator Errors for the FTM_CREATE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_CREATE_CNF_ call in a program begin on line 1063 of the C
version and line 1150 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 43
FTM_DATA_END_REQ_
FTM Procedures
FTM_DATA_END_REQ_
This procedure allows you to request an end to a block data transfer initiated by the
FTM_WRITE_REQ_ procedure.
status := FTM_DATA_END_REQ_ (
,
,
,
cepi
[ action-result ]
[ diagnostic ]
[ tag ] ) ;
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
input
INT(32):value
allows you to specify the result of the current data-transfer operation and
summarize information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
action-result is an optional parameter. If you do not supply this parameter, it
defaults to ZFTM-VAL-ACTION-SUCCESS.
diagnostic
input
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that explains the reason for termination of activities. For a
complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic
Messages. For more information on application-generated diagnostic messages,
see the OSI/FTAM Programming Guide.
diagnostic is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 44
FTM_DATA_END_REQ_
FTM Procedures
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
To complete this procedure call successfully, the association must be in the
data-transfer regime.
You must have previously called the FTM_WRITE_REQ_ procedure and optionally
made zero or more calls to FTM_DATA_REQ_.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-14. Possible FTAM Initiator Errors for the FTM_DATA_END_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6030
ZFTM-ERR-DATA-XFER-CANCELLED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_DATA_END_REQ_
procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in the
data-transfer regime.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 45
FTM_DATA_END_REQ_
FTM Procedures
Examples
Examples of the FTM_DATA_END_REQ_ call in a program begin on line 1293 of the C
version and line 1404 of the TAL version of Example 1, and on line 1204 of the C
version and line 1293 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 46
FTM_DATA_END_IND_
FTM Procedures
FTM_DATA_END_IND_
This procedure allows you to retrieve information on a responder request to end a
block data transfer initiated by the FTM_READ_REQ_ procedure.
error := FTM_DATA_END_IND_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 47
FTM_DATA_END_IND_
FTM Procedures
diagnostic is an optional parameter.
Considerations
•
•
•
•
To complete this procedure call successfully, the association must be in the datatransfer regime.
You must call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-DATAEND-IND event before calling FTM_DATA_END_IND_.
You must call FTM_TRANSFER_END_REQ_ after completion of the
FTM_DATA_END_IND_ procedure call.
An action-result value of ZFTM-VAL-ACTION-FAILURE might indicate that
the responder has rejected a read request you issued previously.
Errors
Table 4-15. Possible FTAM Initiator Errors for the FTM_DATA_END_IND_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_DATA_END_IND_ call in a program begin on line 1198 of the C
version and line 1287 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 48
FTM_DATA_REQ_
FTM Procedures
FTM_DATA_REQ_
This procedure allows you to transfer, or write, a block of data to a previously opened
file. The FTM_WRITE_REQ_ procedure must have been called to start the write
transfer before this procedure is called.
status := FTM_DATA_REQ_ ( cepi
, data-value
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
data-value
input
STRING .EXT:ref:*
contains the data to be sent to the remote responder. This parameter consists of a
data header followed by a series of one or more data elements. The maximum
allowable size of the data-value parameter of an FTM_DATA_REQ_ call is
24 KB. For details on calculating the size of data-value, see the OSI/FTAM
Programming Guide.
data-value is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 49
FTM_DATA_REQ_
FTM Procedures
Considerations
•
•
•
•
To complete this procedure call successfully, the association must be in the
data-transfer regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
The encoded PDU is limited to 16 KB. For more information on calculating the size
of the encoded PDU, see the OSI/FTAM Programming Guide.
The data-value parameter is identical for both the FTM_DATA_REQ_ and the
FTM_DATA_IND_ procedure calls. This parameter consists of a data header
followed by a series of one or more data elements. Each data element consists of
a data element header and the actual data.
Figure 4-2. Structure of the Data-Value Parameter
ZAPS-DDL-DATA-HDR
Data
Element
ZAPS-DDL-DATA-ELEMENT-HDR
Data
ZAPS-DDL-DATA-ELEMENT-HDR
Data
.
.
.
ZAPS-DDL-DATA-ELEMENT-HDR
Data
VST0402.vsd
ZAPS-DDL-DATA-HDR and ZAPS-DDL-DATA-ELEMENT-HDR are defined in the
file ZAPSDDL. The TAL and C equivalents are located in the files ZAPSTAL and
ZAPSC, respectively. For descriptions of both structures, see Appendix A, DDL
Definitions.
All structures begin on word boundaries. If the length of one of the data elements is
an odd number, you must end the data with a pad byte. For sample code
illustrating how to accommodate this requirement, see the OSI/FTAM
Programming Guide.
The structure of individual data elements specified in the data-value parameter
varies, depending on the contents type of the file being transferred. The valid
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 50
FTM_DATA_REQ_
FTM Procedures
values for the data element types (ZAPS-DDL-DATA-ELEMENT-HDR.ZTYPE) are
listed below with descriptions of their structures:
•
ZFTM-VAL-DE-FADU (ZFTM-DDL-DE-FADU)
Only FTAM-2 document types in the FA access context use this data element.
It is used to represent a structuring data element, which can be either a node
descriptor data element, an enter subtree data element, or an exit subtree data
element. Node descriptor data element is the only type used.
•
ZFTM-VAL-DE-TEXT
FTAM-1 and FTAM-2 document types use this data element. Each element will
be encoded as a string of characters. The character string provided will be
encoded as one of the following universal-classes:
PrintableString
(ASN.1 Universal-Class 19)
TeletexString
(ASN.1 Universal-Class 20)
VideotexString
(ASN.1 Universal-Class 21)
IA5String
(ASN.1 Universal-Class 22)
GraphicString
(ASN.1 Universal-Class 25)
VisibleString
(ASN.1 Universal-Class 26)
GeneralString
(ASN.1 Universal-Class 27)
depending on the contents-type activity attribute. To ensure interoperability,
NIST FTAM Phase 2 agreements recommend that elements be no more than
134 characters long.
The abstract syntax for this data element is { ISO standard 8571
abstract-syntax (2) unstructured-text (3) }.
For FTAM-1 and FTAM-2 document types, the interpretation of line breaks
within the text of the file depends on the character set used and on the
string-significance parameter, which is contained in the contents-type
attribute on the F-OPEN confirm. If the character set contains format effectors,
then end-of-line should be designated with those format effectors (carriage
return and line feed).
The string-significance parameter can be a value of variable, fixed, or
not-significant.
•
ZFTM-VAL-DE-BINARY
FTAM-3 document types use this data element. Each element consists of a
string of octets. To ensure interoperability, HP recommends that elements be
no more than 512 octets long.
The abstract syntax for this data element is { ISO standard 8571
abstract-syntax (2) unstructured-binary (4) }.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 51
FTM_DATA_REQ_
FTM Procedures
Errors
Table 4-16. Possible FTAM Initiator Errors for the FTM_DATA_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6010
ZFTM-ERR-INVALID-DATA
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6030
ZFTM-ERR-DATA-XFER-CANCELLED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_DATA_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in the
data-transfer regime.
Error Code:
ZFTM-ERR-INVALID-DATA (-6010)
The data-value
parameter is improperly
formatted or is invalid for
the contents type. For
additional information about
formatting the data-value
parameter, refer to the
OSI/FTAM Programming
Guide or to Appendix B,
NonStop FTAM Initiator
Error Messages, which
describes the relevant
subcodes for this error in
detail.
Examples
Examples of the FTM_DATA_REQ_ call in a program begin on line 1352 of the C
version and line 1460 of the TAL version of Example 1, and on line 1181 of the C
version and line 1265 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 52
FTM_DATA_IND_
FTM Procedures
FTM_DATA_IND_
This procedure allows you to receive, or read, a block of data from the previously
opened file involved in a data transfer.
error := FTM_DATA_IND_ (
,
,
,
,
,
cepi
buffer-size
data-value
[ more-data ]
[ next-position ]
[ start-position ] ) ;
error return
!
!
!
!
!
!
I
I
O
O
O
I
value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
buffer-size
input
INT(32) :value
specifies the size, in octets, of the buffer used for retrieving data-value. This is
the maximum number of octets that FTM_DATA_IND_ returns to the caller. If you
specify a value of 0 for this parameter and also for the start-position
parameter, the more-data parameter returns the number of octets to be read, and
the FTAM API copies no data into the data-value buffer.
buffer-size is a required parameter.
data-value
output
STRING .EXT:ref:*
contains the data returned from the remote responder. This parameter consists of a
data header followed by a series of one or more data elements.
The maximum allowable size of the data-value parameter of an
FTM_DATA_IND_ call is 25 KB. For details on calculating the size of data-value,
see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 53
FTM_DATA_IND_
FTM Procedures
For further details on the structure of data-value, see the OSI/FTAM
Programming Guide.
data-value is a required parameter.
more-data
output
INT(32) .EXT:ref:1
indicates that more data is available. The application should call FTM_DATA_IND_
again to obtain the remaining data. more-data specifies the size in bytes of the
remaining data including all necessary headers. A value of 0 indicates that no
more user data is remaining; a value other than 0 means that the buffer used for
retrieving the data-value parameter was too small to contain the entire data
indication.
more-data is an optional parameter.
next-position
output
INT(32) .EXT:ref:1
specifies the offset of the next octet to be returned from the FTAM internal data
area. The returned value is used as the start-position in a subsequent call to
FTM_DATA_IND_ to receive the next portion of user data starting after the last
returned byte.
next-position is an optional parameter.
start-position
input
INT(32):value
specifies the first data element to be returned by FTM_DATA_IND_. If you omit this
parameter, the value defaults to 0.
If you need to make multiple calls to the FTM_DATA_IND_ procedure to retrieve all
the data contained in the data indication, for the first FTM_DATA_IND_ call, the
start-position parameter must be set to 0. In subsequent calls, the parameter
must be set to the next-position value.
If only a single call to the FTM_DATA_IND_ procedure is needed to retrieve the
data contained in the indication, you do not need to set the start-position
parameter. In this case, the default of 0 is the correct value.
start-position is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 54
FTM_DATA_IND_
FTM Procedures
Considerations
•
•
•
To complete this procedure call successfully, you must have previously called the
FTM_READ_REQ_, and the association must be in the data-transfer regime.
You must call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data.
The size of the data-value buffer, which you specify via the buffer-size
parameter, must be large enough to contain ZAPS-DDL-DATA-HDR, ZAPS-DDLDATA-ELEMENT-HDR, and the current data element. The surest buffer size to use
is 25 KB because that size ensures that the application can retrieve the entire
FDATA indication in one call to the FTM_DATA_IND_ procedure. (An application
can call FTM_DATA_IND_ multiple times if the application’s data-value
parameter is too small to receive all available data in one call.)
However, for an application managing many associations, a buffer size of 25 KB
might consume too much of the application’s memory. If you wish to specify a
smaller buffer, bear in mind that the minimum buffer size is the sum of the length of
ZAPS-DDL-DATA-HDR, the length of ZAPS-DDL-DATA-ELEMENT-HDR, and the
value of the negotiated or default maximum-string-length parameter, which
will allow you to read a single data element and its headers.
•
•
•
If data is available (and buffer-size contains a valid nonzero value), the
minimum information returned in data-value includes the following:
°
°
°
ZAPS-DDL-DATA-HDR
ZAPS-DDL-DATA-ELEMENT-HDR
At least 1 octet of data.
To determine the size of the incoming data without actually retrieving the data, call
FTM_DATA_IND_ with buffer-size and start-position set to 0. The
more-data output parameter then returns the number of octets to be read.
The data-value parameter is identical for both the FTM_DATA_REQ_ and
FTM_DATA_IND_ procedure calls. This parameter consists of a data header
followed by a series of one or more data elements. Each data element consists of
a data element header and the actual data. Figure 4-2 on page 4-50 shows the
structure of data-value.
ZAPS-DDL-DATA-HDR and ZAPS-DDL-DATA-ELEMENT-HDR of the
data-value structure are defined in the file ZAPSDDL. The TAL and C
equivalents are located in the files ZAPSTAL and ZAPSC, respectively. For
descriptions of both structures, see Appendix A, DDL Definitions.
All structures are word addressed and must therefore begin on word boundaries. If
the length of one of the data elements is an odd number, the initiator inserts a pad
byte at the end of the data. For sample program code illustrating how to
accommodate pad bytes, see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 55
FTM_DATA_IND_
FTM Procedures
The structure of individual data elements specified in the data-value parameter
varies, depending on the contents type of the file being transferred. The valid
values for the data element types (ZAPS-DDL-DATA-ELEMENT-HDR.ZTYPE) are
listed below with descriptions of their structures:
°
ZFTM-VAL-DE-FADU (ZFTM-DDL-DE-FADU)
This data element is used only by FTAM-2 document types in the FA access
context. (For more information on document types and access–context types,
see the OSI/FTAM Programming Guide.) It is used to represent a structuring
data element, which can be either a node descriptor data element, an enter
subtree data element, or an exit subtree data element. Node descriptor data
element is the only type used.
°
ZFTM-VAL-DE-TEXT
This data element is used by FTAM-1 and FTAM-2 document types. Each
encoded character string from the responder is returned in a separate data
element.
°
ZFTM-VAL-DE-BINARY
This data element is used by document type FTAM-3. Each element consists
of a string of octets.
°
ZFTM-VAL-DE-DIRECTORY (ZFTM-DDL-READ-ATTR)
This data element is used by document type NBS-9. Each element consists of
the file-read attributes (ZFTM-DDL-READ-ATTR) of a directory entry. A
separate data element will exist for each file in the directory.
Errors
Table 4-17. Possible FTAM Initiator Errors for the FTM_DATA_IND_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
- 6037
ZFTM-ERR-DATA-VALUE-TOO-SMALL
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 56
FTM_DATA_IND_
FTM Procedures
The following table lists the common errors that can occur on the FTM_DATA_IND_
procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-DATA-VALUE-TOO-SMALL
(-6037)
Minimum number of bytes to retrieve at
least one data element and its
associated header information
The buffer-size
parameter is too small to
contain the data header, data
element header, and current
data element.
Reissue FTM_DATA_IND_
providing a larger value for
buffer-size. The
minimum buffer size must be
the sum of the length of
ZAPS-DDL-DATA-HDR, the
length of ZAPS-DDL-DATAELEMENT-HDR, and the
value of the negotiated
maximum-string-length
parameter.
Examples
Examples of the FTM_DATA_IND_ call in a program begin on line 1169 of the C
version and line 1256 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 57
FTM_DELETE_REQ_
FTM Procedures
FTM_DELETE_REQ_
This procedure allows you to request deletion of the currently selected file. The remote
responder’s successful response to this request primitive terminates the file-selection
regime and moves the association to the FTAM regime. For a description of these
regimes, see the OSI/FTAM Programming Guide.
status := FTM_DELETE_REQ_ ( cepi
, [ tag ] ) ;
status
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
To complete this procedure call successfully, the association must be in the
file-selection regime, and you must have set the ZDELETE field of the
requested-action parameter of the FTM_SELECT_REQ_ procedure call to
ON.
Before calling FTM_DELETE_REQ_, you must have negotiated the limited-filemanagement functional unit via the FTM_INITIALIZE_REQ_ call.
For the remote responder to respond affirmatively to this delete primitive, the
delete-file field of the permitted-actions attribute of this file must be set to ON.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 58
FTM_DELETE_REQ_
FTM Procedures
•
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-18. Possible FTAM Initiator Errors for the FTM_DELETE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6004
ZFTM-ERR-ACCESS-NOT-AVAIL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_DELETE_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in the
file-selection regime.
Error Code:
Error Subcode:
ZFTM-ERR-ACCESS-NOT-AVAIL (-6004)
ZFTM-ERR-ACCESS-DELETE (-8)
The requested-access
parameter on the previous
FTM_SELECT_REQ_ call
for this association did not
have the ZDELETE field set
to ZAPS-VAL-TRUE.
Examples
Examples of the FTM_DELETE_REQ_ call in a program begin on line 1438 of the C
version and line 1527 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 59
FTM_DELETE_CNF_
FTM Procedures
FTM_DELETE_CNF_
This procedure allows you to retrieve the responder’s response to the application’s
request to delete the currently selected file.
error := FTM_DELETE_CNF_ (
,
,
,
cepi
[ action-result ]
[ charging ]
[ diagnostic ] ) ;
error
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
charging
output
INT .EXT:ref:(ZFTM-DDL-CHARGING)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 60
FTM_DELETE_CNF_
FTM Procedures
conveys information on the costs attributed to the account during the regime being
released. The charging parameter is present only if you provided the account
parameter on the FTM_INITIALIZE_REQ_ call.
charging is a list of triples, each of which contains a resource identifier, a
charging unit, and a charge value. If the responder returns a resource identifier or
charging unit that is greater than 16 characters, the initiator passes only the first 16
characters to the application.
charging is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values.
diagnostic is an optional parameter, see Appendix C, ISO FTAM Diagnostic
Messages.
Considerations
•
•
To complete this procedure call successfully, the association must be in the fileselection regime.
Before calling FTM_DELETE_CNF_, you must call the following procedures:
FTM_DELETE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-DELETE-CNF event before calling FTM_DELETE_CNF_.
•
Receipt of the ZFTM-VAL-EVT-DELETE-CNF event and an action-result
value of ZFTM-VAL-ACTION-SUCCESS returns the association to the FTAM
regime.
Errors
Table 4-19. Possible FTAM Initiator Errors for the FTM_DELETE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 61
FTM_DELETE_CNF_
FTM Procedures
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_DELETE_CNF_ call in a program begin on line 1474 of the C
version and line 1562 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 62
FTM_DESELECT_REQ_
FTM Procedures
FTM_DESELECT_REQ_
This procedure allows you to request an end to access to the file that was previously
selected. Successful completion of this procedure terminates the file-selection regime
and moves the association to the FTAM regime. For a description of these regimes,
see the OSI/FTAM Programming Guide.
status := FTM_DESELECT_REQ_ ( cepi
, [ tag ] ) ;
status
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
file-selection regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 63
FTM_DESELECT_REQ_
FTM Procedures
Errors
Table 4-20. Possible FTAM Initiator Errors for the FTM_DESELECT_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_DESELECT_REQ_
procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in the
file-selection regime.
Examples
Examples of the FTM_DESELECT_REQ_ call in a program begin on line 1355 of the C
version and line 1445 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 64
FTM_DESELECT_CNF_
FTM Procedures
FTM_DESELECT_CNF_
This procedure allows you to retrieve the responder’s response to the application’s
request to end access to the file that was previously selected.
error := FTM_DESELECT_CNF_ (
,
,
,
cepi
[ action-result ]
[ charging ]
[ diagnostic ] ) ;
error
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
charging
output
INT .EXT:ref:(ZFTM-DDL-CHARGING)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 65
FTM_DESELECT_CNF_
FTM Procedures
conveys information on the costs attributed to the account in the regime being
released. The charging parameter is present only if you provided the account
parameter on the FTM_SELECT_REQ_ call.
charging is a list of triples, each of which contains a resource identifier, a
charging unit, and a charge value. If the responder returns a resource identifier or
charging unit that is greater than 16 characters, the initiator passes only the first 16
characters to the application.
charging is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
conveys either detailed information on the failure of a requested action or
information that qualifies a successful action. For a complete list of possible
diagnostic values, see Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
file-selection regime.
Before calling FTM_DESELECT_CNF_, you must call the following procedures:
FTM_DESELECT_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-DESELECT-CNF event before calling FTM_DESELECT_CNF_.
•
•
Receipt of the ZFTM-VAL-EVT-DESELECT-CNF event returns the association to
the FTAM regime.
The action-result parameter should always be successful. A failure indicates
a problem with the responder.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 66
FTM_DESELECT_CNF_
FTM Procedures
Errors
Table 4-21. Possible FTAM Initiator Errors for the FTM_DESELECT_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_DESELECT_CNF_ call in a program begin on line 1402 of the C
version and line 1490 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 67
FTM_END_GROUP_REQ_
FTM Procedures
FTM_END_GROUP_REQ_
This procedure allows you to signify the end of a group of FTAM requests.
error := FTM_END_GROUP_REQ_ ( cepi
, [ tag ] ) ;
error
! I
! I
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
To successfully complete this procedure call, you must have previously called
FTM_BEGIN_GROUP_REQ_.
Because no values are returned on the F-END-GROUP response, no confirm
procedure is needed to retrieve data. You must, however, verify the success of the
F-END-GROUP primitive by calling APS_STATUS_ and determining that the
end-group confirm has been received. If the value of the APS_STATUS_ eventcode parameter is ZFTM-VAL-EVT-ENDGROUP-CNF, the end-group confirm has
been received.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 68
FTM_END_GROUP_REQ_
FTM Procedures
Errors
Table 4-22. Possible FTAM Initiator Errors for the FTM_END_GROUP_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_END_GROUP_REQ_ procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
FTM_BEGIN_GROUP_REQ
_ was not previously
successfully called, or
FTM_END_GROUP_REQ_
has already been
successfully called. This call
is valid only if the
FTM_BEGIN_GROUP_REQ
_ was successful and no
intervening
FTM_END_GROUP_REQ_
has already terminated the
group.
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-BAD-GROUP (3)
The preceding group is not
one of the five valid groups
defined by FTAM. For a
description of valid groups,
refer to the OSI/FTAM
Programming Guide.
Examples
Examples of the FTM_END_GROUP_REQ_ call in a program begin on line 824 of the
C version and line 922 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 69
FTM_ERASE_REQ_
FTM Procedures
FTM_ERASE_REQ_
This procedure allows you to request erasure of the contents of the specified
file-access data unit (FADU) in the previously selected and opened file.
status := FTM_ERASE_REQ_ ( cepi
, fadu-id
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
fadu-id
input
INT .EXT:ref:(ZFTM-DDL-FADU-ID)
specifies the target FADU for an operation. This value depends on the document
type of the file. Valid values are the following:
ZFTM-VAL-FADUID-FIRST for the ZFIRSTLAST field. This value specifies the
beginning of the first FADU after the root FADU and applies only to FTAM-1
and FTAM-3 document types.
ZFTM-VAL-FADUID-BEGIN for the ZBEGINEND field. This value specifies the
beginning of the root node and applies only to FTAM-2 document types.
fadu-id is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 70
FTM_ERASE_REQ_
FTM Procedures
tag is an optional parameter.
Considerations
•
•
•
•
Before using this procedure, you must have negotiated the file-access functional
unit and file-access service class on the FTM_INITIALIZE_REQ_ call.
To complete this procedure call successfully, the association must be in the fileopen regime, and you must have set the ZERASE field of the process-mode
parameter (ZFTM-DDL-PROC-MODE) of the open request to ON.
For the remote responder to respond affirmatively to this erase primitive, the erase
field of the permitted-actions attribute of this file must be set to ON.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Errors
Table 4-23. Possible FTAM Initiator Errors for the FTM_ERASE_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6006
ZFTM-ERR-FADU-ID-INVALID
- 6008
ZFTM-ERR-PROC-MODE-NOT-AVAIL
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 71
FTM_ERASE_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_ERASE_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-open regime.
Error Code:
ZFTM-ERR-FADU-ID-INVALID (-6006)
The FADU ID is
inconsistent with the
document type
requested when the file
was opened.
Error Code:
Error Subcode:
ZFTM-ERR-PROC-MODE-NOT-AVAIL (-6008)
ZFTM-ERR-PROC-MODE-ERASE (-5)
The erase action was
not specified in the
process-mode
parameter on the
previous
FTM_OPEN_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 72
FTM_ERASE_REQ_
FTM Procedures
Example
The following TAL program illustrates the use of the FTM_ERASE_REQ_ procedure
call:
1. !-----------------------------------------------------------------------!
2. ! This example demonstrates how to erase the contents of an FTAM-2
!
3. ! file. It assumes that the file has already been selected and
!
4. ! opened.
!
5. !
!
6. ! This example abends on all error conditions. Additional application-
!
7. ! specific error handling or recovery could be implemented if
!
8. ! required by an application.
!
9. !-----------------------------------------------------------------------!
10. LITERAL
WAIT_FOREVER = -1d;
! Timeout for event rcv. !
11. STRUCT .EXT diag ( ZFTM^DDL^DIAGNOSTIC^DEF ); ! FTAM diagnostics
!
12. STRUCT .EXT fadu_id ( ZFTM^DDL^FADU^ID^DEF ); ! FADU to be erased
!
13. INT(32) .EXT action_result;
! Result of erase req.
!
14. INT
cepi;
! Connection endpoint ID !
15. INT
status;
! APS status code
!
16. INT
event_code;
! OSI/FTAM event code
!
17. INT
error;
! APS or FTAM error code !
18. !----------------------------------------------------------------------!
19. ! Insert code to initialize APS, make FTAM association, and select and |
20. | open file.
|
21. !----------------------------------------------------------------------!
22. ! Specify the target FADU. For an FTAM-2 file, the FADU ID
!
23. ! for an erase request must be the "begin" FADU.
!
24. !----------------------------------------------------------------------!
25. fadu_id.zid := zftm^val^faduid^beginend;
26. fadu_id.zbeginend := zftm^val^faduid^begin;
27. !----------------------------------------------------------------------!
28. ! Call FTM_ERASE_REQ_ to erase the FADU from the file.
!
29. ! This will erase the entire file.
!
30. !----------------------------------------------------------------------!
31. status := FTM_ERASE_REQ_ ( cepi
32.
, fadu_id
33.
, ! tag ! );
34. IF ( status <> ZAPS^VAL^STATUS^OK ) THEN
35. BEGIN
36.
CALL ABEND;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 73
FTM_ERASE_REQ_
FTM Procedures
37. END;
38. !----------------------------------------------------------------------!
39. ! Call APS_EVENT_RECEIVE_ to receive the confirm for the erase service.!
40. !----------------------------------------------------------------------!
41. status := APS_EVENT_RECEIVE_ ( cepi, WAIT_FOREVER );
42. IF ( status <> ZAPS^VAL^STATUS^EVENT ) THEN
43. BEGIN
44.
CALL ABEND;
45. END;
46. !----------------------------------------------------------------------!
47. ! Call APS_STATUS_ to determine what event has been received. Verify
!
48. ! that the event is the erase confirm.
!
49. !----------------------------------------------------------------------!
50. error := APS_STATUS_ ( cepi, event_code );
51. IF ( error <> ZAPS^ERR^OK ) OR
52. ( event_code <> ZFTM^VAL^EVT^ERASE^CNF) THEN
53. BEGIN
54.
CALL ABEND;
55. END;
56. !----------------------------------------------------------------------!
57. ! Call FTM_ERASE_CNF_ to get the action result and diagnostics.
!
58. !----------------------------------------------------------------------!
59. error := FTM_ERASE_CNF_ ( cepi
60.
, action_result
61.
, diag );
62. IF ( error <> ZAPS^ERR^OK ) THEN
63. BEGIN
64.
CALL ABEND;
65. END;
66. IF ( action_result <> ZFTM^VAL^ACTION^SUCCESS ) THEN
67. BEGIN
68. !----------------------------------------------------------------------!
69. ! The erase request failed. The diagnostics can be examined if
!
70. ! more detailed diagnostic information is required by an application.
!
71. !----------------------------------------------------------------------!
72.
CALL ABEND;
73. END;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 74
FTM_ERASE_CNF_
FTM Procedures
FTM_ERASE_CNF_
This procedure allows you to retrieve the responder’s response to the application’s
request to erase the specified FADU of the previously selected and opened file.
error := FTM_ERASE_CNF_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 75
FTM_ERASE_CNF_
FTM Procedures
diagnostic is an optional parameter.
Considerations
•
•
To successfully complete this procedure call, the association must be in the
file-open regime.
Before calling FTM_ERASE_CNF_, you must call the following procedures:
FTM_ERASE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-ERASE-CNF event before calling FTM_ERASE_CNF_.
Errors
Table 4-24. Possible FTAM Initiator Errors for the FTM_ERASE_CNF_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Example
For an example of a TAL program illustrating the use of the FTM_ERASE_CNF_
procedure, see the Example on page 4-73 subsection in the FTM_ERASE_REQ_
procedure description.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 76
FTM_FILE_CLOSE_REQ_
FTM Procedures
FTM_FILE_CLOSE_REQ_
This grouped procedure issues the primitives F-BEGIN-GROUP, F-CLOSE, either
F-DESELECT or F-DELETE, and F-END-GROUP, allowing you to close and either
deselect or delete a file in a single call. Successful completion of this procedure
terminates the file-open and file-selection regimes and moves the association to the
FTAM regime. For a description of these regimes, see the OSI/FTAM Programming
Guide.
status := FTM_FILE_CLOSE_REQ_ ( cepi
, [ delete-action ]
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
delete-action
input
INT(32):VALUE
indicates whether the file should be deleted after the file is closed. Valid values are
the following:
ZFTM-VAL-CLOSE-NODELETE
ZFTM-VAL-CLOSE-DELETE
The default value for this parameter is ZFTM-VAL-CLOSE-NODELETE.
delete-action is an optional parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 77
FTM_FILE_CLOSE_REQ_
FTM Procedures
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
•
•
•
Before calling FTM_FILE_CLOSE_REQ_, you must have negotiated a service
class other than the file-management service class via the
FTM_INITIALIZE_REQ_ call.
You must also have negotiated the grouping functional unit and the read or write
functional unit.
To complete this procedure call successfully, the association must be in the
file-open regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
The FTM_FILE_CLOSE_REQ_ procedure call is valid only if the grouping
functional unit has been negotiated.
If the delete-action parameter is ZFTM-VAL-CLOSE-NODELETE, this call
results in the following grouped request:
F-BEGIN-GROUP
F-CLOSE
F-DESELECT
F-END-GROUP
If delete-action is ZFTM-VAL-CLOSE-DELETE, the FTM_FILE_OPEN_REQ_
call results in the following grouped request:
F-BEGIN-GROUP
F-CLOSE
F-DELETE
F-END-GROUP
•
The grouping threshold parameter is set to 2 for this grouped procedure. This
means that the entire call must either succeed or fail. If the call does not succeed,
the association remains in the same regime and state as before the call and the file
remains open.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 78
FTM_FILE_CLOSE_REQ_
FTM Procedures
Errors
Table 4-25. Possible FTAM Initiator Errors for the FTM_FILE_CLOSE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_FILE_CLOSE_REQ_ procedure call.
These error
values...
Error Code:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
The association is not in the
file-open regime.
Examples
Examples of the FTM_FILE_CLOSE_REQ_ call in a program begin on line 1200 of the
C version and line 1162 of the TAL version of Example 1 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 79
FTM_FILE_CLOSE_CNF_
FTM Procedures
FTM_FILE_CLOSE_CNF_
This procedure allows you to retrieve the remote responder’s response to the
application’s request to close and either deselect or delete a file.
error := FTM_FILE_CLOSE_CNF_ (
,
,
,
cepi
[ action-result ]
[ charging ]
[ diagnostic ] ) ;
error
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
charging
output
INT .EXT:ref:(ZFTM-DDL-CHARGING)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 80
FTM_FILE_CLOSE_CNF_
FTM Procedures
conveys information on the costs attributed to the account in the regime being
released. The charging parameter is present only if you provided the account
parameter on the FTM_INITIALIZE_REQ_ call.
charging is a list of triples, each of which contains a resource identifier, a
charging unit, and a charge value. If the responder returns a resource identifier or
charging unit that is greater than 16 characters, the initiator passes only the first 16
characters to the application.
charging is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, you must have previously called the
FTM_FILE_CLOSE_REQ_, and the association must be in the file-open regime.
Before calling FTM_FILE_CLOSE_CNF_, you must call the following procedures:
FTM_FILE_CLOSE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-FILECLOSE- CNF event before calling
FTM_FILE_CLOSE_CNF_.
•
•
Receipt of the ZFTM-VAL-EVT-FILECLOSE-CNF event returns the association to
the FTAM regime.
The diagnostic parameter contains a concatenation of diagnostic messages
returned by the remote responder in response to the FTAM primitives issued by the
FTM_FILE_CLOSE_REQ_ procedure.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 81
FTM_FILE_CLOSE_CNF_
FTM Procedures
Errors
Table 4-26. Possible FTAM Initiator Errors for the FTM_FILE_CLOSE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_FILE_CLOSE_CNF_ call in a program begin on line 1234 of the
C version and line 1197 of the TAL version of Example 1 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 82
FTM_FILE_OPEN_REQ_
FTM Procedures
FTM_FILE_OPEN_REQ_
This grouped procedure issues the primitives F-BEGIN-GROUP, F-SELECT or
F-CREATE, F-OPEN, and F-END-GROUP, allowing you to select or create a file and
then open it in a single procedure call. Successful completion of this procedure initiates
the file-selection and file-open regimes and leaves the association in the file-open
regime. For a description of these regimes, see the OSI/FTAM Programming Guide.
status := FTM_FILE_OPEN_REQ_ (
,
,
,
,
,
,
,
,
,
status
cepi
filename
[ requested-access ]
[ access-passwords ]
[ initial-attrib ]
[ create-password ]
[ process-mode ]
[ contents-type ]
[ account ]
[ tag ] ) ;
!
!
!
!
!
!
!
!
!
!
I
I
I
I
I
I
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
filename
input
INT .EXT:ref:(ZAPS-DDL-CHAR128)
is the name of the file to be selected. The name should uniquely identify the file,
according to the requirements of the remote system. You can specify a maximum
of 128 characters for the file name.
filename is a required parameter.
file-status
input
INT(32):value
indicates whether an existing file should be selected or a new file created, and if a
new file is created, what the file attributes should be. The meaning of all these
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 83
FTM_FILE_OPEN_REQ_
FTM Procedures
values except for ZFTM-VAL-FOPEN-OLD is the same as those defined for the
override parameter of the create request.
This table lists the valid values for this parameter and the corresponding actions
taken.
Value Name and Code
If File Does Not Exist...
If File Exists...
ZFTM-VAL-FOPEN-NEW (0)
New file is created.
Call fails.
ZFTM-VAL-FOPEN-UNKNOWN (1)
File is created using the
file attributes specified in
the initial-attrib
parameter.
File is selected.
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.
File is deleted, and a
new file is created
using the file
attributes specified in
the initialattrib parameter.
ZFTM-VAL-FOPEN-OLD (4)
Call fails.
File is selected (the
F-CREATE primitive
is not called).
file-status is an optional parameter. If you omit file-status, the default
value will be ZFTM-VAL-FOPEN-OLD.
requested-access
input
INT .EXT:ref:(ZFTM-DDL-REQUESTED-ACCESS)
specifies the level of access to the file you are requesting after the file is created.
The requested access can reflect any or all the file-action capabilities specified in
the permitted-actions field of the initial-attrib parameter, but no others. If
the requested-access parameter is incompatible with the newly created file, the
file is not created. The default access requested will be ZREAD and ZREADATTR.
requested-access is an optional parameter.
access-passwords
input
INT .EXT:ref:(ZFTM-DDL-ACCESS-PASSWDS)
authenticates the actions requested in the requested-access parameter. You
can specify a value for this parameter only if you negotiated the security group on
the FTM_INITIALIZE_REQ_ call. The remote responder will reject the file selection
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 84
FTM_FILE_OPEN_REQ_
FTM Procedures
if the access passwords for the requested actions do not match the responder’s
access passwords.
access-passwords is an optional parameter. If you do not supply
access-passwords, no passwords will be sent to the remote responder.
initial-attrib
input
INT .EXT:ref:(ZFTM-DDL-CREATE-ATTR-GRP)
defines the file attributes associated with the created file. The remote responder
can respond that no value is available for a proposed attribute if it does not support
the attribute, except for the filename and permitted-actions attributes to which
values must be assigned.
The only attributes to which the remote responder can assign a different value from
the one proposed by the initiator are filename and permitted-actions, for a create
operation, and permitted-actions only, for a select operation. For all other file
attributes, the remote responder must either accept the proposed value or respond
that no value is available. In the case of attributes to which the initiator does not
assign values in the initial-attrib parameter in the
FTM_FILE_OPEN_REQ_, the remote responder can supply its own default values.
You must have negotiated the appropriate attribute group on the
FTM_INITIALIZE_REQ_ call for an attribute to be defined at file creation.
There are no default values for initial-attrib.
initial-attrib is a conditional parameter. If file-status is equal to ZFTM-VALFOPEN-OLD, you should not specify a value for initial-attrib. For all other
values of file-status, you must specify at least the file name attribute and the
document type component of the contents-type attribute in the value for
initial-attrib; if you do not, an error is returned.
create-password
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
is an optional parameter that the responder might require to establish that the user,
identified by the initiator-id parameter of the FTM_INITIALIZE_REQ_ call,
has permission to create files in the file storage system of the responding system.
create-password is an optional parameter. If you do not supply
create-password, no password will be sent to the remote responder.
process-mode
input
INT .EXT:ref:(ZFTM-DDL-PROC-MODE)
specifies the actions permitted on the file after establishment of the file-open
regime. If not specified by your application, process-mode will be the single
action ZREAD.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 85
FTM_FILE_OPEN_REQ_
FTM Procedures
process-mode is an optional parameter.
contents-type
input
INT .EXT:ref:(ZFTM-DDL-CNTNTS-TYPE)
allows you to specify the abstract data type of the contents of the file, including the
structuring information. The contents-type parameter must either match the
contents type of the file being opened or be an allowed simplification of the
document type.
contents-type is an optional parameter. If you do not specify contents-type,
the default value is ZFTM-VAL-CNTNTSTYPE-UNKNOWN, and the remote
responder returns the valid contents-type information for the file, which you
retrieve via the FTM_FILE_OPEN_CNF_ procedure call.
If you do specify contents-type, the parameter value includes a document type
with associated parameters (universal-class, string-significance, and
maximum-string-length). All are optional parameters; however, if you specify
a value for maximum-string-length, it should be in the range of 1 through
7148. For a full description of contents-type and its usage, see the OSI/FTAM
Programming Guide.
Supported document types and their associated object identifiers include the
following:
Document Type
Object Identifier
FTAM-1
{ 1 0 8571 5 1 }
FTAM-2
{ 1 0 8571 5 2 }
FTAM-3
{ 1 0 8571 5 3 }
NBS-9
{ 1 3 14 5 5 9 }
If the remote responder does not return one of these document types, a protocol
violation occurs.
account
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
identifies the account to be charged for costs incurred in the regime being
established.
account is an optional parameter. If you omit account, no account name will be
supplied to the remote responder.
Some responders require an account name. For information on the accounting
methods being used, refer to the responder documentation.
tag
input
INT(32):value
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 86
FTM_FILE_OPEN_REQ_
FTM Procedures
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
•
Before calling FTM_FILE_OPEN_REQ_, you must have negotiated a service class
other than the file-management service class, via the FTM_INITIALIZE_REQ_ call.
You must also have negotiated the grouping functional unit and the read or write
functional unit.
To successfully complete this procedure call, the association must be in the FTAM
regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation
when you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
If the value of the file-status parameter is ZFTM-VAL-FOPEN-OLD, this
procedure does not issue the F-CREATE primitive, and the call results in the
following grouped request:
F-BEGIN-GROUP
F-SELECT
F-OPEN
F-END-GROUP
If file-status is any value other than ZFTM-VAL-FOPEN-OLD, the
FTM_FILE_OPEN_REQ_ call results in the following grouped request:
F-BEGIN-GROUP
F-CREATE
F-OPEN
F-END-GROUP
•
•
•
The grouping threshold parameter is set to 2 for this grouped procedure call.
This means that the entire call must either succeed or fail. For instance, if the
file-selection succeeds but the file-open fails, the association remains in the FTAM
regime and the file is not selected.
The contents-type parameter does not support the specification of abstract
syntax and constraint set as described in ISO 8571-3, clause 17.1.2.4. This is
consistent with National Institute of Standards and Technology, Stable
Implementation Agreements for Open Systems Interconnection Protocols, section
9.10.2.3.
The remote responder supplies values of unassigned initial attributes, depending
on the requirements of the responding system’s FTAM implementation.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 87
FTM_FILE_OPEN_REQ_
FTM Procedures
Errors
Table 4-27. Possible FTAM Initiator Errors for the FTM_FILE_OPEN_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6003
ZFTM-ERR-ACCESS-INCNSTNT
- 6005
ZFTM-ERR-PROC-MODE-INCNSTNT
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 88
FTM_FILE_OPEN_REQ_
FTM Procedures
The following table lists common errors that can occur on the
FTM_FILE_OPEN_REQ_ procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not
in the FTAM regime.
Error Code:
ZFTM-ERR-ACCESS-INCNSTNT (-6003)
The requestedaccess parameter
values are inconsistent
with the negotiated
functional units or
inconsistent with the
contents-type of the
document being
created. The error
subcode shows which
file access capability
was inconsistent.
Error Code:
ZFTM-ERR-PROC-MODE-INCNSTNT (-6005)
The process-mode
parameter values are
inconsistent with the
requested-access
parameter values. The
error subcode shows
which processing mode
was inconsistent.
Error Code:
Error Subcode:
ZAPS-ERR-PARAM-RANGE (-138)
ZFTM-ERR-MAX-STRING-LEN (155)
The maximumstring-length
parameter specified as
part of the contentstype parameter was
too large. The
maximum value for
maximum-stringlength is 7148.
Error Code:
Error Subcode:
ZAPS-ERR-PARAM-RANGE (-138) ZFTMERR-INITIAL-ATTR (119)
The file-status
value was not ZFTMVAL-FOPEN-OLD, and
no initial-attrib
parameter value was
specified.
Examples
Examples of the FTM_FILE_OPEN_REQ_ call in a program begin on line 1058 of the
C version and line 1019 of the TAL version of Example 1 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 89
FTM_FILE_OPEN_CNF_
FTM Procedures
FTM_FILE_OPEN_CNF_
This procedure allows you to retrieve the remote responder’s response to the
application’s request to select and open a file or optionally create and open a file.
error := FTM_FILE_OPEN_CNF_ (
,
,
,
,
,
,
cepi
[ state-result ]
[ action-result ]
[ filename ]
[ initial-attrib ]
[ contents-type ]
[ diagnostic ] ) ;
error
!
!
!
!
!
!
!
I
O
O
O
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
state-result
output
INT(32) .EXT:ref:1
indicates if the responder established the file-open regime as requested. Valid
values are as follows:
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
state-result is an optional parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value. Valid
values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 90
FTM_FILE_OPEN_CNF_
FTM Procedures
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
filename
output
INT .EXT:ref:(ZAPS-DDL-CHAR128)
is the name of the opened file as returned from the remote responder. The name
can have a maximum of 128 characters. If the responder returns a name that is
greater than 128 characters, the initiator passes only the first 128 characters to the
application.
filename is an optional parameter.
initial-attrib
output
INT .EXT:ref:(ZFTM-DDL-CREATE-ATTR-GRP)
defines the file attributes associated with the created file. The remote responder
can respond that no value is available for a proposed attribute if it does not support
the attribute, except for the filename and permitted-actions attributes to which
values must be assigned.
The only attributes to which the remote responder can assign a different value from
the one proposed by the initiator are filename and permitted-actions, for a create
operation, and permitted-actions only, for a select operation. For all other file
attributes, the remote responder must either accept the proposed value or respond
that no value is available. In the case of attributes to which the initiator does not
assign values in the initial-attrib parameter in the
FTM_FILE_OPEN_REQ_, the remote responder can supply its own default values.
You must have negotiated the appropriate attribute group on the
FTM_INITIALIZE_REQ_ call for an attribute to be defined at file creation.
initial-attrib is an optional parameter.
contents-type
output
INT.EXT:ref:(ZFTM-DDL-CNTNTS-TYPE)
returns the contents type of the file that was opened. The contents type returned is
a document type name with appropriate parameters.
If the application specified a value of ZFTM-VAL-FOPEN-NEW (0) or ZFTM-VALFOPEN-RECREATE (3) for the file-status parameter on the
FTM_FILE_OPEN_REQ_, the maximum-string-length value returned as part
of this parameter must match the value proposed on the FTM_FILE_OPEN_REQ_
call. If the two values do not match, the initiator generates a provider abort.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 91
FTM_FILE_OPEN_CNF_
FTM Procedures
contents-type is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
The initiator can also return the informative diagnostic message ZFTM-DIAGCNTNTS-TYPE-SIMPLE (5037) on this call. For more information on this
diagnostic message, see Appendix D, NonStop FTAM Initiator Diagnostic
Messages.
diagnostic is an optional parameter.
Considerations
•
•
•
To successfully complete this procedure call, you must have previously called
FTM_FILE_OPEN_REQ_, and the association must be in the FTAM regime.
You must call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-FILEOPEN-CNF event before calling FTM_FILE_OPEN_CNF_.
The association either stays in the FTAM regime if state-result indicates a
failure, or moves to the file-open regime if state-result indicates success.
Errors
Table 4-28. Possible FTAM Initiator Errors for the FTM_FILE_OPEN_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_FILE_OPEN_CNF_ call in a program begin on line 1100 of the
C version and line 1062 of the TAL version of Example 1 in Appendix G, NonStop
FTAM Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 92
FTM_INITIALIZE_REQ_
FTM Procedures
FTM_INITIALIZE_REQ_
This procedure allows you to request initiation of an association with an FTAM
responder. Successful completion of this procedure initializes the FTAM regime. For a
description of the FTAM regime, see the OSI/FTAM Programming Guide.
status := FTM_INITIALIZE_REQ_ (
,
,
,
,
,
,
,
,
,
,
,
,
,
,
status
cepi
aplmgr-name
remote-appl
[ wait-mode ]
[ local-appl ]
[ local-ae-title ]
[ remote-ae-title ]
[ service-class ]
[ func-units ]
[ attrib-groups ]
[ contents-type-list ]
[ initiator-id ]
[ account ]
[ filestore-password ]
[ tag ] ) ;
! O
! I
! I
! I
! I
! I
! I
! I
! I
! I
! I
! I
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi output
INT.EXT:ref:1
is the connection endpoint identifier (CEPI) used to identify the specific
association.
The CEPI value returned from the FTM_INITIALIZE_REQ_ call is used when
making other FTAM calls for this association. For more information on using the
cepi parameter in the context of establishing an FTAM association, see the
OSI/FTAM Programming Guide.
cepi is a required parameter.
aplmgr-name
input
INT .EXT:ref:(ZAPS-DDL-FILENAME)
is the Guardian process name of the APLMGR to use to establish this association.
The APLMGR process determines which FTAM initiator process services the
FTAM association.
aplmgr-name is in the HP internal form and is a required parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 93
FTM_INITIALIZE_REQ_
FTM Procedures
remote-appl
input
INT .EXT:ref:(ZAPS-DDL-APPL-ADDR)
specifies the common name and/or OSI address of the called FTAM responder.
remote-appl is a required parameter.
wait-mode
input
INT:value
sets the operating mode (wait mode or nowait mode) for the lifetime of the
association. Valid values are as follows:
ZAPS-VAL-WAITED
ZAPS-VAL-NOWAITED
The default mode is ZAPS-VAL-WAITED.
wait-mode is an optional parameter.
local-appl
input
INT .EXT:ref:(ZAPS-DDL-APPL-ADDR)
identifies the common name and/or OSI address of the local application entity.
local-appl is an optional parameter. If you do not supply local-appl, the local
application address will be the address (COMNAME) assigned to the initiator when
it was created. For more information, see the OSI/FTAM Programming Guide.
local-ae-title
input
INT .EXT:ref:(ZAPS-DDL-AE-TITLE)
specifies the application entity (AE) title of the local application. The AE title
consists of an application process (AP) title and an AE qualifier.
local-ae-title is an optional parameter. If you do not supply local-aetitle, the local AE title will be as specified in NIST, Stable Implementation
Agreements for Open Systems Interconnection Protocols, Part 9—FTAM Phase 2,
Section 5.11.1.1. The AP title will have a value of { 1 3 9999 1 7 }, and the AE
qualifier will have a value of 0.
Note. Although FTAM requires the use of AE titles when establishing an association, no
agreements governing the use of AE titles have been made. To satisfy this requirement,
NIST has defined a value for an AE title to be used by FTAM. This value does not identify
an application entity and carries no semantics.
remote-ae-title
input
INT .EXT:ref:(ZAPS-DDL-AE-TITLE)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 94
FTM_INITIALIZE_REQ_
FTM Procedures
specifies the application entity (AE) title of the responding application entity. The
AE title consists of an application process title and an AE qualifier.
remote-ae-title is an optional parameter. If you omit remote-ae-title, the
remote application entity title will be as specified in NIST, Stable Implementation
Agreements for Open Systems Interconnection Protocols, Section 5.11.1.1. The
AP title will have a value of { 1 3 999 1 7 }, and the AE qualifier will have a value of
1. Note that some implementations might not use the same defaults for AE title.
Note. If you plan to use any other value than { 1 3 9999 1 7 1 } for the remote AE title,
refer to NIST, Stable Implementation Agreements for Open Systems Interconnection
Protocols, Part 9—FTAM Phase 2, Section 9.5.7 for details.
service-class
input
INT .EXT.ref:(ZFTM-DDL-SERVICE-CLASS)
requests service classes to be negotiated by the remote responder. For a detailed
explanation of service-class, see the OSI/FTAM Programming Guide.
service-class is an optional parameter.
You can request more than one service class when using the service-class
parameter. Only one of the service classes requested will be accepted. The service
class negotiated and accepted by the responder will be the one that supports the
highest level of functionality. The service class negotiated by the responder is
returned by the FTM_INITIALIZE_CNF_ procedure. Four file service classes are
supported, as follows, where the default values are indicated in the Value column:
Service Class
DDL Identifier
Value
File Transfer
ZTRANSFER
TRUE
File Management
ZMGMT
FALSE
File Transfer and
Management
ZXFERMGMT
FALSE
File Access
ZACCESS
FALSE
If you do not specify a service-class value in this call, only the file-transfer
service class will be negotiated, as shown in the table above. For more information
on service classes and the valid service-class combinations that can be requested,
see the OSI/FTAM Programming Guide.
func-units
input
INT .EXT:ref:(ZFTM-DDL-FUNC-UNITS)
requests the set of file service functional units desired for the association. For a
detailed explanation of functional units, see the OSI/FTAM Programming Guide.
func-units is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 95
FTM_INITIALIZE_REQ_
FTM Procedures
Note. The requested functional units must include all mandatory functional units for the
service classes requested.
If you do not request specific functional units, the functional units requested will be:
Functional Unit
DDL Identifier
Value
Read
ZREAD
TRUE
Write
ZWRITE
TRUE
File access
ZFILEACCESS
FALSE
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 functional units negotiated by the responder will be returned by the
FTM_INITIALIZE_CNF_ procedure.
attrib-groups
input
INT .EXT:ref:(ZFTM-DDL-ATTR-GROUPS)
requests the set of optional file-attribute groups desired for the association, where
storage, security, and private are possible. attrib-groups is an optional
parameter. If you do not supply attrib-groups, only the kernel attribute group
will be requested. If you do supply this parameter, be sure to set the ZPRIVATE
field to ZAPS-VAL-FALSE because NonStop FTAM does not support the private
attribute group.
The attribute groups negotiated by the responder will be returned by the
FTM_INITIALIZE_CNF_ procedure.
For a detailed explanation of attributes, see the OSI/FTAM Programming Guide.
contents-type-list
input
INT .EXT:ref:(ZFTM-DDL-CNTNTS-LIST)
requests the presentation contexts for the association. This parameter carries a
proposed list of document type names. If you do not specify a contents type, the
document types requested will be FTAM-1, FTAM-2, FTAM-3, and NBS-9. For
more information on contents type, see the OSI/FTAM Programming Guide.
The contents-type-list parameter is optional.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 96
FTM_INITIALIZE_REQ_
FTM Procedures
initiator-id
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
identifies the calling application to the responding application entity.
initiator-id is an optional parameter. If you omit initiator-id, no initiator
identity will be specified.
Some responders require an initiator ID. For information on responder
requirements for the initiator ID, refer to the responder documentation.
account
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
identifies the account to be charged for costs that are incurred during the regime
being established.
account is an optional parameter. If you omit account, no account name will be
supplied to the remote responder.
Some responders require an account name. For information on the accounting
methods being used, refer to the responder documentation.
filestore-password
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
conveys a password used by the responder to authenticate the initiator-id. If
this parameter is not provided, no password will be transferred to the remote
responder.
filestore-password is an optional parameter.
Some responders require a filestore password. For information on responder
requirements for the filestore password, refer to the responder documentation.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
When your application is running, but before it establishes its first FTAM
association via the FTM_INITIALIZE_REQ_ procedure, it must call the
APS_INITIALIZE_ procedure once. The APS_INITIALIZE_ procedure allocates an
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 97
FTM_INITIALIZE_REQ_
FTM Procedures
extended segment that the FTAM API uses to maintain the context information for
all the FTAM associations your application establishes.
•
•
•
•
•
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
The local-appl and remote-appl parameters each consist of the common
name (OSI/AS application name) and the corresponding OSI address. If you
specify only the common name, OSI/AS supplies the OSI address. If you specify
the OSI address, OSI/AS ignores any common name you specify.
The mandatory parameter Presentation Context Management (as specified in ISO
8571-3) is not provided because the underlying stack does not support this
functionality. This parameter is not available to your application and its value is
always FALSE.
The mandatory parameter FTAM Quality of Service (as specified in ISO 8571-3) is
not provided because the NonStop FTAM implementation does not support
recovery. The FTAM Quality of Service parameter is not available to your
application and its value will always be NO-RECOVERY.
The mandatory parameter Communications Quality of Service (as specified in ISO
8571-3) is not provided because the NonStop FTAM implementation does not
support recovery. This parameter is not available to your application because the
underlying stack does not support this functionality.
Errors
Table 4-29. Possible FTAM Initiator Errors for the FTM_INITIALIZE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 98
FTM_INITIALIZE_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_INITIALIZE_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-MGR-ERR (-126)
ZAPS-ERR-MGR-LOCAL-NAME (101)
The local application
name is not configured
in OSI/AS.
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-MGR-ERR (-126)
ZAPS-ERR-MGR-REMOTE-NAME (102)
The remote application
name is not configured
in OSI/AS.
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-MGR-ERR (-126)
ZAPS-ERR-MGR-LOCAL-NSAP (103)
The local NSAP name
is not configured in
OSI/AS.
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-MGR-ERR (-126)
ZAPS-ERR-MGR-REMOTE-NSAP (104)
The remote NSAP
name is not configured
in OSI/AS.
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-MGR-ERR (-126)
ZAPS-ERR-MGR-LOCAL-TSEL (105)
The local TSEL name is
not configured in
OSI/AS.
Error Code:
Error Subcode:
Orig. Error Code:
Orig. Subcode:
ZFTM-ERR-BAD-APS-STATUS (-6019)
0
ZAPS-ERR-L5-TRANS-FS-ERROR (-1001)
140
Transport connection
cannot be made. While
there are many causes
of this error, these are
the error codes
returned if the remote
responder is not active,
or if the
communications link is
severed.
Error Code:
Error Subcode:
ZAPS-ERR-FS-ERROR (-125) 13
The name provided for
the aplmgr-name
parameter is not a valid
NonStop process
name.
Error Code:
Error Subcode:
ZAPS-ERR-FS-ERROR (-125) 14
The application
manager process
designated by
aplmgr-name is not
currently running.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4- 99
FTM_INITIALIZE_REQ_
FTM Procedures
These error
values...
are returned if....
Error Code:
Error Subcode:
ZAPS-ERR-MGR-ERR (-126) -10
The NonStop FTAM
initiator has been
overloaded
momentarily with ADD
SU requests from the
APLMGR process. The
APLMGR process can
handle only 16
outstanding register
requests from the
FTAM API at one time,
but will continue
processing until all
associations are
established.
Error Code:
Error Subcode:
ZAPS-ERR-MGR-ERR (-126)
ZFTM-ERR-MGR-ASE-UNAVAIL (7004)
All started FTAM
initiator processes
associated with the
specified APLMGR
have exceeded their
maximum number of
configured
associations.
Error Code:
Error Subcode:
ZAPS-ERR-MGR-ERR (-126)
ZFTM-ERR-MGR-ASE-TBL-EMPTY (7005)
No FTAM initiator
processes have been
defined for the specified
APLMGR.
Error Code:
Error Subcode:
ZAPS-ERR-MGR-ERR (-126)
ZFTM-ERR-MGR-ASE-NOT-READY (7006)
There are no started
FTAM initiator
processes associated
with the specified
APLMGR.
Examples
Examples of the FTM_INITIALIZE_REQ_ call in a program begin on line 410 of the C
version and line 494 of the TAL version of Example 1 and on line 434 of the C version
and line 528 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -100
FTM_INITIALIZE_CNF_
FTM Procedures
FTM_INITIALIZE_CNF_
This procedure allows you to retrieve remote responder’s response to the application’s
request to establish an association with a remote responder.
error := FTM_INITIALIZE_CNF_ (
,
,
,
,
,
,
,
,
,
,
cepi
[ state-result ]
[ action-result ]
[ local-appl ]
[ responding-appl ]
[ responding-ae-title ]
[ service-class ]
[ func-units ]
[ attrib-groups ]
[ contents-type-list ]
[ diagnostic ] ) ;
error
!
!
!
!
!
!
!
!
!
!
!
I
O
O
O
O
O
O
O
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
state-result
output
INT(32) .EXT:ref:1
indicates if the responder established the FTAM regime as requested. Valid values
are as follows:
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
state-result is an optional parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -101
FTM_INITIALIZE_CNF_
FTM Procedures
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and the diagnostic
parameter is likely to contain one or more diagnostic messages.
action-result is an optional parameter.
local-appl
output
INT .EXT:ref:(ZAPS-DDL-APPL-ADDR)
identifies the common name and/or OSI address of the local application entity, as
specified in the initialize request. local-appl is an optional parameter.
responding-appl
output
INT .EXT:ref:(ZAPS-DDL-APPL-ADDR)
identifies the common name and/or OSI address of the remote responding
application entity. Because the responding system can designate another address
to use for the communication, the value of this parameter might not be the same as
the remote-appl parameter sent in the FTM_INITIALIZE_REQ_ procedure.
responding-appl is an optional parameter.
responding-ae-title
output
INT .EXT:ref:(ZAPS-DDL-AE-TITLE)
returns the application entity (AE) title of the responding application entity.
responding-ae-title is an optional parameter.
service-class
output
INT .EXT.ref:(ZFTM-DDL-SERVICE-CLASS)
returns service classes accepted by the remote responder. For a detailed
explanation of service-class, see the OSI/FTAM Programming Guide.
Only one of the service classes requested in the FTM_INITIALIZE_REQ_ will be
accepted. The service class negotiated and accepted by the responder will be the
one that supports the highest level of functionality.
For more information on service classes and the valid service-class combinations
that can be requested, see the OSI/FTAM Programming Guide.
service-class is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -102
FTM_INITIALIZE_CNF_
FTM Procedures
func-units
output
INT .EXT:ref:(ZFTM-DDL-FUNC-UNITS)
returns the file service functional units requested by the initiator and negotiated by
the remote responder. The negotiation process defines the functional units for the
association. For a detailed explanation of functional units, see the OSI/FTAM
Programming Guide.
func-units is an optional parameter.
attrib-groups
output
INT .EXT:ref:(ZFTM-DDL-ATTR-GROUPS)
returns the attribute groups proposed by the initiator that the remote responder will
support. This negotiation defines the attribute groups for the association. For a
detailed explanation of attributes, see the OSI/FTAM Programming Guide.
attrib-groups is an optional parameter.
contents-type-list output
INT .EXT:ref:(ZFTM-DDL-CNTNTS-LIST)
returns the list of document type names proposed by the initiator that the remote
responder and service providers will support. For more information on contents
type, see the OSI/FTAM Programming Guide.
This negotiation defines the presentation context for the association.
contents-type-list is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -103
FTM_INITIALIZE_CNF_
FTM Procedures
Considerations
•
Before calling FTM_INITIALIZE_CNF_, you must call the following procedures:
FTM_INITIALIZE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-INITIALIZE-CNF event before calling FTM_INITIALIZE_CNF_.
•
•
•
•
Depending on the state-result value, the application either establishes or fails
to establish an FTAM regime.
°
An FTAM regime is established if the value of state-result is ZFTM-VALSTATE- SUCCESS.
°
The FTAM regime is not established if the value of state-result is ZFTMVAL-STATE-FAILURE.
The mandatory parameter Presentation Context Management (as specified in ISO
8571-3) is not supported because NonStop OSI/AS does not support this
functionality. This parameter is not available, and its value is always FALSE.
The mandatory parameter FTAM Quality of Service (as specified in ISO 8571-3) is
not supported because the NonStop FTAM implementation does not support
recovery. The FTAM Quality of Service parameter is not available to your
application and its value will always be NO-RECOVERY.
The mandatory parameter Communications Quality of Service (as specified in ISO
8571-3) is not supported because the underlying stack does not support this
functionality.
Errors
Table 4-30. Possible FTAM Initiator Errors for the FTM_INITIALIZE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6032
ZFTM-ERR-ACSE-FAILURE
- 6036
ZFTM-ERR-SU-ABORTED
- 6039
ZFTM-ERR-EMPTY-ASSOC-CNF
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -104
FTM_INITIALIZE_CNF_
FTM Procedures
Examples
Examples of the FTM_INITIALIZE_CNF_ call in a program begin on line 893 of the C
version and line 852 of the TAL version of Example 1, and on line 462 of the C version
and line 556 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -105
FTM_LOCATE_REQ_
FTM Procedures
FTM_LOCATE_REQ_
This procedure allows you to move a location pointer to a specified place in the
previously opened file. The location pointer is used in read and write operations.
status := FTM_LOCATE_REQ_ (
cepi
, fadu-id
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
fadu-id
input
INT .EXT:ref:(ZFTM-DDL-FADU-ID)
specifies the target FADU. The following possible values apply only to the FTAM-2
document type:
Data Structure Field
Possible Values
ZFIRSTLAST
ZFTM-VAL-FADUID-FIRST
ZFTM-VAL-FADUID-LAST
ZRELATIVE
ZFTM-VAL-FADUID-PREVIOUS
ZFTM-VAL-FADUID-CURRENT
ZFTM-VAL-FADUID-NEXT
ZBEGINEND
ZFTM-VAL-FADUID-BEGIN
ZFTM-VAL-FADUID-END
ZFADUNUMBER
(specifies number of FADUs separating desired FADU from
root FADU)
For a full explanation of this parameter and its usage, see ISO 8571, Part 2, or in
the OSI/FTAM Programming Guide.
fadu-id is a required parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -106
FTM_LOCATE_REQ_
FTM Procedures
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
•
Before calling this procedure, you must have negotiated the file-access service
class and the file-access functional unit on the FTM_INITIALIZE_REQ_ call.
To successfully complete this procedure call, you must be in the file-open regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
This procedure cannot be used on a document type whose constraint set is “FTAM
unstructured constraint set.” FTAM-1 and FTAM-3 document types fall into this
category.
Errors
Table 4-31. Possible FTAM Initiator Errors for the FTM_LOCATE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6006
ZFTM-ERR-FADU-ID-INVALID
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6026
ZFTM-ERR-LOCATE-DOCTYPE
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -107
FTM_LOCATE_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_LOCATE_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in the
file-open regime.
Error Code:
ZFTM-ERR-FADU-ID-INVALID (-6006)
The FADU ID is inconsistent
with the document type
requested when the file was
opened.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -108
FTM_LOCATE_REQ_
FTM Procedures
Example
The following TAL program illustrates the use of the FTM_LOCATE_REQ_ procedure
call:
1. !-----------------------------------------------------------------------!
2. ! This example demonstrates how to locate a record of an FTAM-2 file.
!
3. ! It assumes that the file has already been selected and opened.
!
4. !
!
5. ! This example abends on all error conditions. Additional application-
!
6. ! specific error handling or recovery could be implemented if
!
7. ! required by an application.
!
8. !-----------------------------------------------------------------------!
9.
LITERAL WAIT_FOREVER = -1d; ! Timeout for event rcv.
!
10. STRUCT .EXT diag ( ZFTM-DDL-DIAGNOSTIC-DEF ); ! FTAM diagnostics
!
11. STRUCT .EXT fadu_id ( ZFTM-DDL-FADU-ID-DEF ); ! FADU to be located
!
12. INT(32) .EXT action_result; ! Result of locate req.
!
13. INT cepi; ! Connection endpoint ID
!
14. INT status; ! APS status code
!
15. INT event_code; ! OSI/FTAM event code
!
16. INT error; ! APS or FTAM error code
!
17. !----------------------------------------------------------------------!
18. ! Specify the target FADU. This example locates the first record in an !
19. ! FTAM-2 file.
!
20. !----------------------------------------------------------------------!
21. fadu_id.zid := zftm-val-faduid-firstlast;
22. fadu_id.zfirstlast := zftm-val-faduid-first;
23. !----------------------------------------------------------------------!
24. ! Call FTM_LOCATE_REQ_ to locate the FADU.
!
25. !----------------------------------------------------------------------!
26. status := FTM_LOCATE_REQ_ ( cepi
27.
, fadu_id
28.
, ! tag ! );
29. IF ( status <> ZAPS-VAL-STATUS-OK ) THEN
30. BEGIN
31.
CALL ABEND;
32. END;
33. !----------------------------------------------------------------------!
34. !Call APS_EVENT_RECEIVE_ to receive the confirm for the locate service.!
35. !----------------------------------------------------------------------!
36. status := APS_EVENT_RECEIVE_ ( cepi, WAIT_FOREVER );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -109
FTM_LOCATE_REQ_
FTM Procedures
37. IF ( status <> ZAPS-VAL-STATUS-EVENT ) THEN
38. BEGIN
39.
CALL ABEND;
40. END;
41. !----------------------------------------------------------------------!
42. ! Call APS_STATUS_ to determine what event has been received. Verify
!
43. ! that the event is the locate confirm.
!
44. !----------------------------------------------------------------------!
45. error := APS_STATUS_ ( cepi, event_code );
46. IF ( error <> ZAPS-ERR-OK ) OR
47. ( event_code <> ZFTM-VAL-EVT-LOCATE-CNF) THEN
48. BEGIN
49.
CALL ABEND;
50. END;
51. !----------------------------------------------------------------------!
52. ! Call FTM_LOCATE_CNF_. If the service is successful and the responder !
53. ! returns a value for the FADU identity, the value for fadu_id is the
!
54. ! relative record number that was located; otherwise, the ZID field of !
55. ! of the ZFTM-DDL-FADU-ID structure has a value of
!
56. ! ZFTM-VAL-FADU-NOVALUE.
!
57. !----------------------------------------------------------------------!
58. error := FTM_LOCATE_CNF_ ( cepi
59.
, action_result
60.
, fadu_id
61.
, diag );
62. IF ( error <> ZAPS-ERR-OK ) THEN
63. BEGIN
64.
CALL ABEND;
65. END;
66. IF ( action_result <> ZFTM-VAL-ACTION-SUCCESS ) THEN
67. BEGIN
68. !----------------------------------------------------------------------!
69. ! The locate request failed. The diagnostics can be examined if
!
70. ! more detailed diagnostic information is required by an application.
!
71. !----------------------------------------------------------------------!
72.
CALL ABEND;
73. END;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -110
FTM_LOCATE_CNF_
FTM Procedures
FTM_LOCATE_CNF_
This procedure allows you to retrieve the responder’s response to the application’s
request to move the pointer to a specified location in the previously opened file. The
location pointer is used in read and write operations.
error := FTM_LOCATE_CNF_ ( cepi
, [ action-result ]
, [ fadu-id ]
, [ diagnostic ] ) ;
error
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value. Valid
values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
fadu-id
output
INT .EXT:ref:(ZFTM-DDL-FADU-ID)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -111
FTM_LOCATE_CNF_
FTM Procedures
returns the FADU identity. For a full explanation of this parameter and its usage,
see the OSI/FTAM Programming Guide.
fadu-id is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, you must have previously called
FTM_LOCATE_REQ_, and the association must be in the file-open regime.
Before calling FTM_LOCATE_CNF_, you must call the following procedures:
FTM_LOCATE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-LOCATE- CNF event before calling FTM_LOCATE_CNF_.
Errors
Table 4-32. Possible FTAM Initiator Errors for the FTM_LOCATE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Example
For an example of a TAL program illustrating the use of the FTM_LOCATE_CNF_
procedure, see the Example on page 4-109 in the FTM_LOCATE_REQ_ procedure
description.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -112
FTM_OPEN_REQ_
FTM Procedures
FTM_OPEN_REQ_
This procedure allows you to make the contents of the previously selected file available
for access. This procedure initiates the file-open regime. For a description of the
file-open regime, see the OSI/FTAM Programming Guide.
status := FTM_OPEN_REQ_ (
cepi
, [ process-mode ]
, [ contents-type ]
, [ tag ] ) ;
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
process-mode
input
INT .EXT:ref:(ZFTM-DDL-PROC-MODE)
specifies the actions permitted on the file during the file-open regime. If not
specified by your application, process-mode will be the single action ZREAD.
process-mode is an optional parameter.
contents-type
input
INT.EXT:ref:(ZFTM-DDL-CNTNTS-TYPE)
allows you to specify the abstract data type of the contents of the file, including the
structuring information. contents-type must either match the contents type of
the file being opened or be an allowed simplification of the document type.
contents-type is an optional parameter. If you do not specify contents-type,
the default value is ZFTM-VAL-CNTNTSTYPE-UNKNOWN, and the remote
responder returns the valid contents-type information for the file, which you retrieve
via the FTM_OPEN_CNF_ procedure call.
If you do specify contents-type, the information includes a document type with
associated parameters (universal-class, string-significance, and
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -113
FTM_OPEN_REQ_
FTM Procedures
maximum-string-length). All the three are optional parameters; however,
when you specify a value for maximum-string-length, it should be in the range
of 1 through 7148. For a full description of contents-type and its usage, see the
OSI/FTAM Programming Guide.
Supported document types and their associated object identifiers include the
following:
Document Type
Object Identifier
FTAM-1
{ 1 0 8571 5 1 }
FTAM-2
{ 1 0 8571 5 2 }
FTAM-3
{ 1 0 8571 5 3 }
NBS-9
{ 1 3 14 5 5 9 }
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
•
Before calling FTM_OPEN_REQ_, you must have negotiated a service class other
than the file-management service class, as well as the read or write functional unit.
To complete this procedure call successfully, the association must be in the
file-selection regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
The contents-type parameter does not support the specification of abstract
syntax and constraint set (as specified in ISO 8571-3, clause 17.1.2.4). This is
consistent with the National Institute of Standards and Technology, Stable
Implementation Agreements for Open Systems Interconnection Protocols, Part 9—
FTAM Phase 2, Section 9.10.2.3.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -114
FTM_OPEN_REQ_
FTM Procedures
Errors
Table 4-33. Possible FTAM Initiator Errors for the FTM_OPEN_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6005
ZFTM-ERR-PROC-MODE-INCNSTNT
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_OPEN_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-selection regime.
Error Code:
ZFTM-ERR-PROC-MODE-INCNSTNT (-6005)
The process-mode
parameter values are
inconsistent with the
requested-access
parameter values on the
prior call to
FTM_CREATE_REQ_ or
FTM_SELECT_REQ_.
The error subcode
shows which processing
mode is inconsistent.
Error Code:
Error Subcode:
ZAPS-ERR-PARAM-RANGE (-138)
ZFTM-ERR-MAX-STRING-LEN (155)
The maximum-stringlength parameter
specified as part of the
contents-type
parameter was too large.
The maximum value for
maximum-stringlength is 7148.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -115
FTM_OPEN_REQ_
FTM Procedures
Examples
Examples of the FTM_OPEN_REQ_ call in a program begin on line 819 of the C
version and line 917 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -116
FTM_OPEN_CNF_
FTM Procedures
FTM_OPEN_CNF_
This procedure allows you to retrieve the remote responder’s response to the
application’s request to open the previously selected file.
error := FTM_OPEN_CNF_ (
,
,
,
,
cepi
[ state-result ]
[ action-result ]
[ contents-type ]
[ diagnostic ] ) ;
error
!
!
!
!
!
I
O
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
state-result
output
INT(32) .EXT:ref:1
indicates whether the responder established the file-open regime as requested.
Valid values are as follows:
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
state-result is an optional parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value.
Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -117
FTM_OPEN_CNF_
FTM Procedures
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
contents-type
output
INT.EXT:ref:(ZFTM-DDL-CNTNTS-TYPE)
returns the document type with appropriate parameters. If you supply a value of
ZFTM-VAL-CNTNTSTYPE-UNKNOWN for contents-type in the
FTM_OPEN_REQ_ call, the responder returns the actual contents-type
information. For a full description of contents-type and its usage, see the
OSI/FTAM Programming Guide.
Supported document types and their associated object identifiers include the
following:
Document Type
Object Identifier
FTAM-1
{ 1 0 8571 5 1 }
FTAM-2
{ 1 0 8571 5 2 }
FTAM-3
{ 1 0 8571 5 3 }
NBS-9
{ 1 3 14 5 5 9 }
contents-type is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages. The initiator can also return the
informative diagnostic message ZFTM-DIAG-CNTNTS-TYPE-SIMPLE (5037) on
this call. For more information on this diagnostic message, see Appendix D,
NonStop FTAM Initiator Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the fileselection regime.
Before calling FTM_OPEN_CNF_, you must call the following procedures:
FTM_OPEN_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -118
FTM_OPEN_CNF_
FTM Procedures
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-OPEN-CNF event before calling FTM_OPEN_CNF_.
•
The association stays in the file-selection regime if state-result indicates a
failure, or moves to the file-open regime if state-result indicates a success.
Errors
Table 4-34. Possible FTAM Initiator Errors for the FTM_OPEN_CNF_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_OPEN_CNF_ call in a program begin on line 957 of the C
version and line 860 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -119
FTM_P_ABORT_IND_
FTM Procedures
FTM_P_ABORT_IND_
This procedure allows you to retrieve information indicating that the association has
been aborted somewhere in the OSI stack, either on the NonStop system or on the
remote responding system.
error := FTM_P_ABORT_IND_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error return
! I
! O
! O
value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value. Valid
values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -120
FTM_P_ABORT_IND_
FTM Procedures
provides information that qualifies the success or explains the failure of the
requested action. This parameter might not contain any information, depending on
where the provider abort was issued.
For a complete list of possible diagnostic values that can be returned from the
remote responder, see Appendix C, ISO FTAM Diagnostic Messages. For a list of
diagnostic messages that can be returned from the NonStop initiator, see
Appendix D, NonStop FTAM Initiator Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
•
•
To complete this procedure call successfully, you must have previously
successfully called the FTM_INITIALIZE_REQ_ and have a valid CEPI for this
association.
You must call APS_EVENT_RECEIVE_ to receive the indication and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-PABORT-IND event before calling FTM_P_ABORT_IND_.
When you receive the provider abort indication, the association is lost, and the file
storage system is left in an unknown state.
You should call APS_DISCARD_ after completion of this call.
Errors
Table 4-35. Possible FTAM Initiator Errors for the FTM_P_ABORT_IND_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_P_ABORT_IND_ call in a program begin on line 782 of the C
version and line 1281 of the TAL version of Example 1, and on line 1874 of the C
version and line 2053 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -121
FTM_READ_REQ_
FTM Procedures
FTM_READ_REQ_
This procedure allows you to request the transfer of some or all the contents of the
previously opened file. This procedure initiates the data-transfer regime. For a
description of the data-transfer regime, see the OSI/FTAM Programming Guide.
status := FTM_READ_REQ_ (
,
,
,
cepi
fadu-id
access-context
[ tag ] ) ;
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
fadu-id
input
INT .EXT:ref:(ZFTM-DDL-FADU-ID)
specifies the target FADU. Valid values are the following:
ZFTM-VAL-FADUID-FIRST for the ZFIRSTLAST field. This value specifies the
beginning of the first FADU after the root FADU and applies only to FTAM-1,
FTAM-3, and NBS-9 document types.
For FTAM-2 document types, several options are possible.
To read the entire file, use the ZBEGINEND field, where the value of ZFTMVAL-FADUID-BEGIN is valid.
To read individual nodes of an FTAM-2 file, use a fadu-id value of first, last,
current, next, previous, or node number, where the following values are
possible:
Data Structure Field
Possible Values
ZFIRSTLAST
ZFTM-VAL-FADUID-FIRST
ZFTM-VAL-FADUID-LAST
ZRELATIVE
ZFTM-VAL-FADUID-PREVIOUS
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -122
FTM_READ_REQ_
FTM Procedures
Data Structure Field
Possible Values
ZFTM-VAL-FADUID-CURRENT
ZFTM-VAL-FADUID-NEXT
ZFADUNUMBER
(specifies number of FADUs separating desired FADU
from root FADU)
For more information on the use of the above values, see the OSI/FTAM
Programming Guide or ISO 8571, Part 2.
fadu-id is a required parameter.
access-context
input
INT .EXT:ref:(ZFTM-DDL-ACCESS-CNTXT)
specifies the file access structure for transfers in the data-transfer regime. Valid
values are the following:
ZFTM-VAL-ACCESSCNTXT-FA for flat all data units. Both data and node
descriptors are transferred. This value applies to FTAM-2 files only.
ZFTM-VAL-ACCESSCNTXT-UA for unstructured all data units. Only data is
transferred. This value applies to FTAM-1, FTAM-2, FTAM-3, and NBS-9 files.
For a full explanation of this parameter and its usage, see the OSI/FTAM
Programming Guide.
The access-context parameter is required.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
To complete this procedure call successfully, these conditions must be met:
°
°
•
The association must be in the file-open regime.
You must have negotiated the read functional unit and a service class other
than the file-management service class when the association was established
via the FTM_INITIALIZE_REQ_ call.
For the remote responder to respond affirmatively to this read primitive, the read
field of the permitted-actions attribute of this file must be set to ON.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -123
FTM_READ_REQ_
FTM Procedures
•
•
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
Successful completion of the FTM_READ_REQ_ procedure call transfers the
application to the data-transfer regime.
Errors
Table 4-36. Possible FTAM Initiator Errors for the FTM_READ_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6004
ZFTM-ERR-ACCESS-NOT-AVAIL
- 6006
ZFTM-ERR-FADU-ID-INVALID
- 6008
ZFTM-ERR-PROC-MODE-NOT-AVAIL
- 6009
ZFTM-ERR-ACCESS-CNTXT-INVALID
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -124
FTM_READ_REQ_
FTM Procedures
The following table lists common errors that can occur on the FTM_READ_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-open regime.
Error Code:
ZFTM-ERR-FADU-ID-INVALID (-6006)
The FADU ID is
inconsistent with the
document type you
requested when opening
the file.
Error Code:
Error Subcode:
ZFTM-ERR- PROC-MODE-NOT-AVAIL (-6008)
ZFTM-ERR-PROC-MODE-READ (-1)
The read action was not
specified in the
process-mode
parameter of the
previous
FTM_OPEN_REQ_ call.
Error Code:
ZFTM-ERR-ACCESS-CNTXT-INVALID (-6009)
The access-context
value supplied is not
valid for the document
type opened.
Error Code:
Error Subcode:
ZFTM-ERR- SERV-NOT-NEGOTIATED (-6012)
ZFTM-ERR-SERVICE-MGMT (-1)
The file-management
service class was
negotiated, and this
service class does not
permit reading files.
Examples
Examples of the FTM_READ_REQ_ call in a program begin on line 1128 of the C
version and line 1215 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -125
FTM_READ_ATTRIB_REQ_
FTM Procedures
FTM_READ_ATTRIB_REQ_
This procedure allows you to read the file attributes of the previously selected file.
status := FTM_READ_ATTRIB_REQ_ ( cepi
, attrib-names
, [ tag ] ) ;
status
! I
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
attrib-names
input
INT .EXT:ref:(ZFTM-DDL-ATTR-NAMES)
specifies the names of the file attributes to be read.
attrib-names is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
Before calling this procedure, you must have negotiated the limited-filemanagement functional unit and the appropriate attribute groups on the
FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -126
FTM_READ_ATTRIB_REQ_
FTM Procedures
•
•
•
•
To complete this procedure call successfully, you must have previously called
FTM_SELECT_REQ_, and the association must be in the file-selection regime.
For the remote responder to respond affirmatively to the read-attributes primitive,
the read-attributes field of the permitted-actions attribute of this file must be set to
ON.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
The read-attribute field of the requested-access parameter of the select
request must be set to ON.
Errors
Table 4-37. Possible FTAM Initiator Errors for the FTM_READ_ATTRIB_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6024
ZFTM-ERR-ATTR-GRP-NOT-NEG
- 6025
ZFTM-ERR-PRIVATE-USE-NOT-SUPP
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -127
FTM_READ_ATTRIB_REQ_
FTM Procedures
The following table lists common errors that can occur on the
FTM_READ_ATTRIB_REQ_ procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the file-selection regime.
Error Code:
Error Subcode:
ZFTM-ERR-ACCESS-NOT-AVAIL (-6004)
ZFTM-ERR-ACCESS-READ-ATTR (-6)
The requestedaccess parameter on
the previous
FTM_CREATE_REQ_
or
FTM_SELECT_REQ_
call for this association
did not have the
ZREADATTR field set to
ZAPS-VAL-TRUE. You
must request readattribute access when
selecting the file.
Error Code:
ZFTM-ERR-ATTR-GRP-NOT-NEG (-6024)
You requested an
attribute in attribnames that is in an
attribute group that was
not negotiated.
Error Code:
ZFTM-ERR-PRIVATE-USE-NOT-SUPP (-6025)
You requested the
private-use attribute in
attrib-names. This
attribute is not
supported.
Examples
Examples of the FTM_READ_ATTRIB_REQ_ call in a program begin on line 815 of the
C version and line 912 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -128
FTM_READ_ATTRIB_CNF_
FTM Procedures
FTM_READ_ATTRIB_CNF_
This procedure allows you to retrieve the file attributes requested by the
FTM_READ_ATTRIB_REQ_ request.
error := FTM_READ_ATTRIB_CNF_ (
,
,
,
cepi
[ action-result ]
[ file-attrib ]
[ diagnostic ] ) ;
error
!
!
!
!
I
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value.
Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
file-attrib
output
INT .EXT:ref:(ZFTM-DDL-READ-ATTR)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -129
FTM_READ_ATTRIB_CNF_
FTM Procedures
contains values of the attributes associated with the file, returned by the remote
responder. For a description of these attributes, see the OSI/FTAM Programming
Guide.
The initiator limits the length of several of the file attributes and shortens any
attribute value that exceeds these limits. Therefore, if the responder returns a
value for an access-control password that is greater than 32 characters, the
initiator passes only the first 32 characters to the application, or in the case of a
filename attribute, if the value is greater than 128, the initiator passes only the first
128 characters to the application.
file-attrib is an optional parameter.
diagnostic output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, you must have previously called
FTM_SELECT_REQ_, and the association must be in the file-selection regime.
Before calling FTM_READ_ATTRIB_CNF_, you must call the following procedures:
FTM_READ_ATTRIB_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-READATTR- CNF event before calling
FTM_READ_ATTRIB_CNF_.
•
The attributes returned are dependent on responder support of the requested
attributes. The responder might not support all the attributes requested. In such a
case, the responder will give a legal value for those attributes supported and will
respond that no value is available for those attributes not supported.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -130
FTM_READ_ATTRIB_CNF_
FTM Procedures
Errors
Table 4-38. Possible FTAM Initiator Errors for the FTM_READ_ATTRIB_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_READ_ATTRIB_CNF_ call in a program begin on line 851 of the
C version and line 948 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -131
FTM_SELECT_REQ_
FTM Procedures
FTM_SELECT_REQ_
This procedure allows you to make a file available for access. You must have
previously established an association with a remote responder. This procedure initiates
the file-selection regime. For a description of the file-selection regime, see the
OSI/FTAM Programming Guide.
status := FTM_SELECT_REQ_ (
,
,
,
,
,
cepi
filename
[ requested-access ]
[ access-passwords ]
[ account ]
[ tag ] ) ;
status
!
!
!
!
!
!
I
I
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
filename
input
INT .EXT:ref:(ZAPS-DDL-CHAR128)
is the name of the file to be selected. The name should uniquely identify the file,
according to the requirements of the remote system. You can specify a maximum
of 128 characters for the file name.
filename is a required parameter.
requested-access
input
INT .EXT:ref:(ZFTM-DDL-REQUESTED-ACCESS)
specifies the level of access to the file you are requesting. The requested access
does not have to reflect full file-action capabilities as specified in the
permitted-actions field of the initial-attributes parameter of the create
request, but it must be a subset of these capabilities. The default access requested
will be ZREAD and ZREADATTR.
requested-access is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -132
FTM_SELECT_REQ_
FTM Procedures
access-passwords
input
INT .EXT:ref:(ZFTM-DDL-ACCESS-PASSWDS)
authenticates the actions requested in the requested-access parameter. To
successfully use this parameter, you must have first negotiated the security group
on the FTM_INITIALIZE_REQ_ call. If the remote responder requires access
passwords and the access passwords for the requested actions do not match the
responder’s access passwords, the responder will reject the file selection.
access-passwords is an optional parameter. If you do not supply
access-passwords, no passwords are sent to the remote responder.
account
input
INT .EXT:ref:(ZAPS-DDL-CHAR32)
identifies the account to be charged for costs that are incurred during the regime
being established.
account is an optional parameter. If you do not supply account, no account
name will be supplied to the remote responder.
Some responders require an account name. For information on the accounting
methods being used, refer to the responder documentation.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -133
FTM_SELECT_REQ_
FTM Procedures
Errors
Table 4-39. Possible FTAM Initiator Errors for the FTM_SELECT_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6003
ZFTM-ERR-ACCESS-INCNSTNT
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_SELECT_REQ_
procedure call.
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the FTAM regime.
Error Code:
ZFTM-ERR-ACCESS-INCNSTNT (-6003)
The requested-access
parameter values are
inconsistent with the
negotiated functional units
or inconsistent with the
contents-type of the
document being created.
The error subcode shows
which file access capability
is inconsistent.
Examples
Examples of the FTM_SELECT_REQ_ call in a program begin on line 808 of the C
version and line 905 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -134
FTM_SELECT_CNF_
FTM Procedures
FTM_SELECT_CNF_
This procedure allows you to retrieve results of the application’s request to make a file
available for access.
error := FTM_SELECT_CNF_ (
,
,
,
,
cepi
[ state-result ]
[ action-result ]
[ filename ]
[ diagnostic ] ) ;
error
!
!
!
!
!
I
O
O
O
O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
state-result
output
INT(32) .EXT:ref:1
indicates whether the responder established the file-selection regime as requested.
Valid values are as follows:
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
state-result is an optional parameter.
action-result output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -135
FTM_SELECT_CNF_
FTM Procedures
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
filename
output
INT .EXT:ref:(ZAPS-DDL-CHAR128)
is the name of the selected file as returned from the remote responder. The name
will be a maximum of 128 characters. If the responder returns a name that is
greater than 128 characters, the initiator passes only the first 128 characters to the
application.
filename is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
Before calling FTM_SELECT_CNF_, you must call the following procedures:
FTM_SELECT_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-SELECT-CNF event before calling FTM_SELECT_CNF_.
•
Depending on the value of state-result, the association moves to the
file-selection regime (ZFTM-VAL-ACTION-SUCCESS), or remains in the FTAM
regime (ZFTM-VAL-ACTION-FAILURE).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -136
FTM_SELECT_CNF_
FTM Procedures
Errors
Table 4-40. Possible FTAM Initiator Errors for the FTM_SELECT_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_SELECT_CNF_ call in a program begin on line 840 of the C
version and line 937 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -137
FTM_TERMINATE_REQ_
FTM Procedures
FTM_TERMINATE_REQ_
This procedure allows you to terminate an association with a remote responder. This
procedure terminates the FTAM regime. For a description of the FTAM regime, see the
OSI/FTAM Programming Guide.
status := FTM_TERMINATE_REQ_ ( cepi
, [ tag ] ) ;
status
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -138
FTM_TERMINATE_REQ_
FTM Procedures
Errors
Table 4-41. Possible FTAM Initiator Errors for the FTM_TERMINATE_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_TERMINATE_REQ_ procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the FTAM regime.
Examples
Examples of the FTM_TERMINATE_REQ_ call in a program begin on line 1251 of the
C version and line 1213 of the TAL version of Example 1, and on line 1489 of the C
version and line 1576 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -139
FTM_TERMINATE_CNF_
FTM Procedures
FTM_TERMINATE_CNF_
This procedure allows you to retrieve results of the application’s request to terminate
an association with a remote responder.
error := FTM_TERMINATE_CNF_ ( cepi
, [ charging ] ) ;
error
! I
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
charging
output
INT .EXT:ref:(ZFTM-DDL-CHARGING)
conveys information on the costs attributed to the account during the regime being
released. The charging parameter is present only if you provided the account
parameter on the FTM_INITIALIZE_REQ_ call.
charging is a list of triples, each of which contains a resource identifier, a
charging unit, and a charge value. If the responder returns a resource identifier or
charging unit that is greater than 16 characters, the initiator passes only the first 16
characters to the application.
charging is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the FTAM
regime.
Before calling FTM_TERMINATE_CNF_, you must call the following procedures:
FTM_TERMINATE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -140
FTM_TERMINATE_CNF_
FTM Procedures
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-TERMINATE-CNF event before calling FTM_TERMINATE_CNF_.
•
You should call APS_DISCARD_ to discard the association context after the
completion of the FTM_TERMINATE_CNF_ procedure call.
Errors
Table 4-42. Possible FTAM Initiator Errors for the FTM_TERMINATE_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_TERMINATE_CNF_ call in a program begin on line 766 of the C
version and line 1265 of the TAL version of Example 1, and on line 1503 of the C
version and line 1590 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -141
FTM_TRANSFER_END_REQ_
FTM Procedures
FTM_TRANSFER_END_REQ_
This procedure allows you to signify that no more data transfer is required. Before
calling this procedure, you must call the FTM_DATA_END_REQ_ or
FTM_DATA_END_IND_ procedure. This procedure terminates the data-transfer regime
and moves the association to the file-open regime. For a description of these regimes,
see the OSI/FTAM Programming Guide.
status := FTM_TRANSFER_END_REQ_ ( cepi
, [ tag ] ) ;
status
! I
! I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
For this procedure call to complete successfully, two conditions must be met:
°
The application must have previously called the FTM_DATA_END_IND_ or
FTM_DATA_END_REQ_ procedure.
°
The association must be in the data-transfer regime.
If you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call, you must
issue an MFM_AWAITIOX_ call to complete the nowait I/O operation.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -142
FTM_TRANSFER_END_REQ_
FTM Procedures
Errors
Table 4-43. Possible FTAM Initiator Errors for the FTM_TRANSFER_END_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6030
ZFTM-ERR-DATA-XFER-CANCELLED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the
FTM_TRANSFER_END_REQ_ procedure call.
These error
values...
Error Code:
Error Subcode:
are returned if....
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not in
the data-transfer regime,
or you have called
FTM_TRANSFER_END_
REQ_ before calling
FTM_DATA_END_REQ_.
Examples
Examples of the FTM_TRANSFER_END_REQ_ call in a program begin on line 674 of
the C version and line 773 of the TAL version of Example 1, and on line 1275 of the C
version and line 1369 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -143
FTM_TRANSFER_END_CNF_
FTM Procedures
FTM_TRANSFER_END_CNF_
This procedure allows you to retrieve the responder’s response to the application’s
request to end the data-transfer regime. For a description of the data-transfer regime,
see the OSI/FTAM Programming Guide.
error := FTM_TRANSFER_END_CNF_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
! I
! O
! O
error return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value. Valid
values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-SUCCESS indicates that the operation was
successful. Even for a successful operation, the diagnostic parameter might
include one or more informative messages. A value of ZFTM-VAL-ACTIONFAILURE indicates that the operation was not successful, and diagnostic is
likely to contain one or more diagnostic messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -144
FTM_TRANSFER_END_CNF_
FTM Procedures
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
Considerations
•
•
To complete this procedure call successfully, the association must be in the
data-transfer regime.
Before calling FTM_TRANSFER_END_CNF_, you must call the following
procedures:
FTM_TRANSFER_END_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the confirm event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper confirm procedure to use to retrieve the data. You must receive the ZFTMVAL-EVT-TRANSEND-CNF event before calling FTM_TRANSFER_END_CNF_.
•
Receipt of the ZFTM-VAL-EVT-TRANSEND-CNF event returns the association to
the file-open regime.
Errors
Table 4-44. Possible FTAM Initiator Errors for the FTM_TRANSFER_END_CNF_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_TRANSFER_END_CNF_ call in a program begin on line 1179 of
the C version and line 1141 of the TAL version of Example 1, and on line 1281 of the C
version and line 1374 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -145
FTM_U_ABORT_REQ_
FTM Procedures
FTM_U_ABORT_REQ_
This procedure allows you to make a request to abort the association with a remote
responder. This procedure terminates all existing regimes.
status := FTM_U_ABORT_REQ_ (
,
,
,
cepi
[ action-result ]
[ diagnostic ]
[ tag ] ) ;
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
input
INT(32):value
allows you to summarize information available in the diagnostic parameter. The
action-result value is never less severe than the most severe diagnostic
value. Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
action-result is an optional parameter. If omitted, action-result defaults to
ZFTM-VAL-ACTION-SUCCESS. Because it is likely that a permanent error led to
the U-abort, you will probably most often assign the value ZFTM-VAL-ACTIONFAILURE to this parameter.
diagnostic
input
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that explains the reasons for termination of activity. For a
complete list of possible diagnostic values, see Appendix C, ISO FTAM Diagnostic
Messages. For more information on application-generated diagnostic messages,
see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -146
FTM_U_ABORT_REQ_
FTM Procedures
diagnostic is an optional parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
•
•
•
You can call the FTM_U_ABORT_REQ_ procedure at any time after a successful
F-INITIALIZE request.
You must issue an MFM_AWAITIOX_ call to complete the nowait I/O operation if
you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call.
After the FTM_U_ABORT_REQ_ procedure is successfully completed, the
association is lost, and the file storage system is left in an unknown state.
You should call the APS_DISCARD_ procedure call after completion of the
FTM_U_ABORT_REQ_ procedure call.
Errors
Table 4-45. Possible FTAM Initiator Errors for the FTM_U_ABORT_REQ_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_U_ABORT_REQ_ call in a program begin on line 932 of the C
version and line 895 of the TAL version of Example 1, and on line 1887 of the C
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -147
FTM Procedures
FTM_U_ABORT_REQ_
version and line 2066 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -148
FTM_U_ABORT_IND_
FTM Procedures
FTM_U_ABORT_IND_
This procedure allows you to retrieve information on the user abort generated by the
remote responder.
error := FTM_U_ABORT_IND_ ( cepi
, [ action-result ]
, [ diagnostic ] ) ;
error
! I
! O
! O
return value
INT
indicates the outcome of the call. For a list of defined values, see Appendix B,
NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
action-result
output
INT(32) .EXT:ref:1
summarizes information available in the diagnostic parameter. The actionresult value is never less severe than the most severe diagnostic value.
Valid values are the following:
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
A value of ZFTM-VAL-ACTION-FAILURE indicates that the operation was not
successful, and diagnostic is likely to contain one or more diagnostic
messages.
action-result is an optional parameter.
diagnostic
output
INT .EXT:ref:(ZFTM-DDL-DIAGNOSTIC)
provides information that qualifies the success or explains the failure of a
requested action. For a complete list of possible diagnostic values, see
Appendix C, ISO FTAM Diagnostic Messages.
diagnostic is an optional parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -149
FTM_U_ABORT_IND_
FTM Procedures
Considerations
•
•
To successfully complete this procedure call, you must have successfully issued
the F-INITIALIZE request and have a valid CEPI for the association.
Before calling FTM_U_ABORT_IND_, you must call the following procedures:
APS_EVENT_RECEIVE_
APS_STATUS_
You call APS_EVENT_RECEIVE_ to receive the indication event and
APS_STATUS_ to determine, via the APS_STATUS_ event-code parameter, the
proper indication procedure to use to retrieve the data. You must receive the
ZFTM-VAL-EVT-UABORT-IND event before calling FTM_U_ABORT_IND_.
•
•
When you receive the user abort indication, the association is lost, and the file
storage system is left in an unknown state.
You should call the APS_DISCARD_ procedure after completion of the
FTM_U_ABORT_IND_ procedure call.
Errors
Table 4-46. Possible FTAM Initiator Errors for the FTM_U_ABORT_IND_
Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
Examples
Examples of the FTM_U_ABORT_IND_ call in a program begin on line 802 of the C
version and line 1302 of the TAL version of Example 1 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -150
FTM_WRITE_REQ_
FTM Procedures
FTM_WRITE_REQ_
This procedure allows you to request transfer of data to the previously opened file. This
procedure initiates the data-transfer regime. For a description of the data-transfer
regime, see the OSI/FTAM Programming Guide.
status := FTM_WRITE_REQ_ (
,
,
,
cepi
fadu-operation
fadu-id
[ tag ] ) ;
status
!
!
!
!
I
I
I
I
return value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) used to identify the specific
association. Use the CEPI value returned from the FTM_INITIALIZE_REQ_
procedure for this association. For additional information on using the cepi
parameter, see the OSI/FTAM Programming Guide.
cepi is a required parameter.
fadu-operation
input
INT (32):value
specifies what action the responder should take with data it receives. Valid values
are the following:
ZFTM-VAL-FADU-OP-INSERT
ZFTM-VAL-FADU-OP-REPLACE
ZFTM-VAL-FADU-OP-EXTEND
where the value ZFTM-VAL-FADU-OP-INSERT is valid only for FTAM-2 files, and
the values ZFTM-VAL-FADU-OP-REPLACE and ZFTM-VAL-FADU-OP-EXTEND
are valid for FTAM-1 and FTAM-3 files.
fadu-operation is a required parameter.
fadu-id
input
INT .EXT:ref:(ZFTM-DDL-FADU-ID)
specifies the target FADU. This value depends on the document type of the file.
Valid values are the following:
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -151
FTM_WRITE_REQ_
FTM Procedures
ZFTM-VAL-FADUID-FIRST for the ZFIRSTLAST field. This value specifies the
beginning of the first FADU after the root FADU and applies only to FTAM-1
and FTAM-3 document types.
ZFTM-VAL-FADUID-END for the ZBEGINEND field. This value specifies the
end of the last FADU and applies only to FTAM-2 document types.
fadu-id is a required parameter.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
procedure returns the tag value, allowing your application to match the completion
with the correct instance of the procedure call. For details on the use of the tag
parameter, see the OSI/FTAM Programming Guide.
tag is an optional parameter.
Considerations
•
To successfully complete this procedure call, these conditions must be met:
°
°
•
•
•
•
The association must be in the file-open regime.
You must have negotiated the write functional unit and a service class other
than the file-management service class when the association was established
via the FTM_INITIALIZE_REQ_ call.
For the responder to respond affirmatively to the write-request primitive, either the
replace, insert, or extend field of the permitted-actions field of the file must be set
to ON.
If you set the nowait operating mode in the FTM_INITIALIZE_REQ_ call, you must
issue an MFM_AWAITIOX_ call to complete the nowait I/O operation.
Completion of the FTM_WRITE_REQ_ procedure call transfers the application to
the data-transfer regime.
This procedure applies only to the FTAM-1, FTAM-2, and FTAM-3 document types.
An application cannot write to NBS-9 files.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -152
FTM_WRITE_REQ_
FTM Procedures
Errors
Table 4-47. Possible FTAM Initiator Errors for the FTM_WRITE_REQ_ Procedure
Error Code
FTAM Initiator Error
- 6000
ZFTM-ERR-INTERNAL
- 6001
ZFTM-ERR-OUT-OF-SEQUENCE
- 6002
ZFTM-ERR-FU-NOT-NEGOTIATED
- 6006
ZFTM-ERR-FADU-ID-INVALID
- 6007
ZFTM-ERR-FADU-OP-INCNSTNT
- 6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
- 6017
ZFTM-ERR-INVALID-IF-VERSION
- 6018
ZFTM-ERR-INVALID-FIELD-VERSION
- 6019
ZFTM-ERR-BAD-APS-STATUS
- 6022
ZFTM-ERR-CONNECTION-ABORTED
- 6036
ZFTM-ERR-SU-ABORTED
For cause, effect, and recovery information on these errors, see Appendix B, NonStop
FTAM Initiator Error Messages.
The following table lists common errors that can occur on the FTM_WRITE_REQ_
procedure call.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -153
FTM_WRITE_REQ_
FTM Procedures
These error
values...
are returned if....
Error Code:
Error Subcode:
ZFTM-ERR-OUT-OF-SEQUENCE (-6001)
ZFTM-ERR-OOS-STATE-MACHINE (1)
The association is not
in the file-open regime.
Error Code:
ZFTM-ERR-FADU-ID-INVALID (-6006)
The FADU ID is
inconsistent with the
document type you
requested when
opening the file.
Error Code:
ZFTM-ERR- FADU-OP-INCNSTNT (-6007)
The value for faduoperation is
inconsistent with the
process-mode
parameter on the
previous
FTM_OPEN_REQ_
call. This error can also
be returned if the write
functional unit required
for the write service
was not negotiated
when the association
was established.
Error Code:
Error Subcode:
ZFTM-ERR- SERV-NOT-NEGOTIATED (-6012)
ZFTM-ERR-SERVICE-MGMT (-1)
The file-management
service class was
negotiated, and this
service class does not
permit writing files.
Examples
Examples of the FTM_WRITE_REQ_ call in a program begin on line 1144 of the C
version and line 1106 of the TAL version of Example 1, and on line 1123 of the C
version and line 1210 of the TAL version of Example 2 in Appendix G, NonStop FTAM
Programming Examples.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
4 -154
A
DDL Definitions
This appendix describes the Data Definition Language (DDL) for the data structures
used in parameters to the procedures described in Section 4, FTM Procedures.
This appendix covers the following topics:
Topic
Page
Types of DDL Definitions
A-1
Locating DDL Definitions
A-2
Basic Data Types
A-3
Parameter Structures
A-5
Named Values
A-37
Procedure Call Cross Reference Table
A-42
This appendix shows the information in DDL format. As part of the NonStop FTAM
product, you receive the data structures in three forms:
•
•
•
The DDL source code (in the files ZFTMDDL and ZAPSDDL), provided for
reference
The equivalent TAL code (in the files ZFTMTAL and ZAPSTAL), from which you
should source appropriate sections into your TAL programs
The equivalent C code (in the files ZFTMC and ZAPSC), from which you should
include appropriate sections in your C programs
Note that when the DDL compiler translates these definitions into TAL, it changes all
the hyphens in the names to circumflex characters (^) and appends “^DEF” to the end
of the definition. When it translates the definitions into C, the DDL compiler changes all
hyphens to underscores and also appends “_def” to the end of the definition.
Types of DDL Definitions
This appendix describes three major types of DDL definitions in ZFTMDDL and
ZAPSDDL:
•
Basic data types
Basic data types consist of ZAPSDDL structures used as “building blocks.” The
FTAM product uses these building blocks to create parameter structures.
•
Parameter structures (used as data types)
You use these structures to define some of the parameters to the APS and FTM
procedures. For example, within the first few pages of each programming example
in Appendix G, NonStop FTAM Programming Examples, you will find a section that
defines the structures used by the FTM procedures called in that program. These
data structures show how to access the information contained in the reference
parameters.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 1
Locating DDL Definitions
DDL Definitions
•
Named values
Named values identify specific values or sets of values that can be assigned to
parameters or parameter fields.
Status codes, error codes, and error subcodes that the APS and FTM procedures
return are defined in ZAPSDDL and ZFTMDDL. Appendix B, NonStop FTAM Initiator
Error Messages describes these items. The constants assigned to the diagnostics that
can be returned by a remote responder or a local initiator are described in Appendix C,
ISO FTAM Diagnostic Messages and Appendix D, NonStop FTAM Initiator Diagnostic
Messages.
Locating DDL Definitions
In the subsections on ZAPS and ZFTM parameter structures, the descriptions of DDL
data structures are listed alphabetically by DDL identifier. Most DDL data structures
contain data fields, and descriptions of these fields appear after the definition box;
explanations of the named value constants are embedded in the pertinent field
descriptions and appear in ascending numerical order. Named values are also
summarized in a subsection at the end of the appendix.
The identifiers of DDL data structures and named values are multiword mnemonics in
which words or abbreviations are separated by hyphens. The identifiers of structures
and values begin with either ZAPS- or ZFTM-, followed by an abbreviation indicating
the type of constant it is:
•
•
•
•
DDL-, for data structure
VAL-, for named value
DIAG-, for diagnostic message
ERR-, for FTAM initiator or OSI error code or subcode
Note. The error and diagnostic message identifiers (ERR- and DIAG-) are described in
Appendix B, NonStop FTAM Initiator Error Messages, and Appendix D, NonStop FTAM Initiator
Diagnostic Messages.
The remaining parts of the identifier describe what the data structure contains or what
the value semantically represents.
Data structure field identifiers are generally single-word mnemonics, although field
identifiers occasionally consist of two hyphenated words.
The subsections on parameter structures follow a dictionary format, with subheadings
on the even pages showing the first data structure described on the page, and
subheadings on the odd pages showing the last data structure described on the page.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 2
Basic Data Types
DDL Definitions
Basic Data Types
Some DDL data types build upon simple ZAPS or ZFTM data types. First-level data
types provide the lowest-level building blocks. Second-level data types are made from
one or more first-level data types.
First-Level Data Types
First-level data types can stand alone as data types or you can use them to create
more complex data-type levels.
ZAPS-DDL-BOOLEAN
defines the Boolean fields that the procedures use.
DEFINITION
ZAPS-DDL-BOOLEAN
TYPE BINARY 16.
The valid values are:
CONSTANT
CONSTANT
ZAPS-VAL-FALSE
ZAPS-VAL-TRUE
VALUE 0.
VALUE 1.
ZAPS-DDL-ENUM1
is a 16-bit signed enumerated value. For valid values, see the individual data
definitions for this type.
DEFINITION
ZAPS-DDL-ENUM1
TYPE BINARY 16.
ZAPS-DDL-INT1
is a 16-bit signed integer. For valid values, see the individual data definitions for
this type.
DEFINITION
ZAPS-DDL-INT1
TYPE BINARY 16.
ZAPS-DDL-INT2
is a 32-bit signed integer. For valid values, see the individual data definitions for
this type.
DEFINITION
ZAPS-DDL-INT2
TYPE BINARY 32.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 3
Second-Level Data Types
DDL Definitions
Second-Level Data Types
Second-level basic data types consist of one or more of the first-level data types
described in the previous subsection.
ZAPS-DDL-CHAR16
is a string of 16 ASCII characters. You can address them as a structure, as bytes,
or as integers.
DEFINITION
ZAPS-DDL-CHAR16.
02 ZLEN
02 ZC
02 ZS REDEFINES ZC.
03 ZI
02 ZB REDEFINES ZC
END
TYPE ZAPS-DDL-INT1.
PIC X(16).
TYPE BINARY 16 OCCURS 8 TIMES.
PIC X
OCCURS 16 TIMES
ZAPS-DDL-CHAR20
is a string of 20 ASCII characters. You can address them as a structure, as bytes,
or as integers.
DEFINITION ZAPS-DDL-CHAR20.
02 ZLEN
TYPE ZAPS-DDL-INT1.
02 ZC
PIC X(20).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16 OCCURS 10 TIMES.
02 ZB REDEFINES ZC
PIC X
OCCURS 20 TIMES.
END
ZAPS-DDL-CHAR32
is a string of 32 ASCII characters. You can address them as a structure, as bytes,
or as integers.
DEFINITION ZAPS-DDL-CHAR32.
02 ZLEN
TYPE ZAPS-DDL-INT1.
02 ZC
PIC X(32).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16 OCCURS 16 TIMES.
02 ZB REDEFINES ZC
PIC X
OCCURS 32 TIMES.
END
ZAPS-DDL-CHAR128
is a string of 128 ASCII characters. You can address them as a structure, as bytes,
or as integers.
DEFINITION ZAPS-DDL-CHAR128.
02 ZLEN
TYPE ZAPS-DDL-INT1.
02 ZC
PIC X(128).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16 OCCURS 64 TIMES.
02 ZB REDEFINES ZC
PIC X
OCCURS 128 TIMES.
END
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 4
Parameter Structures
DDL Definitions
ZAPS-DDL-ISPRESENT
indicates whether an optional parameter is present.
DEFINITION
ZAPS-DDL-ISPRESENT
TYPE ZAPS-DDL-ENUM1.
The valid values are:
CONSTANT
CONSTANT
ZAPS-VAL-ABSENT
ZAPS-VAL-PRESENT
VALUE 0.
VALUE 1.
ZAPS-DDL-OBJ-ID
is the ASN.1 object identifier used for the abstract syntax name, the transfer syntax
name, and the application context name. For more information, see ZAPS-DDLABSTRACT-SYN-NAME, ZAPS-DDL-TRANSFER-SYN-NAME, ZAPS-DDL-APPLCNTXT, ZFTM-DDL-CNTNTS-LIST, and ZFTM-DDL-CNTNTS-TYPE. The object
identifier must contain at least two elements. The value of the first element must be
less than 3, and the value of the second element must be less than 40; all other
elements must be less than 10,000.
DEFINITION
ZAPS-DDL-OBJ-ID.
02 ZNUM-ELEMENTS
TYPE ZAPS-DDL-INT1.
02 ZOBJ-ID
TYPE ZAPS-DDL-INT1 OCCURS 16 TIMES.
END
ZFTM-DDL-CHAR256
is a string of 256 ASCII characters. You can address them as a structure, as bytes,
or as integers.
DEFINITION
ZFTM-DDL-CHAR256.
02 ZLEN
TYPE ZAPS-DDL-INT1.
02 ZC
PIC X(256).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16
OCCURS 128 TIMES.
02 ZB REDEFINES ZC
PIC X
OCCURS 256 TIMES.
END
Parameter Structures
Structures from the ZAPSDDL and ZFTMDDL files are used to define some of the
parameters to the APS and FTAM procedures. The parameter structures these
procedures use as data types are named parenthetically in the parameter descriptions
in Section A, DDL Definitions. The following pages provide general information about
these structures. Following the DDL codes for each structure are explanations for the
individual fields in the structure and the values each field can assume. Named values
described in the field explanations are cross-referenced under Named Values on
page A-37.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 5
ZAPS Structures
DDL Definitions
ZAPS Structures
The first part of this subsection describes the APS data structures relevant to the
ZFTM structures presented later in this subsection. All APS structures begin with
ZAPS. The OSI/AS Programming Manual also documents these structures.
ZAPS-DDL-ABSTRACT-SYN-NAME
describes an ASN.1 abstract syntax.
DEFINITION
ZAPS-DDL-ABSTRACT-SYN-NAME
TYPE ZAPS-DDL-OBJ-ID.
ZAPS-DDL-AE-TITLE
defines an ACSE application entity title (AE title). You can use ZAPS-DDL-AETITLE to specify local and remote AE titles in the FTAM initialize service.
DEFINITION ZAPS-DDL-AE-TITLE.
02 ZAE-TITLE-TYPE
02 ZAE-TITLE-FORMAT2.
03 ZAE-QUALIFIER-ISPRESENT
03 ZAE-QUALIFIER
03 ZAP-TITLE
END
TYPE ZAPS-DDL-INT1.
TYPE ZAPS-DDL-ISPRESENT.
TYPE ZAPS-DDL-INT2.
TYPE ZAPS-DDL-OBJ-ID.
Valid values for ZAE-TITLE-TYPE are:
CONSTANT ZAPS-VAL-AE-TITLE-NOCONTENT
CONSTANT ZAPS-VAL-AE-TITLE-FORMAT0
CONSTANT ZAPS-VAL-AE-TITLE-FORMAT2
VALUE -1
VALUE 0
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
ZAE-TITLE-TYPE specifies the format of an AE title as one of the following:
ZAPS-VAL-AE-TITLE-NOCONTENT indicates that the AE title has no content
because it was received in format 1. OSI/AS does not support AE titles in format 1.
ZAPS-VAL-AE-TITLE-FORMAT0 indicates that the AE title is not present.
ZAPS-VAL-AE-TITLE-FORMAT2 identifies an AE title in format 2.
ZAE-TITLE-FORMAT2 specifies an AE title in format 2. It can contain either an
application entity qualifier, an application process title, or both:
ZAE-QUALIFIER-ISPRESENT specifies whether an application entity qualifier (AE
qualifier) is present. The value is either ZAPS-VAL-PRESENT or ZAPS-VALABSENT.
ZAE-QUALIFIER is the application entity qualifier, if present.
ZAP-TITLE is the application process title, if present.
ZAPS-DDL-APPL-ADDR
contains the OSI address and the locally assigned name of an application. You can
use this structure to specify local and remote (responder) application addresses
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 6
ZAPS Structures
DDL Definitions
when you establish an association. You can also use ZAPS-DDL-APPL-ADDR to
return the responding address on the association.
DEFINITION ZAPS-DDL-APPL-ADDR.
02 ZPSAP
TYPE ZAPS-DDL-PSAP.
02 ZAPPL-NAME
TYPE ZAPS-DDL-CHAR128.
END
ZPSAP is the OSI address of the application.
ZAPPL-NAME is the locally assigned application name.
ZAPS-DDL-APPL-CNTXT
is an ACSE application context name. To provide an application context name for
ISO FTAM, use this format: {iso standard 8571 application-context(1) iso ftam(1) }.
For this example, ZNUM-ELEMENTS can be set to 5, and ZOBJ-ID can be set to
{1 0 8571 1 1}.
DEFINITION
ZAPS-DDL-APPL-CNTXT TYPE
ZAPS-DDL-OBJ-ID.
ZAPS-DDL-CURRENT-ERROR
provides details of the error currently being reported.
DEFINITION
ZAPS-DDL-CURRENT-ERROR.
02 ZERROR-CODE
TYPE ZAPS-DDL-ERROR-CODE.
02 ZERROR-SUBCODE
TYPE ZAPS-DDL-ERROR-CODE.
02 ZSERVICE-ID
TYPE ZAPS-DDL-SERVICE-ID.
02 ZDIAG-BUF
TYPE ZAPS-DDL-DIAG-BUF.
END
ZERROR-CODE identifies the error being reported. For descriptions of errors reported
by the FTAM initiator or FTAM API, refer to Appendix B, NonStop FTAM Initiator Error
Messages; for errors reported by OSI services below the FTAM level, refer to the
OSI/AS Programming Manual.
ZERROR-SUBCODE further qualifies the error being reported. The interpretation of
this field depends on the value in ZERROR-CODE. For descriptions of subcodes
associated with errors reported by the FTAM initiator or FTAM API, refer to
Appendix B, NonStop FTAM Initiator Error Messages; for subcodes of errors reported
by OSI services below the FTAM level, refer to the OSI/AS Programming Manual.
ZSERVICE-ID identifies the entity reporting the error. For possible values, see ZAPSDDL-SERVICE-ID.
ZDIAG-BUF is a diagnostic buffer. The format of this buffer is considered HP internal.
ZAPS-DDL-DATA-ELEMENT-HDR
describes the length and type of a data element in the data parameter. FTAM
implements this structure differently from OSI/AS: the ZTYPE constants have
different values and the ZPCID is not used. For more information on the use of
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 7
ZAPS Structures
DDL Definitions
data element headers, refer to the OSI/FTAM Programming Guide and ZAPS-DDLDATA-HDR in this subsection.
DEFINITION
ZAPS-DDL-DATA-ELEMENT-HDR.
02 ZLEN
TYPE ZAPS-DDL-INT2.
02 ZTYPE
TYPE ZAPS-DDL-ENUM1.
*02 ZPCID
TYPE ZAPS-DDL-PRES-CNTXT-ID.
02 FILLER
PIC X(18).
END
The only valid values of ZTYPE are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-DE-NOTSUPPORTED
ZFTM-VAL-DE-FADU
ZFTM-VAL-DE-TEXT
ZFTM-VAL-DE-BINARY
ZFTM-VAL-DE-DIRECTORY
* DEFINITION
ZAPS-DDL-PRES-CNTXT-ID
VALUE
VALUE
VALUE
VALUE
VALUE
1.
2.
3.
4.
5.
TYPE ZAPS-DDL-INT1.
ZLEN defines the length in bytes of the data in this element, excluding the header and
pad byte, if one is needed. For more information on pad bytes, see the OSI/FTAM
Programming Guide.
ZTYPE specifies the type of data in this element as follows:
ZFTM-VAL-DE-NOTSUPPORTED is reserved.
ZFTM-VAL-DE-FADU represents a structuring data element that can be either a
node descriptor data element, an enter subtree data element, or an exit subtree
data element. Only FTAM-2 in the “FA” access context uses this data element. (For
more information on the data type used for FTAM structuring data elements, see
ZFTM-DDL-DE-FADU on page A-26.)
ZFTM-VAL-DE-TEXT indicates that each element consists of a string of characters.
FTAM-1 and FTAM-2 files use this data element.
ZFTM-VAL-DE-BINARY indicates that each element consists of a string of octets.
FTAM-3 uses this data element.
ZFTM-VAL-DE-DIRECTORY indicates that each element consists of the file read
attributes of a directory entry. NBS-9 files use this data element. Only
FTM_DATA_IND_ calls can use ZFTM-VAL-DE-DIRECTORY because NBS-9 files
cannot be written.
FILLER is not used by FTAM.
ZAPS-DDL-DATA-HDR
is the header of the data parameter. For more information, refer to the OSI/FTAM
Programming Guide and ZAPS-DDL-DATA-ELEMENT-HDR in this subsection.
DEFINITION
ZAPS-DDL-DATA-HDR.
02 ZNUM-ELEMENTS
TYPE ZAPS-DDL-INT1.
02 FILLER
PIC X(14).
END
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 8
ZAPS Structures
DDL Definitions
The value of ZNUM-ELEMENTS specifies the number of data elements in the data
parameter.
ZAPS-DDL-DIAG-BUF
is a diagnostic buffer that conveys additional information helpful in analyzing the
problem being reported. The format of this structure is considered HP internal.
DEFINITION
ZAPS-DDL-DIAG-BUF.
02 ZC
PIC X(64).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16
02 ZB REDEFINES ZC
PIC X
END
OCCURS 32 TIMES.
OCCURS 64 TIMES.
ZAPS-DDL-ERROR-CODE
identifies the type of APS error that occurred. For the values and descriptions of
the APS error codes, refer to Appendix B, NonStop FTAM Initiator Error Messages.
DEFINITION
ZAPS-DDL-ERROR-CODE
TYPE ZAPS-DDL-INT1.
ZAPS-DDL-ERROR-CODE is the ZAPS error code number.
ZAPS-DDL-FILENAME
is the data type for a file name in internal format. ZAPS-DDL-FILENAME is not
used to define FTAM file names; use it to define the names of Guardian processes,
such as APLMGR.
DEFINITION
ZAPS-DDL-FILENAME.
02 ZC
PIC X(24).
02 ZS REDEFINES ZC.
03 ZI
TYPE BINARY 16 OCCURS 12 TIMES.
02 ZB REDEFINES ZC
PIC X
OCCURS 24 TIMES.
END
ZAPS-DDL-ORIGINAL-ERROR
tells you the first error that was detected in the current error situation.
DEFINITION
ZAPS-DDL-ORIGINAL-ERROR.
02 ZDEVICE-NAME
TYPE ZAPS-DDL-FILENAME.
02 ZERROR
TYPE ZAPS-DDL-CURRENT-ERROR.
END
ZDEVICE-NAME contains the fully qualified device name of the entity that originally
detected the error, including the subdevice, if applicable. If not applicable, this field is
blank.
ZERROR contains details of the error originally detected and identifies the service that
detected it.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A- 9
ZAPS Structures
DDL Definitions
ZAPS-DDL-PSAP
defines a presentation service access point address. It contains the OSI address of
an application process.
DEFINITION
ZAPS-DDL-PSAP.
02 ZPSEL
02 ZSSEL
02 ZTSEL
02 ZNSAP
END
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-CHAR16.
ZAPS-DDL-CHAR16.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR20.
ZPSEL is the presentation selector address.
ZSSEL is the session selector address.
ZTSEL is the transport selector address. It defines a user of the Transport Layer
service.
ZNSAP is the network service access point. It is unique in an OSI network and is
defined by an authority of the network.
ZAPS-DDL-SERVICE-ID
identifies a service within the NonStop FTAM or OSI/AS subsystem that is the
source of an error.
DEFINITION ZAPS-DDL-SERVICE-ID
TYPE
ZAPS-DDL-ENUM1.
The valid values are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZAPS-VAL-SERVICE-NOVALUE
ZAPS-VAL-SERVICE-APS
ZAPS-VAL-SERVICE-SESSION
ZAPS-VAL-SERVICE-PRESENTATION
ZAPS-VAL-SERVICE-ACSE
ZAPS-VAL-SERVICE-FTAM
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
0.
1.
5.
6.
7.
8.
ZAPS-DDL-SERVICE-ID can take one of the following values:
ZAPS-VAL-SERVICE-NOVALUE shows that no service is reported.
ZAPS-VAL-SERVICE-APS indicates that the source of the error is the OSI/AS API.
ZAPS-VAL-SERVICE-SESSION indicates that the source of the error is the
session service.
ZAPS-VAL-SERVICE-PRESENTATION indicates that the source of the error is the
presentation service.
ZAPS-VAL-SERVICE-ACSE indicates that the source of the error is the ACSE
service.
ZAPS-VAL-SERVICE-FTAM indicates that the source of the error is the FTAM API
or initiator.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -10
ZAPS Structures
DDL Definitions
ZAPS-DDL-SWAP-VOLUME
defines the name of a disk to be used as a swap volume for the API segment.
DEFINITION ZAPS-DDL-SWAP-VOLUME.
02 ZC
PIC X(8).
END
ZAPS-DDL-TRANSFER-SYN-NAME
describes an ASN.1 transfer syntax.
DEFINITION
ZAPS-DDL-TRANSFER-SYN-NAME
TYPE ZAPS-DDL-OBJ-ID.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -11
ZFTM Structures
DDL Definitions
ZFTM Structures
The following subsection describes the FTAM structures that define reference
parameters for FTAM procedures. All FTAM structures begin with ZFTM.
ZFTM-DDL-ACCESS-CNTRL-ATTR
is the file attribute that defines the conditions under which access to the file is
allowed.
DEFINITION ZFTM-DDL-ACCESS-CNTRL-ATTR.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZACCESSCNTRL
TYPE ZFTM-DDL-ACCESS-CNTRL-ELEM.
END
The valid values for ZID are:
CONSTANT ZFTM-VAL-ATTR-NOVALUE
CONSTANT ZFTM-VAL-ATTR-ISPRESENT
VALUE 0.
VALUE 1.
ZID indicates whether the ZACCESSCNTRL value is available. The ZID field of this
structure is not used in initiator requests and indications. The following values for this
field are possible:
ZFTM-VAL-ATTR-NOVALUE indicates that the application did not return a value for
the attribute.
ZFTM-VAL-ATTR-ISPRESENT indicates that an attribute value is present.
ZACCESSCNTRL contains the information that controls file access.
ZFTM-DDL-ACCESS-CNTRL-CHNG
indicates whether ZFTM-DDL-ACCESS-CNTRL-ELEM values are to be changed
(inserted, deleted, or both) and what the changed values are.
DEFINITION ZFTM-DDL-ACCESS-CNTRL-CHNG.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZINSERTISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZINSERTVALUES
TYPE ZFTM-DDL-ACCESS-CNTRL-ELEM.
02 ZDELETEISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZDELETEVALUES
TYPE ZFTM-DDL-ACCESS-CNTRL-ELEM.
END
ZID indicates whether the application is to make an insertion or deletion of access
control information. ZID has two possible values: ZFTM-VAL-ATTR-NOVALUE in cases
in which no change is to be made, and ZFTM-VAL-ATTR-ISPRESENT in cases in
which insertion or deletion of access control information is expected.
ZINSERTISPRESENT indicates whether the application program is to insert
access-control information.
ZINSERTVALUES contains the access-control attribute values to be inserted.
ZDELETEISPRESENT indicates whether the application program is to delete
access-control information.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -12
ZFTM Structures
DDL Definitions
ZDELETEVALUES contains the access-control element values to be deleted.
ZFTM-DDL-ACCESS-CNTRL-ELEM
contains the information used to determine when an application can access a file.
DEFINITION ZFTM-DDL-ACCESS-CNTRL-ELEM.
02 ZACTIONLIST
TYPE ZFTM-DDL-REQUESTED-ACCESS.
02 ZCONCURRENCYISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZCONCURRENCYACCESS
TYPE ZFTM-DDL-CONCURRENCY.
02 ZIDENTITYISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZIDENTITY
TYPE ZAPS-DDL-CHAR32.
02 ZPASSWDSISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZPASSWDS
TYPE ZFTM-DDL-ACCESS-PASSWDS.
02 ZLOCATIONISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZLOCATION
TYPE ZAPS-DDL-AE-TITLE.
END
ZACTIONLIST lists the actions that an application can perform on the file.
ZCONCURRENCYISPRESENT indicates whether the concurrency access field is
specified.
ZCONCURRENCYACCESS indicates what actions an application can perform
concurrently on the file.
ZIDENTITYISPRESENT indicates whether the identity is specified.
ZIDENTITY contains the identity granted access to the file. Note that if the responder
returns a value for the identity that is greater than 32 characters, the initiator passes
only the first 32 characters to the application.
ZPASSWDSISPRESENT indicates whether passwords are specified to authenticate
the identity.
ZPASSWDS lists the passwords associated with each of the actions in the action list.
ZLOCATIONISPRESENT indicates whether an application entity (AE) title is present.
ZLOCATION specifies the AE title required to gain access to the file. This AE title must
match the one specified on the initialize request that establishes the FTAM regime.
ZFTM-DDL-ACCESS-CNTXT
specifies the access context of a file on the FTM_READ_REQ_ procedure call. It
tells you how the file is organized internally.
DEFINITION ZFTM-DDL-ACCESS-CNTXT.
02 ZCNTXT
TYPE ZAPS-DDL-INT2.
02 ZLEVELNUMISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZLEVELNUM
TYPE ZAPS-DDL-INT2.
END
The valid values for ZCNTXT are:
CONSTANT
CONSTANT
ZFTM-VAL-ACCESSCNTXT-FA
ZFTM-VAL-ACCESSCNTXT-UA
VALUE 2
VALUE 5
TYPE BINARY 32.
TYPE BINARY 32.
ZCNTXT indicates the access context. The following values are valid for ZCNTXT:
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -13
ZFTM Structures
DDL Definitions
ZFTM-VAL-ACCESSCNTXT-FA, Flat All Data Units. According to this access
context, Node-Descriptor-Data-Elements and File-Contents-Data-Elements from
the addressed FADU are transferred.
ZFTM-VAL-ACCESSCNTXT-UA, Unstructured All Data Units. According to this
access context, only File-Contents-Data-Elements from the addressed FADU are
transferred.
ZLEVELNUMISPRESENT indicates if a level number value is present. The value of
this field is always ZAPS-VAL-ABSENT.
ZLEVELNUM provides an optional level number which is used to limit access to a
specified level. This field applies only to the ZFTM-VAL-ACCESSCNTXT-FL access
context, which is not used in this implementation.
ZFTM-DDL-ACCESS-PASSWDS
contains the set of passwords used on the select, create, read attributes, and
change attributes services to control access to files for various activities. Note that
if the responder returns a value for a password that is greater than 32 characters,
the initiator passes only the first 32 characters to the application.
DEFINITION ZFTM-DDL-ACCESS-PASSWDS.
02 ZREADPASSWD
TYPE
02 ZINSERTPASSWD
TYPE
02 ZREPLACEPASSWD
TYPE
02 ZEXTENDPASSWD
TYPE
02 ZERASEPASSWD
TYPE
02 ZREADATTRPASSWD
TYPE
02 ZCHNGATTRPASSWD
TYPE
02 ZDELETEPASSWD
TYPE
END
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZAPS-DDL-CHAR32.
ZREADPASSWD contains the password that allows you to read the file.
ZINSERTPASSWD contains the password that allows you to insert data into the file.
ZREPLACEPASSWD contains the password that allows you to replace data in the file.
ZEXTENDPASSWD contains the password that allows you to extend the file.
ZERASEPASSWD contains the password that allows you to erase some or all the file
contents.
ZREADATTRPASSWD contains the password that allows you to read the file
attributes.
ZCHNGATTRPASSWD contains the password that allows you to change the file
attributes.
ZDELETEPASSWD contains the password that allows you to delete the file.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -14
ZFTM Structures
DDL Definitions
ZFTM-DDL-ACCOUNT-ATTR
defines a file attribute that identifies the account to be charged for FTAM use.
DEFINITION ZFTM-DDL-ACCOUNT-ATTR.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZACCOUNT
TYPE ZAPS-DDL-CHAR32.
END
ZID indicates whether a ZACCOUNT value is available. The ZID field of this structure
is not used in initiator requests and indications. ZID has two possible values:
ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT.
ZACCOUNT specifies the identity of the account. Valid values for ZACCOUNT depend
upon the installation.
ZFTM-DDL-ATTR-GROUPS
indicates which groups of attributes are available for use in the FTAM regime. You
can use this structure on the initialize request and confirm services.
DEFINITION ZFTM-DDL-ATTR-GROUPS.
02 ZSTORAGE
TYPE ZAPS-DDL-BOOLEAN.
02 ZSECURITY
TYPE ZAPS-DDL-BOOLEAN.
02 ZPRIVATE
TYPE ZAPS-DDL-BOOLEAN.
END
ZSTORAGE specifies whether the storage attribute group is available. The storage
attribute group includes the following file attributes that give information about a file:
Storage account
Date and time of creation
Date and time of last modification
Date and time of last read access
Date and time of last attribute modification
Identity of creator
Identity of last modifier
Identity of last reader
Identity of last attribute modifier
File availability
Filesize
Future filesize
ZSECURITY specifies whether the security attribute group is available. The security
attribute group includes the following file attributes that regulate file security and
access:
Access control
Legal qualifications
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -15
ZFTM Structures
DDL Definitions
ZPRIVATE specifies whether the private attribute group is available. Because NonStop
FTAM does not support the private attribute group, always set this field to
ZAPS-VAL-FALSE.
ZFTM-DDL-ATTR-NAMES
identifies the file attributes that you wish the responder to return when you issue an
FTM_READ_ATTRIB_REQ_ procedure call. This structure is also used in NBS-9
operations to specify the file attributes of the contents-type (ZFILEATTRS field of
ZDOCTYPE in ZFTM-DDL-CNTNTS-TYPE). Requesting an attribute that is part of
a non-negotiated attribute group is not valid and results in an error. For a more
detailed description of file attributes, refer to the OSI/FTAM Programming Guide.
DEFINITION ZFTM-DDL-ATTR-NAMES.
02 ZFILENAME
02 ZPERMITTEDACTIONS
02 ZCNTNTSTYPE
02 ZSTORAGEACCOUNT
02 ZCREATION
02 ZLASTMOD
02 ZLASTREADACCESS
02 ZLASTATTRMOD
02 ZCREATORID
02 ZLASTMODID
02 ZLASTREADERID
02 ZLASTATTRMODID
02 ZFILEAVLBLTY
02 ZFILESIZE
02 ZFUTUREFILESIZE
02 ZACCESSCNTRL
02 ZLEGALQUALIF
02 ZPRIVATEUSE
END
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZFILENAME requests the file name.
ZPERMITTEDACTIONS requests the actions permitted on the file.
ZCNTNTSTYPE requests the file contents type.
ZSTORAGEACCOUNT requests the identity of the storage account.
ZCREATION requests the date and time the file was created.
ZLASTMOD requests the date and time the file was last modified.
ZLASTREADACCESS requests the date and time the file was last read.
ZLASTATTRMOD requests the date and time the file attributes were last modified.
ZCREATORID requests the identity of the file creator.
ZLASTMODID requests the identity of the individual who last modified the file.
ZLASTREADERID requests the identity of the individual who last read the file.
ZLASTATTRMODID requests the identity of the individual who last modified the file
attributes.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -16
ZFTM Structures
DDL Definitions
ZFILEAVLBLTY requests the file availability status.
ZFILESIZE requests the file size.
ZFUTUREFILESIZE requests the future file size.
ZACCESSCNTRL requests the access control specifications.
ZLEGALQUALIF requests the legal status of the file.
ZPRIVATEUSE requests the private use attribute. This attribute is not used.
ZFTM-DDL-CHANGE-ATTR
specifies the attributes you wish to change, along with their new values, when you
issue the FTM_CHANGE_ATTRIB_REQ_ procedure call. This structure is also
used in the FTM_CHANGE_ATTRIB_CNF_ procedure to return the new values for
the file attributes that were changed by the remote responder. For a more detailed
description of file attributes, refer to the OSI/FTAM Programming Guide.
DEFINITION ZFTM-DDL-CHANGE-ATTR.
02 ZATTRSAREPRESENT
* Kernel group
02 ZFILENAMEISPRESENT
02 ZFILENAME
* Storage group
02 ZSTORAGEACCOUNTISPRESENT
02 ZSTORAGEACCOUNT
02 ZFILEAVLBLTYATTRISPRESENT
02 ZFILEAVLBLTYATTR
02 ZFUTUREFILESIZEISPRESENT
02 ZFUTUREFILESIZE
* Security group
02 ZACCESSCNTRLISPRESENT
02 ZACCESSCNTRL
02 ZLEGALQUALIFISPRESENT
02 ZLEGALQUALIFICATION
TYPE ZAPS-DDL-ISPRESENT.
TYPE ZAPS-DDL-ISPRESENT.
TYPE ZAPS-DDL-CHAR128.
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCOUNT-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILEAVLBLTY-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILESIZE-ATTR.
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCESS-CNTRL-CHNG.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-LEGALQUALIF-ATTR.
END
ZATTRSAREPRESENT indicates whether attributes are present.
ZATTRSAREPRESENT must be set to ZAPS-VAL-PRESENT when issuing an
FTM_CHANGE_ATTRIB_REQ_ call. ZATTRSAREPRESENT is used in the
FTM_CHANGE_ATTRIB_CNF_ call to indicate whether the remote responder returned
any of the changed parameters.
ZFILENAMEISPRESENT indicates whether the file name is to be changed.
ZFILENAME contains the new file name. If the responder returns a value for the
filename attribute that is greater than 128 characters, the initiator passes only the first
128 characters to the application.
ZSTORAGEACCOUNTISPRESENT indicates whether the identity of the storage
account value is to be changed.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -17
ZFTM Structures
DDL Definitions
ZSTORAGEACCOUNT identifies the storage account to be used for tracking
FTAM-use charges.
ZFILEAVLBLTYATTRISPRESENT indicates whether the file availability status is to be
changed.
ZFILEAVLBLTYATTR specifies immediate or deferred file availability.
ZFUTUREFILESIZEISPRESENT indicates whether the future file size value is to be
changed.
ZFUTUREFILESIZE contains the future file size value.
ZACCESSCNTRLISPRESENT indicates whether access control specifications are to
be changed.
ZACCESSCNTRL contains the changes that are to be made to the access control
elements that define the conditions under which access to a file is allowed.
ZLEGALQUALIFISPRESENT indicates whether a legal qualification specification is to
be changed.
ZLEGALQUALIFICATION conveys information about the legal status of the file. Its use
depends on the implementation of the responder.
ZFTM-DDL-CHARGING
reports the charges incurred in the regime being released. This is an optional
output parameter returned only if a storage account was specified when the regime
was established.
DEFINITION ZFTM-DDL-CHARGING.
02 ZCOUNT
02 ZCHARGINGISPRESENT
02 ZCHARGING
03 ZRESOURCEID
03 ZCHARGEUNIT
03 ZCHARGEVALUE
END
TYPE ZAPS-DDL-INT1.
TYPE ZAPS-DDL-ISPRESENT.
OCCURS 10 TIMES.
TYPE ZAPS-DDL-CHAR16.
TYPE ZAPS-DDL-CHAR16.
TYPE ZAPS-DDL-INT2.
ZCOUNT indicates how many charging elements—triples including resourceid,
chargeunit, and chargevalue—are included in the list. The maximum number allowed is
10.
ZCHARGINGISPRESENT indicates whether a charging value is present.
ZCHARGING is implementation dependent. Charges are made only when there is an
account specified. This field specifies the values for each charging element, as follows:
ZRESOURCEID contains the identity of the resource being charged. The
resources available depend on the implementation. If the responder returns a
value for the resource identity that is greater than 16, the initiator passes only the
first 16 characters to the application.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -18
ZFTM Structures
DDL Definitions
ZCHARGEUNIT specifies the units used for measuring charges. The unit depends
on the implementation. If the responder returns a value for the unit of
measurement that is greater than 16, the initiator passes only the first 16
characters to the application.
ZCHARGEVALUE indicates how many of the units specified in ZCHARGEUNIT
are to be charged.
ZFTM-DDL-CNTNTS-LIST
is the contents-type-list parameter. It tells what document types are
available for negotiating presentation context. For more information about the
presentation context, refer to the OSI/AS Programming Manual.
DEFINITION ZFTM-DDL-CNTNTS-LIST.
02 ZCOUNT
02 ZCNTNTS-TYPE-ISPRESENT
02 ZCNTNTS-TYPE-LIST
03 ZID
03 ZCNTNTSTYPE
03 ZDOCTYPENAME
03 ZASNAME
TYPE ZAPS-DDL-INT1.
TYPE ZAPS-DDL-ISPRESENT.
OCCURS 10 TIMES.
TYPE ZAPS-DDL-ENUM1.
TYPE ZAPS-DDL-OBJ-ID.
REDEFINES ZCNTNTSTYPE
TYPE ZAPS-DDL-OBJ-ID.
REDEFINES ZCNTNTSTYPE
TYPE ZAPS-DDL-OBJ-ID.
END
Valid values for ZID are:
CONSTANT ZFTM-VAL-CNTNTSLIST-NOVALUE
CONSTANT ZFTM-VAL-CNTNTSLIST-DOCNAME
CONSTANT ZFTM-VAL-CNTNTSLIST-ASNAME
VALUE 0.
VALUE 1.
VALUE 2.
ZCOUNT indicates how many document type names the contents type list contains.
The maximum number is 10.
ZCNTNTS-TYPE-ISPRESENT indicates whether a contents-type list is present.
ZCNTNTS-TYPE-LIST contains the following information for each element in the
contents-type list:
ZID identifies whether a document name is specified. Valid values include:
ZFTM-VAL-CNTNTSLIST-NOVALUE indicates that no value is present for the
contents-type-list element.
ZFTM-VAL-CNTNTSLIST-DOCNAME indicates that a document name is
present for the contents-type-list element. The corresponding attribute
identifies the document name.
ZFTM-VAL-CNTNTSLIST-ASNAME is reserved, and application programs
should not use it.
ZCNTNTSTYPE identifies the abstract data type of the contents of the file.
ZDOCTYPENAME contains the document type name.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -19
ZFTM Structures
DDL Definitions
ZASNAME is reserved, and application programs should not use it.
ZFTM-DDL-CNTNTS-TYPE
specifies the contents type of an abstract data type file when an application opens
the file.
DEFINITION ZFTM-DDL-CNTNTS-TYPE.
02 ZID
02 ZCNTNTSTYPE
TYPE ZAPS-DDL-ENUM1.
TYPE ZAPS-DDL-CHAR128.
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.
TYPE ZAPS-DDL-ISPRESENT.
TYPE ZAPS-DDL-INT2.
TYPE ZAPS-DDL-ISPRESENT.
TYPE ZFTM-DDL-ATTR-NAMES.
02 ZCONSTRAINTSETASNAME
03 ZCONSTRAINTSETNAME
03 ZASNAME
REDEFINES ZCNTNTSTYPE.
TYPE ZAPS-DDL-OBJ-ID.
TYPE ZAPS-DDL-OBJ-ID.
END
The valid values for ZID are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-CNTNTSTYPE-NOVALUE
ZFTM-VAL-CNTNTSTYPE-DOCTYPE
ZFTM-VAL-CNTNTSTYPE-CNSTRTAS
ZFTM-VAL-CNTNTSTYPE-UNKNOWN
VALUE
VALUE
VALUE
VALUE
0.
1.
2.
3.
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
19
20
21
22
25
26
27
The valid values for ZUNIVERSALCLASS are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-UC-PRINTABLE-STRING
ZFTM-VAL-UC-TELETEX-STRING
ZFTM-VAL-UC-VIDEOTEX-STRING
ZFTM-VAL-UC-IA5-STRING
ZFTM-VAL-UC-GRAPHIC-STRING
ZFTM-VAL-UC-VISIBLE-STRING
ZFTM-VAL-UC-GENERAL-STRING
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
BINARY
BINARY
BINARY
BINARY
BINARY
BINARY
BINARY
32.
32.
32.
32.
32.
32.
32.
The valid values for ZSTRINGSIG are:
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-STRINGSIG-VARIABLE
ZFTM-VAL-STRINGSIG-FIXED
ZFTM-VAL-STRINGSIG-NOTSIG
VALUE 0
VALUE 1
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
ZID indicates whether the file has a ZCNTNTSTYPE or a ZDOCTYPE value. Valid
values include:
ZFTM-VAL-CNTNTSTYPE-NOVALUE indicates that no value is present for the
contents type.
ZFTM-VAL-CNTNTSTYPE-DOCTYPE indicates that a document type value is
present for the contents type. The ZDOCTYPE field identifies the document type.
ZFTM-VAL-CNTNTSTYPE-CNSTRTAS indicates that a constraint set and abstract
syntax name is present for the contents type. The ZCONSTRAINTSETASNAME
field identifies the constraint set and abstract syntax name.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -20
ZFTM Structures
DDL Definitions
ZFTM-VAL-CNTNTSTYPE-UNKNOWN indicates that the contents type is
unknown.
ZCNTNTSTYPE allocates space for the contents type information redefined by
ZDOCTYPE; application programs do not need to access this structure.
ZDOCTYPE contains the following document type parameters that an application can
access:
ZDOCTYPENAME specifies the document type name.
ZUNIVERSALCLASSISPRESENT indicates whether a universal class value is
present.
ZUNIVERSALCLASS indicates the value of the universal class for FTAM-1 and
FTAM-2 document types and tells you what type of text string the file contains.
Refer to ISO 8824 for additional information about these character-string types.
Valid values are:
ZFTM-VAL-UC-PRINTABLE-STRING (Class 19) indicates that the strings
contain only printable characters and the space character, as defined in ISO
8824. These strings do not contain format effectors.
ZFTM-VAL-UC-TELETEX-STRING (Class 20) indicates that the strings
conform to CCITT Recommendation T.61. These strings can contain format
effectors.
ZFTM-VAL-UC-VIDEOTEX-STRING (Class 21) indicates that the strings
conform to CCITT Recommendation T.100. These strings can contain format
effectors.
ZFTM-VAL-UC-IA5-STRING (Class 22) indicates that the strings contain any of
the 32 control characters, 94 displayable characters, the space character, and
the delete character as defined by ISO 646. These strings can contain format
effectors.
ZFTM-VAL-UC-GRAPHIC-STRING (Class 25) indicates that the strings contain
any of the characters for all G sets, as defined by ISO 2022, and the space
character. These strings do not contain format effectors.
ZFTM-VAL-UC-VISIBLE-STRING (Class 26) indicates that the strings contain
any of the 94 graphic characters and the space character, as defined by ISO
646. These strings do not contain format effectors.
ZFTM-VAL-UC-GENERAL-STRING (Class 27) indicates that the strings
contain any of the characters for all G sets and all C sets (as defined by ISO
2022), the space character, and the delete character. These strings can
contain format effectors.
ZMAXSTRINGLENISPRESENT indicates whether a maximum string length value
is present.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -21
ZFTM Structures
DDL Definitions
ZMAXSTRINGLEN is a required parameter for FTAM-1, FTAM-2, and FTAM-3
document types. This field indicates how long a data string can be.
ZSTRINGSIGISPRESENT indicates whether a string significance value is present.
ZSTRINGSIG indicates whether the length of the string used for transferring data
is significant to the semantics of the file. If it is significant, it indicates whether the
length is variable or fixed. Valid values are:
ZFTM-VAL-STRINGSIG-VARIABLE (significant) indicates that a string can be
of a variable length.
ZFTM-VAL-STRINGSIG-FIXED (significant) indicates that a string must be of
fixed length.
ZFTM-VAL-STRINGSIG-NOTSIG indicates that how data is broken into strings
is not significant.
ZFILEATTRSISPRESENT indicates whether file attributes are included.
ZFILEATTRS contains a set of file attributes to be included in data elements when
reading NBS-9 documents. This is an optional parameter applicable only to the
NBS-9 document type.
ZCONSTRAINTSETASNAME is reserved, and application programs should not use it.
ZFTM-DDL-CONCURRENCY
specifies what actions can be performed concurrently on files. For a description of
different levels of concurrency, refer to ZFTM-DDL-CONCURRENCY-KEY.
DEFINITION ZFTM-DDL-CONCURRENCY.
02 ZREAD
TYPE
02 ZINSERT
TYPE
02 ZREPLACE
TYPE
02 ZEXTEND
TYPE
02 ZERASE
TYPE
02 ZREADATTR
TYPE
02 ZCHNGATTR
TYPE
02 ZDELETE
TYPE
END
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZFTM-DDL-CONCURRENCY-KEY.
ZREAD defines the read activity allowed for the specified file.
ZINSERT defines the insert activity allowed for the specified file.
ZREPLACE defines the replace activity allowed for the specified file.
ZEXTEND defines the extend activity allowed for the specified file.
ZERASE defines the erase activity allowed for the specified file.
ZREADATTR defines the read-attribute activity allowed for the specified file.
ZCHNGATTR defines the change-attribute activity allowed for the specified file.
ZDELETE defines the delete activity allowed for the specified file.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -22
ZFTM Structures
DDL Definitions
ZFTM-DDL-CONCURRENCY-KEY
defines the levels of concurrency applied to various file activities in
ZFTM-DDL-CONCURRENCY.
DEFINITION ZFTM-DDL-CONCURRENCY-KEY.
02 ZNOTREQUIRED
TYPE
02 ZSHARED
TYPE
02 ZEXCLUSIVE
TYPE
02 ZNOACCESS
TYPE
END
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZNOTREQUIRED indicates that the primary user does not intend to perform the
specified activity on the file.
ZSHARED indicates that anyone can perform the specified activity on the file.
ZEXCLUSIVE indicates that only the primary user can perform the specified activity on
the file.
ZNOACCESS indicates that no one is allowed to perform the specified activity on the
file.
ZFTM-DDL-CREATE-ATTR
indicates the values of the file attributes to be specified during file creation. Only
attributes whose attribute group was negotiated when the association was
established can be specified. NonStop FTAM does not support the private group.
For a detailed description of file attributes, refer to the OSI/FTAM Programming
Guide
DEFINITION ZFTM-DDL-CREATE-ATTR.
* Kernel group
02 ZFILENAME
02 ZPERMITTEDACTIONS
02 ZCNTNTSTYPEVALUE
* Storage group
02 ZSTORAGEACCOUNTISPRESENT
02 ZSTORAGEACCOUNT
02 ZFILEAVLBLTYATTRISPRESENT
02 ZFILEAVLBLTYATTR
02 ZFUTUREFILESIZEISPRESENT
02 ZFUTUREFILESIZE
* Security group
02 ZACCESSCNTRLATTRISPRESENT
02 ZACCESSCNTRLATTR
02 ZLEGALQUALIFISPRESENT
02 ZLEGALQUALIFICATION
TYPE ZAPS-DDL-CHAR128.
TYPE ZFTM-DDL-PERMITTED-ACTIONS.
TYPE ZFTM-DDL-CNTNTS-TYPE.
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCOUNT-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILEAVLBLTY-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILESIZE-ATTR.
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCESS-CNTRL-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-LEGALQUALIF-ATTR.
END
ZFILENAME provides the name of the file. If the responder returns a value for the
filename attribute that is greater than 128 characters, the initiator passes only the first
128 characters to the application.
ZPERMITTEDACTIONS lists the actions that are permitted for this file. These are
limited by document type and the implementation of the responder.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -23
ZFTM Structures
DDL Definitions
ZCNTNTSTYPEVALUE specifies the contents type of the file.
ZSTORAGEACCOUNTISPRESENT indicates whether a storage account has been
specified.
ZSTORAGEACCOUNT identifies the storage account to be charged for FTAM activity.
ZFILEAVLBLTYATTRISPRESENT indicates whether file availability is specified.
ZFILEAVLBLTYATTR contains the file availability status.
ZFUTUREFILESIZEISPRESENT indicates whether a future file size has been
specified.
ZFUTUREFILESIZE provides the future file size.
ZACCESSCNTRLATTRISPRESENT indicates whether access control has been
defined.
ZACCESSCNTRLATTR specifies access control for the file.
ZLEGALQUALIFISPRESENT indicates whether a legal-qualifications statement is
present.
ZLEGALQUALIFICATION conveys information about the legal status of the file. Its use
depends on the implementation of the responder.
ZFTM-DDL-CREATE-ATTR-GRP
indicates the values of the file attributes to be specified during file creation using
the grouped procedure FTM_FILE_OPEN_REQ_. This definition is identical to the
ZFTM DDL-CREATE-ATTR definition except that the filename attribute is not
included. For a detailed description of file attributes, refer to the OSI/FTAM
Programming Guide.
DEFINITION ZFTM-DDL-CREATE-ATTR-GRP.
* Kernel group
02 ZPERMITTEDACTIONS
TYPE
02 ZCNTNTSTYPEVALUE
TYPE
* Storage group
02 ZSTORAGEACCOUNTISPRESENT TYPE
02 ZSTORAGEACCOUNT
TYPE
02 ZFILEAVLBLTYATTRISPRESENT TYPE
02 ZFILEAVLBLTYATTR
TYPE
02 ZFUTUREFILESIZEISPRESENT TYPE
02 ZFUTUREFILESIZE
TYPE
* Security group
02 ZACCESSCNTRLATTRISPRESENT TYPE
02 ZACCESSCNTRLATTR
TYPE
02 ZLEGALQUALIFISPRESENT
TYPE
02 ZLEGALQUALIFICATION
TYPE
*
ZFTM-DDL-PERMITTED-ACTIONS.
ZFTM-DDL-CNTNTS-TYPE.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCOUNT-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILEAVLBLTY-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILESIZE-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCESS-CNTRL-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-LEGALQUALIF-ATTR.
Private group - unsupported
END
ZPERMITTEDACTIONS lists the actions that are permitted for this file. Document type
and the implementation of the responder limit the permitted actions.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -24
ZFTM Structures
DDL Definitions
ZCNTNTSTYPEVALUE specifies the contents type of the file.
ZSTORAGEACCOUNTISPRESENT indicates whether a storage account has been
specified.
ZSTORAGEACCOUNT identifies the storage account to be charged for FTAM activity.
ZFILEAVLBLTYATTRISPRESENT indicates whether file availability is specified for the
file.
ZFILEAVLBLTYATTR contains the file availability status.
ZFUTUREFILESIZEISPRESENT indicates whether a future file size has been
specified.
ZFUTUREFILESIZE provides the future file size.
ZACCESSCNTRLATTRISPRESENT indicates whether access control has been
defined.
ZACCESSCNTRLATTR specifies access control for the file.
ZLEGALQUALIFISPRESENT indicates whether a legal qualifications statement is
present.
ZLEGALQUALIFICATION conveys information about the legal status of the file. Its use
is dependent upon the implementation of the responder.
ZFTM-DDL-DATETIME
is the generalized time used by ZFTM-DDL-READ-ATTR.
DEFINITION ZFTM-DDL-DATETIME.
02 ZID
02 ZDATETIME
END
TYPE ZAPS-DDL-ENUM1.
TYPE ZAPS-DDL-CHAR32.
ZID indicates whether a ZDATETIME value is available. ZID has two possible values:
ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT.
ZDATETIME presents the generalized time in the calendar-date and time-of-day
format, YYYYMMDDHHMMSS.S
This time can be supplied in any of the following ways:
Local time: for example, 19920129051533.2 for a local time of 5:15:33.2 on
January 29, 1992.
Coordinated universal time: for example, 19920129051533.2Z adds “Z” for a
coordinated universal time of 5:15:33.2 on January 29, 1992.
Local time differential: for example, 19920129051533.2-0300 subtracts three hours
from the coordinated universal time (without the “Z”) of 5:15:33.2 on January 29,
1992.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -25
ZFTM Structures
DDL Definitions
ZFTM-DDL-DE-FADU
is the data type for an FTAM structuring data element. ZFTM-DDL-DE-FADU is not
a valid data element for FTAM-1, FTAM-3, or NBS-9 document types.
DEFINITION ZFTM-DDL-DE-FADU.
02 ZTYPE
02 ZNAMEISPRESENT
02 ZNAME
02 ZARCLENGTHISPRESENT
02 ZARCLENGTH
02 ZDATAEXISTSISPRESENT
02 ZDATAEXISTS
END
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-INT2.
ZAPS-DDL-ISPRESENT.
ZAPS-DDL-CHAR32.
ZAPS-DDL-ISPRESENT.
ZAPS-DDL-INT2.
ZAPS-DDL-ISPRESENT.
ZAPS-DDL-BOOLEAN.
The valid values for ZTYPE are:
CONSTANT ZFTM-VAL-DE-NODE-DESC
CONSTANT ZFTM-VAL-DE-ENTER-SUBTREE
CONSTANT ZFTM-VAL-DE-EXIT-SUBTREE
VALUE 0
VALUE 1
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
ZTYPE indicates the type of structuring data element for a file. Allowable values for
ZTYPE are:
ZFTM-VAL-DE-NODE-DESC describes the node of the FADU.
ZFTM-VAL-DE-ENTER-SUBTREE is reserved.
ZFTM-VAL-DE-EXIT-SUBTREE is reserved.
ZNAMEISPRESENT indicates whether a node name is provided.
ZNAME indicates the node name used by the node descriptor data element. This field
is not used.
ZARCLENGTHISPRESENT indicates whether an arc length has been specified.
ZARCLENGTH indicates how many nodes in the hierarchy you are from the root node.
The arc length of an FTAM-2 document type is always 1.
ZDATAEXISTSISPRESENT indicates whether data exists in the file. The default value
is ZAPS-VAL-PRESENT.
ZDATAEXISTS indicates that there is data associated with the node descriptor. The
value for ZDATAEXISTS should always be ZAPS-VAL-TRUE for an FTAM-2 document
type.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -26
ZFTM Structures
DDL Definitions
ZFTM-DDL-DIAG-ELEM
contains the information returned in a single FTAM diagnostic message.
DEFINITION ZFTM-DDL-DIAG-ELEM.
02 ZDIAGTYPE
02 ZERRORID
02 ZERROROBSERVER
02 ZERRORSOURCE
02 ZSUGGESTEDDELAYISPRESENT
02 ZSUGGESTEDDELAY
02 ZFURTHERDETAILSISPRESENT
02 ZFURTHERDETAILS
END
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-INT2.
ZAPS-DDL-INT2.
ZFTM-DDL-ENTITY-REF.
ZFTM-DDL-ENTITY-REF.
ZAPS-DDL-ISPRESENT.
ZAPS-DDL-INT2.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-CHAR256.
The valid values for ZDIAGTYPE are:
CONSTANT ZFTM-VAL-DIAG-INFORMATIVE
CONSTANT ZFTM-VAL-DIAG-TRANSIENT
CONSTANT ZFTM-VAL-DIAG-PERMANENT
VALUE 0
VALUE 1
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
ZDIAGTYPE indicates the severity of the message as follows:
ZFTM-VAL-DIAG-INFORMATIVE provides information about an operation. This
field is informative; it does not affect the current state of the file service and does
not require any recovery.
ZFTM-VAL-DIAG-TRANSIENT indicates that the failure is temporary and might not
occur if the operation is repeated.
ZFTM-VAL-DIAG-PERMANENT indicates that the failure of at least the present
operation is likely to occur every time the sequence of events is repeated.
ZERRORID identifies the diagnostic error code. For the meanings of diagnostic error
codes, see Appendix C, ISO FTAM Diagnostic Messages.
ZERROROBSERVER names the entity that reported the error.
ZERRORSOURCE names the presumed source of the error.
ZSUGGESTEDDELAYISPRESENT indicates whether a specific delay has been
suggested.
ZSUGGESTEDDELAY contains a suggested time to wait before error recovery is
attempted. The returned value is the exponent of 2 that specifies the suggested delay
in seconds.
ZFURTHERDETAILSISPRESENT indicates if further details about the error are
present.
ZFURTHERDETAILS is a text message giving further details about the cause of the
error. Only the first 256 characters of the message are sent to the application from the
FTAM API.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -27
ZFTM Structures
DDL Definitions
ZFTM-DDL-DIAGNOSTIC
is the structure used by FTAM to return up to 10 diagnostic elements.
DEFINITION ZFTM-DDL-DIAGNOSTIC.
02 ZDIAGCOUNT
TYPE ZAPS-DDL-INT1.
02 ZDIAGELEMSISPRESENT
TYPE ZAPS-DDL-ISPRESENT.
02 ZDIAGELEMS
TYPE ZFTM-DDL-DIAG-ELEM OCCURS 10 TIMES.
END
ZDIAGCOUNT specifies how many diagnostic elements are present, if any.
ZDIAGELEMSISPRESENT indicates whether diagnostic elements are present.
ZDIAGELEMS contains up to 10 diagnostic elements. If more than 10 elements are
returned, all but the last 10 are lost. After the first 10 values are returned, the
subsequent values wrap around the diagnostic buffer.
ZFTM-DDL-ENTITY-REF
returns values for ZERROROBSERVER and ZERRORSOURCE in the
ZFTM-DDL-DIAG-ELEM structure that identify the observer and source of a
diagnostic message.
DEFINITION ZFTM-DDL-ENTITY-REF TYPE ZAPS-DDL-INT2.
Valid values are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-ENTITYREF-NOCATPOSS
ZFTM-VAL-ENTITYREF-INITFSRVUSR
ZFTM-VAL-ENTITYREF-INITFPMCH
ZFTM-VAL-ENTITYREF-SRVFPMCH
ZFTM-VAL-ENTITYREF-RESFPMCH
ZFTM-VAL-ENTITYREF-RESFSRVUSR
VALUE
VALUE
VALUE
VALUE
VALUE
VALUE
0
1
2
3
4
5
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
BINARY
BINARY
BINARY
BINARY
BINARY
BINARY
32.
32.
32.
32.
32.
32.
ZFTM-VAL-ENTITYREF-NOCATPOSS indicates that no categorization is possible.
This value is valid for the source identifier only.
ZFTM-VAL-ENTITYREF-INITFSRVUSR identifies the initiating file service user
(application).
ZFTM-VAL-ENTITYREF-INITFPMCH identifies the initiating file protocol machine (file
provider or initiator process).
ZFTM-VAL-ENTITYREF-SRVFPMCH identifies the service supporting the file protocol
machine (local or remote OSI services). This value is valid for the source identifier only.
ZFTM-VAL-ENTITYREF-RESFPMCH identifies the responding file protocol machine
(responder).
ZFTM-VAL-ENTITYREF-RESFSRVUSR identifies the responding file service user (file
system).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -28
ZFTM Structures
DDL Definitions
ZFTM-DDL-FADU-ID
identifies a specific file data access unit (FADU) in any one of five possible ways.
Use this structure to locate FADUs on erase, locate, read, and write requests.
DEFINITION ZFTM-DDL-FADU-ID.
02 ZID
02 ZFADUID
02 ZFIRSTLAST
02
ZRELATIVE
02
ZBEGINEND
02
ZFADUNUMBER
TYPE ZAPS-DDL-ENUM1.
TYPE ZAPS-DDL-INT2.
REDEFINES ZFADUID
TYPE ZAPS-DDL-INT2.
REDEFINES ZFADUID
TYPE ZAPS-DDL-INT2.
REDEFINES ZFADUID
TYPE ZAPS-DDL-INT2.
REDEFINES ZFADUID
TYPE ZAPS-DDL-INT2.
END
Valid values for ZID are:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-FADUID-NOVALUE
ZFTM-VAL-FADUID-FIRSTLAST
ZFTM-VAL-FADUID-RELATIVE
ZFTM-VAL-FADUID-BEGINEND
ZFTM-VAL-FADUID-FADUNUMBER
VALUE
VALUE
VALUE
VALUE
VALUE
0
1
2
3
4
TYPE
TYPE
TYPE
TYPE
TYPE
BINARY
BINARY
BINARY
BINARY
BINARY
16.
16.
16.
16.
16.
Valid values for ZFIRSTLAST are:
CONSTANT
CONSTANT
ZFTM-VAL-FADUID-FIRST
ZFTM-VAL-FADUID-LAST
VALUE 0
VALUE 1
TYPE BINARY 32.
TYPE BINARY 32.
VALUE 0
VALUE 1
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
VALUE 0
VALUE 1
TYPE BINARY 32.
TYPE BINARY 32.
Valid values for ZRELATIVE are:
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-FADUID-PREVIOUS
ZFTM-VAL-FADUID-CURRENT
ZFTM-VAL-FADUID-NEXT
Valid values for ZBEGINEND are:
CONSTANT
CONSTANT
ZFTM-VAL-FADUID-BEGIN
ZFTM-VAL-FADUID-END
ZID specifies one of the following five ways to identify the FADU:
ZFTM-VAL-FADUID-NOVALUE indicates that no FADU-identity value is provided.
ZFTM-VAL-FADUID-FIRSTLAST indicates that the first FADU after the root FADU
or the last FADU is provided.
ZFTM-VAL-FADUID-RELATIVE indicates the FADU is identified relative to the
current FADU.
ZFTM-VAL-FADUID-BEGINEND indicates that the beginning of the first FADU (the
root FADU) or the end of the last FADU is provided.
ZFTM-VAL-FADUID-FADUNUMBER indicates that the FADU is identified as an
integer specifying the number of FADUs separating it from the root FADU. The root
FADU has a FADU number of 0.
ZFADUID contains the identity of the FADU specified by the method of identification in
the ZID field. Only the method of identification that corresponds with the ZID value is
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -29
ZFTM Structures
DDL Definitions
used at one time. The remaining fields in this structure identify the FADU according to
that method.
ZFIRSTLAST identifies the FADU as either of the following:
ZFTM-VAL-FADUID-FIRST specifies the first FADU after the root FADU.
ZFTM-VAL-FADUID-LAST specifies the last FADU.
ZRELATIVE identifies the relative position of the FADU as one of the following:
ZFTM-VAL-FADUID-PREVIOUS specifies the previous FADU.
ZFTM-VAL-FADUID-CURRENT specifies the current FADU.
ZFTM-VAL-FADUID-NEXT specifies the next FADU.
ZBEGINEND identifies the FADU as either of the following:
ZFTM-VAL-FADUID-BEGIN specifies the beginning of the first FADU.
ZFTM-VAL-FADUID-END specifies the end of the last FADU.
ZFADUNUMBER identifies the FADU by specifying how many FADUs it is removed
from the root FADU.
ZFTM-DDL-FILEAVLBLTY-ATTR
indicates the availability status of a file.
DEFINITION ZFTM-DDL-FILEAVLBLTY-ATTR.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZFILEAVLBLTY
TYPE ZAPS-DDL-INT2.
END
Valid values for ZFILEAVLBLTY are:
CONSTANT
CONSTANT
ZFTM-VAL-FILEAVLBLTY-IMMED
ZFTM-VAL-FILEAVLBLTY-DEFRRD
VALUE 0
VALUE 1
TYPE BINARY 32.
TYPE BINARY 32.
ZID indicates whether there is a ZFILEAVLBLTY attribute value. The ZID field of this
structure is not used in initiator requests and indications. ZID has two possible values:
ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT.
ZFILEAVLBLTY indicates that file availability has either of the following values:
ZFTM-VAL-FILEAVLBLTY-IMMED indicates that a file is available for immediate
access.
ZFTM-VAL-FILEAVLBLTY-DEFRRD indicates that file access is delayed; for
example, the file might be stored on a demountable device.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -30
ZFTM Structures
DDL Definitions
ZFTM-DDL-FILESIZE-ATTR
specifies the file attribute that represents the size of the file in octets.
DEFINITION ZFTM-DDL-FILESIZE-ATTR.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZFILESIZE
TYPE ZAPS-DDL-INT2.
END
ZID indicates whether there is a ZFILESIZE attribute available. The ZID field of this
structure is not used in initiator requests and indications. ZID has two possible values:
ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT.
ZFILESIZE contains the size of the file.
ZFTM-DDL-FUNC-UNITS
identifies the functional units negotiated by the FTAM initialize service. For further
information about functional units, refer to the OSI/FTAM Programming Guide.
DEFINITION ZFTM-DDL-FUNC-UNITS.
02 ZREAD
02 ZWRITE
02 ZFILEACCESS
02 ZFILEMGMT
02 ZFILEMGMTENHANCED
02 ZGROUP
02 ZFADULOCK
02 ZRECOVERY
02 ZRESTART
END
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZREAD specifies the read functional unit.
ZWRITE specifies the write functional unit.
ZFILEACCESS specifies the file-access functional unit.
ZFILEMGMT specifies the limited-file-management functional unit.
ZFILEMGMTENHANCED specifies the enhanced-file-management functional unit.
ZGROUP specifies the grouping functional unit.
ZFADULOCK specifies the FADU-locking functional unit. ZFADULOCK with a value of
ZAPS-VAL-TRUE is not supported. Specify a value of ZAPS-VAL-FALSE, or an error is
returned.
ZRECOVERY specifies the recovery functional unit. ZRECOVERY with a value of
ZAPS-VAL-TRUE is not supported. Specify a value of ZAPS-VAL-FALSE, or an error is
returned.
ZRESTART specifies the restart functional unit. ZRESTART with a value of ZAPS-VALTRUE is not supported. Specify a value of ZAPS-VAL-FALSE, or an error is returned.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -31
ZFTM Structures
DDL Definitions
ZFTM-DDL-LEGALQUALIF-ATTR
defines the legal status of the file.
DEFINITION ZFTM-DDL-LEGALQUALIF-ATTR.
02 ZID
TYPE ZAPS-DDL-ENUM1.
02 ZLEGALQUALIF
TYPE ZAPS-DDL-CHAR128.
END
ZID indicates whether there is a ZLEGALQUALIF attribute value for this file. The ZID
field of this structure is not used in initiator requests and indications. ZID has two
possible values: ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTRISPRESENT.
ZLEGALQUALIF contains a text string giving information about the legal status of the
file.
ZFTM-DDL-PERMITTED-ACTIONS
is a file attribute that indicates the file actions that will be allowed for a file. Once a
file has been created, permitted actions cannot be changed.
DEFINITION ZFTM-DDL-PERMITTED-ACTIONS.
02 ZREAD
TYPE ZAPS-DDL-BOOLEAN.
02 ZINSERT
TYPE ZAPS-DDL-BOOLEAN.
02 ZREPLACE
TYPE ZAPS-DDL-BOOLEAN.
02 ZEXTEND
TYPE ZAPS-DDL-BOOLEAN.
02 ZERASE
TYPE ZAPS-DDL-BOOLEAN.
02 ZREADATTR
TYPE ZAPS-DDL-BOOLEAN.
02 ZCHNGATTR
TYPE ZAPS-DDL-BOOLEAN.
02 ZDELETEFILE
TYPE ZAPS-DDL-BOOLEAN.
02 ZTRAVERSAL
TYPE ZAPS-DDL-BOOLEAN.
02 ZREVERSETRAVERSAL
TYPE ZAPS-DDL-BOOLEAN.
02 ZRANDOM
TYPE ZAPS-DDL-BOOLEAN.
END
ZREAD specifies access that permits you to read the file.
ZINSERT specifies access that permits you to insert data into the file.
ZREPLACE specifies access that permits you to replace information in the file.
ZEXTEND specifies access that permits you to extend the file.
ZERASE specifies access that permits you to erase some or all the contents of the file.
ZREADATTR specifies access that permits you to read the file attributes.
ZCHNGATTR specifies access that permits you to change the file attributes.
ZDELETEFILE specifies access that permits you to delete the file.
ZTRAVERSAL specifies sequential access that permits you to traverse the file from the
first FADU to the last FADU.
ZREVERSETRAVERSAL specifies sequential access that permits you to traverse the
file from the last FADU to the first FADU.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -32
ZFTM Structures
DDL Definitions
ZRANDOM specifies access that permits you to select any FADU by the FADU identity
specified in a read, write, or locate request.
ZFTM-DDL-PROC-MODE
specifies the processing mode that defines the actions permitted on the FADUs of
the file in the open regime. To allow multiple actions, set the corresponding fields in
ZFTM-DDL-PROC-MODE to ZAPS-VAL-TRUE.
DEFINITION ZFTM-DDL-PROC-MODE.
02 ZREAD
02 ZINSERT
02 ZREPLACE
02 ZEXTEND
02 ZERASE
END
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZREAD requests the ability to read a FADU in the file.
ZINSERT requests the ability to insert a new FADU into a file.
ZREPLACE requests the ability to replace a FADU in the file.
ZEXTEND requests the ability to extend an existing FADU in a file.
ZERASE requests the ability to erase a FADU from a file.
ZFTM-DDL-READ-ATTR
returns the values of the attributes that can be read when you issue a request to
read the attributes of a file. You also use this structure in the data-value
parameter of the FTM_DATA_IND_ procedure to read NBS-9 files from a remote
responder. For a detailed description of file attributes, refer to the OSI/FTAM
Programming Guide. For more information on reading NBS-9 files, see that
manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -33
ZFTM Structures
DDL Definitions
DEFINITION ZFTM-DDL-READ-ATTR.
02
ZATTRSAREPRESENT
* Kernel group
02 ZFILENAMEISPRESENT
02 ZFILENAME
02 ZPERMITTEDACTIONSISPRESENT
02 ZPERMITTEDACTIONS
02 ZCNTNTSTYPEVALUEISPRESENT
02 ZCNTNTSTYPEVALUE
* Storage group
02 ZSTORAGEACCOUNTISPRESENT
02 ZSTORAGEACCOUNT
02 ZCREATIONISPRESENT
02 ZCREATION
02 ZLASTMODISPRESENT
02 ZLASTMOD
02 ZLASTREADISPRESENT
02 ZLASTREAD
02 ZLASTATTRMODISPRESENT
02 ZLASTATTRMOD
02 ZCREATORIDISPRESENT
02 ZCREATORID
02 ZLASTMODIDISPRESENT
02 ZLASTMODID
02 ZLASTREADIDISPRESENT
02 ZLASTREADID
02 ZLASTATTRMODISPRESENT
02 ZLASTATTRMODID
02 ZFILEAVLBLTYATTRISPRESENT
02 ZFILEAVLBLTYATTR
02 ZFILESIZEATTRISPRESENT
02 ZFILESIZEATTR
02 ZFUTUREFILESIZEISPRESENT
02 ZFUTUREFILESIZE
* Security group
02 ZACCESSCNTRLATTRISPRESENT
02 ZACCESSCNTRLATTR
02 ZLEGALQUALIFISPRESENT
02 ZLEGALQUALIFICATION
TYPE ZAPS-DDL-ISPRESENT.
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZAPS-DDL-CHAR128.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-PERMITTED-ACTIONS.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-CNTNTS-TYPE.
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCOUNT-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-DATETIME.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-DATETIME.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-DATETIME.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-DATETIME.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-USER-ID.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-USER-ID.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-USER-ID.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-USER-ID.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILEAVLBLTY-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILESIZE-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-FILESIZE-ATTR.
TYPE
TYPE
TYPE
TYPE
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-ACCESS-CNTRL-ATTR.
ZAPS-DDL-ISPRESENT.
ZFTM-DDL-LEGALQUALIF-ATTR.
END
ZATTRSAREPRESENT indicates whether attributes are present. If any attribute is
returned, ZATTRSAREPRESENT is equal to ZAPS-VAL-PRESENT.
ZFILENAMEISPRESENT indicates whether a file name was returned.
ZFILENAME contains the file name. If the responder returns a value for the filename
attribute that is greater than 128 characters, the initiator passes only the first 128
characters to the application.
ZPERMITTEDACTIONSISPRESENT indicates whether permitted actions were
returned.
ZPERMITTEDACTIONS specifies the actions permitted on the file. Permitted actions
are set when the file is created and cannot be changed.
ZCNTNTSTYPEVALUEISPRESENT indicates whether the file contents type was
returned.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -34
ZFTM Structures
DDL Definitions
ZCNTNTSTYPEVALUE indicates the contents type.
ZSTORAGEACCOUNTISPRESENT indicates whether a storage account was
returned.
ZSTORAGEACCOUNT identifies the storage account.
ZCREATIONISPRESENT indicates whether a file creation date was returned.
ZCREATION returns the date and time that the file was created.
ZLASTMODISPRESENT indicates whether the date and time of the last modification
was returned.
ZLASTMOD returns the date and time the file was last modified.
ZLASTREADISPRESENT indicates whether the date and time of the last read was
returned.
ZLASTREAD returns the date and time that the file was last read.
ZLASTATTRMODISPRESENT indicates whether the date and time of the last attribute
modification was returned.
ZLASTATTRMOD returns the date and time that the file attributes were last modified.
ZCREATORIDISPRESENT indicates whether the creator identity was returned.
ZCREATORID returns the identity of the file creator.
ZLASTMODIDISPRESENT indicates whether the identity of the entity that last
modified the file was returned.
ZLASTMODID identifies the entity that last modified the file.
ZLASTREADIDISPRESENT indicates whether the identity of the entity that last read
the file was returned.
ZLASTREADID identifies the entity that last read the file.
ZLASTATTRMODISPRESENT indicates whether the identity of the entity that last
modified the file attributes was returned.
ZLASTATTRMODID identifies the entity that last modified the file attributes.
ZFILEAVLBLTYATTRISPRESENT indicates whether the file availability attribute was
returned.
ZFILEAVLBLTYATTR returns the file availability status.
ZFILESIZEATTRISPRESENT indicates whether a file size was returned.
ZFILESIZEATTR returns the current file size.
ZFUTUREFILESIZEISPRESENT indicates whether the future-filesize attribute was
returned.
ZFUTUREFILESIZE returns the maximum allowed file size.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -35
ZFTM Structures
DDL Definitions
ZACCESSCNTRLATTRISPRESENT indicates whether the access control attribute
was returned.
ZACCESSCNTRLATTR returns the access control values.
ZLEGALQUALIFISPRESENT indicates whether the legal qualification attribute was
returned.
ZLEGALQUALIFICATION returns a text string giving information about the legal status
of the file.
ZFTM-DDL-REQUESTED-ACCESS
specifies the types of access that you want for a file you are selecting or creating.
DEFINITION ZFTM-DDL-REQUESTED-ACCESS.
02 ZREAD
TYPE
02 ZINSERT
TYPE
02 ZREPLACE
TYPE
02 ZEXTEND
TYPE
02 ZERASE
TYPE
02 ZREADATTR
TYPE
02 ZCHNGATTR
TYPE
02 ZDELETE
TYPE
END
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZREAD indicates that you want to read the file.
ZINSERT indicates that you want to insert information into the file.
ZREPLACE indicates that you want to replace some or all of the contents of the file.
ZEXTEND indicates that you want to extend the file.
ZERASE indicates that you want to erase some or all of the contents of the file.
ZREADATTR indicates that you want to read the attributes of the file.
ZCHNGATTR indicates that you want to change the attributes of the file.
ZDELETE indicates that you want to be able to delete the file.
ZFTM-DDL-SERVICE-CLASS
specifies the service classes proposed (on the FTM_INITIALIZE_REQ_) and the
single service class negotiated (on the FTM_INITIALIZE_CNF_). For information
about service classes, refer to the OSI/FTAM Programming Guide.
DEFINITION ZFTM-DDL-SERVICE-CLASS.
02 ZUNCONSTRAINED
TYPE
02 ZMGMT
TYPE
02 ZTRANSFER
TYPE
02 ZXFERMGMT
TYPE
02 ZACCESS
TYPE
END
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZAPS-DDL-BOOLEAN.
ZUNCONSTRAINED is reserved, and application programs should not use it.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -36
Named Values
DDL Definitions
ZMGMT specifies the file-management class.
ZTRANSFER specifies the file-transfer class.
ZXFERMGMT specifies the file-transfer-management class.
ZACCESS specifies the file-access class.
ZFTM-DDL-USER-ID
identifies the user identity responsible for various file activities including creating a
file, reading it, modifying it, and reading and modifying its attributes.
DEFINITION ZFTM-DDL-USER-ID.
02 ZID
02 ZUSERID
END
TYPE ZAPS-DDL-ENUM1.
TYPE ZAPS-DDL-CHAR32.
ZID indicates whether a ZUSERID value is available. ZID has two possible values:
ZFTM-VAL-ATTR-NOVALUE and ZFTM-VAL-ATTR-ISPRESENT.
ZUSERID identifies the entity responsible for the file activity.
Named Values
The following subsection lists the values for individual fields in the APS and FTM data
structures. Named values give the constant values that these fields can assume. All
named values begin with ZAPS-VAL- or ZFTM-VAL-. Named values are listed
alphabetically.
ZAPS-VAL-ABSENT
indicates that an optional parameter is absent. The second-level data type
ZAPS-DDL-ISPRESENT identifies the optional parameter.
ZAPS-VAL-AE-TITLE-xxx
See ZAPS-DDL-AE-TITLE on page A-6.
ZAPS-VAL-FALSE
indicates that the condition in the ZAPS-DDL-BOOLEAN data type is false.
ZAPS-VAL-PRESENT
indicates that an optional parameter is present. The second-level data type
ZAPS-DDL-ISPRESENT identifies the optional parameter.
ZAPS-VAL-SERVICE-xxx
See ZAPS-DDL-SERVICE-ID on page A-10.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -37
Named Values
DDL Definitions
ZAPS-VAL-TRUE
indicates that the condition in the ZAPS-DDL-BOOLEAN data type is true.
ZFTM-VAL-ACCESSCNTXT-xxx
See ZFTM-DDL-ACCESS-CNTXT on page A-13.
ZFTM-VAL-ACTION-xxx
indicates the outcome of an action. The following values are returned on the FTM
procedures:
CONSTANT
CONSTANT
ZFTM-VAL-ACTION-SUCCESS
ZFTM-VAL-ACTION-FAILURE
VALUE 0
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
ZFTM-VAL-ACTION-SUCCESS indicates that the action was a success.
ZFTM-VAL-ACTION-FAILURE indicates that the action was a failure.
ZFTM-VAL-ATTR-xxx
See ZFTM-DDL-ACCESS-CNTRL-ATTR on page A-12.
ZFTM-VAL-CLOSE-xxx
indicates the value of a close-file attribute. These values are used only for the FTM
file-close service.
CONSTANT
CONSTANT
ZFTM-VAL-CLOSE-NODELETE
ZFTM-VAL-CLOSE-DELETE
VALUE 0
VALUE 1
TYPE BINARY 32.
TYPE BINARY 32.
ZFTM-VAL-CLOSE-NODELETE indicates that the file currently open should be closed
and deselected but not deleted.
ZFTM-VAL-CLOSE-DELETE indicates that the file currently open should be closed and
deleted.
ZFTM-VAL-CNTNTSLIST-xxx
See ZFTM-DDL-CNTNTS-LIST.
ZFTM-VAL-CNTNTSTYPE-xxx
See ZFTM-DDL-CNTNTS-TYPE.
ZFTM-VAL-DE-xxx
For applicable ZTYPE field values, see ZFTM-DDL-DE-FADU and ZAPS-DDLDATA-ELEMENT-HDR.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -38
Named Values
DDL Definitions
ZFTM-VAL-DIAG-xxx
provides diagnostic information returned by the FTAM responder. For a listing of
possible messages, refer to Appendix C, ISO FTAM Diagnostic Messages.
ZFTM-VAL-ENTITYREF-xxx
See ZFTM-DDL-ENTITY-REF on page A-28.
ZFTM-VAL-EVT-xxx
tells you which event (a primitive or an error) has been received. The event values
are listed in Table A-1. This table also lists the procedure to call to retrieve the
event information, where applicable. The name of each constant begins with
ZFTM-VAL-EVT-.
ZFTM-VAL-FADUID-xxx
See ZFTM-DDL-FADU-ID on page A-29.
ZFTM-VAL-FADU-OP-xxx
specifies the operations that can be performed on FADUs.
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-FADU-OP-INSERT
ZFTM-VAL-FADU-OP-REPLACE
ZFTM-VAL-FADU-OP-EXTEND
VALUE 0
VALUE 1
VALUE 2
TYPE BINARY 32.
TYPE BINARY 32.
TYPE BINARY 32.
ZFTM-VAL-FADU-OP-INSERT indicates the insertion of a new FADU in a file.
ZFTM-VAL-FADU-OP-REPLACE indicates replacement of an existing FADU.
ZFTM-VAL-FADU-OP-EXTEND indicates the extension of an existing FADU.
ZFTM-VAL-FILEAVLBLTY-xxx
See ZFTM-DDL-FILEAVLBLTY-ATTR on page A-30.
Table A-1. Event Code Values and Their Primitives (page 1 of 2)
Constant
(ZFTM-VAL-EVT-)
Value
Primitive Received
Procedure to Call
NOVALUE
0
No event
Not applicable
INITIALIZE-CNF
901
Initialize confirm
FTM_INITIALIZE_CNF_
TERMINATE-CNF
903
Terminate confirm
FTM_TERMINATE_CNF_
UABORT-IND
905
User abort indication
FTM_U_ABORT_IND_
PABORT-IND
906
Provider abort
indication
FTM_P_ABORT_IND_
SELECT-CNF
907
Select confirm
FTM_SELECT_CNF_
DESELECT-CNF
909
Deselect confirm
FTM_DESELECT_CNF_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -39
Named Values
DDL Definitions
Table A-1. Event Code Values and Their Primitives (page 2 of 2)
Constant
(ZFTM-VAL-EVT-)
Value
Primitive Received
Procedure to Call
CREATE-CNF
911
Create confirm
FTM_CREATE_CNF_
DELETE-CNF
913
Delete confirm
FTM_DELETE_CNF_
READATTR-CNF
915
Read attribute confirm
FTM_READ_ATTRIB_CNF_
CHANGEATTR-CNF
917
Change attribute
confirm
FTM_CHANGE_ATTRIB_CNF_
OPEN-CNF
919
Open confirm
FTM_OPEN_CNF_
CLOSE-CNF
921
Close confirm
FTM_CLOSE_CNF_
LOCATE-CNF
923
Locate confirm
FTM_LOCATE_CNF_
ERASE-CNF
925
Erase confirm
FTM_ERASE_CNF_
DATA-IND
932
Data indication
FTM_DATA_IND_
DATAEND-IND
933
Data end indication
FTM_DATA_END_IND_
TRANSEND-CNF
934
Transfer end confirm
FTM_TRANSFER_END_CNF_
CANCEL-CNF
936
Cancel confirm
FTM_CANCEL_CNF_
CANCEL-IND
937
Cancel indication
FTM_CANCEL_IND_
FILECLOSE-CNF
938
File close confirm
FTM_FILE_CLOSE_CNF_
FILEOPEN-CNF
940
File open confirm
FTM_FILE_OPEN_CNF_
BEGINGROUP-CNF
946
Beginning group
confirm
Not applicable
ENDGROUP-CNF
947
End group confirm
Not applicable
ZFTM-VAL-FOPEN-xxx
identifies the different ways files can be opened.
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-FOPEN-NEW
ZFTM-VAL-FOPEN-UNKNOWN
ZFTM-VAL-FOPEN-REPLACE
ZFTM-VAL-FOPEN-RECREATE
ZFTM-VAL-FOPEN-OLD
VALUE
VALUE
VALUE
VALUE
VALUE
0
1
2
3
4
TYPE
TYPE
TYPE
TYPE
TYPE
BINARY
BINARY
BINARY
BINARY
BINARY
32.
32.
32.
32.
32.
ZFTM-VAL-FOPEN-NEW indicates that a new file is created, but only if the file does
not already exist. If the file does already exist, the call to open the file fails.
ZFTM-VAL-FOPEN-UNKNOWN indicates that if the file exists, it is selected. If the file
does not exist, it is created using the file attributes specified in the initial-attrib
parameter.
ZFTM-VAL-FOPEN-REPLACE indicates that the existing file is to be deleted and a
new file is to be created having the same file attributes as the old file. If the file does
not exist, the new file is created and the call succeeds.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -40
Named Values
DDL Definitions
ZFTM-VAL-FOPEN-RECREATE indicates that the existing file is to be deleted and a
new file is to be created using the file attributes specified in the initial-attrib
parameter.
If the file does not exist, the new file is created and the call succeeds.
ZFTM-VAL-FOPEN-OLD indicates that an existing file is selected. If the file does not
exist, the call to open the file fails.
ZFTM-VAL-OVR-xxx
is the override parameter that defines the action taken if the file named in the
create or select procedure call already exists.
CONSTANT
CONSTANT
CONSTANT
CONSTANT
ZFTM-VAL-OVR-CREATE-FAIL
ZFTM-VAL-OVR-SELECT-OLD
ZFTM-VAL-OVR-CREATE-OLD
ZFTM-VAL-OVR-CREATE-NEW
VALUE
VALUE
VALUE
VALUE
0
1
2
3
TYPE
TYPE
TYPE
TYPE
BINARY
BINARY
BINARY
BINARY
32.
32.
32.
32.
ZFTM-VAL-OVR-CREATE-FAIL indicates that the file creation is to fail, that is, not
complete, if the file already exists.
ZFTM-VAL-OVR-SELECT-OLD indicates that the existing file is to be selected. If the
file does not exist, it is created using the file attributes specified in the
initial-attrib parameter.
ZFTM-VAL-OVR-CREATE-OLD indicates that the existing file is to be deleted and a
new file is to be created using the attributes of the deleted file.
ZFTM-VAL-OVR-CREATE-NEW indicates that the existing file is to be deleted and a
new file is to be created using the attributes specified in the initial-attrib
parameter.
ZFTM-VAL-STATE-xxx
indicates the outcome of a state (regime) transition.
CONSTANT
CONSTANT
ZFTM-VAL-STATE-SUCCESS
ZFTM-VAL-STATE-FAILURE
VALUE 0
VALUE 1
TYPE BINARY 32.
TYPE BINARY 32.
ZFTM-VAL-STATE-SUCCESS indicates that the association has changed regimes as
expected.
ZFTM-VAL-STATE-FAILURE indicates that the association has not changed regimes
as expected.
ZFTM-VAL-STRINGSIG-xxx
See ZFTM-DDL-CNTNTS-TYPE.
ZFTM-VAL-UC-xxx
See ZFTM-DDL-CNTNTS-TYPE.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -41
Procedure Call Cross Reference Table
DDL Definitions
Procedure Call Cross Reference Table
Table A-2. Data Types Used by Procedure Calls (page 1 of 2)
Data Type
Procedure Call
ZAPS-DDL-AE-TITLE
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZAPS-DDL-APPL-ADDR
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZAPS-DDL-CHAR128
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
FTM_SELECT_CNF_
FTM_SELECT_REQ_
ZAPS-DDL-CURRENT-ERROR
APS_STATUS_
ZAPS-DDL-DIAG-BUF
APS_STATUS_
ZAPS-DDL-ERROR-CODE
APS_STATUS_
ZAPS-DDL-FILENAME
APS_STATUS_
FTM_INITIALIZE_REQ_
ZAPS-DDL-ORIGINAL-ERROR
APS_STATUS_
ZAPS-DDL-PSAP
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZAPS-DDL-SERVICE-ID
APS_STATUS_
ZFTM-DDL-ACCESS-CNTXT
FTM_READ_REQ_
ZFTM-DDL-ACCESS-PASSWDS
FTM_CREATE_REQ_
FTM_FILE_OPEN_REQ_
FTM_SELECT_REQ_
ZFTM-DDL-ATTR-GROUPS
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZFTM-DDL-ATTR-NAMES
FTM_READ_ATTRIB_REQ_
ZFTM-DDL-CHANGE-ATTR
FTM_CHANGE_ATTRIB_CNF_
FTM_CHANGE_ATTRIB_REQ_
ZFTM-DDL-CHARGING
FTM_DELETE_CNF_
FTM_DESELECT_CNF_
FTM_FILE_CLOSE_CNF_
FTM_TERMINATE_CNF_
ZFTM-DDL-CNTNTS-LIST
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZFTM-DDL-CNTNTS-TYPE
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
FTM_OPEN_CNF_
FTM_OPEN_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -42
Procedure Call Cross Reference Table
DDL Definitions
Table A-2. Data Types Used by Procedure Calls (page 2 of 2)
Data Type
Procedure Call
ZFTM-DDL-CREATE-ATTR
FTM_CREATE_CNF_
FTM_CREATE_REQ_
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
ZFTM-DDL-DIAGNOSTIC
FTM_CANCEL_CNF_
FTM_CANCEL_IND_
FTM_CANCEL_REQ_
FTM_CANCEL_RSP_
FTM_CHANGE_ATTRIB_CNF_
FTM_CLOSE_CNF_
FTM_CREATE_CNF_
FTM_DATA_END_IND_
FTM_DATA_END_REQ_
FTM_DELETE_CNF_
FTM_DESELECT_CNF_
FTM_ERASE_CNF_
FTM_FILE_CLOSE_CNF_
FTM_FILE_OPEN_CNF_
FTM_INITIALIZE_CNF_
FTM_LOCATE_CNF_
FTM_OPEN_CNF_
FTM_P_ABORT_IND_
FTM_READ_ATTRIB_CNF_
FTM_SELECT_CNF_
FTM_TRANSFER_END_CNF_
FTM_U_ABORT_IND_
FTM_U_ABORT_REQ_
ZFTM-DDL-FADU-ID
FTM_ERASE_REQ_
FTM_LOCATE_CNF_
FTM_LOCATE_REQ_
FTM_READ_REQ_
FTM_WRITE_REQ_
ZFTM-DDL-FUNC-UNITS
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
ZFTM-DDL-PROC-MODE
TM_FILE_OPEN_REQ_
FTM_OPEN_REQ_
ZFTM-DDL-READ-ATTR
FTM_READ_ATTRIB_CNF_
ZFTM-DDL-REQUESTED-ACCESS
FTM_CREATE_REQ_
FTM_FILE_OPEN_REQ_
FTM_SELECT_REQ_
ZFTM-DDL-SERVICE-CLASS
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -43
DDL Definitions
Procedure Call Cross Reference Table
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
A -44
B
NonStop FTAM Initiator Error
Messages
This appendix describes the following types of error messages that you might
encounter in developing NonStop FTAM applications:
•
•
APS error messages and subcodes
Error messages and subcodes generated by the NonStop FTAM initiator or FTAM
API
This appendix covers the following topics:
Topic
Page
Status Codes
B-2
Error Codes
B-4
The NonStop FTAM initiator also generates FTAM diagnostic messages, which are
described in Appendix D, NonStop FTAM Initiator Diagnostic Messages.
The quick reference tables, Table B-1 on page B-2, Table B-2 on page B-4, and
Table B-5 on page B-19 outline the error codes used in the NonStop FTAM
implementation. The tables list the errors in numeric order. Error explanations that
follow the tables are also listed in numeric order by error value.
NonStop FTAM initiator error messages are locally generated. The FTAM API and
initiator provide error checking on FTAM requests and responses, eliminating the need
to test across the network for procedure call errors. A nonzero return value for status
or error on an FTM, APS, or MFM procedure call indicates that an error has
occurred.
The status value is returned by the procedures that perform I/O operations, including
all request procedures and the FTM_CANCEL_RSP_ procedure; it is also returned by
the MFM_AWAITIOX_ procedure call when an FTM procedure is called in nowait
mode. If the returned status value does not equal ZAPS-VAL-STATUS-OK, the
procedure call did not run successfully. In this case, the status value gives you initial
guidelines on error recovery. For further error information, you can call APS_STATUS_
to obtain the error code and error subcode.
The error value is returned by procedures that do not perform I/O operations, including
all indications and confirms.
The following subsections describe the status, error, and error-subcode values that can
be returned by the FTM, APS, and MFM procedure calls used in the NonStop FTAM
applications that you develop.
For an overview of error handling, refer to the OSI/FTAM Programming Guide. For
FTM procedure-specific information on some of the errors described in this appendix,
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 1
Status Codes
NonStop FTAM Initiator Error Messages
see the “Errors” subsections in the individual procedure descriptions in Section 4, FTM
Procedures. For information about MFM and APS procedures, refer to Appendix E,
MFM Procedures and Appendix F, APS Procedures, respectively.
For the data structures related to error messages, see the following entries in
Appendix A, DDL Definitions:
ZAPS-DDL-CURRENT-ERROR
ZAPS-DDL-DIAG-BUF
ZAPS-DDL-ERROR-CODE
ZAPS-DDL-FILENAME
ZAPS-DDL-ORIGINAL-ERROR
ZAPS-DDL-SERVICE-ID
ZFTM-DDL-DIAGNOSTIC
Status Codes
In general, the status codes returned by the FTM and APS procedures and by
MFM_AWAITIOX_ indicate the success or failure of a procedure call. If a procedure
call fails, the status code indicates the recommended recovery action. This code can
inform you, for example, to wait until later to retry an operation or not to retry the
operation at all. Treat the recovery actions listed in this section as recommendations,
not as strict rules.
The special status code value ZAPS-VAL-STATUS-EVENT indicates that an event has
been received. This code is returned only on the completion of the
APS_EVENT_RECEIVE_ procedure call.
Table B-1 summarizes the most common status code values you can receive
programmatically. The name of each value starts with ZAPS-VAL-STATUS-. More
detailed descriptions of the values follow the table, listed in numeric order by status
code. For a list of all possible status codes that can be either returned
programmatically or observed in traces, see the OSI/FTAM Programming Guide
.
Table B-1. Status Code Values
Constant
(ZAPS-VAL-STATUS-)
Code
Meaning
OK
0
Operation succeeded.
EVENT
1
Event received; call APS_STATUS_ to determine
which event.
NO-RETRY
2
Operation failed; don’t retry.
RETRY-LATER
4
Operation failed; retry after a delay.
DISCARD
7
Operation failed; status unknown; discard association.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 2
NonStop FTAM Initiator Error Messages
Status Codes
0
ZAPS-VAL-STATUS-OK
Effect. This code has two meanings.
If you receive ZAPS-VAL-STATUS-OK (0) after a call to an FTM or APS procedure in
wait mode or after MFM_AWAITIOX_ in nowait mode, the operation was successful.
If you receive ZAPS-VAL-STATUS-OK (0) after a call to an FTM or APS procedure in
nowait mode, the operation was successfully initiated.
Recovery. None is required.
1
ZAPS-VAL-STATUS-EVENT
Effect. This code shows that you have received an event. Only the following two
procedures return ZAPS-VAL-STATUS-EVENT:
•
•
APS_EVENT_RECEIVE_, when you call it in wait mode.
MFM_AWAITIOX_, when it completes a nowait event receive operation.
Recovery. Call APS_STATUS_ to identify the event. Take appropriate action
depending on the event. For a list of possible event values, see Table A-1 on
page A-39.
2
ZAPS-VAL-STATUS-NO-RETRY
Effect. This code shows that the operation you requested failed, and you should not
retry it.
Recovery. None is specified.
4
ZAPS-VAL-STATUS-RETRY-LATER
Effect. The operation you requested failed, but you should retry it after a delay. For
example, this value is returned when you issue an APS_EVENT_RECEIVE_ call with
the time-limit parameter set to 0D (check for event without waiting) and no event
has been received.
Recovery. Wait and then repeat the procedure call that failed.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 3
Error Codes
NonStop FTAM Initiator Error Messages
7
ZAPS-VAL-STATUS-DISCARD
Effect. The operation you requested failed because of an aborted association or
internal causes rendering the association useless (for example, the associated SU was
aborted).
Recovery. Discard the association context, as described in the OSI/FTAM
Programming Guide.
Error Codes
When an FTM, APS, or MFM procedure call returns a value for status that does not
equal APS-VAL-STATUS-OK, you can determine the error condition by calling
APS_STATUS_. If an FTM confirm or indication procedure call returns a value for
error that does not equal ZAPS-ERR-OK, you must also call APS_STATUS_; in this
case, APS_STATUS_ returns the error-subcode value that provides more
information about the nature of the problem. The following subsections describe two
types of errors returned by APS_STATUS_:
•
•
APS error codes
FTAM initiator error codes
APS Error Codes
The APS error codes are listed in Table B-2. Those error codes that have been
redefined for use in NonStop FTAM have an asterisk (*) by the constant. If these error
codes are returned in the original-error-info parameter on an APS_STATUS_
call with a service ID of ZAPS-VAL-SERVICE-FTAM, they have the meanings
described below. If the service ID is ZAPS-VAL-SERVICE-APS, the errors have the
meanings described below or in the OSI/AS Programming Manual, depending on
whether the source of the problem is the FTAM or OSI/AS API. If the service ID is any
value other than ZAPS-VAL-SERVICE-FTAM or ZAPS-VAL-SERVICE-APS, they are
OSI/AS error codes and have the meaning described in the OSI/AS Programming
Manual.
If the APS error codes are returned as error-code on an APS_STATUS_ call or in
error on FTM confirm or indication calls, they are as described below.
Table B-2. APS Error Codes for NonStop FTAM (page 1 of 3)
Constant
(ZAPS-ERR-)
OK
Code
0
NO-SEGMENT-SPACE
-101
Meaning
No error occurred
No virtual memory available
* These are APS error codes redefined for use in NonStop FTAM.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 4
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-2. APS Error Codes for NonStop FTAM (page 2 of 3)
Constant
(ZAPS-ERR-)
Code
Meaning
NO-POOL-SPACE
-102
No pool space available in segment
INTERNAL
-104
Logic or data-consistency error
PARAMETER*
-105
Invalid parameter(s) with procedure
TOO-MANY-PENDING
-106
Too many requests pending
STATE-MACHINE
-107
Internal error in state machine
INVALID-OPERATION*
-108
Operation invalid in this context
UNKNOWN-CEPI
-109
CEPI supplied is unknown
OPERATOR-ABORT
-114
Association aborted by operator
NO-DATA
-116
No data available at the position given
SEGMENT-ACCESS*
-117
FTAM API segment not accessible
MFM-ERROR
-118
MFM error unrecoverable
POOL-CLOBBERED
-119
FTAM API pool corrupted
SSINIT
-120
SPI error using SSINIT
SSNULL
-121
SPI error using SSNULL
SSGET*
-122
SPI error using SSGET or SSGETTKN
SSPUT
-123
SPI error using SSPUT OR SSPUTTKN
BAD-MGR*
-124
Invalid APLMGR process name
MGR-FS-ERROR*
-125
File error communicating with APLMGR process
MGR-ERROR*
-126
Connection not established because of error in
APLMGR process
TABLE-ERROR
-127
Internal error; unexpected data in FTAM API table
HASHTABLE-ERROR
-128
Internal error; unexpected data in hash table
NO-EVENT
-129
No event received within time limit set
NO-CONNECTION
-131
No connection exists
TAPS-FS-ERROR*
-134
File-system error from TAPS process
NONE-PENDING
-135
No operation pending
PARAM-MISSING*
-136
Mandatory parameter(s) missing
PARAM-BOUNDS*
-137
Reference parameter(s) out of bounds
PARAM-RANGE*
-138
Value of parameter(s) outside range
INVALID-SERVICE*
-141
Unrecognized service ID
NO-EVENT
-129
No event received within time limit set
NO-CONNECTION
-131
No connection exists
TAPS-FS-ERROR*
-134
File-system error from TAPS process
* These are APS error codes redefined for use in NonStop FTAM.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 5
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-2. APS Error Codes for NonStop FTAM (page 3 of 3)
Constant
(ZAPS-ERR-)
Code
Meaning
NONE-PENDING
-135
No operation pending
PARAM-MISSING*
-136
Mandatory parameter(s) missing
PARAM-BOUNDS*
-137
Reference parameter(s) out of bounds
PARAM-RANGE*
-138
Value of parameter(s) outside range
INVALID-SERVICE*
-141
Unrecognized service ID
* These are APS error codes redefined for use in NonStop FTAM.
-101
ZAPS-ERR-NO-SEGMENT-SPACE
Cause. No more virtual memory space was available when the FTAM API attempted
to initialize or resize the segment. This request, and possibly any future requests, will
not be accepted.
Subcodes. None.
Recovery. If this error occurs when you call APS_INITIALIZE_, no recovery is
possible. To resolve this problem, redesign the application to use fewer memory
resources.
-102
ZAPS-ERR-NO-POOL-SPACE
Cause. No more allocated pool space was available within the FTAM API segment
when the API attempted to use more space. The current request, and possibly all
FTAM API requests for your application instance, cannot be satisfied.
Subcodes. None.
Recovery. If this error occurs when you call APS_INITIALIZE_, no recovery is
possible. To resolve this problem, redesign the application to use fewer memory
resources.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 6
NonStop FTAM Initiator Error Messages
APS Error Codes
-104
ZAPS-ERR-INTERNAL
Cause. An internal error has occurred.
Subcodes. A number of undocumented subcodes internal to NonStop Kernel are
possible.
Recovery. Trace the TAPS process and note the error and subcode, if any. Follow the
standard procedures at your site for contacting the appropriate support personnel.
These procedures might involve contacting your local HP support analyst.
-105
ZAPS-ERR-PARAMETER
Cause. The parameters you supplied with an APS or FTM procedure contained one or
more errors.
Subcodes. The subcode indicates the parameter concerned. For FTM-procedure
parameters, see Table B-4 on page B-16 under error code -137, later in this
subsection, and for APS procedure parameters, the OSI/AS Programming Manual.
Recovery. Correct your use of parameters, rebuild the application, and then retry the
operation.
-106
ZAPS-ERR-TOO-MANY-PENDING
Cause. Too many requests are pending. You cannot have more than one primitive
request and one event receive request pending at any given time for one CEPI
(connection endpoint identifier).
Subcodes. None.
Recovery. Await completion of the pending primitive request before issuing another
primitive request.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 7
NonStop FTAM Initiator Error Messages
APS Error Codes
-107
ZAPS-ERR-STATE-MACHINE
Cause. Cause. Your application attempted to invoke a primitive that was not valid in
the current state.
Subcodes. The possible subcodes are ZAPS-ERR-SM-BAD-STATE and ZAPS-ERRSM-BAD-EVENT. For more information, see the OSI/AS Programming Manual.
Recovery. Check your application’s calling sequence against the situation you are
encountering. For example, an abort might have occurred, the responding system
might have gone down, you might have opened a file in an unknown state, and so on.
If the calling sequence is incorrect for the situation—for example, the application is still
issuing requests although either the NonStop initiator or remote responder has
aborted—adjust your sequence of procedures to the encountered situation.
If the calling sequence is correct for the situation, trace the initiator and TAPS
processes and follow the standard procedures at your site for contacting the
appropriate support personnel. These procedures might involve contacting your local
HP support analyst.
-108
ZAPS-ERR-INVALID-OPERATION
Cause. The operation you tried to initiate is not supported or not available. For
example, you could have called an FTM confirm or indication procedure that does not
correspond to the primitive that you received. The call is ignored.
Subcodes. None.
Recovery. Recovery. Check your application calling sequence for errors.
-109
ZAPS-ERR-UNKNOWN-CEPI
Cause. The FTAM API does not recognize the CEPI you have specified. This causes
the procedure you have called to fail.
Subcodes. None.
Recovery. Recall the procedure using the correct CEPI.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 8
NonStop FTAM Initiator Error Messages
APS Error Codes
114
ZAPS-ERR-OPERATOR-ABORT
Cause. The association has been aborted by the operator.
Subcodes. None.
Recovery. Call APS_DISCARD_ to discard the association context.
-116
ZAPS-ERR-NO-DATA
Cause. You requested data, but no data is available to satisfy the request. Possible
causes for this error include:
•
•
You requested data, but none was received with the incoming primitive.
You specified a start position beyond the end of the data.
Subcodes. None.
Recovery. None is specified.
-117
ZAPS-ERR-SEGMENT-ACCESS
Cause. The FTAM API was unable to access the APS segment or to restore the user
segment. A possible cause of this error is that you attempted to make an APS or FTM
procedure call before calling the APS_INITIALIZE_ procedure.
Subcodes. None.
Recovery. Add a call to APS_INITIALIZE_ to your application before calling other APS
or FTM procedures.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B- 9
NonStop FTAM Initiator Error Messages
APS Error Codes
-118
ZAPS-ERR-MFM-ERROR
Cause. The Module File Management (MFM) software returned an unrecoverable
error.
Subcodes. The error subcodes are Guardian file-system error codes, indicating the
error code returned from the MFM software. For descriptions of file-system errors, refer
to the Guardian Procedure Errors and Messages Manual.
Recovery. Abort the association or discard the association context. Depending on the
subcode, you might also have to abandon the use of the FTAM API by this instance of
the application.
-119
ZAPS-ERR-POOL-CLOBBERED
Cause. The pool containing FTAM API information is unusable. This can happen when
internal associate or attach requests fail.
Subcodes. None.
Recovery. Stop the program and rerun it. If the problem persists, follow the standard
procedures at your site for contacting the appropriate support personnel. These
procedures might involve contacting your local HP support analyst.
-120
ZAPS-ERR-SSINIT
Cause. A Subsystem Programmatic Interface (SPI) error was encountered during the
execution of the SSINIT procedure. This is an internal error involving SPI buffer
management.
Subcodes. The subcode indicates the error returned by SSINIT. For descriptions of
the SPI errors, refer to the Guardian Procedure Errors and Messages Manual.
Recovery. Follow the standard procedures at your site for contacting the appropriate
support personnel. These procedures might involve contacting your local HP support
analyst.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -10
NonStop FTAM Initiator Error Messages
APS Error Codes
-121
ZAPS-ERR-SSNULL
Cause. An SPI error was encountered during the execution of the SSNULL procedure.
This is an internal error involving SPI buffer management.
Subcodes. The subcode indicates the error returned by SSNULL. For descriptions of
the SPI errors, refer to the Guardian Procedure Errors and Messages Manual.
Recovery. Follow the standard procedures at your site for contacting the appropriate
support personnel. These procedures might involve contacting your local HP support
analyst.
-122
ZAPS-ERR-SSGET
Cause. An SPI error was encountered during the execution of the SSGET or the
SSGETTKN procedure. This is an internal error involving SPI buffer management.
Subcodes. The subcode indicates the error returned by SSGET or SSGETTKN. For
descriptions of the SPI errors, refer to the Guardian Procedure Errors and Messages
Manual.
Recovery. Trace the APLMGR process, as described in the OSI/FTAM and
OSI/APLMGR SCF Reference Manual or the OSI/FTAM Configuration and
Management Manual. Then follow the standard procedures at your site for contacting
the appropriate support personnel. These procedures might involve contacting your
local HP support analyst.
-123
ZAPS-ERR-SSPUT
Cause. An SPI error was encountered during the execution of the SSPUT or the
SSPUTTKN procedure. This is an internal error involving SPI buffer management.
Subcodes. The subcode indicates the error returned by SSPUT or SSPUTTKN. For
descriptions of the SPI errors, refer to the Guardian Procedure Errors and Messages
Manual.
Recovery. Follow the standard procedures at your site for contacting the appropriate
support personnel. These procedures might involve contacting your local HP support
analyst.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -11
APS Error Codes
NonStop FTAM Initiator Error Messages
-124
ZAPS-ERR-BAD-MGR
Cause. You specified an invalid APLMGR process name in a call to the
FTM_INITIALIZE_REQ_ procedure, or that the process specified is not an APLMGR
process of the correct version.
Subcodes. None.
Recovery. Specify a valid APLMGR process name.
-125
ZAPS-ERR-MGR-FS-ERROR
Cause. The FTAM API encountered a file-system error while communicating with the
APLMGR process. This error indicates that the connect sequence has failed.
Subcodes. The error subcode specifies the file-system error encountered. For
descriptions of file-system errors, refer to the Guardian Procedure Errors and
Messages Manual.
Recovery. Check the subcode to discover the precise error, and correct as indicated.
-126
ZAPS-ERR-MGR-ERROR
Cause. The FTAM API has failed to establish an association because the APLMGR
process detected an error.
Subcodes. If APLMGR returns a positive subcode, the error is an APLMGR error.
Table B-3 lists the error subcodes that APLMGR returns if it detects an error when you
use the FTM_INITIALIZE_REQ_ procedure to establish an association. If a negative
subcode is returned, the error is a communications management error; for descriptions
of communications management errors, refer to the Communications Management
Programming Manual.
Table B-3. APLMGR Subcodes (page 1 of 2)
Constant
(ZFTM-ERR-MGR-)
Value
Meaning
BOUNDS-ERR
7000
Bounds error- internal error
SUBTYPE-BAD
7001
Bad subtype - internal error
REGREQ-TBL
7002
Register-request table - internal error
ASE-FS-ERR
7003
FTAM file-system error
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -12
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-3. APLMGR Subcodes (page 2 of 2)
Constant
(ZFTM-ERR-MGR-)
Value
Meaning
ASE-UNAVAIL
7004
FTAM process not available
ASE-TBL-EMPTY
7005
FTAM process table empty, no processes defined, or
APLMGR is in suspended state
ASE-NOT-READY
7006
FTAM process not ready, no processes in started state
Recovery. Recovery depends on the subcode received. For APLMGR-generated
values 7000, 7001, and 7002, stop the program and rerun it. If the problem persists,
follow the standard procedures at your site for contacting the appropriate support
personnel. These procedures might involve contacting your local HP support analyst.
For the value 7003, check the EMS event log file for an FTAM FS^ERR event (event
number 11). The Error value of the event message indicates the file-system error that
has occurred. For descriptions of file-system errors and appropriate recovery actions,
refer to the Guardian Procedure Errors and Messages Manual. APLMGR returns
subcode 7003, for example, if too many applications attempt to establish associations
with one initiator at the same time; when this happens, the initiator can become
overrun and generate a file-system error indicating an overflow problem.
For values 7004, 7005, and 7006, make sure that you have configured FTAM so that
there are FTAM processes in a started state and at less than maximum capacity.
-127
ZAPS-ERR-TABLE-ERROR
Cause. An internal FTAM API table error occurred.
Subcodes. None.
Recovery. Stop the program and rerun it. If the problem persists, follow the standard
procedures at your site for contacting the appropriate support personnel. These
procedures might involve contacting your local HP support analyst.
-128
ZAPS-ERR-HASHTABLE-ERROR
Cause. The FTAM API has encountered an internal error in maintaining CEPIs.
Subcodes. None.
Recovery. Follow the standard procedures at your site for contacting the appropriate
support personnel. These procedures might involve contacting your local HP support
analyst.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -13
NonStop FTAM Initiator Error Messages
APS Error Codes
-129
ZAPS-ERR-NO-EVENT
Cause. You set a time limit of 0D when calling APS_EVENT_RECEIVE_, but no event
was received.
Subcodes. None.
Recovery. Continue with other processing.
-131
ZAPS-ERR-NO-CONNECTION
Cause. No association exists.
Subcodes. None.
Recovery. Call APS_DISCARD_ to discard the association context and release the
CEPI. Then call FTM_INITIALIZE_REQ_ to reinitiate the association.
-134
ZAPS-ERR-TAPS-FS-ERROR
Cause. The FTAM initiator process has reported a file-system error in communicating
with the TAPS process. The current operation fails.
Subcodes. The subcode indicates the file-system error. For descriptions of the
file-system errors, refer to the Guardian Procedure Errors and Messages Manual.
Recovery. Recovery depends on the subcode received.
-135
ZAPS-ERR-NONE-PENDING
Cause. A request failed because no operation was pending on the association. This
error can be returned under these conditions:
•
•
The application called APS_EVENT_RECEIVE_, MFM_AWAITIOX_, or an FTM
confirm or indication procedure out of sequence. For example, the application
might call MFM_AWAITIOX_ to wait for completion of an I/O operation, but no I/O
operation is pending.
The application called MFM_CANCEL_REQ_ to cancel an operation that no longer
exists.
Subcodes. None.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -14
NonStop FTAM Initiator Error Messages
APS Error Codes
Recovery. Check the calling sequence used in your application. If you have issued an
APS_EVENT_RECEIVE_, for example, make sure that you have first called the
desired FTM request or response procedure that will cause a confirm or indication. If
you have issued an MFM_AWAITIOX_ call, you should have first issued the
appropriate FTM request or response nowaited procedure and that procedure should
have returned a status value of ZAPS-VAL-STATUS-OK (0). Before calling an FTM
confirm or indication procedure to map the desired information into your application,
you must first call APS_EVENT_RECEIVE_ to receive the confirm or indication and
APS_STATUS_ to determine the type of event.
-136
ZAPS-ERR-PARAM-MISSING
Cause. One or more mandatory parameters were missing. This code corresponds to
file-system error 29 (missing parameter). This error might be returned during program
debugging but is unlikely to be returned during program run time.
Subcodes. For FTM-procedure parameters, see Table B-4 on page B-16, and for
APS-procedure parameters, see the OSI/AS Programming Manual.
Recovery. Add the missing parameter(s) to your procedure call, rebuild the
application, and then retry the operation.
-137
ZAPS-ERR-PARAM-BOUNDS
Cause. Either the parameter that the application passed to an FTM procedure call did
not address the runtime data (or stack) space reserved for the parameters of that
procedure, or an internal error occurred when the FTAM initiator passed a value to the
OSI/AS API. This code corresponds to file-system error 22 (application parameter out
of bounds).
Subcodes. For FTM-procedure parameters, see Table B-4 on page B-16, and for
APS-procedure parameters, the OSI/AS Programming Manual.
Recovery. Correct your use of parameters, rebuild the application, and then retry the
operation.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -15
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-4. FTM-Procedure Parameter Subcodes (page 1 of 3)
Parameter
Meaning
Constant (ZFTM-ERR-)
Value
Associated Procedure Calls
CEPI
100
All
Connection
endpoint identifier
APLMGR-NAME
101
FTM_INITIALIZE_REQ_
APLMGR process
name
REMOTE-APPL
102
FTM_INITIALIZE_REQ_
Remote
application
WAIT-MODE
103
FTM_INITIALIZE_REQ_
Wait mode
LOCAL-APPL
104
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Local application
LOCAL-AETITLE
105
FTM_INITIALIZE_REQ_
Local application
entity title
REMOTE-AETITLE
106
FTM_INITIALIZE_REQ_
Remote
application entity
title
SERVICE-CLASS
107
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Service class
FUNC-UNITS
108
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Functional units
ATTR-GROUPS
109
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Attribute group
CNTNTS-TYPE-LIST
110
FTM_INITIALIZE_CNF_
FTM_INITIALIZE_REQ_
Contents-type list
INITIATOR-ID
111
FTM_INITIALIZE_REQ_
Initiator
identification
ACCOUNT
112
FTM_CREATE_REQ_
FTM_FILE_OPEN_REQ_
FTM_INITIALIZE_REQ_
FTM_SELECT_REQ_
Account
FS-PASSWD
113
FTM_INITIALIZE_REQ_
Filestore password
ACTION-RESULT
114
FTM_CANCEL_RSP_
FTM_CANCEL_REQ_
FTM_DATA_END_REQ_
FTM_U_ABORT_REQ_ Most
confirm and indication
procedures
Action result
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -16
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-4. FTM-Procedure Parameter Subcodes (page 2 of 3)
Parameter
Meaning
Constant (ZFTM-ERR-)
Value
Associated Procedure Calls
DIAGNOSTIC
115
FTM_CANCEL_REQ_
FTM_CANCEL_RSP_
FTM_DATA_END_REQ_
FTM_U_ABORT_REQ_
Most confirm and indication
procedures
Diagnostic
message
FILE-NAME
116
FTM_FILE_OPEN_REQ_
FTM_SELECT_REQ_
FTM_FILE_OPEN_CNF_
FTM_SELECT_CNF_
File name
REQUESTED-ACCESS
117
FTM_CREATE_REQ_
FTM_FILE_OPEN_REQ_
FTM_SELECT_REQ_
Requested access
ACCESS-PASSWDS
118
FTM_CREATE_REQ_
FTM_FILE_OPEN_REQ_
FTM_SELECT_REQ_
Access passwords
INITIAL-ATTR
119
FTM_CREATE_REQ_
FTM_CREATE_CNF_
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
Initialize attributes
OVERRIDE
120
FTM_CREATE_REQ_
Override
CREATE-PASSWD
121
FTM_CREATE_REQ_
Create password
ATTR-NAMES
122
FTM_READ_ATTRIB_REQ_
Attribute names
CHANGE-ATTR
123
FTM_CHANGE_ATTRIB_CNF_
FTM_CHANGE_ATTRIB_REQ_
Change attributes
PROCESS-MODE
124
FTM_FILE_OPEN_REQ_
FTM_OPEN_REQ_
Processing mode
CNTNTS-TYPE
125
FTM_FILE_OPEN_CNF_
FTM_FILE_OPEN_REQ_
FTM_OPEN_CNF_
FTM_OPEN_REQ_
Contents type
FILE-STATUS
126
FTM_FILE_OPEN_REQ_
File status
DELETE-ACTION
127
FTM_FILE_CLOSE_REQ_
Delete action
THRESHOLD
128
FTM_BEGIN_GROUP_REQ_
Threshold
FADU-ID
129
FTM_ERASE_REQ_
FTM_LOCATE_REQ_
FTM_READ_REQ_
FTM_WRITE_REQ_
FTM_LOCATE_CNF_
FADU
identification
ACCESS-CNTXT
130
FTM_READ_REQ_
Access context
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -17
APS Error Codes
NonStop FTAM Initiator Error Messages
Table B-4. FTM-Procedure Parameter Subcodes (page 3 of 3)
Constant (ZFTM-ERR-)
Value
Associated Procedure Calls
Parameter
Meaning
FADU-OPERATION
131
FTM_WRITE_REQ_
FADU operation
DATA-VALUE
132
FTM_DATA_REQ_
FTM_DATA_IND_
Data value
FILE-ATTR
140
FTM_READ_ATTRIB_REQ_
File attributes
CHARGING
141
FTM_DELETE_CNF_
FTM_DESELECT_CNF_
FTM_FILE_CLOSE_CNF_
FTM_TERMINATE_CNF_
Charging
QOS*
142
FTM_INITIALIZE_REQ_
Quality of service
PROTOCOL-VERSION*
143
FTM_INITIALIZE_REQ_
Protocol version
PRES-CNTXT-MGMT*
144
FTM_INITIALIZE_REQ_
Presentation
context
management
CHKPT-WINDOW*
145
FTM_INITIALIZE_REQ_
Checkpoint
window
STATE-RESULT
146
FTM_CREATE_CNF_
FTM_FILE_OPEN_CNF_
FTM_INITIALIZE_CNF_
FTM_OPEN_CNF_
FTM_SELECT_CNF_
State result
BUFFER-SIZE
147
FTM_DATA_IND_
Buffer size
MORE-DATA
148
FTM_DATA_IND_
More data
NEXT-POSITION
149
FTM_DATA_IND_
Next position
RESPONDING-APPL
150
FTM_INITIALIZE_CNF_
Responding
application
RESPONDING-AETITLE
151
FTM_INITIALIZE_CNF_
Responding
application entity
title
* If the ZFTM-ERR-QOS, ZFTM-ERR-PROTOCOL-VERSION, ZFTM-ERR-PRES-CNTXT-MGMT, or ZFTM-ERRCHKPT-WINDOW error is returned, an internal error has occurred. Follow the standard procedures at your site
for contacting the appropriate support personnel. These procedures might involve contacting your local HP
support analyst.
START-POSITION
152
FTM_DATA_IND_
Start position
MAX-STRING-LEN
155
FTM_FILE_OPEN_REQ_
FTM_OPEN_REQ_
Maximumstring-length
parameter of
contents type
* If the ZFTM-ERR-QOS, ZFTM-ERR-PROTOCOL-VERSION, ZFTM-ERR-PRES-CNTXT-MGMT, or ZFTM-ERRCHKPT-WINDOW error is returned, an internal error has occurred. Follow the standard procedures at your site
for contacting the appropriate support personnel. These procedures might involve contacting your local HP
support analyst.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -18
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
-138
ZAPS-ERR-PARAM-RANGE
Cause. One or more parameters were outside the permissible range of values.
Subcodes. For FTM-procedure parameters, see Table B-4 on page B-16, and for
APS-procedure parameters, the OSI/AS Programming Manual.
Recovery. Correct your use of parameters, rebuild the application, and then retry the
operation.
-141
ZAPS-ERR-INVALID-SERVICE
Cause. An operation was issued on a CEPI that was not allocated for an FTAM
service. For example, an FTM_SELECT_REQ_ procedure is called using a CEPI that
was allocated for an ACSE or Session service and not the one returned in a call to the
FTM_INITIALIZE_REQ_ procedure.
Subcodes. None.
Recovery. Retry using the CEPI returned from FTM_INITIALIZE_REQ_.
FTAM Initiator Error Codes
FTAM initiator error codes identify error messages that the FTAM initiator and FTAM
API can return. This subsection provides cause, effect, and recovery information for
each error code and indicates whether the error has subcodes associated with it.
Table B-5 lists the FTAM error codes in numeric order. Following the table, the error
descriptions are arranged also in numeric order. The related error subcode tables
appear throughout this subsection.
Note. If your program is not set up to return error-code, error-subcode, and serviceid in the case of an error, you might need to modify it to do so.
Table B-5. FTAM Initiator Error Codes (page 1 of 2)
Constant (ZFTM-ERR-)
Value
Meaning
INTERNAL
-6000
Internal error
OUT-OF-SEQUENCE
-6001
Request received in invalid sequence
FU-NOT-NEGOTIATED
-6002
Functional unit not negotiated
ACCESS-INCNSTNT
-6003
Requested access inconsistent with negotiated
functional units
ACCESS-NOT-AVAIL
-6004
File access not requested
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -19
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
Table B-5. FTAM Initiator Error Codes (page 2 of 2)
Constant (ZFTM-ERR-)
Value
Meaning
PROC-MODEINCNSTNT
-6005
Processing mode inconsistent with requested access
FADU-ID-INVALID
-6006
FADU ID invalid
FADU-OP-INCNSTNT
-6007
FADU operation inconsistent with processing mode
PROC-MODE-NOTAVAIL
-6008
Processing mode not requested
ACCESS-CNTXTINVALID
-6009
Access context invalid
INVALID-DATA
-6010
Invalid data
SERV-NOTNEGOTIATED
-6012
Service not negotiated
INVALID-IF-VERSION
-6017
FTAM initiator/FTAM API interface version mismatch
INVALID-FIELDVERSION
-6018
FTAM initiator/FTAM API field version mismatch
BAD-APS-STATUS
-6019
Bad APS status
RESRC-DCB-ALLOC
-6021
Resource data control block allocation failed
CONNECTIONABORTED
-6022
Connection aborted
ATTR-GRP-NOT-NEG
-6024
Attribute group not negotiated
PRIVATE-USE-NOTSUPP
-6025
Private use not supported
LOCATE-DOCTYPE
-6026
Locate not supported by document type
DATA-XFERCANCELLED
-6030
Data transfer canceled
ACSE-FAILURE
-6032
ACSE Layer failure
SU-ABORTED
-6036
Association SU aborted via SCF command
DATA-VALUE-TOOSMALL
-6037
Data-value parameter specified on FTM_DATA_IND_
is too small
API-FS-ERROR
-6038
FTAM API has reported an error in communicating
with FTAM initiator
EMPTY-ASSOC-CNF
-6039
Initialize confirm was received without user data
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -20
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
-6000
ZFTM-ERR-INTERNAL
Cause. The FTAM API or the FTAM initiator detected an internal error.
Subcodes. The subcode identifies the general location in the code where the error
was detected. These subcodes are not documented in this manual.
Effect. The initiator rejects your request. Files involved in a data transfer might be left
in an unknown state.
Recovery. Abort the association and call APS_DISCARD_ to discard the association
context. Rerun your application. If the condition persists, reload the FTAM
environment. If the condition still persists, record the error-code, error-subcode,
and service-id returned from APS_STATUS_, trace the initiator, and follow the
standard procedures at your site for contacting the appropriate support personnel.
These procedures might involve contacting your local HP support analyst.
-6001
ZFTM-ERR-OUT-OF-SEQUENCE
Cause. You issued a request that was invalid, given the current state of the
association.
Subcodes. For more information about what is out of sequence, see Table B-6.
Table B-6. Out-Of-Sequence Subcodes
Constant
(ZFTM-ERR-OOS-)
Value
Meaning
STATE-MACHINE
1
Request to FTAM initiator invalid for state of
association (relative to regimes, grouping, and so
on).
GROUP-SEQ
2
FTM_BEGIN_GROUP_REQ_ or
FTM_END_GROUP_REQ_ was called at invalid
place in protocol for grouped requests. This subcode
can be returned if you issue begin-group or endgroup request twice, or issue one of these requests in
middle of data transfer.
BAD-GROUP
3
Invalid group used. See the OSI/FTAM Programming
Guide.
SERVICE-CLASS
4
Nongrouped sequence used after transfer,
management, or transfer-and-management service
class negotiated (only file-access service class allows
you to do ungrouped sequences).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -21
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
Effect. The initiator rejects your request.
Recovery. Issue a valid request, or retry with the procedures in proper sequence. For
the procedure sequence for major FTAM tasks, refer to the OSI/FTAM Programming
Guide. For protocol information, refer to Section 4, FTM Procedures and to the ISO
8571 standard. In the case of an internal problem in the initiator, if you suspect an
interoperability problem, contact the appropriate support personnel. These procedures
might involve contacting your local HP support analyst.
-6002
ZFTM-ERR-FU-NOT-NEGOTIATED
Cause. You called an FTM procedure and the functional unit required for the
associated service had not been negotiated when the association was established.
Subcodes. To determine which functional unit was required, see Table B-7.
Table B-7. FTAM Functional-Unit Subcodes
Constant (ZFTM-ERR-FU-)
Value
Meaning
READ
-1
Read functional unit
WRITE
-2
Write functional unit
FILE-ACCESS
-3
File-access functional unit
LMTD-MGMT
-4
Limited-file-management functional unit
ENHANCED-MGMT
-5
Enhanced-file-management functional unit
GROUPING
-6
Grouping functional unit
Effect. The initiator rejects your request.
Recovery. Determine which functional units are required for the requested service and
negotiate them. For the functional units required for the relevant procedures, see
Table B-8. After you establish a new association, check the initialize confirm to verify
that the required functional units were negotiated.
Table B-8. Functional Units Required for Create, Change-Attribute, and BeginGroup Services (page 1 of 2)
Procedure
Functional Unit Required
FTM_BEGIN_GROUP_REQ_
Grouping
FTM_CREATE_REQ_
Limited file management
FTM_CHANGE_ATTRIB_REQ_
Enhanced file management
FTM_DELETE_REQ_
Limited file management
FTM_ERASE_REQ_
File access
FTM_FILE_CLOSE_REQ_
Grouping, read, or write
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -22
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
Table B-8. Functional Units Required for Create, Change-Attribute, and BeginGroup Services (page 2 of 2)
Procedure
Functional Unit Required
FTM_FILE_OPEN_REQ_
Grouping, read, or write
FTM_LOCATE_REQ_
File access
FTM_OPEN_REQ_
Read or write
FTM_READ_ATTRIB_REQ_
Limited file management
-6003
ZFTM-ERR-ACCESS-INCNSTNT
Cause. On the FTM_CREATE_REQ_ or FTM_SELECT_REQ_ procedure, you
specified a requested-access action that was not supported or inconsistent with the
functional units negotiated when the association was established.
Subcodes. See Table B-9 to identify the action that was not supported or inconsistent
with the actions permitted for the document selected. Only the subcode of the first
reported inconsistency is displayed.
Table B-9. File-Access Subcodes
Constant
(ZFTM-ERR-ACCESS-)
Value
Meaning
READ
-1
Read access
INSERT
-2
Insert access
REPLACE
-3
Replace access
EXTEND
-4
Extend access
ERASE
-5
Erase access
READ-ATTR
-6
Read-attribute access
CHNG-ATTR
-7
Change-attribute access
DELETE
-8
Delete access
Effect. The initiator rejects your request.
Recovery. Determine if the inconsistency is in the functional unit or the requested
access. If the requested access is incorrect, reissue the create or select request with a
valid requested access.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -23
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
-6004
ZFTM-ERR-ACCESS-NOT-AVAIL
Cause. You called the FTM_READ_ATTRIB_REQ_, FTM_CHANGE_ATTRIB_REQ_
or FTM_DELETE_REQ_ when requested-access on the FTM_SELECT_REQ_ or
FTM_CREATE_REQ_ procedure call did not include the read-attribute, changeattribute, or delete-file action, respectively.
Subcodes. For the required access, see Table B-9 on page B-23. Only the subcode of
the file access first detected as missing is displayed.
Effect. The initiator rejects your request.
Recovery. Request only valid services or back out of the select regime and reissue
either the FTM_SELECT_REQ_ or FTM_CREATE_REQ_ procedure specifying the
proper requested access.
-6005
ZFTM-ERR-PROC-MODE-INCNSTNT
Cause. On the FTM_OPEN_REQ_ or FTM_FILE_OPEN_REQ_ procedure, you
specified a processing mode that was inconsistent with the requested access specified
when the file was selected.
Subcodes. See Table B-10 to determine which processing mode was inconsistent.
Table B-10. Processing-Mode Subcodes
Constant
(ZFTM-ERR-PROC-MODE-)
Value
Meaning
READ
-1
Read processing mode
INSERT
-2
Insert processing mode
REPLACE
-3
Replace processing mode
EXTEND
-4
Extend processing mode
ERASE
-5
Erase processing mode
Effect. The initiator rejects your request.
Recovery. Reissue the open request with a processing mode that is consistent with
the requested access specified when the file was selected, or reselect the file to
provide the requested access needed to be consistent with the desired processing
mode. Compare the values of the fields of the ZFTM-DDL-PROC-MODE data structure
used in the open request with the values of the fields of the ZFTM-DDL-REQUESTEDACCESS data structure used in the select request. These data structures are
described in Appendix A, DDL Definitions.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -24
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
-6006
ZFTM-ERR-FADU-ID-INVALID
Cause. On the FTM_LOCATE_REQ_, FTM_ERASE_REQ_, FTM_READ_REQ_, or
FTM_WRITE_REQ_ procedure, you specified a file-access data unit (FADU) ID that
was inconsistent with the document type requested when the file was opened.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. Reissue the request using a FADU ID that is compatible with the document
type. For an explanation of FADU IDs and the document types compatible with them,
see the OSI/FTAM Programming Guide.
-6007
ZFTM-ERR-FADU-OP-INCNSTNT
Cause. On the FTM_WRITE_REQ_ procedure, you requested a FADU operation that
was inconsistent with the processing mode(s) requested when the file was opened.
The initiator can also return this error on the FTM_WRITE_REQ_ procedure if you did
not negotiate the write functional unit when the association was established.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. If you are using a FADU operation, you must have set the processing mode
of the same name. Reissue the write request using a FADU operation that is consistent
with the file being accessed, or close and reopen the file, specifying a processing
mode that is compatible with the FADU operation requested. Note that the FADU
operation value ZFTM-VAL-FADU-OP-INSERT is valid only for FTAM-2 files, and the
FADU operation values ZFTM-VAL-FADU-OP-REPLACE and ZFTM-VAL-FADU-OPEXTEND are valid only for FTAM-1 and FTAM-3 files.
Only the insert, replace, and extend processing modes are supported by the FADU
operations; the read and erase processing modes are associated with the F-READ and
F-ERASE primitives.
If you did not negotiate the correct functional units, terminate the existing association
and establish a new association negotiating the required functional units.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -25
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
-6008
ZFTM-ERR-PROC-MODE-NOT-AVAIL
Cause. You called FTM_READ_REQ_ or FTM_ERASE_REQ_ after opening the file
with a processing mode that did not include the read or erase actions, respectively.
Subcodes. To determine what processing mode was required, see Table B-10 on
page B-24.
Effect. The initiator rejects your request.
Recovery. Close the file and reopen it specifying the correct processing mode. If the
processing mode required is inconsistent with the access requested when the file was
selected, then deselect the file and reselect it with the requested access that supports
the required processing mode.
-6009
ZFTM-ERR-ACCESS-CNTXT-INVALID
Cause. On the FTM_READ_REQ_ procedure, you specified an access context that
was not supported or inconsistent with the document type being accessed.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. Retry the request using a valid access context selected from Table B-11.
For an explanation of access context, see the OSI/FTAM Programming Guide.
Table B-11. Access Contexts by Document Type
Document Type
Access Context
FTAM-2
FA, UA
FTAM-1, FTAM-2, FTAM-3, and NBS-9
UA
-6010
ZFTM-ERR-INVALID-DATA
Cause. The data-value parameter of the FTM_DATA_REQ_ procedure was
incorrectly specified.
Subcodes. The error subcodes listed in Table B-12 on page B-27 indicate how you
could have improperly specified the data-value parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -26
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
Table B-12. Invalid-Data Subcodes
Constant
(ZFTM-ERR-INVLD-DATA-)
Value
Meaning
ZTYPE
-21
Data-element-header ZTYPE invalid
DOC-TYPE
-22
ZTYPE field inconsistent with document type
FADU
-23
ZFTM-DDL-DE-FADU values invalid
SIZE
-24
Encoded PDU greater than 16 KB
MSL
-25
Maximum string length exceeded or mismatched
Subcode -21 indicates that the ZTYPE value you specified for one of the data elements
is improper, given your specification of the first data element. For example, in the case
of writing FTAM-2 files to multiple nodes, the data should consist of one or more data
elements of type ZFTM-VAL-DE-TEXT, preceded by a data element of type
ZFTM-VAL-DE-FADU.
Subcode -22 indicates that the ZTYPE value is invalid for the specified document type.
For example, you might have specified a value of ZFTM-VAL-DE-TEXT for an FTAM-3
file.
Subcode -23 indicates that the structure used to identify the node descriptor in an
FTAM-2 operation (ZFTM-DDL-DE-FADU) contained invalid values. For example, you
might not have specified the proper ZTYPE value of ZFTM-VAL-DE-NODE-DESC.
Subcode -24 indicates that the data you specified has been encoded into a PDU that is
greater than the maximum value of 16 KB.
Subcode -25 can indicate that the string-significance value returned in the
contents type attribute on the FTM_OPEN_CNF_ or FTM_FILE_OPEN_CNF_ call is
fixed, but the length of the data element you are trying to transfer does not match the
value of the maximum-string-length parameter. This subcode can also be
returned when the string-significance value is variable or not-significant, and
the length of one of the data elements exceeds the value of the maximum-stringlength parameter.
Effect. The operation fails.
Recovery. Try the operation again, ensuring that your formatting of the data-value
parameter is consistent with the negotiated document type, string significance,
universal class, and maximum string length, and that the size of the encoded PDU is
16 KB or less. Note that you can supply up to 24 KB for the data-value parameter
(which includes both header information and data), but after the data is encoded the
size of the encoded PDU must be no more than 16 KB. For more information on the
data-value parameter, see Section 4, FTM Procedures and the OSI/FTAM
Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -27
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
-6012
ZFTM-ERR-SERV-NOT-NEGOTIATED
Cause. You have not negotiated the correct service class to perform the current task.
This error message can be returned when you attempt to perform:
•
•
•
A task within a grouped request that is not supported by the negotiated service
class
An erase or locate action in a service class other than the file-access service class
A read or write action in the management service class
Subcodes. See Table B-13 to determine the incorrect negotiated service class.
Table B-13. Service-Class Subcodes
Constant
(ZFTM-ERR-SERVICE-)
Value
Meaning
MGMT
-1
File-management service class
TRANSFER
-2
File-transfer service class
XFER-MGMT
-3
File-transfer-and-management service class
ACCESS
-4
File-access service class
Effect. The initiator rejects your request.
Recovery. If you selected the wrong group, refer to the OSI/FTAM Programming
Guide for group and service class pairings. If you attempted an erase or locate without
having negotiated the file-access service class, either reinitialize the association
negotiating the file-access service class on the FTM_INITIALIZE_REQ_ call, or
perform a function allowed in the current service class. If you attempted a read or write
in the management class, either negotiate a different service class or perform a
function allowed in the management class.
-6017
ZFTM-ERR-INVALID-IF-VERSION
Cause. The application is using a version of the FTM procedure module that is
inconsistent with the FTAM initiator process interface version.
Subcodes. None.
Effect. The program cannot run.
Recovery. This is an internal error and is unlikely to occur. If it does occur, install the
current FTAM software version, rerun the program using the current software, and retry
the operation in progress when this error occurred. If the problem persists, follow the
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -28
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
standard procedures at your site for contacting the appropriate support personnel.
These procedures might involve contacting your local HP support analyst.
-6018
ZFTM-ERR-INVALID-FIELD-VERSION
Cause. The application is using a version of the FTM procedure module that is
incompatible with the maximum field version of the FTAM initiator process.
Subcodes. None.
Effect. The program cannot run.
Recovery. This is an internal error and is unlikely to occur. If it does occur, install the
current FTAM software version, rerun the program using the current software, and retry
the operation in progress when this error occurred. If the problem persists, follow the
standard procedures at your site for contacting the appropriate support personnel.
These procedures might involve contacting your local HP support analyst.
-6019
ZFTM-ERR-BAD-APS-STATUS
Cause. The FTAM initiator detected an error while attempting to establish an
association via an APS procedure call or while interacting with the underlying OSI
layers after association establishment.
If an FTM_INITIALIZE_REQ_ procedure returned this error, an improperly configured
FTAM initiator, OSIMGR, or TAPS process could have caused it. For example, the OSI
manager name, local/remote application address, or common name might be incorrect.
If a procedure other than FTM_INITIALIZE_REQ_ returned the error, it might indicate
that the TAPS process has failed, that the association was aborted, or that a
file-system error was detected.
The initiator can also return this error when the remote system is not running.
Subcodes. None.
Effect. If an association exists, the initiator generates a provider abort.
Recovery. If an association existed, obtain the abort indication and call
APS_DISCARD_ to release the FTAM API context allocated for this CEPI. This might
be a transient condition, so establish another association and retry the operation. The
original-error-info parameter returned from APS_STATUS_ contains more
information about the problem detected by the APS procedures, OSIMGR process, or
the TAPS process. For information on the original-error-info error code and
subcode values, refer to the OSI/AS Programming Manual. For help in verifying the
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -29
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
configuration, refer to the OSI/FTAM and OSI/APLMGR SCF Reference Manual and
the OSI/AS SCF Reference Manual.
-6021
ZFTM-ERR-RESRC-DCB-ALLOC
Cause. The FTAM initiator has detected a memory allocation problem; it was unable
to allocate sufficient memory to complete your request.
Subcodes. None.
Effect. The service fails, and any file in the process of being written is left in an
unknown state.
Recovery. Call APS_DISCARD_ to discard the association context and then check
the system configuration, redistribute the workload over multiple initiators, and try
again.
-6022
ZFTM-ERR-CONNECTION-ABORTED
Cause. The FTAM initiator aborted the association or received an abort indication.
Subcodes. None.
Effect. Any request or response primitive that was in progress is returned with this
error. A provider- or user-abort-indication event is available to your application. The
initiator generates this error only when a request is in progress and an abort indication
is detected or generated. Any file in the process of being written is left in an unknown
state.
Recovery. Call APS_EVENT_RECEIVE_ to determine that an event has occurred,
and then APS_STATUS_ to determine the type of event. Then call the appropriate
FTM_U_ABORT_IND_ or FTM_P_ABORT_IND_ functions to receive the diagnostic
information to determine why the association aborted. Call APS_DISCARD_ to release
the FTAM API context allocated for this CEPI. If this is a transient condition, establish
another association and retry the operation. For more information on handling abort
indications, see the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -30
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
-6024
ZFTM-ERR-ATTR-GRP-NOT-NEG
Cause. In calling an FTM_READ_ATTRIB_REQ_ or FTM_CHANGE_ATTRIB_REQ_
procedure, you tried to use an attribute that is inconsistent with the attribute group
negotiated when the association was established using the FTM_INITIALIZE_REQ_
procedure.
Subcodes. None.
Effect. The initiator rejects your request. The attribute groups returned on the
FTM_INITIALIZE_CNF_ procedure are the valid attribute groups for the association.
Recovery. Reissue the request using only attributes in attribute groups returned on
the FTM_INITIALIZE_CNF_ procedure. If the attribute group required for the task at
hand is not supported by the responder, you might not be able to complete the task
when interoperating with that responder. For an explanation of negotiating attribute
groups, see the OSI/FTAM Programming Guide.
-6025
ZFTM-ERR-PRIVATE-USE-NOT-SUPP
Cause. Cause. You requested the private-use attribute on an
FTM_READ_ATTRIB_REQ_ procedure. The NonStop FTAM initiator does not support
the private-use attribute.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. Retry the FTM_READ_ATTRIB_REQ_ call with the ZPRIVATEUSE field of
attrib-names set to ZAPS-VAL-FALSE.
-6026
ZFTM-ERR-LOCATE-DOCTYPE
Cause. You attempted to locate a FADU in a file with a document type that does not
support multiple FADUs. For example, you used FTM_LOCATE_REQ_ on a file of
FTAM-1 or FTAM-3 document type.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. Recovery. Look at the value of contents-type from the
FTM_OPEN_CNF_ procedure. A document type of {1 0 8571 5 2} indicates that the file
is an FTAM-2 document type. Select and open an FTAM-2 file before calling
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -31
FTAM Initiator Error Codes
NonStop FTAM Initiator Error Messages
FTM_LOCATE_REQ_. For information on functional units and procedures, refer to the
OSI/FTAM Programming Guide.
-6030
ZFTM-ERR-DATA-XFER-CANCELLED
Cause. Before the initiator could act upon a data request from the FTAM application, it
received a cancel request from the responder and was therefore unable to send the
requested data.
Subcodes. None.
Effect. The data is not sent.
Recovery. Call FTM_CANCEL_IND_ to obtain the cancel indication and diagnostic
messages. Then issue the cancel response.
-6032
ZFTM-ERR-ACSE-FAILURE
Cause. The initialize request was rejected on the responding system. This indicates
an inability to establish an ACSE association.
Subcodes. None.
Effect. The association was not established. The error-code field of the
original-error-info parameter of the APS_STATUS_ call indicates the type of
error.
Table B-14. Association-Rejection Error Types
Constant
(ZAPS-VAL-CON-REJECT-)
Value
Meaning
PERM
300
A permanent error caused the association to be
rejected.
TRANS
301
A transient error caused the association to be
rejected.
The error-subcode field of the original-error-info parameter of APS_STATUS_
contains the ACSE diagnostic message (ZAPS-VAL-DIAG-xxxx). For a complete
listing of these values, see the OSI/AS Programming Manual.
Recovery. Call the APS_DISCARD_ procedure to discard the association context. If
the error is transient, retry the initialize request. If the error is permanent, determine the
cause of the failure by tracing the FTAM initiator, TAPS process, or both processes.
Also, the OSI stack on the responding system should be examined. Fix the problem,
and then rerun the application.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -32
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
-6036
ZFTM-ERR-SU-ABORTED
Cause. The SCF command ABORT SU has just been issued to a subdevice that your
application is using.
Subcodes. None.
Effect. The association associated with the aborted SU is terminated.
Recovery. Call the APS_DISCARD_ procedure to discard the association context.
Determine what problem has caused the system management staff to abort the SU. If
the problem is now fixed or is transient, establish another association and retry the
operation in progress when the SU was aborted.
-6037
ZFTM-ERR-DATA-VALUE-TOO-SMALL
Cause. The buffer-size parameter that the application specified in the
FTM_DATA_IND_ call is too small to contain the data header, the data element header,
and the current data element.
Subcodes. The subcode indicates the minimum number of bytes needed to retrieve at
least one data element and its associated header information.
Effect. The initiator rejects your request.
Recovery. Reissue the FTM_DATA_IND_ procedure, providing a larger value for the
buffer-size parameter, which determines the size of the buffer used to retrieve
data-value.
The minimum buffer size must be the sum of the length of ZAPS-DDL-DATA-HDR, the
length of ZAPS-DDL-DATA-ELEMENT-HDR, and the value of the negotiated maximum
string length. The maximum buffer size can be 25 KB.
-6038
ZFTM-ERR-API-FS-ERROR
Cause. The FTAM API has reported a file-system error in communicating with the
FTAM initiator process. The current operation fails.
Subcodes. The subcode indicates the file-system error. For descriptions of the
file-system errors, refer to the Guardian Procedure Errors and Messages Manual.
Recovery. Recovery depends on the subcode received.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -33
NonStop FTAM Initiator Error Messages
FTAM Initiator Error Codes
-6039
ZFTM-ERR-EMPTY-ASSOC-CNF
Cause. Cause. An internal ACSE confirm (A-ASSOCIATE) was received without user
data. Normally, the user data of the A-ASSOCIATE confirm would contain the
FINITIALIZE confirm. This error indicates a problem with the responding entity on the
remote system.
Subcodes. None.
Effect. The initiator rejects your request.
Recovery. Call the APS_DISCARD_ procedure to discard the association context.
Determine the cause of the failure by tracing the FTAM initiator, TAPS process, or both
processes. Also, investigate the remote system to which the initialize request was sent.
A problem with OSI addresses or configuration on that system might be causing this
error. Fix the problem and then rerun the application.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
B -34
C
ISO FTAM Diagnostic Messages
The ISO FTAM diagnostic messages returned by remote responders can have a
variety of meanings depending on their use in a particular FTAM implementation.
This appendix covers the following topics:
Topic
Page
General FTAM Diagnostic Messages
C-3
Protocol and Supporting Service-Related Diagnostic Messages
C-3
Association-Related Diagnostic Messages
C-4
Selection-Related Diagnostic Messages
C-5
File-Management-Related Diagnostic Messages
C-6
Access-Related Diagnostic Messages
C-6
Recovery-Related Diagnostic Messages
C-8
Each message contains the following information:
•
•
•
•
Error type: a code that indicates the severity of the error. Table C-1 on page C-2
lists the valid type values and their meanings.
Error identifier: a code that identifies the error condition. Table C-3 on page C-3 to
Table C-9 on page C-8 list the error identifier codes and their meanings.
Error observer: a code that identifies the entity that reported the error. Table C-2 on
page C-2 lists the valid observer values and their meanings.
Error source: a code that identifies the presumed source of the error. Table C-2 on
page C-2 lists the valid source values and their meanings.
Two fields are optional within the diagnostic element:
•
•
Suggested delay: a delay before recovery from a transient error is attempted. The
value is an integer x, which proposes a delay time of 2-to-power-x seconds.
Further details: text containing additional details on the cause of the error. It can
include nonstandardized concepts relating to the local system environment of the
file-storage provider (responder).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 1
ISO FTAM Diagnostic Messages
Table C-1. Error Types
Constant
(ZFTM-VAL-DIAG-)
Error
Type
Value
INFORMATIVE
0
An error message that does not affect the current state
of the file service and does not require any recovery.
TRANSIENT
1
An error that indicates that the failure of the operation
being performed cannot recur if the sequence is
repeated.
PERMANENT
2
An error condition that indicates that the failure of at
least the present operation is likely to occur every time
the sequence of events is repeated.
Error Type Meaning
Table C-2. Observers and Sources of Errors
Constant
(ZFTM-VALENTITYREF)
Value
Description
Qualification
NOCATPOSS
0
No categorization possible
Source only
INITFSRVUSR
1
Initiating file-service user (user
application)
INITFPMCH
2
Initiating file-protocol machine (initiator)
SRVFPMCH
3
Service supporting the file-protocol
machines (local or remote OSI services)
RESFPMCH
4
Responding file-protocol machine
(responder)
RESFSRVUSR
5
Responding file-service user (file system)
Source only
This appendix provides a series of tables listing the messages specified by the ISO
8571 standard. The messages are grouped according to the FTAM function in progress
when the error condition arises. For more information about these diagnostic
messages, consult the documentation for the FTAM responder implementation in
question. For the structures related to diagnostic messages, see ZFTM-DDL-DIAGELEM on page A-27, ZFTM-DDL-DIAGNOSTIC on page A-28, and ZFTM-DDLENTITY-REF on page A-28.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 2
General FTAM Diagnostic Messages
ISO FTAM Diagnostic Messages
General FTAM Diagnostic Messages
Table C-3. General FTAM Diagnostic Messages
Constant (ZFTM-DIAG-)
Value
Meaning
NO-REASON
0
No reason
RESPONDER-ERROR
1
Responder error (unspecific)
SYSTEM-SHUTDOWN
2
System shutdown
MGMT-PROBLEM
3
FTAM management problem (unspecific)
MGMT-BAD-ACCOUNT
4
FTAM management, bad account
MGMT-SECURITY
5
FTAM management, security not passed
DELAY-MAYBE
6
Delay might be encountered
INITIATOR-ERROR
7
Initiator error (unspecific)
SUBSEQUENT-ERROR
8
Subsequent error
INSUFF-RESOURCE
9
Temporal insufficiency of resources
VIOLATES-VFS-SECURE
10
Access request violates VFS security
VIOLATES-LOC-SECURE
11
Access request violates local security
Protocol and Supporting Service-Related
Diagnostic Messages
Table C-4. Protocol and Supporting Service-Related Diagnostic
Messages (page 1 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
CONFLICT-PARAMS
1000
Conflicting parameter values
UNSUPP-PARAM-VALUE
1001
Unsupported parameter values
MAND-PARAM-NOT-SET
1002
Mandatory parameter not set
UNSUPP-PARAMETER
1003
Unsupported parameter
DUPLICATE-PARAM
1004
Duplicated parameter
ILLEGAL-PARAM-TYPE
1005
Illegal parameter type
UNSUPP-PARAM-TYPE
1006
Unsupported parameter type
PROTOCOL-ERROR
1007
FTAM protocol error (unspecific)
PROTOCOL-ERROR-PROC
1008
FTAM protocol error, procedure error
PROTOCOL-ERROR-FU
1009
FTAM protocol error, functional unit
error
PROTOCOL-ERROR-CORR
1010
FTAM protocol error, corruption error
LOWER-LAYER-FAILURE
1011
Lower layer failure
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 3
Association-Related Diagnostic Messages
ISO FTAM Diagnostic Messages
Table C-4. Protocol and Supporting Service-Related Diagnostic
Messages (page 2 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
LOWER-LAYER-ADDRESS
1012
Lower layer addressing error
TIMEOUT
1013
Timeout
PROT-SYSTEM-SHUTDOWN
1014
System shutdown
ILLEGAL-GROUPING
1015
Illegal grouping sequence
GROUP-THRESHOLD
1016
Grouping threshold violation
ACCESS-INCNSTNT
1017
Specific PDU request inconsistent
with the current requested access
Association-Related Diagnostic Messages
Table C-5. Association-Related Diagnostic Messages
Constant (ZFTM-DIAG-)
Value
Meaning
ASSOC-NOT-ALLOWED
2000
Association with user not allowed
UNSUPP-SERV-CLASS
2002
Unsupported service class
UNSUPP-FU
2003
Unsupported functional unit
ATTR-GRP-ERROR
2004
Attribute group error (unspecific)
UNSUPP-ATTR-GROUP
2005
Attribute group not supported
UNALLOW-ATTR-GROUP
2006
Attribute group not allowed
BAD-ACCOUNT
2007
Bad account
ASSOC-MGMT
2008
Association management (unspecific)
ASSOC-MGMT-BADADDR
2009
Association management - bad address
ASSOC-MGMT-BADACCNT
2010
Association management - bad account
CHKPT-TOO-LARGE
2011
Checkpoint window error - too large
CHKPT-TOO-SMALL
2012
Checkpoint window error - too small
CHKPT-WINDOW
2013
Checkpoint window error - unsupported
UNSUPP-QOS
2014
Communications quality of service not
supported
INITIATOR-ID
2015
Initiator identity unacceptable
PRES-CNTXT-MGMT
2016
Context management refused
ROLLBACK-NOT-AVAIL
2017
Rollback not available
CNTNTS-TYPE-LIST-CUT
2018
Contents type list cut by responder
CNTNTS-TYPE-BY-PRES
2019
Contents type list by Presentation service
INVALID-FS-PASSWD
2020
Invalid file system password
INCOMPAT-SERV-CLASS
2021
Incompatible service classes
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 4
Selection-Related Diagnostic Messages
ISO FTAM Diagnostic Messages
Selection-Related Diagnostic Messages
Table C-6. Selection-Related Diagnostic Messages (page 1 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
FILENAME-NOT-FOUND
3000
File name not found
SELECT-ATTR-UNMATCH
3001
Selection attributes not matched
INIT-ATTR-NOT-GOOD
3002
Initial attributes not possible
BAD-ATTR-NAME
3003
Bad attribute name
NONEXIST-FILE
3004
Non-existent file
FILE-EXISTS
3005
File already exists
FILE-CANNOT-CREATE
3006
File cannot be created
FILE-CANNOT-DELETE
3007
File cannot be deleted
CON-CNTRL-UNAVAIL
3008
Concurrency control not available
CON-CNTRL-UNSUPP
3009
Concurrency control not supported
CON-CNTRL-BAD
3010
Concurrency control not possible
MORE-RESTRICT-LOCK
3011
More restrictive lock
FILE-BUSY
3012
File busy
FILE-UNAVAIL
3013
File not available
ACC-CNTRL-UNAVAIL
3014
Access control not available
ACC-CNTRL-UNSUPP
3015
Access control not supported
ACC-CNTRL-INCNSTNT
3016
Access Control Inconsistent
FILENAME-TRUNCATED
3017
File name truncated
INIT-ATTR-ALTERED
3018
Initial attributes altered
SELECT-BAD-ACCOUNT
3019
Bad account
OVR-SELECTED
3020
Override selected existing file
OVR-RECREATED-OLD
3021
Override deleted and recreated file with old
attributes
OVR-RECREATED-NEW
3022
Create override deleted and recreated file with
new attributes
OVR-NOT-POSS
3023
Create override - not possible
AMBIG-FILE-SPEC
3024
Ambiguous file specification
INVALID-CRT-PASSWD
3025
Invalid create password
INVALID-DLT-PASSWD
3026
Invalid delete password on override
BAD-ATTR-VALUE
3027
Bad attribute value
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 5
File-Management-Related Diagnostic Messages
ISO FTAM Diagnostic Messages
Table C-6. Selection-Related Diagnostic Messages (page 2 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
ACCESS-VIOLATES-PA
3028
Requested access violates permitted actions
FU-UNAVAIL
3029
Functional unit not available for requested
access
CREATED-NOT-SELECTED
3030
File created but not selected
File-Management-Related Diagnostic
Messages
Table C-7. File-Management-Related Diagnostic Messages
Constant (ZFTM-DIAG-)
Value
Meaning
ATTR-NONEXIST
4000
Attribute non-existent
ATTR-NOT-READ
4001
Attribute cannot be read
ATTR-CANT-CHNG
4002
Attribute cannot be changed
ATTR-UNSUPP
4003
Attribute not supported
FMGMT-BAD-ATTR-NAME
4004
Bad attribute name
FMGMT-BAD-ATTR-VAL
4005
Bad attribute value
ATTR-PARTIAL-SUPP
4006
Attribute partially supported
ATTR-INDISTINCT
4007
Additional set attribute value not distinct
Access-Related Diagnostic Messages
Table C-8. Access-Related Diagnostic Messages (page 1 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
BAD-FADU
5000
Bad FADU (unspecific)
BAD-FADU-SIZE
5001
Bad FADU - size error
BAD-FADU-TYPE
5002
Bad FADU - type error
BAD-FADU-SPEC
5003
Bad FADU - poorly specified
BAD-FADU-LOCATION
5004
Bad FADU - bad location
FADU-NOT-EXIST
5005
FADU does not exist
FADU-UNAVAIL
5006
FADU not available (unspecific)
FADU-UNAVAIL-READ
5007
FADU not available for reading
FADU-UNAVAIL-WRITE
5008
FADU not available for writing
FADU-UNAVAIL-LOCAT
5009
FADU not available for location
FADU-UNAVAIL-ERASE
5010
FADU not available for erasure
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 6
Access-Related Diagnostic Messages
ISO FTAM Diagnostic Messages
Table C-8. Access-Related Diagnostic Messages (page 2 of 2)
Constant (ZFTM-DIAG-)
Value
Meaning
FADU-CANT-INSERT
5011
FADU cannot be inserted
FADU-CANT-REPLACE
5012
FADU cannot be replaced
FADU-CANT-LOCATE
5013
FADU cannot be located
BAD-ELEM-TYPE
5014
Bad data element type
OP-UNAVAIL
5015
Operation not available
OP-UNSUPP
5016
Operation not supported
OP-INCNSTNT
5017
Operation inconsistent
ACC-CON-CNTRL-UNAV
5018
Concurrency control not available
ACC-CON-CNTRL-UNSU
5019
Concurrency control not supported
ACC-CON-CNTRL-INCN
5020
Concurrency control inconsistent
PROC-MODE-UNAVAIL
5021
Processing mode not available
PROC-MODE-UNSUPP
5022
Processing mode not supported
PROC-MODE-INCNSTNT
5023
Processing mode inconsistent
ACC-CTX-UNAVAIL
5024
Access context not available
ACC-CTX-UNSUPP
5025
Access context not supported
BAD-WRITE
5026
Bad write (unspecific)
BAD-READ
5027
Bad read (unspecific)
LOCAL-FAILURE
5028
Local failure (unspecific)
LOCAL-FAIL-FILESPACE
5029
Local failure - file space exhausted
LOCAL-FAIL-DATA
5030
Local failure - data corrupted
LOCAL-FAIL-DEVICE
5031
Local failure - device failure
FUTURE-SIZE-EXCEEDED
5032
Future file size exceeded
FUTURE-SIZE-INCREASE
5034
Future file size increased
FU-INVALID-IN-PM
5035
Functional unit invalid in processing mode
CNTNTS-TYPE-INCNST
5036
Contents type inconsistent
CNTNTS-TYPE-SIMPLE
5037
Contents type simplified
DUPLICATE-FADU-NAME
5038
Duplicate FADU name
DAMAGE-TO-REGIME
5039
Damage to select/open regime
FADU-LOCK-UNAVAIL
5040
FADU locking not available on file
FADU-LOCKED
5041
FADU locked by another user
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 7
Recovery-Related Diagnostic Messages
ISO FTAM Diagnostic Messages
Recovery-Related Diagnostic Messages
Table C-9. Recovery-Related Diagnostic Messages
Constant (ZFTM-DIAG-)
Value
Meaning
BAD-CHKPT
6000
Bad checkpoints (unspecific)
ACTIVITY-NOT-UNIQ
6001
Activity not unique
CHKPT-OUTSIDE
6002
Checkpoint outside window
ACTIVITY-NONEXIST
6003
Activity no longer exists
ACTIVITY-UNRECOG
6004
Activity not recognized
NO-DOCKET
6005
No docket
CORRUPT-DOCKET
6006
Corrupt docket
WAITING-RESTART
6007
File waiting restart
BAD-REC-PT
6008
Bad recovery point
REC-PT-NONEXIST
6009
Non-existent recovery point
REC-MODE-UNAVAIL
6010
Recovery mode not available
REC-MODE-INCNSTNT
6011
Recovery mode inconsistent
REC-MODE-REDUCED
6012
Recovery mode reduced
REC-ACC-CNTRL-UNAV
6013
Access control not available
REC-ACC-CNTRL-UNSU
6014
Access control not supported
REC-ACC-CNTRL-INCN
6015
Access control inconsistent
REC-CNTNTS-TYPE-IN
6016
Contents type inconsistent
REC-CNTNTS-TYPE-SI
6017
Contents type simplified
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
C- 8
D
NonStop FTAM Initiator Diagnostic
Messages
The NonStop FTAM initiator diagnostic messages are returned on indication and
confirm procedures when the NonStop FTAM initiator detects a problem either locally
or on the remote responder. Because there are so few of these messages, they are not
grouped in the same way that the ISO FTAM diagnostic messages in the previous
appendix are grouped. All the NonStop FTAM initiator diagnostic messages are listed
in numerical order in one table and are followed by detailed explanations of each
message, also arranged in numerical order by the value of the diagnostic message.
For the structures related to diagnostic messages, see ZFTM-DDL-DIAG-ELEM on
page A-27, ZFTM-DDL-DIAGNOSTIC on page A-28, and ZFTM-DDL-ENTITY-REF on
page A-28.
Table D-1 lists the diagnostic messages generated by the NonStop FTAM initiator. All
but message 5037 are returned by the FTM_P_ABORT_IND_ procedure and are
permanent or transient diagnostics. The only informative message is 5037, returned on
open confirm procedures.
Table D-1. NonStop FTAM Initiator Diagnostic Messages
Constant (ZFTM-DIAG-)
Value
Meaning
INITIATOR-ERROR
7
Unspecific initiator error
INSUFF-RESOURCE
9
Temporarily insufficient resources
MAND-PARAM-NOT-SET
1002
Mandatory parameter not set
PROTOCOL-ERROR
1007
Unspecific FTAM protocol error
LOWER-LAYER-FAILURE
1011
Lower-layer failure
ILLEGAL-GROUPING
1015
Illegal grouping sequence
CNTNTS-TYPE-SIMPLE
5037
Contents type simplified
7
ZFTM-DIAG-INITIATOR-ERROR
Cause. An internal software error has occurred in the initiator. The initiator can return
this diagnostic for a number of reasons. One, for example, is if it encounters problems
related to the value of the maximum-string-length parameter or the incomingPDU size.
Effect. The initiator aborts the association.
Recovery. If the Further Details field of this diagnostic contains the message
smaller PDU or larger MSL needed, the size of the encoded data received from
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
D- 1
NonStop FTAM Initiator Diagnostic Messages
the remote responder might be too large for the initiator to properly decode. You need
either to increase the size of the maximum-string-length parameter or have the
responder send smaller PDUs. You can increase the size of the maximum-stringlength parameter only if the string-significance value is not-significant. Otherwise, the
responder must send smaller PDUs.
In all other error conditions, the application should retry the operation. This message
might indicate a transient problem. If the condition persists, trace the initiator and follow
the standard procedures at your site for contacting the appropriate support personnel.
These procedures might involve contacting your local HP support analyst. For more
information on support procedures, refer to OSI/FTAM Configuration and Management
Manual.
9
ZFTM-DIAG-INSUFF-RESOURCE
Cause. The initiator has attempted to allocate memory for a data control block (DCB),
but the memory table does not have sufficient space to satisfy the request.
Effect. The initiator aborts the association.
Recovery. This message indicates a transient condition. Retry the operation. If the
condition persists, start another FTAM initiator process to balance the workload. For
information about adding an initiator process, refer to the OSI/FTAM and OSI/APLMGR
SCF Reference Manual.
1002
ZFTM-DIAG-MAND-PARAM-NOT-SET
Cause. The confirm or indication was malformed: The initiator received a confirm or
indication that required mandatory parameters, which the remote responder had not
included.
Effect. The initiator aborts the association.
Recovery. This message could indicate an interoperability problem. Consult with the
person managing the responder to determine why the responder is not providing the
required parameters.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
D- 2
NonStop FTAM Initiator Diagnostic Messages
1007
ZFTM-DIAG-PROTOCOL-ERROR
Cause. The initiator has detected a protocol error.
Effect. The initiator aborts the association.
Recovery. This message might indicate an interoperability problem. Verify that the
responder is making a valid response to the initiator. This can be done by tracing the
initiator and verifying the protocol. For help in tracing the initiator process and
troubleshooting the problem, refer to the OSI/FTAM and OSI/APLMGR SCF Reference
Manual and OSI/FTAM Configuration and Management Manual.
For protocol details, refer to Section 4, FTM Procedures.
1011
ZFTM-DIAG-LOWER-LAYER-FAILURE
Cause. The initiator has detected an error communicating with a TAPS process.
Effect. The initiator aborts the association.
Recovery. Retry the operation. If the problem persists, verify that the TAPS process is
configured properly and trace the initiator process using the PROV option. Examine the
status, error-code, error-subcode, and original-error-info information
displayed in the trace record. This information should help identify the cause of the
problem communicating with the TAPS process. For more information about tracing the
FTAM initiator/provider interface activity, refer to the OSI/FTAM and OSI/APLMGR SCF
Reference Manual.
1015
ZFTM-DIAG-ILLEGAL-GROUPING
Cause. The initiator has received a group that is invalid for the service class
negotiated for the association, or the group of procedure calls is out of sequence.
Effect. The grouped service is not performed, and the initiator aborts the association.
Recovery. This message could indicate an interoperability problem. Use the SCF
TRACE command and PTRACE to trace the initiator process and verify the group
sequence. For information about tracing the initiator process, refer to the OSI/FTAM
and OSI/APLMGR SCF Reference Manual. To verify the sequence of procedure calls,
refer to the OSI/FTAM Programming Guide.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
D- 3
NonStop FTAM Initiator Diagnostic Messages
5037
ZFTM-DIAG-CNTNTS-TYPE-SIMPLE
Cause. The initiator included an informative diagnostic message in the open confirm
because the responder had simplified the contents type from FTAM-2 to FTAM-1.
Effect. This is an information-only diagnostic message. The file-open request is
complete for an FTAM-1 contents type.
Recovery. If the simplification to FTAM-1 is acceptable to you, no action is required,
and you can continue your application. Otherwise, close the file. The remote responder
does not allow you to access the file as an FTAM-2 document.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
D- 4
E
MFM Procedures
This appendix contains detailed reference information for the module file management
(MFM) procedure calls: MFM_AWAITIOX_ and MFM_CANCELREQ_. These calls are
provided for NonStop FTAM programs using associations established in nowait mode.
Using MFM Procedure Calls
The external declarations for the current version of the MFM procedures are provided
in the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL declarations) and
$SYSTEM.SYSTEM.CEXTDECS (C declarations). You must include a ?SOURCE
EXTDECS0 directive or #include CEXTDECS directive at the beginning of each
program module that calls these procedures.
Typically, your FTAM application contains a mixture of Guardian file-system, APS
general-support, and FTM protocol procedure calls. To complete nowait operations for
all these types of procedures, you use the MFM_AWAITIOX_ procedure, rather than
the Guardian AWAITIO or AWAITIOX procedure. The reason for this practice is that a
single request from your application can cause an FTM or APS procedure to make
multiple internal calls that perform I/O operations. Each of those internal calls has its
own completion, reported to the FTAM API, and the API reports completion to your
application after all internal calls are complete. If your application used the Guardian
AWAITIO or AWAITIOX procedure, it might be misled as to the actual completion
status of its request, and the FTAM API might not get the information it needs for
processing the internal calls. The safest strategy is to use the MFM_AWAITIOX_
procedure to wait for completion of all calls requiring I/O operations—even calls you
make to Guardian file-system procedures.
The MFM_CANCELREQ_ procedure is used to cancel a nowait operation started by a
previous FTM or APS procedure call.
If you are modifying an existing program that calls AWAITIOX, you can change the
AWAITIOX calls to MFM_AWAITIOX_ calls by altering the parameters to the format
specified in this appendix and by including the declaration for MFM_AWAITIOX_ from
$SYSTEM.SYSTEM.EXTDECS0. You can make similar alterations to change
CANCELREQ calls to MFM_CANCELREQ_ calls.
For general information about how to use the MFM_CANCELREQ_ and
MFM_AWAITIOX_ procedures, refer to the OSI/FTAM Programming Guide. For
information about the significance of condition codes, see the “Considerations”
subsections for each of the procedures in this appendix. For a description of status and
error values returned by MFM_AWAITIOX_ and MFM_CANCELREQ_ procedure calls,
refer to Appendix B, NonStop FTAM Initiator Error Messages and the OSI/AS
Programming Manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 1
Procedure Descriptions
MFM Procedures
Procedure Descriptions
The names of all MFM procedures start with the characters “MFM_.” Figure 4-1 on
page 4-10 shows the syntax notation used to describe procedure calls in this manual.
This notation gives the syntax for calling the procedures from C or TAL programs. This
appendix provides the syntax and semantics of the MFM procedures, in alphabetic
order. The information about each procedure call includes the following:
•
•
•
•
Description of its use
Syntax
Parameter descriptions
Considerations (added information about the procedure)
MFM_AWAITIOX_
This procedure allows you, when in nowait mode, to check for completion of, and
obtain the information returned from, a previous file-system, APS procedure call, or
FTM procedure call. If your application uses NonStop FTAM procedures, you cannot
call AWAITIOX directly; you must call MFM_AWAITIOX_ instead. Except where stated
otherwise, the parameters to MFM_AWAITIOX_ have the same syntax and use as the
corresponding parameters for AWAITIOX.
For further information about the use of these parameters with file-system files, see the
OSI/FTAM Programming Guide and the description of the AWAITIOX procedure in the
Guardian Procedure Calls Reference Manual.
CALL MFM_AWAITIOX_ (
,
,[
,[
,[
,[
,[
status
status
filenum
buffer-addr ]
count-transferred ]
tag ]
timelimit ]
segment-id ] );
!
!
!
!
!
!
!
O
I/O
O
O
O
I
O
output
INT .EXT:ref:1
indicates the outcome of an FTM or APS procedure call. For a list of possible
ZAPS-VAL-STATUS-xxx values, see Table B-1 on page B-2. If the call was to a
file-system procedure rather than an FTM or APS procedure, the value is 0.
filenum
input, output
INT .EXT:ref:1
identifies a file number or CEPI for which you are requesting returned information.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 2
MFM_AWAITIOX_
MFM Procedures
When you call this procedure, give the filenum parameter one of the following
values:
•
•
•
-1, to show that you want information on the first completion of an FTM, APS,
or file-system procedure.
A CEPI, to show that you want information on the first completion of an FTM or
APS procedure for a particular connection.
A file-system file number, to show that you want information on the completion
of a file-system call made on a particular file-system open. On completion of
this procedure, the filenum parameter shows the CEPI or file-system file
number of the completed procedure.
On completion of this procedure, the filenum parameter shows the CEPI or
file-system file number of the completed procedure.
buffer-addr
output
INT(32) .EXT:ref:1
displays the relative extended address of the buffer specified when the operation
was initiated. For NonStop FTAM operations, this parameter is not relevant and
has the value -1D.
count-transferred
output
INT .EXT:ref:1
displays the number of bytes transferred by the associated operation. For NonStop
FTAM operations, this parameter is not relevant and has the value -1.
tag
output
INT(32) .EXT:ref:1
displays the application-defined tag that was stored by the file system when the I/O
operation associated with this completion was initiated. If you did not specify a tag
when the operation was initiated, the value of this parameter is -1D.
timelimit
input
INT(32):value
specifies the length of time you are willing to wait for a completion.
The following values are possible:
•
•
•
0, to check for a completion without waiting.
-1, to wait indefinitely for a completion.
A positive number n, to wait for n time units for a completion. Do not specify
this value if you specify a CEPI for the filenum parameter. If timelimit is a
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 3
MFM_CANCELREQ_
MFM Procedures
positive number and filenum is a CEPI, the call is rejected with a status
value of ZAPS-VAL-STATUS-NO-RETRY.
segment-id output
INT .EXT:ref:1
displays the segment ID of the extended segment containing the buffer when the
operation was initiated. For NonStop FTAM operations, this parameter is not
relevant and has the value -1.
Considerations
•
Perform error checking as follows:
1. Immediately after the call to MFM_AWAITIOX_, check the filenum returned.
2. If filenum is a CEPI (a value in the range -10 through -32767), then check
the status value returned by MFM_AWAITIOX_.
If filenum is not a CEPI, check the condition code and/or call FILEINFO with
the filenum value returned by MFM_AWAITIOX_.
•
•
For a file-system completion, the condition code is identical to that set by
AWAITIOX. For an FTM or APS completion, the condition code has no meaning.
To get APS_STATUS_ information from an FTM or APS procedure call in nowait
mode, you must call APS_STATUS_ immediately after the call to
MFM_AWAITIOX_. Between the procedure call and the call to APS_STATUS_, you
can perform error checking, but you cannot call any other FTM or APS procedure
to invoke a primitive or receive an event. APS_STATUS_ provides information only
on the most recently completed primitive or the most recently received event;
information on earlier primitives and events is not queued.
MFM_CANCELREQ_
This procedure allows you to cancel a nowait operation started by a previous FTM or
APS procedure. To cancel a file-system operation, call CANCELREQ instead.
error := MFM_CANCELREQ_ ( pseudofn
,[ tag ] );
error
! I
! I
return value
INT
indicates the outcome of the call. For the possible values of error, see Appendix B,
NonStop FTAM Initiator Error Messages, Table B-2 on page B-4.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 4
MFM_CANCELREQ_
MFM Procedures
pseudofn
input
INT:value
is the pseudo file number for which you want to cancel an operation. For FTAM or
APS procedures, this is the connection endpoint identifier (CEPI).
tag
input
INT(32):value
identifies the operation you wish to cancel.
Considerations
•
•
•
The semantics of MFM_CANCELREQ_ are similar to those of the file-system
procedure CANCELREQ.
The condition code is undefined after a call to MFM_CANCELREQ_.
A successful call to MFM_CANCELREQ_ does not guarantee that the operation
being canceled was not performed. It does, however, guarantee that the FTAM
initiator will not notify you of its completion.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 5
MFM Procedures
MFM_CANCELREQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
E- 6
F
APS Procedures
This appendix contains detailed reference information on the general-support
procedures provided with NonStop FTAM API, including APS_DISCARD_,
APS_EVENT_RECEIVE_, APS_INITIALIZE_, and APS_STATUS_. You use these
procedures mainly to allocate and deallocate buffer space for use by the FTAM API, or
retrieve event and error information.
If you are familiar with the OSI/AS API, you might recognize the APS procedures
contained in the FTAM API, which are a small subset of the APS procedures that make
up the OSI/AS API. The APS procedures that are part of the FTAM API perform
equivalent functions to procedures by the same name that are part of the OSI/AS API.
This appendix covers the following topics:
Topic
Page
Using APS Procedure Calls
F-1
Procedure Descriptions
F-2
Using APS Procedure Calls
The external declarations for the current version of the APS procedures are provided in
the system files $SYSTEM.SYSTEM.EXTDECS0 (TAL declarations) and
$SYSTEM.SYSTEM.CEXTDECS (C declarations). You must include EXTDECS0 or
CEXTDECS in your program before making any calls to the procedures.
The NonStop FTAM distribution subvolume ZOSIFTAM supplies files containing the
data declarations needed for these FTAM procedures, as follows:
•
•
•
The file ZAPSTAL contains TAL declarations for the data structures used in the
parameters to the APS procedure calls.
The file ZAPSC contains the C declarations for the data structures used in the
parameters to the APS procedure calls.
The file ZAPSDDL is the DDL source from which the ZAPSTAL and ZAPSC
declarations were produced. For a detailed description of pertinent structures in
ZAPSDDL, refer to Appendix A, DDL Definitions. For a description of all structures
in ZAPSDDL, refer to the OSI/AS Programming Manual.
For general information about how to use these procedure calls, refer to the OSI/FTAM
Programming Guide. The use of some of these procedure calls in applications written
using the FTM procedure calls are also illustrated in that manual. For a description of
errors returned by APS procedure calls, refer to Appendix B, NonStop FTAM Initiator
Error Messages and the OSI/AS Programming Manual.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-1
Procedure Descriptions
APS Procedures
Procedure Descriptions
The names of all APS procedures start with the characters “APS_.” Figure 4-1 on
page 4-10 shows the syntax notation used to describe procedure calls in this manual.
This notation gives the syntax for calling the procedures from C or TAL programs.
This appendix provides the syntax and semantics of the APS procedures, in alphabetic
order. The information about each procedure call includes the following:
•
•
•
•
Description of its use
Syntax
Parameter descriptions
Considerations (added information about the procedure)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-2
APS_DISCARD_
APS Procedures
APS_DISCARD_
This procedure allows you to delete the API context information for an association.
After APS_DISCARD_ has completed successfully, you can no longer use the CEPI. In
normal circumstances, call APS_DISCARD_ after the association has been released
or aborted by your application, by the remote responder, or by the service provider. In
exceptional circumstances, you can call APS_DISCARD_ without previously releasing
or aborting the association. Doing this provides the most abrupt disconnection
possible.
status := APS_DISCARD_ ( cepi );
status
! I
returned value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) for this association. Note that after this
procedure has completed successfully, no further FTM or APS procedures can be
called for this CEPI.
Considerations
•
•
•
In nowait mode, do not call MFM_AWAITIOX_ to complete this procedure.
You can call APS_DISCARD_ at any time, even when FTAM or APS procedures
are awaiting completion.
If a problem occurs and you call APS_DISCARD_, the source of the problem might
be hard to determine: APS_DISCARD_ deletes the subdevice, and it can no longer
be referenced through the SCF interactive interface.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-3
APS_EVENT_RECEIVE_
APS Procedures
APS_EVENT_RECEIVE_
This procedure allows you to receive an event. In other words, it notifies you when an
indication or confirm primitive becomes available to you. If the association is in nowait
mode, complete this operation by calling MFM_AWAITIOX_ on page E-2.
When you have received an event, call APS_STATUS_ to determine which event. For
further information about the use of this procedure, see in the OSI/FTAM Programming
Guide.
status := APS_EVENT_RECEIVE_ ( cepi
,[ time-limit ]
,[ tag ] )
,[ block-size ] );
status
!
!
!
!
I
I
I
I
returned value
INT
indicates the outcome of the call. For a list of possible ZAPS-VAL-STATUS-xxx
values, see Table B-1 on page B-2. If you are in wait mode, the value ZAPS-VALSTATUS-EVENT tells you that you have received an event. In nowait mode, the
value ZAPS-VAL-STATUS-EVENT is returned later, when you call
MFM_AWAITIOX_.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) for this association.
time-limit
input
INT(32):value
indicates how long you are willing to wait for an event to occur. The following
values are valid for this parameter:
0D
Check for an event without waiting.
-1D
Wait indefinitely for an event. This is the default value.
Note. If you use the value -1D in wait mode, the procedure does not complete until you receive
an event. If you simply want to check for an event but carry on processing if no event is
available, specify the value 0D.
tag
input
INT(32):value
is for use in nowait mode only. Specify a unique value to identify this instance of
the procedure call. When the operation is complete, the MFM_AWAITIOX_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-4
APS_EVENT_RECEIVE_
APS Procedures
procedure displays the tag value, allowing you to match the completion with the
correct instance of the procedure call.
block-size
input
INT:value
is an optional parameter that determines how events are to be retrieved. In
NonStop FTAM operations, this parameter is not used.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-5
APS_INITIALIZE_
APS Procedures
APS_INITIALIZE_
This procedure allocates and initializes a segment that holds context information for all
of your API associations. This procedure must be the first FTAM procedure you call in
your program. Call it only once.
error := APS_INITIALIZE_ ( [ swapvol ] );
error
! I
returned value
INT
indicates the outcome of the call. This value can be either a negative APS error
code or a positive file-system error number. For the possible errors, see in
Appendix B, NonStop FTAM Initiator Error Messages. For the possible file-system
errors, refer to the Guardian Procedure Errors and Messages Manual.
swapvol
input
INT .EXT:ref:(ZAPS-DDL-SWAP-VOLUME)
contains the name of the optional disk volume you wish to use as the swap volume
for your API segment. The volume name must be in internal form (blankfilled on
the right). If this parameter is omitted, the volume used for swapping the data stack
of the program is used by default.
Considerations
•
•
Because this procedure does not perform any file-system I/O operations, the
request is always completed immediately after the procedure call. Even in nowait
mode, do not call MFM_AWAITIOX_ to complete this procedure.
Once you have successfully called this procedure, subsequent calls to the same
procedure are rejected with an error (ZAPS-ERR-INVALID-OPERATION) and are
ignored.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-6
APS_STATUS_
APS Procedures
APS_STATUS_
This procedure allows you to obtain status information for an established association or
an association attempt. Use it in the following circumstances:
•
•
•
After an error, to obtain the error code and other details.
After an event, to obtain the event code.
After the successful completion of an FTM_INITIALIZE_REQ_ procedure, if you
wish to obtain the name of the subdevice (SU) created for the association.
error := APS_STATUS_ ( cepi
,[ event-code ]
,[ device-name ]
,[ error-code ]
,[ error-subcode ]
,[ service-id ]
,[ diagnostic-buffer ]
,[ original-error-info ] )
,[ transport-state ]
,[ transport-substate ] );
error
!
!
!
!
!
!
!
!
!
!
I
O
O
O
O
O
O
O
O
O
returned value
INT
indicates the outcome of the call. For the possible values of ZAPS-ERR-xxx, see
Appendix B, NonStop FTAM Initiator Error Messages.
cepi
input
INT:value
is the connection endpoint identifier (CEPI) for this association. Use it to specify
the association for which you require status information. Specify a cepi value of -1
if you need status information about an error that has occurred in either of the
following situations:
•
•
Before an association is established via the FTM_INITIALIZE_REQ_
procedure.
When you did not supply a CEPI in a procedure for which cepi is a mandatory
parameter.
event-code
output
INT .EXT:ref:1
indicates the most recent event received on the association. For a list of the
ZFAPS-VAL-EVT-xxx values and their definitions, see Table A-1 on page A-39.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-7
APS_STATUS_
APS Procedures
device-name
output
INT .EXT:ref:(ZAPS-DDL-FILENAME)
is the complete FTAM device name, including subdevice, of the association for the
CEPI you specified. This parameter is available for the CEPI after an
FTM_INITIALIZE_REQ_ procedure has completed successfully. For more
information about subdevices (SUs), refer to the OSI/FTAM Programming Guide or
the OSI/FTAM and OSI/APLMGR SCF Reference Manual.
error-code
output
INT .EXT:ref:1
indicates the current error condition, if any, for this CEPI. For the possible values of
this parameter, see Appendix B, NonStop FTAM Initiator Error Messages.
error-subcode
output
INT .EXT:ref:1
is a subcode qualifying error-code. For the possible values of this parameter, see
Appendix B, NonStop FTAM Initiator Error Messages.
service-id
output
INT .EXT:ref:1
identifies the service that generated an error condition. For the possible values of
this parameter, see ZAPS-DDL-SERVICE-ID on page A-10. If no error has
occurred, the value is ZAPS-VAL-SERVICE-NOVALUE.
diagnostic-buffer output
INT .EXT:ref:(ZAPS-DDL-DIAG-BUF)
is a diagnostic-message buffer used to analyze errors. This parameter is reserved
for NonStop internal use.
original-error-info
output
INT .EXT:ref:(ZAPS-DDL-ORIGINAL-ERROR)
indicates the first detected error. This parameter is intended to be used in problem
diagnosis.
transport-state
output
INT .EXT:ref:1
indicates the current transport state, if applicable, for the specified CEPI. This
parameter is not used in NonStop FTAM operations and returns a value of 0.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-8
APS_STATUS_
APS Procedures
transport-substate
output
INT .EXT:ref:1
indicates the substate qualifying the current transport state, if applicable, for the
specified CEPI. This parameter is not used in NonStop FTAM operations and
returns a value of 0.
Considerations
•
•
•
•
Because this procedure does not perform any file-system I/O operations, the
request is always completed immediately after the procedure call. Even in nowait
mode, do not call MFM_AWAITIOX_ to complete this procedure.
To get APS_STATUS_ information from an APS or FTM procedure call, you must
call APS_STATUS_ immediately after that procedure call if in wait mode, or
immediately after the completing call to MFM_AWAITIOX_ if in nowait mode. The
call to APS_STATUS_ must be made before you call any other APS or FTM
procedure to invoke a primitive or receive an event. APS_STATUS_ provides
information only on the most recently completed primitive or the most recently
received event; information on earlier primitives and events is not retained.
The returned function value, error, shows the outcome of the procedure call, not
the status of the CEPI. When the returned function value indicates an error, the
APS_STATUS_ procedure has failed and the values of the output parameters are
undefined.
To retrieve additional information on an error condition, you can trace your
application.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F-9
APS_STATUS_
APS Procedures
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
F- 10
G
NonStop FTAM Programming
Examples
This appendix covers the following topics:
Topic
Page
Example Structure and Protocol
G-2
Example 1 in C—Updating a Remote File (in Nowait Mode)
G-12
Example 1 in TAL—Updating a Remote File (in Nowait Mode)
G-56
Example 2 in C—Moving a File Between Two Remote Systems (in Wait Mode)
G-106
Example 2 in TAL—Moving a File Between Two Remote Systems (in Wait Mode)
G-161
Translation Application Example
G-221
This appendix contains sample programs that illustrate the use of FTAM programming
procedures. Example 1 updates a remote FTAM-2 file in nowait mode. Example 2
moves an FTAM-3 file between two remote systems in wait mode. Both examples are
provided in the C and TAL programming languages, and the source programs for each
version are included in the release subvolume ZOSIFTAM.
In addition to the example programs contained in this appendix, the OSI/FTAM
Programming Guide also contains two example programs. One example, called
EXCREAF3 and written in the C programming language, reads an FTAM-3 file from a
remote system and writes the contents to a file on the NonStop system. A second
example, called EXTWRIF1 and written in the TAL programming language, creates an
FTAM-1 file on a remote system and writes to it the contents of an edit file on the
NonStop system.
To fully understand these programs, you should be familiar with the material in the
OSI/FTAM Programming Guide. Section 4, FTM Procedures also provides reference
information about these procedure calls and their parameters.
All procedure calls except those for the erase and locate procedures are included in
one or both of the examples in this appendix. Short program excerpts illustrating how
to use the erase and locate procedures are included in the procedure descriptions in
Section 4, FTM Procedures. The programming examples illustrate the use of all
optional parameters. For references to line numbers on which a procedure call is
illustrated, see “Examples” under each procedure call description in Section 4, FTM
Procedures.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 1
NonStop FTAM Programming Examples
Example Structure and Protocol
Note. Besides making changes to the environmental variables contained in the programming
examples in this manual, you might need to modify the examples to exclude certain procedure
calls, depending upon the FTAM implementation with which you are interoperating. For
example, the F-CHANGE-ATTRIB primitive might not be supported by all vendors; if the
responding system does not support the F-CHANGE-ATTRIB primitive, you should not call the
FTM_CHANGE_ATTRIB_REQ_ used in the examples.
Appendix A, DDL Definitions lists and defines the DDL structures used by the FTM
procedures. DDL structures are punctuated with hyphens (-) while structures in C code
are punctuated with underscores ( _ ), and in TAL code, with circumflexes ( ^ ).
Structure names in C and TAL end with “_def” and “^DEF,” respectively. For
descriptions of the information contained in the FTAM structures used in the
programming examples, see the corresponding DDL structures in Appendix A, DDL
Definitions.
For information about error codes and subcodes returned on FTAM procedures, refer
to Appendix B, NonStop FTAM Initiator Error Messages. Section 4, FTM Procedures
lists errors returned on specific procedure calls and indicates what some of them mean
in the context of that call. The OSI/FTAM Programming Guide describes how to handle
errors returned in applications on FTM procedure calls.
This appendix also includes diagrams of the primitive sequences used in the two
programming examples.
Example Structure and Protocol
This subsection provides protocol diagrams for the four programming examples that
follow. Example 1 updates a remote FTAM-2 file in nowait mode. The example is
provided in two versions:
•
•
EXCINSF2 written in the C programming language (for details, refer to page G-12);
EXTINSF2 written in the TAL programming language (for details, refer to page
G-56).
Example 2 moves an FTAM-3 file between two remote systems in wait mode. The
example is also provided in two versions:
•
•
EXCMOVF3 written in the C programming language (for details, refer to page
G-106);
EXTMOVF3 written in the TAL programming language (for details, refer to page
G-161).
The Translation Application Example on page G-221 opens the responder and issues
the Enable Translation command. It then reads its $RECEIVE and processes all
translation requests.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 2
NonStop FTAM Programming Examples
Example 1—Updating a Remote File (in Nowait
Mode)
Example 1—Updating a Remote File (in Nowait Mode)
This programming example illustrates selective updating of an FTAM-2 file. It
implements the routines for writing a FADU to a file on a remote system. All the FTAM
routines operate in nowait mode. Nowait mode provides the benefits of improved
performance in that it allows the program to perform multiple I/O operations
concurrently. This also allows a faster response to remote indications. For more
information about nowait mode, see the OSI/FTAM Programming Guide.
To demonstrate the use of nowait mode, this program has at least two operations
outstanding after the initialize request has been issued: an event receive and a request
to the remote responder. During data transfer, a Guardian read is also outstanding.
This example does the following:
1. Opens the local Guardian file for reading.
2. Establishes an APS segment for the association.
3. Initializes the association.
4. Selects and opens the file on the remote responder.
5. Requests the transfer of the FADU data to the remote file.
6. Reads a Guardian file with a Guardian READ call.
7. Transfers the data.
8. Indicates the end of the transfer of FADU data.
9. Ends the transferring of data to the file.
10. Closes and deselects the file.
11. Terminates the association.
12. Discards the association.
13. Closes the local Guardian file.
Figure G-1 on page G-4 shows the protocol diagram detailing the sequence of APS
and FTM procedure calls used in Example 1. The numbers at the left of the diagram
correspond to the program tasks (1 through 13) described above. To distinguish
MFM_AWAITIOX_ procedures for network events and I/O completions, suffixes (EVT)
and (I/O) have been appended to the MFM_AWAITIOX_ procedure calls.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 3
NonStop FTAM Programming Examples
Example 1—Updating a Remote File (in Nowait
Mode)
Figure G-1. Protocol Diagram for Programming Example 1 (page 1 of 2)
Application
Program
1
2
FTAM
Regime
Remote
Responder
GUARDIAN OPEN
APS_INITIALIZE_
FTM_INITIALIZE_REQ_
MFM_AWAITIOX_(I/O)
APS_EVENT-RECEIVE_
MFM_AWAITIOX_(EVT)
APS_STATUS_
FTM_INITIALIZE_CNF_
3
4 Selection FTM_FILE_OPEN_REQ_
and Open APS_EVENT_RECEIVE_
MFM_AWAITIOX_(I/O)
Regimes
MFM_AWAITIOX_(EVT)
APS_STATUS_
FTM_INITIALIZE_CNF_
5 Data
Transfer
Regime
6
7
Tandem FTAM
Initiator
FTM_WRITE_REQ_
APS_EVENT_RECEIVE_
MFM_AWAITIOX_(I/O)
GUARDIAN READ
MFM_AWAITIOX_(I/O)
FTM_DATA_REQ_
GUARDIAN READ
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(I/O)
FTM_DATA_REQ_
GUARDIAN READ
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(I/O)
FTM_DATA_REQ_
GUARDIAN READ
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(I/O)
FTM_DATA_REQ_
F-INITIALIZE indication
F-INITIALIZE response
Grouped
indication
Grouped
response
F-BEGIN-GROUP
F-SELECT
F-OPEN
F-END-GROUP
F-WRITE indication
F-DATA indication
F-DATA indication
F-DATA indication
F-DATA indication
VSTG01a.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 4
NonStop FTAM Programming Examples
Example 1—Updating a Remote File (in Nowait
Mode)
Figure G-1. Protocol Diagram for Programming Example 1 (page 2 of 2)
Application
Program
GUARDIAN READ
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(I/O)
FTM_DATA_REQ_
GUARDIAN READ
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(I/O)
FTM_DATA_END_REQ_
MFM_AWAITIOX_(I/O)
FTM_TRANSFER_END_REQ_
MFM_AWAITIOX_(I/O)
AMFM_AWAITIOX_(EVT)
APS_STATUS_
FTM_TRANSFER_END_CNF_
Tandem FTAM
Initiator
Remote
Responder
Data
Transfer
Regime
8
9
Selection
10 and Open
FTM_FILE_CLOSE_REQ_
Regimes APS_EVENT_RECEIVE_
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(EVT)
APS_STATUS_
FTM_FILE_CLOSE_CNF_
F-DATA indication
F-DATA-END indication
F-TRANSFER-END indication
F-TRANSFER-END response
Grouped
indication
Grouped
response
F-BEGIN-GROUP
F-SELECT
F-OPEN
F-END-GROUP
F-WRITE indication
11 FTAM
Regime
12
13
FTM_TERMINATE_REQ_
APS_EVENT_RECEIVE_
MFM_AWAITIOX_(I/O)
MFM_AWAITIOX_(EVT)
APS_STATUS_
FTM_TERMINATE_CNF_
F-TERMINATE indication
F-TERMINATE response
APS_DISCARD_
GUARDIAN CLOSE
VSTG01b.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 5
NonStop FTAM Programming Examples
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
Example 2—Moving a File Between Two Remote Systems (in
Wait Mode)
This programming example illustrates moving a simple binary file. This example
implements the routines for moving an FTAM-3 file from one remote system to another
remote system on the network. The FTAM routines used in this example operate in
wait mode. The example does the following:
1. Establishes an APS segment.
2. Initializes an association with the source system.
3. Initializes an association with the destination system.
4. Selects the source file.
5. Reads the file attributes from the source file.
6. Opens the source file.
7. Creates the destination file, using file attributes based on the source file attributes.
8. Opens the destination file.
9. Sends a write request to the destination.
10. Sends a read request to the source.
11. Receives a cancel indication from the source, and then sends a cancel response to
the source, sends a cancel request to the destination, and receives a cancel
confirm from the destination.
or
Receives a data indication from the source and sends a data request to the
destination.
Note. It is also possible to receive a cancel indication from the destination system. This
example program does not formally handle cancel indications from the destination system.
If the destination system sends a cancel indication, you will detect it in the return code
from a data request to the destination system. In this case, the example program discards
the association—a program task that is not reflected in the following protocol diagram. The
diagram shows only the final discard that is normally done after terminating an association.
or
Receives a data end indication from the source and sends a data end request to
the destination.
12. Terminates the transfer of data from the source file.
13. Terminates the transfer of data to the destination file.
14. Closes the destination file.
15. Changes the destination file attributes on the basis of the source file attributes.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 6
NonStop FTAM Programming Examples
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
16. Deselects the destination file.
17. Closes the source file.
18. Deletes the source file.
19. Terminates the association with the source system.
20. Terminates the association with the destination system.
21. Discards the association with the source system.
22. Discards the association with the destination system.
When APS_STATUS_ is called and an error is returned, the program branches to an
error-handling routine. Within this routine, aborts are checked and handled if present.
Any of the following procedures can be called during error handling:
FTM_U_ABORT_REQ_
FTM_U_ABORT_IND_
FTM_P_ABORT_IND_
Figure G-2 on page G-8 shows the protocol diagram detailing the sequence of APS
and FTM procedure calls used in Example 2. The numbers at the left of the
“Application Program” box in the diagram correspond to the program tasks (1 through
22) described above.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 7
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
NonStop FTAM Programming Examples
Figure G-2. Protocol Diagram for Programming Example 2 (page 1 of 4)
Source
Responder
FTAM Regime
FTAM
Initiator
Application
Program
1
FTAM
Initiator
Destination
Responder
APS_INITIALIZE_
2 FTM_INITIALIZE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_INITIALIZE_CNF_
F-INITIALIZE indication
F-INITIALIZE response
3 FTM_INITIALIZE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_INITIALIZE_CNF_
F-INITIALIZE indication
F-INITIALIZE response
Select and Open
Regimes
F-BEGIN-GROUP
F-SELECT
F-READ-ATTRIB
F-OPEN
F-END-GROUP
indication
F-BEGIN-GROUP
F-SELECT
F-READ-ATTRIB
F-OPEN
F-END-GROUP
response
FTM_BEGIN_GROUP_REQ_
FTM_SELECT_REQ_
5 FTM_READ_ATTRIB_REQ_
FTM_OPEN_REQ_
6
FTM_END_GROUP_REQ_
4
APS_EVENT_RECEIVE_
APS_STATUS_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_SELECT_CNF_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_READ_ATTRIB_CNF_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_OPEN_CNF_
APS_EVENT_RECEIVE_
APS_STATUS_
VSTG02a.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 8
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
NonStop FTAM Programming Examples
Figure G-2. Protocol Diagram for Programming Example 2 (page 2 of 4)
Source
Responder
Select and Open
Regimes (continued)
FTAM
Initiator
Application
Program
7
8
FTM_BEGIN_GROUP_REQ_
FTM_CREATE_REQ_
FTM_OPEN_REQ_
FTM_END_GROUP_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CREATE_CNF_
FTAM
Initiator
Destination
Responder
F-BEGIN-GROUP
F-CREATE
F-OPEN
F-END-GROUP
indication
F-BEGIN-GROUP
F-CREATE
F-OPEN
F-END-GROUP
response
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_OPEN_CNF_
APS_EVENT_RECEIVE_
APS_STATUS_
Data Transfer Regime
9
10
F-READ indication
F-CANCEL request
11
F-CANCEL confirm
F-DATA request
FTM_WRITE_REQ_
FTM_READ_REQ_
Start Loop
APS_EVENT_RECEIVE_
APS_STATUS_
Either
FTM_CANCEL_IND_
FTM_CANCEL_RSP_
FTM_CANCEL_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CANCEL_CNF_
F-WRITE indication
F-CANCEL indication
F-CANCEL response
Or
FTM_DATA_IND_
FTM_DATA_REQ_
F-DATA indication
F-DATA-END request
Or
FTM_DATA_END_IND_
FTM_DATA_END_REQ_
F-DATA-END indication
End Loop
VSTG02b.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 9
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
NonStop FTAM Programming Examples
Figure G-2. Protocol Diagram for Programming Example 2 (page 3 of 4)
Source
Responder
Data Transfer Regime
(continued)
F-TRANSFER-END
indication
F-TRANSFER-END
response
FTAM
Initiator
Application
Program
Destination
Responder
12 FTM_TRANSFER_END_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_TRANSFER_END_CNF_
13 FTM_TRANSFER_END_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_TRANSFER_END_CNF_
Select and Open
Regimes
FTAM
Initiator
FTM_BEGIN_GROUP_REQ_
FTM_CLOSE_REQ_
14
15 FTM_CHANGE_ATTRIB_REQ_
FTM_DESELECT_REQ_
16
FTM_END_GROUP_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CLOSE_CNF_
F-TRANSFER-END
indication
F-TRANSFER-END
response
F-BEGIN-GROUP
F-CLOSE
F-CHANGE-ATTRIB
F-DESELECT
F-END-GROUP
indication
F-BEGIN-GROUP
F-CLOSE
F-CHANGE-ATTRIB
F-DESELECT
F-END-GROUP
response
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CHANGE_ATTRIB_CNF
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_DESELECT_CNF
APS_EVENT_RECEIVE_
APS_STATUS_
VSTG02c.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -10
Example 2—Moving a File Between Two Remote
Systems (in Wait Mode)
NonStop FTAM Programming Examples
Figure G-2. Protocol Diagram for Programming Example 2 (page 4 of 4)
Source
Responder
FTAM
Initiator
Application
Program
Select and Open
Regimes (continued)
F-BEGIN-GROUP
F-CLOSE
F-DELETE
F-END-GROUP
indication
17
18
F-BEGIN-GROUP
F-CLOSE
F-DELETE
F-END-GROUP
response
FTAM
Initiator
Destination
Responder
FTM_BEGIN_GROUP_REQ_
FTM_CLOSE_REQ_
FTM_DELETE_REQ_
FTM_END_GROUP_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_CLOSE_CNF_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_DELETE_CNF_
10
FTAM Regime
F-TERMINATE indication
F-TERMINATE response
APS_EVENT_RECEIVE_
APS_STATUS_
19 FTM_TERMINATE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_TERMINATE_CNF_
20 FTM_TERMINATE_REQ_
APS_EVENT_RECEIVE_
APS_STATUS_
FTM_TERMINATE_CNF_
21
22
F-TERMINATE indication
F-TERMINATE response
APS_DISCARD_
APS_DISCARD_
VSTG02d.vsd
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -11
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
Example 1 in C—Updating a Remote File (in
Nowait Mode)
1
/***********************************************************************/
2
/*
*/
3
/* Example 1 in C - Updating a Remote FTAM-2 File (in Nowait Mode)
*/
4
/*
*/
5
/***********************************************************************/
6
/*
*/
7
/* Program Name: EXCINSF2
*/
8
/*
*/
9
/* Program Description:
*/
10 /*
*/
11 /* This program, in nowait mode, inserts five records into a remote
*/
12 /* FTAM-2 file. The application initiates and manages this data
*/
13 /* transfer. It opens and reads a local (Enscribe relative) file
*/
14 /* using Guardian system procedures and sends five records as data
*/
15 /* requests to the remote file. Both the Guardian system calls
*/
16 /* and the Tandem FTAM procedure calls are made in nowait mode.
*/
17 /*
*/
18 /* The main procedure contains the initialization code, the control
*/
19 /* statements for the main processing loop, and the termination code.
*/
20 /* This procedure analyzes input received from MFM_AWAITIOX_ and
*/
21 /* calls one of three procedures to perform processing as indicated:
*/
22 /*
*/
23 /*
ftam_io_cmpl
24 /*
A routine that handles FTAM I/O
*/
completions
*/
25 /*
26 /*
*/
ftam_event_rcvd
27 /*
A routine that handles FTAM events
*/
received from the remote responder
*/
28 /*
29 /*
*/
data_transfer
A routine that obtains data from the
*/
30 /*
local file, formats it, and then
*/
31 /*
sends it to the remote file
*/
32 /*
*/
33 /* Four error-handling routines are used in this program:
*/
34 /*
*/
35 /*
36 /*
check_status
A procedure that checks status
*/
returned by FTM request and
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -12
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
37 /*
response procedures, as well as the
*/
38 /*
I/O completions
*/
39 /*
40 /*
*/
check_error
A procedure that checks for errors
*/
41 /*
returned by FTM indication and
*/
42 /*
confirm procedures
*/
43 /*
44 /*
*/
check_action_diag
A procedure that checks the action
*/
45 /*
result and diagnostic messages
*/
46 /*
returned by an FTM procedure
*/
47 /*
48 /*
*/
bad_state A procedure
49 /*
that handles an invalid
*/
FTM state result
*/
50 /*
*/
51 /*
FTM requests and responses return a status value on both
*/
52 /*
the procedure call and the I/O completion. The check_status
*/
53 /*
procedure checks the results of the operation. The FTM
*/
54 /*
indication and confirm procedures return an error value and
*/
55 /*
do not have I/O completions. The check_error procedure checks
*/
56 /*
the return value.
*/
57 /*
*/
58 /***********************************************************************/
59 /*
60 /*
*/
NOTE : Before attempting to run this program, make sure:
61 /*
*/
*/
62 /*
a) the environmental variables are set correctly
*/
63 /*
b) the local file contains at least five records
*/
64 /*
c) the local file record length is less than or
*/
65 /*
66 /*
67 /*
equal to 132 bytes
d) the required parameters (currently using defaults)
in the FTM_INITIALIZE_REQ_ call are set correctly
68 /*
*/
*/
*/
*/
69 /***********************************************************************/
70
71 #pragma NOLIST
72 #include <stdioh>
73 #include <stdlibh>
74 #include <stringh>
75 #include <talh>
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -13
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
76
77 /***********************************************************************/
78 /* Source in
*/
79 /*
- APS and FTM structure definitions and literals
*/
80 /*
- External function declarations for FTM, APS, MFM,
*/
81 /*
and Guardian procedures
*/
82 /***********************************************************************/
83
84 #include
"zapsc"
/* APS DDL
*/
85 #include
"zftmc"
/* FTM DDL
*/
86 #include
"cextdecs
( FTM_INITIALIZE_REQ_
\
87
, FTM_INITIALIZE_CNF_
\
88
, FTM_FILE_OPEN_REQ_
\
89
, FTM_FILE_OPEN_CNF_
\
90
, FTM_FILE_CLOSE_REQ_
\
91
, FTM_FILE_CLOSE_CNF_
\
92
, FTM_LOCATE_REQ_
\
93
, FTM_LOCATE_CNF_
\
94
, FTM_WRITE_REQ_
\
95
, FTM_DATA_REQ_
\
96
, FTM_DATA_END_REQ_
\
97
, FTM_TRANSFER_END_REQ_ \
98
, FTM_TRANSFER_END_CNF_ \
99
, FTM_TERMINATE_REQ_
\
100
, FTM_TERMINATE_CNF_
\
101
, FTM_P_ABORT_IND_
\
102
, FTM_U_ABORT_IND_
\
103
, FTM_U_ABORT_REQ_
\
104
, FTM_CANCEL_IND_
\
105
, FTM_CANCEL_RSP_
\
106
, APS_INITIALIZE_
\
107
, APS_STATUS_
\
108
, APS_EVENT_RECEIVE_
\
109
, APS_DISCARD_
\
110
, MFM_AWAITIOX_
\
111
, READX
\
112
, OPEN
\
113
, FILEINFO
\
114
, CLOSE )"
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -14
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
115 #pragma LIST
116
117 /**********************************************************************/
118 /* Global data declarations
*/
119/***********************************************************************/
120
121 /***********************************************************************/
122 /* Environment-specific fields
*/
123 /* You will need to change these fields to reflect your FTAM
*/
124 /* environment.local_file must contain a valid expanded Guardian
*/
125 /* file name in internal format, and remote_file_name must contain a
*/
126 /* valid file name for the remote system. In this example,
*/
127 /* remote_file_name is shown as a Guardian file.
*/
128 /**********************************************************************/
129
130 #define local_appl_name "APPL1"
131 #define responding_appl_name "APPL2"
132 #define manager_name "$APMGR "
133 #define local_file "$VOLUME SUBVOL LOCALF "
134 #define remote_file_name "$VOLUME.SUBVOL.REMOTEF"
135
136 /**********************************************************************/
137 /* Nowait I/O tags
*/
138 /**********************************************************************/
139
140 #define
ABORT_TAG
1
/* User-abort request tag
*/
141 #define
DATA_TAG
2
/* FTM data request tag
*/
142 #define
DATAEND_TAG
3
/* FTM data-end request tag
*/
143 #define
EVENTREC_TAG
4
/* APS event-receive request tag */
144 #define
FILECLOSE_TAG
5
/* FTM file-close request tag
*/
145 #define
FILEOPEN_TAG
6
/* FTM file-open request tag
*/
146 #define
INITIALIZE_TAG
7
/* FTM initialize request tag
*/
147 #define
TERMINATE_TAG
8
/* FTM terminate request tag
*/
148 #define
TRANSFEREND_TAG
9
/* FTM transfer-end request tag
*/
149 #define
WRITE_TAG
10
/* FTM write request tag
*/
150 #define
READ_TAG
11
/* Guardian read tag
*/
151
152 /**********************************************************************/
153 /* Miscellaneous literals
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -15
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
154 /**********************************************************************/
155
156 #define
NOCEPI
-1
/* Indicates no valid CEPI
*/
157 #define
NOWAIT
0
/* Indicates nowait mode
*/
158 #define
WAIT_FOREVER
/* MFM_AWAITIOX_ wait value
*/
159 #define
FALSE
0
/* Boolean value for FALSE
*/
160 #define
TRUE
1
/* Boolean value for TRUE
*/
161 #define
MAX_RECORDS
5
/* Maximum number of records
*/
162 #define
BASE
/* Used with NUMOUT as base
*/
163 #define
WIDTH
5
/* Width of NUMOUT field
*/
164 #define
MAX_BUF
250
/* Maximum bytes to send
*/
165 #define
MAX_READ_COUNT 132
/* Maximum bytes to read
*/
166 #define
OPEN_FLAGS
/* Open for nowait read
*/
-1
10
1
167
168 /**********************************************************************/
169 /* Miscellaneous variables
*/
170 /**********************************************************************/
171
172 int
event_code;
/* FTAM event code
*/
173 long
tag;
/* Tag value for nowait I/O operation */
174 int
records = 0;
/* Number of records sent
*/
175 int
local_filenum;
/* Local file number
*/
176 int
cepi = NOCEPI;
/* Connection endpoint ID
*/
177 int
wait_mode;
/* Wait or nowait mode
*/
178 int
condition_code;
/* Condition code
*/
179
180 /***********************************************************************/
181 /* Local and remote buffer pointers
*/
182 /**********************************************************************/
183
184 char
local_buffer[MAX_READ_COUNT];
/* Used for Guardian read
*/
185 char
remote_buffer[MAX_BUF];
/* Used for FTM data request
*/
186 char
*data_ptr;
/* Points into remote_buffer
*/
187
188 /**********************************************************************/
189 /* Variables used by the MFM_AWAITIOX_ procedure
*/
190 /**********************************************************************/
191
192 int
filenum;
/* Returned from MFM_AWAITIOX_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -16
*/
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
193 long
buffer_addr;
/* Returned buffer address
*/
194 int
count_transferred;
/* Number of bytes read
*/
195 int
buf_count_transferred;
/* Holding place for # of bytes
*/
196
197 /**********************************************************************/
198 /* Variables used by the FTM procedures
*/
199 /**********************************************************************/
200
201 long
file_status;
/* Used by file-open request
*/
202 long
delete_action;
/* Do not delete after close
*/
203 long
state_result;
/* Status of regime change
*/
204 long
action_result;
/* Status of FTAM operation
*/
205 long
fadu_op;
/* Insert operation is used
*/
206 int
document_type[5] =
/* Object ID for FTAM-2
*/
207 { 1, 0, 8571, 5, 2 };
208
209 /**********************************************************************/
210 /* Boolean variables used to manage nowait I/O processing
*/
211 /**********************************************************************/
212
213 int
local_read_io_cmplt = TRUE;
/* Local file read completed
214 int
remote_io_cmplt = TRUE;
/* Data-req to remote completed*/
215 int
remote_file_update_cmplt = FALSE; /* While loop control flag
*/
216 int
file_update_failed = TRUE;
*/
/* Remote file update failed
*/
217
218 /**********************************************************************/
219 /* Error-handling variables */
220 /**********************************************************************/
221
222 int
status;
/* Used for I/O-request calls
*/
223 int
error;
/* Used for confirm calls
*/
224 int
error_code;
/* Returns error code
*/
225 int
error_subcode;
/* Returns error subcode
*/
226
227
228 /***********************************************************************/
229 /* Structures used by the FTM procedures
*/
230 /**********************************************************************/
231
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -17
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
232
zaps_ddl_data_element_hdr_def
*element_hdr_ptr;
233
zaps_ddl_data_hdr_def
*data_hdr_ptr;
234
zaps_ddl_filename_def
aplmgr_name;
235
zaps_ddl_appl_addr_def
responding_appl;
236
zaps_ddl_appl_addr_def
local_appl;
237
zftm_ddl_func_units_def
func_units;
238
zftm_ddl_service_class_def
service_class;
239
zaps_ddl_char128_def
remote_file;
240
zaps_ddl_original_error_def
original_error_info;
241
zftm_ddl_requested_access_def
requested_access;
242
zftm_ddl_proc_mode_def
process_mode;
243
zftm_ddl_cntnts_list_def
contents_type_list;
244
zftm_ddl_cntnts_type_def
contents_type;
245
zftm_ddl_fadu_id_def
fadu_id;
246
zftm_ddl_diagnostic_def
diag;
247
248 /**********************************************************************/
249 /* End global data declarations
*/
250 /**********************************************************************/
251
252 /**********************************************************************/
253 /* Local function declarations
*/
254 /**********************************************************************/
255
256
void ftam_io_cmpl ();
257
void ftam_event_rcvd ();
258
void init_cnf_open_req ();
259
void open_cnf_write_req ();
260
void transend_cnf_close_req ();
261
void close_cnf_terminate_req ();
262
void data_transfer ();
263
void check_status ();
264
void check_error ();
265
void check_action_diag ();
266
void bad_state ();
267
268
269 #pragma PAGE "INSERT"
270 /**********************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -18
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
271 /*
*/
272 /* Name:
insert
*/
273 /*
*/
274 /* Description: The insert program, written in nowait mode, updates
*/
275 /*
a file on a remote system of an OSI network by
*/
276 /*
inserting five records in it. This application
*/
277 /*
initiates and manages the data transfer. It reads
*/
278 /*
the data transferred from a local Guardian file.
*/
279 /*
*/
280 /* Input:
None
*/
281 /*
*/
282 /* Output:
None
*/
283 /*
*/
284 /**********************************************************************/
285
286
main ()
287
288
{
289
char main_buffer[36];
290
291
/*******************************************************************/
292
/* Open the local Guardian file for reading in nowait mode.
293
/*******************************************************************/
*/
294
295
strcpy( main_buffer, local_file );
296
condition_code = OPEN ( (int *) main_buffer
297
, &local_filenum
298
, OPEN_FLAGS);
299
300
if ( condition_code != CCE )
301
{
302
FILEINFO ( local_filenum, &error );
303
printf ("Local file open error %d\n", error);
304
exit (EXIT_SUCCESS);
305
}
306
307
/*******************************************************************/
308
/* Allocate and initialize a segment used by the FTM and APS
*/
309
/* procedures.
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -19
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
310
/*******************************************************************/
311
312
error = APS_INITIALIZE_ (/* swapvol */);
313
if ( error != ZAPS_ERR_OK )
314
{
315
printf ("Initialization of the FTAM/APS segment failed\n");
316
exit (EXIT_SUCCESS);
317
}
318
319
/******************************************************************/
320
/* The following sections initialize the various parameters
*/
321
/* for the FTM_INITIALIZE_REQ_ procedure.
*/
322
/******************************************************************/
323
324
/*******************************************************************/
325
/* Set the processing mode for the association to nowait and
*/
326
/* initialize the APLMGR process.
*/
327
/*******************************************************************/
328
329
wait_mode = ZAPS_VAL_NOWAITED;
330
memcpy (&aplmgr_name, manager_name, strlen (manager_name));
331
332 /**********************************************************************/
333 /* Supply the remote and local OSI addresses or common names. This
*/
334 /* application uses common names. Set the length fields of the
*/
335 /* OSI addresses to 0.
*/
336 /**********************************************************************/
337
338
responding_appl.zpsap.zpsel.zlen = 0;
339
responding_appl.zpsap.zssel.zlen = 0;
340
responding_appl.zpsap.ztsel.zlen = 0;
341
responding_appl.zpsap.znsap.zlen = 0;
342
responding_appl.zappl_name.zlen
343
memcpy (responding_appl.zappl_name.u_zc.zb, responding_appl_name,
344
= strlen (responding_appl_name);
responding_appl.zappl_name.zlen);
345
346
local_appl.zpsap.zpsel.zlen
= 0;
347
local_appl.zpsap.zssel.zlen
= 0;
348
local_appl.zpsap.ztsel.zlen
= 0;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -20
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
349
local_appl.zpsap.znsap.zlen
= 0;
350
local_appl.zappl_name.zlen
= strlen (local_appl_name);
351
memcpy (local_appl.zappl_name.u_zc.zb, local_appl_name,
352
local_appl.zappl_name.zlen);
353
354 /**********************************************************************/
355 /* Select the service class/classes required. This application needs
*/
356 /* only the file-access service class. The file-access service class
*/
357 /* allows insertion of data into a structured file.
*/
358 /**********************************************************************/
359
360
service_class.zunconstrained = ZAPS_VAL_FALSE;
361
service_class.zmgmt
= ZAPS_VAL_FALSE;
362
service_class.ztransfer
= ZAPS_VAL_FALSE;
363
service_class.zxfermgmt
= ZAPS_VAL_FALSE;
364
service_class.zaccess
= ZAPS_VAL_TRUE;
365
366 /**********************************************************************/
367 /* Select the functional units required by this application. The
*/
368 /* following functional units are mandatory for the file-access
*/
369 /* service class: read, write, and file-access.
*/
370 /*
*/
371 /* Also, the FTM_FILE_OPEN_REQ_ and FTM_FILE_CLOSE_REQ_ procedures
*/
372 /* require that you select the grouping functional unit.
*/
373 /**********************************************************************/
374
375
func_units.zread
= ZAPS_VAL_TRUE;
376
func_units.zwrite
= ZAPS_VAL_TRUE;
377
func_units.zfileaccess
= ZAPS_VAL_TRUE;
378
func_units.zfilemgmt
= ZAPS_VAL_FALSE;
379
func_units.zfilemgmtenhanced
= ZAPS_VAL_FALSE;
380
func_units.zgroup
= ZAPS_VAL_TRUE;
381
func_units.zfadulock
= ZAPS_VAL_FALSE;
382
func_units.zrecovery
= ZAPS_VAL_FALSE;
383
func_units.zrestart
= ZAPS_VAL_FALSE;
384
385 /**********************************************************************/
386 /* Set up the contents-type-list to request a document of
*/
387 /* type FTAM-2.
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -21
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
388 /**********************************************************************/
389
390 contents_type_list.zcount = 1;
391 contents_type_list.zcntnts_type_ispresent = ZAPS_VAL_PRESENT;
392 contents_type_list.zcntnts_type_list[0].zid= ZFTM_VAL_CNTNTSLIST_DOCNAME;
393 contents_type_list.zcntnts_type_list[0].u_zcntntstype.zcntntstype.
394 znum_elements = 5;
395 memcpy ( contents_type_list.zcntnts_type_list[0].u_zcntntstype.
396 zcntntstype.zobj_id, document_type, sizeof (document_type) );
397
398 /**********************************************************************/
399 /* Establish the association with the remote FTAM responder. Do this
*/
400 /* by calling the FTM_INITIALIZE_REQ_ procedure. In this example,
*/
401 /* default values are used for many parameters. For example, the
*/
402 /* default values 0, for AE qualifier, and [1,3,9999,1,7], for
*/
403 /* AP title, are used in the ae_title parameter, and 1 and
*/
404 /* [1,3,9999,1,7], respectively, are used in the remote_ae_title
*/
405 /* parameter. The remote system, however, might require other
*/
406 /* values for certain parameters (e.g., ae_title, remote_ae_title,
*/
407 /* initiator_id, filestore_password, and so on).
*/
408 /**********************************************************************/
409
410
status = FTM_INITIALIZE_REQ_ ( (int *) &cepi
411
, (int *) &aplmgr_name
412
, (int *) &responding_appl
413
, wait_mode
414
, (int *) &local_appl
415
, /* ae_title */
416
, /* remote_ae_title */
417
, (int *) &service_class
418
, (int *) &func_units
419
, /* attr_groups - defaults to kernel only */
420
, (int *) &contents_type_list
421
, /* initiator_id - defaults to spaces */
422
, /* account - defaults to spaces */
423
424
, /* filestore_password - defaults to spaces*/
, (long) INITIALIZE_TAG );
425
426
if ( status != ZAPS_VAL_STATUS_OK )
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -22
NonStop FTAM Programming Examples
427
{
428
check_status ();
429
exit (EXIT_SUCCESS);
430
Example 1 in C—Updating a Remote File (in Nowait
Mode)
}
431
432 /**********************************************************************/
433 /* The main control loop continues processing until an abort or
*/
434 /* discard condition occurs, or until the last data request is sent.
*/
435 /**********************************************************************/
436
437
while ( ! remote_file_update_cmplt )
438
{
439
440
/*******************************************************************/
441
/* Assign a filenum value of -1 to make the process wait for the
*/
442
/* first I/O completion of an FTM, APS, or Guardian file-system
*/
443
/*
*/
444
/*******************************************************************/
procedure.
445
446
filenum = -1;
447
448
/*******************************************************************/
449
/* Wait for the next I/O completion from an FTM, APS, or
*/
450
/* Guardian file-system procedure.
*/
451
/*******************************************************************/
452
453
condition_code = MFM_AWAITIOX_ ( &status /* Output */
454
, &filenum /* I/O */
455
, &buffer_addr /* Output */
456
, &count_transferred /* Output */
457
, &tag /* Output */
458
, (long) WAIT_FOREVER /* Input */
459
, /* segment_id */ );
460
461
/*******************************************************************/
462
/* If an I/O completion for READX is received, save the value of
*/
463
/* count_transferred in buf_count_transferred for later use.
*/
464
/*******************************************************************/
465
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -23
NonStop FTAM Programming Examples
466
if ( count_transferred != -1 )
467
{
468
469
Example 1 in C—Updating a Remote File (in Nowait
Mode)
buf_count_transferred = count_transferred;
}
470
471
472
473
if ( filenum != local_filenum )
/* Process the I/O completion of an FTAM or APS procedure or event */
{
474
475
/****************************************************************/
476
/* Determine whether an FTAM I/O operation completed or an
*/
477
/* event was received. If neither, display the error code
*/
478
/* and error subcode.
*/
479
/****************************************************************/
480
481
if ( status == ZAPS_VAL_STATUS_OK )
482
{
483
ftam_io_cmpl ();
484
}
485
else if ( status == ZAPS_VAL_STATUS_EVENT )
486
{
487
ftam_event_rcvd ();
488
}
489
else
490
{
491
check_status ();
492
APS_DISCARD_ ( cepi );
493
exit (EXIT_FAILURE);
494
}
495
496
497
}
else /* Process the local file I/O completion */
{
498
/****************************************************************/
499
/* Check the condition code to determine if the local file
*/
500
/* I/O operation completed successfully.
*/
501
/****************************************************************/
502
503
if ( condition_code != CCE )
504
{
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -24
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
505
FILEINFO ( local_filenum, &error );
506
printf ("Local file error %d\n", error);
507
APS_DISCARD_ ( cepi );
508
exit (EXIT_SUCCESS);
509
}
510
511
/****************************************************************/
512
/* Verify that the local I/O completion was for a file read.
513
/****************************************************************/
*/
514
515
if ( tag == READ_TAG )
516
{
517
/*************************************************************/
518
/* Indicate that the local file read completed successfully
*/
519
/* and transfer the data that was read to the responder.
*/
520
/*************************************************************/
521
522
local_read_io_cmplt = TRUE;
523
data_transfer ();
524
}
525
else
526
{
527
printf ("Invalid TAG\n");
528
APS_DISCARD_ ( cepi );
529
exit (EXIT_FAILURE);
530
531
532
}
}
} /* End of WHILE loop */
533
534 /**********************************************************************/
535 /* Discard the API context information for the association.
*/
536 /**********************************************************************/
537
538
APS_DISCARD_ ( cepi );
539
540 /**********************************************************************/
541 /* Close the local file that was opened for transfer.
*/
542 /**********************************************************************/
543
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -25
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
544 CLOSE ( local_filenum );
545
546
/*********************************************************************/
547
/* Display a message to the terminal that an error occurred or that
*/
548
/* the program completed successfully.
*/
549
/*********************************************************************/
550
551
if ( file_update_failed )
552
{
553
printf ("File update error\n");
554
}
555
else
556
{
557
printf ("File update complete\n");
558
}
559
560
} /* End INSERT */
561
562
563
#pragma PAGE "FTAM_IO_CMPL"
564 /**********************************************************************/
565 /*
*/
566 /* Name:
ftam_io_cmpl
*/
567 /*
*/
568 /* Description: This procedure processes I/O completions for FTM
*/
569 /*
request and response procedures. It uses the tag
*/
570 /*
field to determine which FTM procedure completed.
*/
571 /*
It takes a specified action depending on the type
*/
572 /*
of request or response.
*/
573 /*
*/
574 /* Input:
None
575 /*
*/
*/
576 /* Outputs:
Requests to remote responder
*/
577 /*
Error message to the terminal
*/
578 /*
*/
579 /**********************************************************************/
580
581 void ftam_io_cmpl ()
582
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -26
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
583 {
584
585
/*******************************************************************/
586
/* The tag value represents the type of FTM request or response
*/
587
/* procedure associated with this I/O completion. The tag value
*/
588
/* comes from the MFM_AWAITIOX_ call.
*/
589
/*******************************************************************/
590
591
switch (tag)
592
{
593
594
case INITIALIZE_TAG:
595
/****************************************************************/
596
/* After FTM_INITIALIZE_REQ_ completes, issue an event-
*/
597
/* receive call to retrieve the initialize confirm. All subse-
*/
598
/* quent event-receive calls are issued from the ftam_event_rcvd*/
599
/* procedure after each event-receive request completes.
600
/****************************************************************/
*/
601
602
status = APS_EVENT_RECEIVE_ ( cepi
603
, /* WAIT_FOREVER */
604
, (long) EVENTREC_TAG );
605
606
607
check_status ();
break;
608
609
case FILEOPEN_TAG:
610
case TRANSFEREND_TAG:
611
case FILECLOSE_TAG:
612
case TERMINATE_TAG:
613
/****************************************************************/
614
/* These requests do not require any action. The
*/
615
/* ftam_event_rcvd procedure has already issued an event-
*/
616
/* receive call.
*/
617
/****************************************************************/
618
619
break;
620
621
case WRITE_TAG:
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -27
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
622
/****************************************************************/
623
/* The remote system is now set up for writing. Read the first
*/
624
/* record from the file into the local buffer. The file was
*/
625
/* opened in nowait mode.
*/
626
/****************************************************************/
627
628
condition_code = READX ( local_filenum
629
, (char *) &local_buffer
630
, MAX_READ_COUNT
631
, /* count_read - waited I/O only */
632
, READ_TAG );
633
634
if (condition_code != CCE)
635
{
636
FILEINFO ( local_filenum, &error );
637
printf ("Local file error %d\n", error);
638
APS_DISCARD_ ( cepi );
639
exit (EXIT_SUCCESS);
640
}
641
642
/****************************************************************/
643
/* Set flags to indicate that the remote I/O operation is com-
*/
644
/* plete (this to know that there are no outstanding I/O oper-
*/
645
/* ations) and that there is a local read I/O operation out-
*/
646
/* standing.
*/
647
/****************************************************************/
648
649
remote_io_cmplt = TRUE;
650
local_read_io_cmplt = FALSE;
651
break;
652
653
case DATA_TAG:
654
/****************************************************************/
655
/* An FTM data request has completed. Send the next record
*/
656
/* if the local file read has completed.
*/
657
/****************************************************************/
658
659
remote_io_cmplt = TRUE;
660
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -28
NonStop FTAM Programming Examples
661
if ( local_read_io_cmplt )
662
{
663
664
Example 1 in C—Updating a Remote File (in Nowait
Mode)
data_transfer ();
}
665
666
break;
667
668
case DATAEND_TAG:
669
/****************************************************************/
670
/* All records have been transferred. Terminate the
*/
671
/* data-transfer regime now.
*/
672
/****************************************************************/
673
674
status = FTM_TRANSFER_END_REQ_ ( cepi
675
, (long) TRANSFEREND_TAG );
676
677
check_status ();
678
break;
679
680
case ABORT_TAG:
681
/****************************************************************/
682
/* If an abort I/O operation completes, exit the main control
*/
683
/* loop after returning from this routine.
*/
684
/****************************************************************/
685
686
remote_file_update_cmplt = TRUE;
687
688
break;
689
690
default:
691
/****************************************************************/
692
/* Display the invalid tag error message and exit.
693
/****************************************************************/
694
695
printf ("Invalid TAG\n");
696
APS_DISCARD_ ( cepi );
697
exit (EXIT_FAILURE);
698
699
break;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -29
*/
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
700
701
} /* end of case */
702
703
} /* ftam_io_cmpl */
704
705
706 #pragma PAGE "FTAM_EVENT_RCVD"
707 /**********************************************************************/
708 /*
*/
709 /* Name:
ftam_event_rcvd
*/
710 /*
*/
711 /* Description: This procedure is called whenever an FTAM event is
*/
712 /*
received. It calls APS_STATUS_ to determine which
*/
713 /*
FTAM event has been received. Depending on the
*/
714 /*
event code that is returned, it calls the
*/
715 /*
appropriate FTM confirm or indication procedure.
*/
716 /*
It issues the next FTM request and another
*/
717 /*
event-receive request to receive the next FTAM
*/
718 /*
event.
*/
719 /*
*/
720 /* Input:
None
721 /*
*/
*/
722 /* Output:
None
723 /*
*/
*/
724 /**********************************************************************/
725
726
void ftam_event_rcvd ()
727
728
{
729
/********************************************************************/
730
/* An event-receive completed. Retrieve the event code from APS.
731
/********************************************************************/
*/
732
733
error = APS_STATUS_ ( cepi, &event_code );
734
735
check_error ();
736
737
/********************************************************************/
738
/* Process the event that was received.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -30
*/
NonStop FTAM Programming Examples
739
Example 1 in C—Updating a Remote File (in Nowait
Mode)
/********************************************************************/
740
741
switch ( event_code )
742
{
743
744
case ZFTM_VAL_EVT_INITIALIZE_CNF:
init_cnf_open_req ();
745
break;
746
case ZFTM_VAL_EVT_FILEOPEN_CNF:
747
open_cnf_write_req ();
748
break;
749
case ZFTM_VAL_EVT_TRANSEND_CNF:
750
transend_cnf_close_req ();
751
break;
752
case ZFTM_VAL_EVT_FILECLOSE_CNF:
753
close_cnf_terminate_req ();
754
break;
755
case ZFTM_VAL_EVT_TERMINATE_CNF:
756
757
/**************************************************************/
758
/* Retrieve the FTM terminate-confirm data. The charging
*/
759
/* parameter conveys information related to the cost charged
*/
760
/* to the account. This parameter is present only if the
*/
761
/* account parameter was provided on the FTM_INITIALIZE_REQ_
*/
762
/* procedure call. Set the flags to indicate that the file
*/
763
/* update completed successfully.
*/
764
/**************************************************************/
765
766
error = FTM_TERMINATE_CNF_ ( cepi
767
, /* charging */);
768
769
check_error ();
770
771
remote_file_update_cmplt = TRUE;
772
file_update_failed = FALSE;
773
break;
774
case ZFTM_VAL_EVT_PABORT_IND:
775
776
/****************************************************************/
777
/* Retrieve the FTAM provider-abort indication data. Check
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -31
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
778
/* the action result and display any diagnostic messages. Then
*/
779
/* set the flag to indicate that the file update is complete.
*/
780
/****************************************************************/
781
782
error = FTM_P_ABORT_IND_ ( cepi
783
, &action_result
784
, (int *) &diag );
785
786
check_error ();
787
check_action_diag ();
788
789
printf ( "The association has been aborted\n" );
790
791
remote_file_update_cmplt = TRUE;
792
793
break;
794
case ZFTM_VAL_EVT_UABORT_IND:
795
796
/****************************************************************/
797
/* Retrieve the FTM user-abort indication data. Check the
*/
798
/* action result and display any diagnostic messages. Then
*/
799
/* set the flag to indicate that the file update is complete.
*/
800
/****************************************************************/
801
802
error = FTM_U_ABORT_IND_ ( cepi
803
, &action_result
804
, (int *) &diag );
805
806
check_error ();
807
check_action_diag ();
808
809
printf ( "The association has been aborted\n" );
810
811
remote_file_update_cmplt = TRUE;
812
813
break;
814
case ZFTM_VAL_EVT_CANCEL_IND:
815
816
/***************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -32
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
817
/* The remote system has cancelled the transfer. Call
*/
818
/* FTM_CANCEL_IND_ to get the action result and diagnostic
*/
819
/* messages and FTM_CANCEL_RSP_ to acknowledge the indication
*/
820
/* from the remote system. This terminates the data-transfer
*/
821
/* regime.
*/
822
/***************************************************************/
823
824
error = FTM_CANCEL_IND_ ( cepi
825
, &action_result
826
, (int *) &diag );
827
828
check_error ();
829
check_action_diag ();
830
831
printf ( "The data transfer has been cancelled\n" );
832
833
status = FTM_CANCEL_RSP_ ( cepi
834
, /* action_result */
835
, /* diag */ );
836
837
check_status ();
838
remote_file_update_cmplt = TRUE;
839
break;
840
841
default: /* Unknown event */
842
printf ("Invalid Event\n");
844
APS_DISCARD_ ( cepi );
845
exit (EXIT_FAILURE);
846
break;
847
848
} /* end of case */
849
850
/*******************************************************************/
851
/* If the file update is not complete, issue another
*/
852
/* APS_EVENT_RECEIVE_ to receive the next event.
*/
853
/********************************************************************/
854
855
if ( remote_file_update_cmplt == FALSE )
856
{
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -33
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
857
status = APS_EVENT_RECEIVE_ ( cepi
858
, /* WAIT_FOREVER */
859
, (long) EVENTREC_TAG );
860
861
check_status ();
862
}
863
864
} /* ftam_event_rcvd */
865
866
867
#pragma PAGE "INIT_CNF_OPEN_REQ"
868
/*********************************************************************/
869
/*
870
/* Name:
871
/*
*/
872
/* Description: This procedure is called when an initialize confirm
*/
873
/*
is received. It calls FTM_INITIALIZE_CNF_ and
*/
874
/*
checks the error status and state result. It then
*/
875
/*
initializes parameters for the call to
*/
876
/*
FTM_FILE_OPEN_REQ_, makes the call, and returns
*/
877
/*
to the calling routine.
*/
878
/*
879
/* Input:
880
/*
881
/* Output:
882
/*
883
/*********************************************************************/
*/
init_cnf_open_req
*/
*/
Initialize confirm
*/
*/
File-select/open request to remote responder
*/
*/
884
885
void init_cnf_open_req ()
886
887
{
888
889
/********************************************************************/
890
/* Retrieve the FTAM initialize-confirm data.
891
/********************************************************************/
892
893
error = FTM_INITIALIZE_CNF_ ( cepi
894
, &state_result
895
, &action_result
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -34
*/
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
896
, (int *) &local_appl
897
, (int *) &responding_appl
898
, /* remote_ae_title */
899
, (int *) &service_class
900
, (int *) &func_units
901
, /* attr_groups */
902
, (int *) &contents_type_list
903
, (int *) &diag );
904
905
check_error ();
906
907
/*********************************************************************/
908
/* Check the state result and the action result.
909
/*********************************************************************/
*/
910
911
check_action_diag ();
912
if ( state_result == ZFTM_VAL_STATE_FAILURE )
913
{
914
915
bad_state ();
}
916
917
/********************************************************************/
918
/* Check to make sure that the requested functional units have not
*/
919
/* been negotiated down from what was requested. If the requested
*/
920
/* functional units are not available, this application ends.
*/
921
/********************************************************************/
922
923
if ( func_units.zread != ZAPS_VAL_TRUE ||
924
func_units.zwrite != ZAPS_VAL_TRUE ||
925
func_units.zgroup != ZAPS_VAL_TRUE ||
926
func_units.zfileaccess != ZAPS_VAL_TRUE )
927
928
{
printf ( "Functional units unavailable for the association\n" );
929
930
action_result = ZFTM_VAL_ACTION_FAILURE;
931
932
status = FTM_U_ABORT_REQ_ ( cepi
933
, action_result
934
, /* diagnostics */
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -35
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
935
, (long) ABORT_TAG );
936
937
/******************************************************************/
938
/* If the above abort request is sent to the remote system,
*/
939
/* calling the main procedure sets the remote_file_update_cmpl
*/
940
/* flag, and the program is terminated. If the request is not
*/
941
/* sent out, set the flag here and return to the main procedure.
*/
942
/******************************************************************/
943
944
if ( status != ZAPS_VAL_STATUS_OK )
945
remote_file_update_cmplt = TRUE;
946
return;
947
948
}
949
950
/********************************************************************/
951
/* Verify that the contents-type-list has not been negotiated down
*/
952
/* from what was requested. If the requested contents type is
*/
953
/* not available, then discard the association and exit the program.*/
954
/* Additional application-specific error handling or recovery could */
955
/* be implemented if required by an application.
956
/********************************************************************/
*/
957
958
if ( memcmp ( contents_type_list.zcntnts_type_list[0].u_zcntntstype.
959
zcntntstype.zobj_id
960
961
, document_type, sizeof (document_type) ) == 0 )
{
962
contents_type.zid = ZFTM_VAL_CNTNTSTYPE_DOCTYPE;
963
contents_type.u_zcntntstype.zdoctype.zdoctypename.znum_elements = 5;
964
memcpy ( contents_type.u_zcntntstype.zdoctype.zdoctypename.zobj_id
965
,
document_type, sizeof (document_type) );
966
967
968
969
970
971
972
973
contents_type.u_zcntntstype.zdoctype.zuniversalclassispresent
= ZAPS_VAL_PRESENT;
contents_type.u_zcntntstype.zdoctype.zuniversalclass
= ZFTM_VAL_UC_GRAPHIC_STRING;
contents_type.u_zcntntstype.zdoctype.zmaxstringlenispresent
= ZAPS_VAL_PRESENT;
contents_type.u_zcntntstype.zdoctype.zmaxstringlen
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -36
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
974
= (long) MAX_READ_COUNT;
975
contents_type.u_zcntntstype.zdoctype.zstringsigispresent
976
= ZAPS_VAL_PRESENT;
977
contents_type.u_zcntntstype.zdoctype.zstringsig
978
= ZFTM_VAL_STRINGSIG_NOTSIG;
979
contents_type.u_zcntntstype.zdoctype.zfileattrsispresent
980
= ZAPS_VAL_ABSENT;
981
982
}
983
else
984
{
985
printf ( "Contents type list unavailable for the association\n" );
986
987
action_result = ZFTM_VAL_ACTION_FAILURE;
988
989
status = FTM_U_ABORT_REQ_ ( cepi
990
, action_result
991
, /* diagnostics */
992
, (long) ABORT_TAG );
993
994
/*****************************************************************/
995
/* If the above abort request is sent to the remote system,
*/
996
/* calling the main procedure sets the remote_file_update_cmplt
*/
997
/* flag, and the program is terminated. If the request is not
*/
998
/* sent out, set the flag here and return to the main procedure. */
999
/*****************************************************************/
1000
1001
if ( status != ZAPS_VAL_STATUS_OK )
1002
remote_file_update_cmplt = TRUE;
1003
return;
1004
1005
}
1006
1007
1008
/*******************************************************************/
1009
/* The following sections initialize the parameters for the
*/
1010
/* FTM_FILE_OPEN_REQ_ procedure.
*/
1011
/*******************************************************************/
1012
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -37
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1013
/*******************************************************************/
1014
/* Initialize the remote-file-name parameter. The remote-file-name */
1015
/* format is dependent on the remote system.
1016
/*******************************************************************/
*/
1017
1018
remote_file.zlen = strlen (remote_file_name);
1019
memcpy (remote_file.u_zc.zb, remote_file_name, remote_file.zlen);
1020
1021
/*******************************************************************/
1022
/* If the remote file exists, it is selected and opened. If the
*/
1023
/* file does not exist, the file-open request fails.
*/
1024
/*******************************************************************/
1025
1026
file_status = ZFTM_VAL_FOPEN_OLD;
1027
1028
/*******************************************************************/
1029
/* Set up the following remote file-access parameter required for
*/
1030
/* this application: insert.
*/
1031
/*******************************************************************/
1032
1033
requested_access.zread = ZAPS_VAL_FALSE;
1034
requested_access.zinsert = ZAPS_VAL_TRUE;
1035
requested_access.zreplace = ZAPS_VAL_FALSE;
1036
requested_access.zextend = ZAPS_VAL_FALSE;
1037
requested_access.zerase = ZAPS_VAL_FALSE;
1038
requested_access.zreadattr = ZAPS_VAL_FALSE;
1039
requested_access.zchngattr = ZAPS_VAL_FALSE;
1040
requested_access.zdelete = ZAPS_VAL_FALSE;
1041
1042
/*******************************************************************/
1043
/* Set up the following remote file process-mode parameter required*/
1044
/* for this application: insert.
1045
/*******************************************************************/
1046
1047
process_mode.zread = ZAPS_VAL_FALSE;
1048
process_mode.zinsert = ZAPS_VAL_TRUE;
1049
process_mode.zreplace = ZAPS_VAL_FALSE;
1050
process_mode.zextend = ZAPS_VAL_FALSE;
1051
process_mode.zerase = ZAPS_VAL_FALSE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -38
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1052
1053
1054
/*******************************************************************/
1055
/* Issue the file-open request.
1056
/*******************************************************************/
*/
1057
1058
status = FTM_FILE_OPEN_REQ_ ( cepi
1059
, (int *) &remote_file
1060
, file_status
1061
, (int *) &requested_access
1062
, /* access_passwords */
1063
, /* initial_attr */
1064
, /* create_password */
1065
, (int *) &process_mode
1066
, (int *) &contents_type
1067
, /* account */
1068
, (long) FILEOPEN_TAG );
1069
1070
check_status ();
1071
1072
} /* init_cnf_open_req */
1073
1074
1075
1076 #pragma PAGE "OPEN_CNF_WRITE_REQ"
1077 /*********************************************************************/
1078 /*
*/
1079 /* Name:
open_cnf_write_req
1080 /*
*/
*/
1081 /* Description: This procedure is called when a file-open confirm is */
1082 /*
received. It calls FTM_FILE_OPEN_CNF_ and checks
*/
1083 /*
the error status and state result. It then calls
*/
1084 /*
FTM_WRITE_REQ_ and returns to the calling routine.
*/
1085 /*
*/
1086 /* Input:
File-select/open confirm
1087 /*
*/
*/
1088 /* Output:
Write request sent to remote responder
1089 /*
*/
*/
1090 /*********************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -39
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1091
1092
void open_cnf_write_req ()
1093
1094
{
1095
1096
/******************************************************************/
1097
/* Retrieve the file-open confirm data.
1098
/******************************************************************/
*/
1099
1100
error = FTM_FILE_OPEN_CNF_ ( cepi
1101
, &state_result
1102
, &action_result
1103
, (int *) &remote_file
1104
, /* initial_attr */
1105
, (int *) &contents_type
1106
, (int *) &diag );
1107
1108
check_error ();
1109
1110
/******************************************************************/
1111
/* Check the state result and the action result.
1112
/******************************************************************/
*/
1113
1114
check_action_diag ();
1115
if ( state_result == ZFTM_VAL_STATE_FAILURE )
1116
{
1117
1118
bad_state ();
}
1119
1120
/**************************** **************************************/
1121
/* Send a write-request primitive to the remote responder to
*/
1122
/* establish the data-transfer regime. Set up the required
*/
1123
/* parameters and call FTM_WRITE_REQ_.
*/
1124
/*******************************************************************/
1125
1126
/*******************************************************************/
1127
/* Use the insert operation to append records to an FTAM-2 file.
1128
/*******************************************************************/
1129
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -40
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1130
fadu_op = ZFTM_VAL_FADU_OP_INSERT;
1131
1132
/*******************************************************************/
1133
/* Specify the target FADU identity. Records can be inserted only
*/
1134
/* at the end of an FTAM-2 file.
*/
1135
/*******************************************************************/
1136
1137
fadu_id.zid = ZFTM_VAL_FADUID_BEGINEND;
1138
fadu_id.u_zfaduid.zbeginend = ZFTM_VAL_FADUID_END;
1139
1140
/*******************************************************************/
1141
/* Issue the write-request primitive.
1142
/*******************************************************************/
*/
1143
1144
status = FTM_WRITE_REQ_ ( cepi
1145
, fadu_op
1146
, (int *) &fadu_id
1147
, (long) WRITE_TAG );
1148
1149
check_status ();
1150
1151 } /* open_cnf_write_req */
1152
1153
1154 #pragma PAGE "TRANSEND_CNF_CLOSE_REQ"
1155 /*********************************************************************/
1156 /*
*/
1157 /* Name:
transend_cnf_close_req
1158 /*
*/
*/
1159 /* Description: This procedure is called when a transfer-end confirm */
1160 /*
is received. It calls FTM_TRANSFER_END_CNF_ and
*/
1161 /*
checks the error status and state result. It then
*/
1162 /*
calls FTM_FILE_CLOSE_REQ_ and returns to the calling */
1163 /*
routine.
1164 /*
*/
*/
1165 /* Input:
Transfer-end confirm
1166 /*
*/
*/
1167 /* Output:
File-deselect/close request to remote responder
1168 /*
*/
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -41
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1169 /*********************************************************************/
1170
1171 void transend_cnf_close_req ()
1172
1173 {
1174
1175
/*****************************************************************/
1176
/* Retrieve the transfer-end confirm data.
1177
/*****************************************************************/
*/
1178
1179
error = FTM_TRANSFER_END_CNF_ ( cepi
1180
, &action_result
1181
, (int *) &diag );
1182
1183
check_error ();
1184
1185
/******************************************************************/
1186
/* Check the action result and display any diagnostic messages.
1187
/******************************************************************/
*/
1188
1189
check_action_diag ();
1190
1191
/******************************************************************/
1192
/* The transfer is now complete. Deselect and close the
1193
/* remote file. The delete-action parameter specifies closing the */
1194
/* file without deleting it. The FTM_FILE_CLOSE_REQ_ handles
*/
1195
/* both deselecting and closing the file.
*/
1196
/*******************************************************************/
1197
1198
delete_action = ZFTM_VAL_CLOSE_NODELETE;
1199
1200
status = FTM_FILE_CLOSE_REQ_ ( cepi
1201
, delete_action
1202
, (long) FILECLOSE_TAG );
1203
1204
check_status ();
1205
1206
} /* transend_cnf_close_req */
1207
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -42
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1208
1209 #pragma PAGE "CLOSE_CNF_TERMINATE_REQ"
1210 /*********************************************************************/
1211 /*
*/
1212 /* Name:
close_cnf_terminate_req
*/
1213 /*
*/
1214 /* Description: This procedure is called when a file-close confirm
*/
1215 /*
is received. It calls FTM_FILE_CLOSE_CNF_ and
*/
1216 /*
checks the error status and state result. It then
*/
1217 /*
calls FTM_TERMINATE_REQ_ and returns to the calling
*/
1218 /*
routine.
*/
1219 /*
*/
1220 /* Input:
File-deselect/close confirm
1221 /*
*/
*/
1222 /* Output:
Association-termination request to remote responder
1223 /*
*/
*/
1224 /*********************************************************************/
1225
1226
void close_cnf_terminate_req ()
1227
1228
{
1229
1230
/******************************************************************/
1231
/* Retrieve the file-close confirm data.
1232
/******************************************************************/
*/
1233
1234
error = FTM_FILE_CLOSE_CNF_ ( cepi
1235
, &action_result
1236
, /* charging */
1237
, (int *) &diag );
1238
1239
check_error ();
1240
1241
/******************************************************************/
1242
/* Check the action result and display any diagnostic messages.
1243
/*******************************************************************/
1244
1245
*/
check_action_diag ();
1246
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -43
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1247
/******************************************************************/
1248
/* The file has been closed. The association can be terminated.
1249
/******************************************************************/
*/
1250
1251
status = FTM_TERMINATE_REQ_ ( cepi
1252
, (long) TERMINATE_TAG );
1253
1254
check_status ();
1255
1256
} /* close_cnf_terminate_req */
1257
1258
1259 #pragma PAGE "DATA_TRANSFER"
1260 /*********************************************************************/
1261 /*
*/
1262 /* Name:
data_transfer
*/
1263 /*
*/
1264 /* Description: This procedure is called when a Guardian read or
*/
1265 /*
FTM data request completes. It determines whether
*/
1266 /*
another data request can be sent to the remote file, */
1267 /*
or whether the data must be held until the I/O
*/
1268 /*
completion for the previous call to FTM_DATA_REQ_
*/
1269 /*
or the Guardian read request is received.
*/
1270 /*
*/
1271 /* Input:
None
1272 /*
*/
*/
1273 /* Output:
File records being sent to remote responder
1274 /*
*/
*/
1275 /*********************************************************************/
1276
1277 void data_transfer ()
1278
1279 {
1280
1281
/*******************************************************************/
1282
/*When all records have been sent and there are no outstanding I/O */
1283
/*operations, notify the remote system that all data has been sent.*/
1284
/*******************************************************************/
1285
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -44
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1286
if ( records == MAX_RECORDS && remote_io_cmplt )
1287
{
1288
1289
/*****************************************************************/
1290
/* Issue the data-end primitive.
1291
/*****************************************************************/
*/
1292
1293
status = FTM_DATA_END_REQ_ ( cepi
1294
, /* action_result */
1295
, /* diag */
1296
, (long) DATAEND_TAG );
1297
1298
check_status ();
1299
return;
1300
}
1301
1302
/*******************************************************************/
1303
/* Once both the local read from the file system and the previous
*/
1304
/* FTM data request have completed, issue the next data request.
*/
1305
/*******************************************************************/
1306
1307
if ( remote_io_cmplt && local_read_io_cmplt )
1308
{
1309
/***************************************************************/
1310
/* The following sections initialize the data buffer
*/
1311
/* that contains the data to be transferred to the remote
*/
1312
/* system. The buffer contains a data header, a data-element
*/
1313
/* header, and the data to be transferred.
*/
1314
/***************************************************************/
1315
1316
/***************************************************************/
1317
/* Initialize a pointer to the data header. Then set the
*/
1318
/* number of data elements that follow. Only a single data
*/
1319
/* element is used in this example.
*/
1320
/***************************************************************/
1321
1322
data_hdr_ptr = (zaps_ddl_data_hdr_def *) remote_buffer;
1323
data_hdr_ptr->znum_elements = 1;
1324
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -45
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1325
/***************************************************************/
1326
/* Initialize a pointer to the data-element header. Then set
*/
1327
/* the length of the data to be transferred and the type of
*/
1328
/* data to be transferred. The data length is returned from
*/
1329
/* the local file-system read. The data type is set to text
*/
1330
/* in this example.
*/
1331
/***************************************************************/
1332
1333 element_hdr_ptr=(zaps_ddl_data_element_hdr_def *)((char*)data_hdr_ptr +
1334
sizeof (zaps_ddl_data_hdr_def));
1335
element_hdr_ptr->zlen = (long) buf_count_transferred;
1336
element_hdr_ptr->ztype = ZFTM_VAL_DE_TEXT;
1337
1338
/***************************************************************/
1339
/* Initialize a pointer to the data portion of the buffer
*/
1340
/* that follows the data header and data-element header. Copy
*/
1341
/* the data from the local read buffer into the data buffer.
*/
1342
/***************************************************************/
1343
1344
1345
1346
data_ptr = (char *) element_hdr_ptr +
sizeof (zaps_ddl_data_element_hdr_def);
memcpy (data_ptr, local_buffer, buf_count_transferred);
1347
1348
/***************************************************************/
1349
/* Issue the FTM data-request primitive.
1350
/***************************************************************/
*/
1351
1352
status = FTM_DATA_REQ_ ( cepi
1353
, (char *) &remote_buffer
1354
, (long) DATA_TAG );
1355
1356
check_status ();
1357
1358
/***************************************************************/
1359
/* Indicate that an FTM data request is in progress.
1360
/***************************************************************/
1361
1362
remote_io_cmplt = FALSE;
1363
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -46
*/
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1364
/***************************************************************/
1365
/* Update the number of records that have been read. If
1366
/* the maximum number of records has been read, then return to */
1367
/* the main control loop and wait for an I/O operation or
*/
1368
/* an FTAM event to complete. Otherwise, read another record
*/
1369
/* from the local Guardian file.
*/
1370
/***************************************************************/
*/
1371
1372
records = records + 1;
1373
if ( records < MAX_RECORDS )
1374
{
1375
/**************************************************************/
1376
/* Read the next record from the file.
1377
/**************************************************************/
*/
1378
1379
condition_code = READX ( local_filenum
1380
, (char *) &local_buffer
1381
, MAX_READ_COUNT
1382
, /* count_read - waited I/O only */
1383
, READ_TAG );
1384
1385
if ( condition_code != CCE )
1386
{
1387
FILEINFO ( local_filenum, &error );
1388
printf ("Local file error %d\n", error);
1389
APS_DISCARD_ ( cepi );
1390
exit (EXIT_SUCCESS);
1391
}
1392
1393
/**************************************************************/
1394
/* Indicate that a local file read is in progress.
1395
/**************************************************************/
1396
1397
local_read_io_cmplt = FALSE;
1398
1399
}
1400
1401
}
1402
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -47
*/
NonStop FTAM Programming Examples
1403
Example 1 in C—Updating a Remote File (in Nowait
Mode)
} /* data_transfer */
1404
1405
1406 #pragma PAGE "CHECK_STATUS"
1407 /*********************************************************************/
1408 /*
*/
1409 /* Name:
check_status
*/
1410 /*
*/
1411 /* Description: The following procedure checks status returned from
*/
1412 /*
a previous FTAM procedure call. It checks for
*/
1413 /*
NORETRY, RETRYLATER, or DISCARD. If status is OK,
*/
1414 /*
it returns to the main program; otherwise, it
*/
1415 /*
displays a message and aborts or discards the
*/
1416 /*
association.
*/
1417 /*
*/
1418 /* Input:
None
1419 /*
*/
*/
1420 /* Output:
Error message to the terminal
1421 /*
*/
*/
1422 /*********************************************************************/
1423
1424
void check_status ()
1425
1426
{
1427
1428
/*******************************************************************/
1429
/* Check for a valid status.
1430
/*******************************************************************/
*/
1431
1432
if ( status == ZAPS_VAL_STATUS_OK )
1433
{
1434
1435
return;
}
1436
1437
/*******************************************************************/
1438
/* Get the error-code and error-subcode values if the status is
*/
1439
/* not OK.
*/
1440
/*******************************************************************/
1441
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -48
Example 1 in C—Updating a Remote File (in Nowait
Mode)
NonStop FTAM Programming Examples
1442
error = APS_STATUS_ ( cepi
1443
, /* event_code */
1444
, /* device_name */
1445
, &error_code
1446
, &error_subcode
1447
, /* service_id */
1448
, /* diagnostic_buffer */
1449
, (int *) &original_error_info );
1450
1451
check_error ();
1452
1453
/*******************************************************************/
1454
/* Display the status code, error code, and error subcode.
1455
/*******************************************************************/
*/
1456
1457
printf ("STATUS : %d ERROR CODE : %d ERROR SUBCODE : %d\n",
1458
status, error_code, error_subcode);
1459
1460
/*******************************************************************/
1461
/* Display the original error code and error subcode.
1462
/*******************************************************************/
*/
1463
1464
printf ("ORIGINAL ERROR INFO -\n");
1465
printf (" SERVICE ID : %d\n", original_error_info.zerror.zservice_id );
1466
printf (" ERROR CODE : %d\n", original_error_info.zerror.zerror_code );
1467
printf (" ERROR SUBCODE : %d\n",
1468
original_error_info.zerror.zerror_subcode );
1469
1470
if ( cepi == NOCEPI )
1471
return;
1472
1473
/*******************************************************************/
1474
/* Perform error handling, depending on the status value returned. */
1475
/* Additional application-specific error handling or recovery could*/
1476
/* be implemented, depending on application requirements.
1477
/*******************************************************************/
1478
1479
switch (status)
1480
{
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -49
*/
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1481
1482
case ZAPS_VAL_STATUS_NO_RETRY:
1483
case ZAPS_VAL_STATUS_RETRY_LATER:
1484
1485
/****************************************************************/
1486
/* The nowait I/O completion indicates an error was detected,
*/
1487
/* and the association should be aborted. If an abort request
*/
1488
/* is in progress, do not issue another abort request.
*/
1489
/****************************************************************/
1490
1491
if ( tag != ABORT_TAG )
1492
{
1493
status = FTM_U_ABORT_REQ_ ( cepi
1494
, /* action_result */
1495
, /* diag */
1496
, (long) ABORT_TAG );
1497
1498
/**************************************************************/
1499
/* If the above abort request is sent to the remote system,
1500
/* calling the main procedure sets the remote_file_update_cmpl*/
1501
/* flag, and the program is terminated. If the request is not */
1502
/* sent out, set the flag here and return to the main procedure.*/
1503
/**************************************************************/
*/
1504
1505
if ( status != ZAPS_VAL_STATUS_OK )
1506
{
1507
remote_file_update_cmplt = TRUE;
1508
}
1509
1510
1511
1512
printf ( "The association has been aborted\n" );
}
break;
1513
1514
case ZAPS_VAL_STATUS_DISCARD:
1515
/***************************************************************/
1516
/* The operation failed because the association was lost.
*/
1517
/* Indicate that the file update completed with a failure.The
*/
1518
/* API context information for the association is discarded
*/
1519
/* in the main processing loop for this application.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -50
*/
NonStop FTAM Programming Examples
1520
Example 1 in C—Updating a Remote File (in Nowait
Mode)
/**************************************************************/
1521
1522
remote_file_update_cmplt = TRUE;
1523
1524
break;
1525
1526
default: /* Unknown status value */
1527
1528
printf ("Unknown Status\n");
1529
APS_DISCARD_ ( cepi );
1530
exit (EXIT_FAILURE);
1531
1532
break;
1533
1534
} /* end of case */
1535
1536
} /* check_status */
1537
1538
1539 #pragma PAGE "CHECK_ERROR"
1540 /*********************************************************************/
1541 /*
*/
1542 /* Name:
check_error
*/
1543 /*
*/
1544 /* Description: The following procedure checks the error code
*/
1545 /*
returned from an FTM or APS procedure. If it
*/
1546 /*
detects an error, the procedure displays the error
*/
1547 /*
code, discards the association, and the program
*/
1548 /*
exits. Additional application-specific error
*/
1549 /*
handling or recovery could be implemented if
*/
1550 /*
required by an application.
*/
1551 /*
*/
1552 /* Input:
None
1553 /*
*/
*/
1554 /* Output:
Error message to the terminal
1555 /*
*/
*/
1556 /*********************************************************************/
1557
1558
void check_error ()
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -51
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1559
1560
{
1561
1562
/******************************************************************/
1563
/* Check for an error condition and display the error code.
1564
/******************************************************************/
*/
1565
1566
if ( error != ZAPS_ERR_OK )
1567
{
1568
/*****************************************************************/
1569
/* Display the error code.
1570
/*****************************************************************/
*/
1571
1572
printf ("ERROR # %d - Association aborted\n", error);
1573
1574
/*****************************************************************/
1575
/* Discard the API context information for the association
*/
1576
/* and exit the program.
*/
1577
/******************************************************************/
1578
1579
APS_DISCARD_ ( cepi );
1580
exit (EXIT_SUCCESS);
1581
1582
}
1583
1584
} /* check_error */
1585
1586
1587
#pragma PAGE "CHECK_ACTION_DIAG"
1588
/********************************************************************/
1589
/*
1590
/* Name:
1591
/*
*/
1592
/* Description: The following procedure determines whether the
*/
1593
/*
action requested of a remote responder was
*/
1594 /*
successful or not. If not, the procedure displays
*/
1595 /*
the diagnostic message and error ID for each
*/
1596 /*
diagnostic message element, discards the association,*/
1597 /*
and the program exits. Additional application-
*/
check_action_diag
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -52
*/
*/
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1598 /*
specific error handling or recovery could be
*/
1599 /*
implemented if required by an application.
*/
1600 /*
*/
1601 /* Input:
None
1602 /*
*/
*/
1603 /* Output:
Error messages to the terminal
1604 /*
*/
*/
1605 /*********************************************************************/
1606
1607
void check_action_diag ()
1608
1609
{
1610
1611
int i; /* index into diagnostic array */
1612
1613
/*******************************************************************/
1614
/* Check the action result for failure and display diagnostic
*/
1615
/* messages.
*/
1616
/*******************************************************************/
1617
1618
if ( action_result == ZFTM_VAL_ACTION_FAILURE )
1619
{
1620
/*******************************************************************/
1621
/* Display the number of diagnostic messages received.
1622
/*******************************************************************/
*/
1623
1624
printf ("Following is a list of %d diagnostic elements -\n",
1625
diag.zdiagcount);
1626
1627
/*******************************************************************/
1628
/* Display the diagnostic message and error ID for each message.
1629
/*******************************************************************/
*/
1630
1631
for (i = 0; i < diag.zdiagcount; i++)
1632
{
1633
printf (" Diagnostic Type: %ld\n", diag.zdiagelems[i].zdiagtype );
1634
printf (" Error ID: %ld\n", diag.zdiagelems[i].zerrorid );
1635
if (diag.zdiagelems[i].zfurtherdetailsispresent == ZAPS_VAL_PRESENT)
1636
printf (" Details: %s\n",
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -53
NonStop FTAM Programming Examples
1637
Example 1 in C—Updating a Remote File (in Nowait
Mode)
diag.zdiagelems[i].zfurtherdetails.u_zc.zb );
1638
}
1639
1640
/******************************************************************/
1641
/* Discard the API context information for the association and
*/
1642
/* exit the program.
*/
1643
/******************************************************************/
1644
1645
APS_DISCARD_ ( cepi );
1646
printf ( "Association discarded\n" );
1647
exit (EXIT_SUCCESS);
1648
1649
}
1650
1651
} /* check_action_diag */
1652
1653
1654 #pragma PAGE "BAD_STATE"
1655 /*********************************************************************/
1656 /*
*/
1657 /* Name:
bad_state
*/
1658 /*
*/
1659 /* Description: The following procedure is called when an FTM
*/
1660 /*
confirm procedure returns a bad state result.
*/
1661 /*
The procedure displays an error message, discards
*/
1662 /*
the association, and abends the program. Additional
*/
1663 /*
application-specific error handling or recovery
*/
1664 /*
could be implemented, depending on application
*/
1665 /*
requirements.
*/
1666 /*
*/
1667 /* Input:
None
1668 /*
*/
*/
1669 /* Output:
Error message to terminal
1670 /*
*/
*/
1671 /*********************************************************************/
1672
1673
void bad_state ()
1674
1675
{
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -54
NonStop FTAM Programming Examples
Example 1 in C—Updating a Remote File (in Nowait
Mode)
1676
1677
/******************************************************************/
1678
/* Display the invalid state-result error message. You might also */
1679
/* want to print out the diagnostic field to obtain more
*/
1680
/* information about the error condition.
*/
1681
/******************************************************************/
1682
1683
printf ("BAD STATE # %d Association aborted\n", state_result);
1684
1685
/*******************************************************************/
1686
/* Discard the API context information for the association
*/
1687
/* and abend the program.
*/
1688
/*******************************************************************/
1689
1690
APS_DISCARD_ ( cepi );
1691
exit (EXIT_FAILURE);
1692
1693
} /* bad_state */
1694
1695
1696
1697
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -55
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1
!-----------------------------------------------------------------------!
2
!
!
3
! Example 1 in TAL - Updating a Remote FTAM-2 File (in Nowait Mode)
!
4
!
!
5
!-----------------------------------------------------------------------!
6
!
!
7
! Program Name: EXTINSF2
!
8
!
!
9
! Program Description:
!
10 !
!
11 ! This program, in nowait mode, inserts five records into a remote
!
12 ! FTAM-2 file. The application initiates and manages this data
!
13 ! transfer. It opens and reads a local (Enscribe relative) file
!
14 ! using Guardian system procedures and sends five records as data
!
15 ! requests to the remote file. Both the Guardian system calls
!
16 ! and the Tandem FTAM procedure calls are made in nowait mode.
!
17 !
!
18 ! The main procedure contains the initialization code, the control
!
19 ! statements for the main processing loop, and the termination code.
!
20 ! This procedure analyzes input received from MFM_AWAITIOX_ and
!
21 ! calls one of three procedures to perform processing as indicated:
!
22 !
!
23 !
ftam_io_cmpl
24 !
A routine that handles FTAM I/O
!
completions
!
25 !
26 !
!
ftam_event_rcvd
27 !
A routine that handles FTAM events
!
received from the remote responder
!
28 !
29 !
!
data_transfer
A routine that obtains data from the
!
30 !
local file, formats it, and then
!
31 !
sends it to the remote file
!
32 !
33 !
!
Four error-handling routines are used in this program:
34 !
35 !
36 !
!
!
check_error
A procedure that checks for errors
!
returned by FTM indication and
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -56
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
37 !
confirm procedures
38 !
39 !
!
!
check_status
A procedure that checks status
!
40 !
returned by FTM request and
!
41 !
response procedures as well as the
!
42 !
I/O completions
!
43 !
44 !
!
bad_state
45 !
A procedure that handles an invalid
!
FTAM state result
!
46 !
47 !
!
check_action_diag
A procedure that checks the action
!
48 !
result and diagnostic messages
!
49 !
returned by an FTM procedure
!
50 !
!
51 ! FTM requests and responses return a status value on both
!
52 ! the procedure call and the I/O completion. The check_status
!
53 ! procedure checks the results of the operation. The FTM
!
54 ! indication and confirm procedures return an error value and
!
55 ! do not have I/O completions. The check_error procedure checks
!
56 ! the return value.
!
57 !
!
58 !-----------------------------------------------------------------------!
59 !
!
60 ! NOTE : Before attempting to run this program, make sure:
!
61 !
!
62 !
a) the environmental variables are set correctly
!
63 !
b) the local file contains at least five records
!
64 !
c) the local file record length is less than or
!
65 !
66 !
67 !
equal to 132 bytes
d) the required parameters (currently using defaults)
in the FTM_INITIALIZE_REQ_ call are set correctly
68 !
!
!
!
!
69 !-----------------------------------------------------------------------!
70
71
72 !-----------------------------------------------------------------------!
73 ! Source in the FTM and APS structure definitions and literals from
!
74 ! the appropriate volume and subvolume.
!
75 !-----------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -57
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
76
77 ?nolist, source zftmtal
! FTM DDL
!
! APS DDL
!
78 ?list
79 ?nolist, source zapstal
80 ?list
81 ?nocode
82 ?nomap
83
84 !-----------------------------------------------------------------------!
85 ! Global data declarations
!
86 !-----------------------------------------------------------------------!
87
88 !-----------------------------------------------------------------------!
89 ! Macro for word addressing
!
90 !-----------------------------------------------------------------------!
91
92
DEFINE SADDR( x ) = (@x '<<' 1)#; ! String address of word object
!
93
94 !-----------------------------------------------------------------------!
95 ! Nowait I/O tags
!
96 !-----------------------------------------------------------------------!
97
98
LITERAL
ABORT_TAG
= 1;
! User-abort request tag
!
99
LITERAL
DATA_TAG
= 2;
! FTM data request tag
!
100 LITERAL
DATAEND_TAG
= 3;
! FTM data-end request tag
!
101 LITERAL
EVENTREC_TAG
= 4;
! APS event-receive req. tag
!
102 LITERAL
FILECLOSE_TAG
= 5;
! FTM file-close req. tag
!
103 LITERAL
FILEOPEN_TAG
= 6;
! FTM file-open req. tag
!
104 LITERAL
INITIALIZE_TAG
= 7;
! FTM initialize req. tag
!
105 LITERAL
TERMINATE_TAG
= 8;
! FTM terminate request tag
!
106 LITERAL
TRANSFEREND_TAG = 9;
! FTM transfer-end req. tag
!
107 LITERAL
WRITE_TAG
= 10;
! FTM write request tag
!
108 LITERAL
READ_TAG
= 11;
! Guardian read tag
!
109
110 !----------------------------------------------------------------------!
111 ! Miscellaneous literals
!
112 !----------------------------------------------------------------------!
113
114 LITERAL
NOCEPI
= -1;
! Indicates no valid CEPI
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -58
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
115 LITERAL
NOWAIT
= 0D;
! Indicates nowait mode
!
116 LITERAL
WAIT_FOREVER
= -1D;
! MFM_AWAITIOX_ wait value
!
117 LITERAL FALSE
= 0;
! Boolean value for FALSE
!
118 LITERAL TRUE
= 1;
! Boolean value for TRUE
!
119 LITERAL MAX_RECORDS
= 5;
! Maximum number of records
!
120 LITERAL BASE
= 10;
! Used with DNUMOUT as base
!
121 LITERAL MAX_BUF
= 250;
! Maximum bytes to send
!
122 LITERAL MAX_READ_COUNT
= 132;
! Maximum bytes to read
!
123 LITERAL OPEN_FLAGS
= 1;
! Open for nowait read
!
124
125
126 !----------------------------------------------------------------------!
127 ! Environment-specific fields
!
128 ! You will need to change these fields to reflect your FTAM
!
129 ! environment. local_file must contain a valid expanded Guardian
!
130 ! file name (in
!
internal format), and remote_file_name must contain
131 ! a valid file name for the remote system. In this example,
!
132 ! remote_file_name is shown as a Guardian file name.
!
133 !
!
134 ! When changing these values, you might also need to change
!
135 ! the length of the corresponding variables (array size).
!
136 !----------------------------------------------------------------------!
137
138
STRING .EXT
local_appl_name[0:4]
139
STRING .EXT
responding_appl_name[0:4] := "APPL2";
140
STRING .EXT
manager_name[0:23]
141
INT
142
STRING .EXT
.local_file[0:11]
:= "APPL1";
:= "$APMGR ";
:= "$VOLUME SUBVOL LOCALF ";
remote_file_name[0:21]
:= "$VOLUME.SUBVOL.REMOTEF";
143
144
145 !----------------------------------------------------------------------!
146 ! Miscellaneous variables
!
147 !----------------------------------------------------------------------!
148
149 INT
event_code;
! FTAM event code
!
150 INT(32) tag;
! Tag value for nowait I/O
!
151 INT
records := 0;
! Number of records sent
!
152 INT
local_filenum;
! Local file number
!
153 INT
cepi := NOCEPI;
! Connection endpoint id
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -59
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
154 INT
wait_mode;
! Wait or nowait I/O
!
155 INT
condition_code;
! Condition code
!
156 INT
width;
! Used for DNUMOUT calls
!
157
158 !----------------------------------------------------------------------!
159 ! Variables used by the MFM_AWAITIOX_ procedure !
160 !----------------------------------------------------------------------!
161
162 INT
filenum;
! Returned by MFM_AWAITIOX_
!
163 INT(32) buffer_addr;
! Returned buffer address
!
164 INT
count_transferred;
! Number of bytes read
!
165 INT
buf_count_transferred;
! Holding place for # bytes
!
166
167 !----------------------------------------------------------------------!
168 ! Variables used by the FTM procedures
!
169 !----------------------------------------------------------------------!
170
171 INT(32) file_status;
! Used by FTM_FILE_OPEN_REQ_
!
172 INT(32) delete_action;
! Do not delete after close
!
173 INT(32) state_result;
! Status of regime change
!
174 INT(32) action_result;
! Status in FTM CNF_ calls
!
175 INT(32) fadu_op;
! Insert operation used
!
176
177 !----------------------------------------------------------------------!
178 ! Boolean variables used to manage nowait I/O processing
!
179 !----------------------------------------------------------------------!
180
181 INT
local_read_io_cmplt := FALSE;
! Local file read completed
!
182 INT
remote_io_cmplt := FALSE;
! Data-req to rem.completed
!
183 INT
remote_file_update_cmplt := FALSE; ! While loop control flag
!
184 INT
file_update_failed := TRUE;
!
! Remote file update failed
185
186 !----------------------------------------------------------------------!
187 ! Error-handling variables
!
188 !----------------------------------------------------------------------!
189
190 INT
status;
! Used for I/O request calls
!
191 INT
error;
! Used for confirm calls
!
192 INT
error_code;
! Returns error number
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -60
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
193 INT
error_subcode;
! Returns error subcodes
!
194 INT
file_error;
! Local file I/O errors
!
195
196 !----------------------------------------------------------------------!
197 ! Local and remote buffer pointers
!
198 !----------------------------------------------------------------------!
199
200 STRING .EXT remote_buffer[0:MAX_BUF-1];
! Used for FTM_DATA_REQ_
201 STRING .EXT local_buffer[0:MAX_READ_COUNT-1];!Used for Guardian read
202 INT
.EXT data_ptr;
!
!
! Points to remote_buffer !
203
204 !----------------------------------------------------------------------!
205 ! Structures used by the FTM procedures
!
206 !----------------------------------------------------------------------!
207
208 STRUCT .EXT element_hdr_ptr
( ZAPS^DDL^DATA^ELEMENT^HDR^DEF );
209 STRUCT .EXT data_hdr_ptr
( ZAPS^DDL^DATA^HDR^DEF );
210 STRUCT .EXT aplmgr_name
( ZAPS^DDL^FILENAME^DEF );
211 STRUCT .EXT responding_appl
( ZAPS^DDL^APPL^ADDR^DEF );
212 STRUCT .EXT local_appl
( ZAPS^DDL^APPL^ADDR^DEF );
213 STRUCT .EXT func_units
( ZFTM^DDL^FUNC^UNITS^DEF );
214 STRUCT .EXT service_class
( ZFTM^DDL^SERVICE^CLASS^DEF );
215 STRUCT .EXT remote_file
( ZAPS^DDL^CHAR128^DEF );
216 STRUCT .EXT original_error_info ( ZAPS^DDL^ORIGINAL^ERROR^DEF );
217 STRUCT .EXT requested_access
( ZFTM^DDL^REQUESTED^ACCESS^DEF );
218 STRUCT .EXT process_mode
( ZFTM^DDL^PROC^MODE^DEF );
219 STRUCT .EXT contents_type_list
( ZFTM^DDL^CNTNTS^LIST^DEF );
220 STRUCT .EXT contents_type
( ZFTM^DDL^CNTNTS^TYPE^DEF );
221 STRUCT .EXT fadu_id
( ZFTM^DDL^FADU^ID^DEF );
222 STRUCT .EXT diag
( ZFTM^DDL^DIAGNOSTIC^DEF );
223
224 !----------------------------------------------------------------------!
225 ! Variables used for startup-message processing
!
226 !----------------------------------------------------------------------!
227
228 STRUCT .STARTUP;
229
BEGIN
230
INT
msg_code;
231
INT
default_vol [0:7];
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -61
NonStop FTAM Programming Examples
232
INT
infile [0:11];
233
INT
outfile [0:11];
234
STRING params [0:131];
235
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
END;
236
237
INT
.receive [0:11] := ["$RECEIVE",8*[" "]];
238
INT
fn := -1;
239
240
!---------------------------------------------------------------------!
241
! Variables used for local terminal I/O processing
242
!---------------------------------------------------------------------!
!
243
244
INT
termname [0:11];
245
INT
termnum;
246
INT
text_len;
247
INT
.outbuf [0:133];
248
STRING
.tempbuf := SADDR(outbuf);
249
STRING
.text_ptr;
250
251
!---------------------------------------------------------------------!
252
! End global data declarations
!
253 !----------------------------------------------------------------------!
254
255 !----------------------------------------------------------------------!
256 ! External function declarations for FTM, APS, MFM, and Guardian
!
257 ! procedures
!
258 !----------------------------------------------------------------------!
259
260
?nolist, source extdecs0
( FTM_INITIALIZE_REQ_
261
?
, FTM_INITIALIZE_CNF_
262
?
, FTM_FILE_OPEN_REQ_
263
?
, FTM_FILE_OPEN_CNF_
264
?
, FTM_FILE_CLOSE_REQ_
265
?
, FTM_FILE_CLOSE_CNF_
266
?
, FTM_LOCATE_REQ_
267
?
, FTM_LOCATE_CNF_
268
?
, FTM_WRITE_REQ_
269
?
, FTM_DATA_REQ_
270
?
, FTM_DATA_END_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -62
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
271
?
, FTM_TRANSFER_END_REQ_
272
?
, FTM_TRANSFER_END_CNF_
273
?
, FTM_TERMINATE_REQ_
274
?
, FTM_TERMINATE_CNF_
275
?
, FTM_P_ABORT_IND_
276
?
, FTM_U_ABORT_IND_
277
?
, FTM_U_ABORT_REQ_
278
?
, FTM_CANCEL_IND_
279
?
, FTM_CANCEL_RSP_
280
?
, APS_INITIALIZE_
281
?
, APS_STATUS_
282
?
, APS_EVENT_RECEIVE_
283
?
, APS_DISCARD_
284
?
, MFM_AWAITIOX_
285
?
, ABEND
286
?
, STOP
287
?
, WRITE
288
?
, DNUMOUT
289
?
, READ
290
?
, READX
291
?
, OPEN
292
?
, FILEINFO
293
?
, CLOSE
294
?
, MYTERM )
295
?list
296
297 !----------------------------------------------------------------------!
298 ! Forward declarations
!
299 !----------------------------------------------------------------------!
300
301
PROC BAD_STATE;
302
FORWARD;
303
PROC CHECK_ACTION_DIAG;
304
FORWARD;
305
PROC CHECK_ERROR;
306
FORWARD;
307
PROC CHECK_STATUS;
308
FORWARD;
309
PROC DATA_TRANSFER;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -63
NonStop FTAM Programming Examples
310
FORWARD;
311
PROC FTAM_EVENT_RCVD;
312
FORWARD;
313
PROC FTAM_IO_CMPL;
314
FORWARD;
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
315
316
317
318 ?PAGE "proc INSERT"
319 !----------------------------------------------------------------------!
320 !
!
321 ! Name:
insert
!
322 !
!
323 ! Description: The insert program, written in nowait mode, updates
!
324 !
a file on a remote system of an OSI network by
!
325 !
inserting five records in it. This application
!
326 !
initiates and manages the data transfer. It reads
!
327 !
the data transferred from a local Guardian file.
!
328 !
!
329 ! Inputs:
None
330 !
!
!
331 ! Outputs:
None
332 !
!
!
333 !----------------------------------------------------------------------!
334
335 PROC insert MAIN;
336
337 BEGIN
338
339
!------------------------------------------------------------------!
340
! Get the process-startup message and open the terminal
!
341
! for output.
!
342
!------------------------------------------------------------------!
343
344
CALL MYTERM ( termname );
345
CALL OPEN ( termname, termnum );
346
347
CALL OPEN ( receive, fn );
348
IF <> THEN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -64
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
349
BEGIN
350
tempbuf ':=' "$RECEIVE open error" -> @text_ptr;
351
text_len := @text_ptr - @tempbuf;
352
CALL WRITE ( termnum, outbuf, text_len );
353
CALL STOP;
354
END;
355
356
CALL READ ( fn, startup, $len(startup));
357
IF <> THEN
358
BEGIN
359
tempbuf ':=' "$RECEIVE read error" -> @text_ptr;
360
text_len := @text_ptr - @tempbuf;
361
CALL WRITE ( termnum, outbuf, text_len );
362
CALL STOP;
363
END;
364
365
CALL CLOSE ( fn );
366
367
!--------------------------------------------------------------------!
368
! Open the local Guardian file for reading in nowait mode.
369
!--------------------------------------------------------------------!
!
370
371
CALL OPEN ( local_file
372
, local_filenum
373
, OPEN_FLAGS);
374
375
IF <> THEN
376
BEGIN
377
CALL FILEINFO ( local_filenum, file_error );
378
tempbuf ':=' "Local file open error " -> @text_ptr;
379
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
380
, $DBL ( file_error )
381
, BASE );
382
text_len := @text_ptr - @tempbuf;
383
CALL WRITE ( termnum, outbuf, text_len );
384
CALL STOP;
385
END;
386
387
!--------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -65
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
388
! Allocate and initialize a segment used by the FTM and APS
!
389
! procedures.
!
390
!--------------------------------------------------------------------!
391
392
error := APS_INITIALIZE_ (! swapvol !);
393
IF ( error <> ZAPS^ERR^OK ) THEN
394
BEGIN
395
tempbuf ':=' "Initialization of the FTAM/APS segment failed"
396
-> @text_ptr;
397
text_len := @text_ptr - @tempbuf;
398
CALL WRITE ( termnum, outbuf, text_len );
399
CALL STOP;
400
END;
401
402
!--------------------------------------------------------------------!
403
! The following sections initialize the various parameters
!
404
! for the FTM_INITIALIZE_REQ_ procedure.
!
405
!--------------------------------------------------------------------!
406
407
!--------------------------------------------------------------------!
408
! Set the wait mode for the association to nowait and initialize the !
409
! APLMGR process.
410
!--------------------------------------------------------------------!
!
411
412
wait_mode := ZAPS^VAL^NOWAITED;
413
aplmgr_name ':=' manager_name FOR $occurs(manager_name) BYTES;
414
415
!--------------------------------------------------------------------!
416
! Supply the remote and local OSI addresses or common names. This
!
417
! application uses the common name. Set the length fields of the
!
418
! OSI addresses to 0.
!
419
!--------------------------------------------------------------------!
420
421
responding_appl.zpsap.zpsel.zlen := 0;
422
responding_appl.zpsap.zssel.zlen := 0;
423
responding_appl.zpsap.ztsel.zlen := 0;
424
responding_appl.zpsap.znsap.zlen := 0;
425
responding_appl.zappl^name.zlen
426
responding_appl.zappl^name.zb
:= $occurs(responding_appl_name);
':=' responding_appl_name FOR
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -66
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
427
responding_appl.zappl^name.zlen BYTES;
428
429
local_appl.zpsap.zpsel.zlen := 0;
430
local_appl.zpsap.zssel.zlen := 0;
431
local_appl.zpsap.ztsel.zlen := 0;
432
local_appl.zpsap.znsap.zlen := 0;
433
local_appl.zappl^name.zlen
434
local_appl.zappl^name.zb
435
:= $occurs(local_appl_name);
':=' local_appl_name FOR
local_appl.zappl^name.zlen BYTES;
436
437
!--------------------------------------------------------------------!
438
! Select the service class/classes required. This application needs
!
439
! only the file-access service class. The file-access service class
!
440
! allows insertion of data into a structured file.
!
441
!--------------------------------------------------------------------!
442
443
service_class.zunconstrained := ZAPS^VAL^FALSE;
444
service_class.zmgmt
:= ZAPS^VAL^FALSE;
445
service_class.ztransfer
:= ZAPS^VAL^FALSE;
446
service_class.zxfermgmt
:= ZAPS^VAL^FALSE;
447
service_class.zaccess
:= ZAPS^VAL^TRUE;
448
449
!--------------------------------------------------------------------!
450
! Select the functional units required by this application. The
!
451
! following functional units are mandatory for the file-access
!
452
! service class: read, write, and file-access.
!
453
!
!
454
! Also, the FTM_FILE_OPEN_REQ_ and FTM_FILE_CLOSE_REQ_ procedures
!
455
! require that you select the grouping functional unit.
!
456
!--------------------------------------------------------------------!
457
458
func_units.zread
:= ZAPS^VAL^TRUE;
459
func_units.zwrite
:= ZAPS^VAL^TRUE;
460
func_units.zfileaccess
:= ZAPS^VAL^TRUE;
461
func_units.zfilemgmt
:= ZAPS^VAL^FALSE;
462
func_units.zfilemgmtenhanced := ZAPS^VAL^FALSE;
463
func_units.zgroup
:= ZAPS^VAL^TRUE;
464
func_units.zfadulock
:= ZAPS^VAL^FALSE;
465
func_units.zrecovery
:= ZAPS^VAL^FALSE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -67
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
466
func_units.zrestart
:= ZAPS^VAL^FALSE;
467
468
!---------------------------------------------------------------------!
469
! Set up the contents-type-list to request a document of
!
470
! type FTAM-2. The object ID breaks down as follows:
!
471
! 1 = ISO, 0 = Standard, 8571 = FTAM, 5 = document type,
!
472
! 2 = FTAM-2.
!
473
!---------------------------------------------------------------------!
474
475
contents_type_list.zcount := 1;
476
contents_type_list.zcntnts^type^ispresent := ZAPS^VAL^PRESENT;
477 contents_type_list.zcntnts^type^list[0].zid:=ZFTM^VAL^CNTNTSLIST^DOCNAME;
478
contents_type_list.zcntnts^type^list[0].zcntntstype.znum^elements := 5;
479
contents_type_list.zcntnts^type^list[0].zcntntstype.zobj^id
480
':=' [1,0,8571,5,2];
481
482
!---------------------------------------------------------------------!
483
! Establish the association with the remote FTAM responder. Do this
!
484
! by calling the FTM_INITIALIZE_REQ_ procedure. In this example,
!
485
! default values are used for many parameters. For example, the
!
486
! default values 0, for AE qualifier, and [1,3,9999,1,7], for AP
!
487
! title, are used in the ae_title parameter; and 1 and
!
488
! [1,3,9999,1,7], respectively, are used in the remote_ae_title
!
489
! parameter. The remote system, however, might require other
!
490
! values for certain parameters (e.g., ae_title, remote_ae_title,
!
491
! initiator_id, filestore_password, and so on).
!
492
!---------------------------------------------------------------------!
493
494
status := FTM_INITIALIZE_REQ_ ( cepi
495
, aplmgr_name
496
, responding_appl
497
, wait_mode
498
, local_appl
499
, ! ae_title !
500
, ! remote_ae_title !
501
, service_class
502
, func_units
503
504
, ! attr_groups - defaults to kernel only !
, contents_type_list
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -68
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
505
, ! initiator_id - defaults to spaces !
506
, ! account - defaults to spaces !
507
, ! filestore_password - defaults to spaces !
508
, $dbl (INITIALIZE_TAG) );
509
510
511
IF ( status <> ZAPS^VAL^STATUS^OK ) THEN
BEGIN
512
CALL check_status;
513
CALL STOP;
514
END;
515
516
!---------------------------------------------------------------------!
517
! The main control loop continues processing until an abort or
!
518
! discard, or until the last data request is sent.
!
519
!---------------------------------------------------------------------!
520
521
WHILE ( NOT remote_file_update_cmplt ) DO
522
BEGIN
523
524
!-----------------------------------------------------------------!
525
! Assign a filenum value of -1 to make the process wait for the
!
526
! first I/O completion of an FTM, APS, or Guardian file system
!
527
! procedure.
!
528
!-----------------------------------------------------------------!
529
530
filenum := -1;
531
532
!-----------------------------------------------------------------!
533
! Wait for the next I/O completion from an FTM, APS, or
!
534
! Guardian file-system procedure.
!
535
!-----------------------------------------------------------------!
536
537
CALL MFM_AWAITIOX_ ( status ! Output !
538
, filenum ! I/O !
539
, buffer_addr ! Output !
540
, count_transferred ! Output !
541
, tag ! Output !
542
, WAIT_FOREVER ! Input !
543
, ! segment_id ! );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -69
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
544
545
546
547
!-----------------------------------------------------------------!
548
! If an I/O completion for READX is received, save the value of
!
549
! count_transferred in buf_count_transferred for later use.
!
550
!-----------------------------------------------------------------!
551
552
553
IF <> THEN
condition_code := -1;
554
555
556
IF ( count_transferred <> -1 ) THEN
buf_count_transferred := count_transferred;
557
558
559
IF ( filenum <> local_filenum ) THEN
560
!-----------------------------------------------------------------!
561
! Process the I/O completion of an FTM or APS procedure or event. !
562
!-----------------------------------------------------------------!
563
BEGIN
564
565
!--------------------------------------------------------------!
566
! Determine whether an FTAM I/O operation completed or an FTAM !
567
! event was received. If neither, display the error code and
!
568
! error subcode.
!
569
!--------------------------------------------------------------!
570
571
IF ( status = ZAPS^VAL^STATUS^OK ) THEN
572
BEGIN
573
CALL ftam_io_cmpl;
574
END
575
ELSE IF ( status = ZAPS^VAL^STATUS^EVENT ) THEN
576
BEGIN
577
CALL ftam_event_rcvd;
578
END
579
ELSE
580
BEGIN
581
CALL check_status;
582
CALL APS_DISCARD_ ( cepi );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -70
NonStop FTAM Programming Examples
583
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
CALL ABEND;
584
END;
585
END
586
ELSE ! Process the local file I/O completion. !
587
BEGIN
588
589
!--------------------------------------------------------------!
590
! Check the condition code to determine if the local file
!
591
! I/O operation completed successfully.
!
592
!--------------------------------------------------------------!
593
594
IF ( condition_code <> 0 ) THEN
595
BEGIN
596
CALL FILEINFO ( local_filenum, file_error );
597
tempbuf ':=' "Local file error " -> @text_ptr;
598
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
599
, $DBL ( file_error )
600
, BASE );
601
text_len := @text_ptr - @tempbuf;
602
CALL WRITE ( termnum, outbuf, text_len );
603
CALL APS_DISCARD_ ( cepi );
604
CALL STOP;
605
END;
606
607
!--------------------------------------------------------------!
608
! Verify that the local I/O completion was for a file read.
609
!--------------------------------------------------------------!
!
610
611
IF (tag = $dbl (READ_TAG)) THEN
612
BEGIN
613
!-----------------------------------------------------------!
614
! Indicate that the local file read completed successfully
!
615
! and transfer the data that was read to the responder.
!
616
!-----------------------------------------------------------!
617
618
local_read_io_cmplt := TRUE;
619
CALL data_transfer;
620
END
621
ELSE
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -71
NonStop FTAM Programming Examples
622
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
BEGIN
623
tempbuf ':=' "Invalid TAG" -> @text_ptr;
624
text_len := @text_ptr - @tempbuf;
625
CALL WRITE ( termnum, outbuf, text_len );
626
CALL APS_DISCARD_ ( cepi );
627
CALL ABEND; ! Unknown tag value. !
628
END;
629
630
END;
END; --- End of WHILE loop ---
631
632
!--------------------------------------------------------------------!
633
! Discard the API context information for the association. !
634
!--------------------------------------------------------------------!
635
636
CALL APS_DISCARD_ ( cepi );
637
638
!--------------------------------------------------------------------!
639
! Close the local file that was opened for transfer.
640
!--------------------------------------------------------------------!
!
641
642
CALL CLOSE ( local_filenum );
643
644
!--------------------------------------------------------------------!
645
! Display a message to the terminal that an error occurred or that
!
646
! the program completed successfully.
!
647
!--------------------------------------------------------------------!
648
649
IF ( file_update_failed ) THEN
650
BEGIN
651
tempbuf ':=' "File update error" -> @text_ptr;
652
END
653
ELSE
654
BEGIN
655
656
tempbuf ':=' "File update complete" -> @text_ptr;
END;
657
658
text_len := @text_ptr - @tempbuf;
659
CALL WRITE ( termnum, outbuf, text_len );
660
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -72
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
661 END; --- End INSERT --662
663
664
?PAGE "proc FTAM_IO_CMPL"
665
!---------------------------------------------------------------------!
666
!
667
! Name:
668
!
!
669
! Description: This procedure processes I/O completions for FTM
!
670
!
request and response procedures. It uses the tag
!
671
!
field to determine which FTM procedure completed.
!
672
!
It takes a specified action, depending on the type
!
673
!
of request or response.
!
674
!
675
! Input:
676
!
677
! Output:
Requests to remote responder
!
678
!
Error message to the terminal
!
679
!
680
!---------------------------------------------------------------------!
!
ftam_io_cmpl
!
!
None
!
!
!
681
682
PROC ftam_io_cmpl;
683
684
BEGIN
685
686
!-----------------------------------------------------------------!
687
! The tag value represents the type of FTM request or response
!
688
! procedure associated with this I/O completion. The tag value
!
689
! comes from the MFM_AWAITIOX_ call.
!
690
!-----------------------------------------------------------------!
691
692
CASE ($int (tag)) OF
693
BEGIN
694
695
INITIALIZE_TAG ->
696
!--------------------------------------------------------------!
697
! After FTM_INITIALIZE_REQ_ completes, issue an event-
!
698
! receive. All subsequent event-receive calls are issued
!
699
! from the ftam_event_rcvd procedure after each event-receive
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -73
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
700
! completes.
!
701
!--------------------------------------------------------------!
702
703
status := APS_EVENT_RECEIVE_ ( cepi
704
, ! WAIT_FOREVER !
705
, $dbl (EVENTREC_TAG) );
706
707
CALL check_status;
708
709
FILEOPEN_TAG,
710
TRANSFEREND_TAG,
711
FILECLOSE_TAG,
712
TERMINATE_TAG ->
713
!--------------------------------------------------------------!
714
! These requests do not require any action. The
!
715
! ftam_event_rcvd procedure has already issued an event-
!
716
! receive.
!
717
!--------------------------------------------------------------!
718
719
;
720
721
WRITE_TAG ->
722
!--------------------------------------------------------------!
723
! The remote system is now set up for writing. Read the first
!
724
! record from the file into the local buffer. The file was
!
725
! opened in nowait mode.
!
726
!--------------------------------------------------------------!
727
728
CALL READX ( local_filenum
729
, local_buffer
730
, MAX_READ_COUNT
731
, ! count_read - waited I/O only !
732
, $dbl (READ_TAG) );
733
IF <> THEN
734
BEGIN
735
CALL FILEINFO ( local_filenum, file_error );
736
tempbuf ':=' "Local file error " -> @text_ptr;
737
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
738
, $DBL ( file_error )
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -74
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
739
, BASE );
740
text_len := @text_ptr - @tempbuf;
741
CALL WRITE ( termnum, outbuf, text_len );
742
CALL APS_DISCARD_ ( cepi );
743
CALL STOP;
744
END;
745
746
!--------------------------------------------------------------!
747
! Set flags to indicate that the remote I/O operation is com-
!
748
! plete (this is to know that there are no outstanding I/O
!
749
! operations) and that there is a local read I/O operation
!
750
! outstanding.
!
751
!--------------------------------------------------------------!
752
753
remote_io_cmplt := TRUE;
754
local_read_io_cmplt := FALSE;
755
756
DATA_TAG ->
757
!--------------------------------------------------------------!
758
! An FTM data request has completed. Send the next record if
!
759
! the local file read has completed.
!
760
!--------------------------------------------------------------!
761
762
remote_io_cmplt := TRUE;
763
764
765
IF (local_read_io_cmplt) THEN
CALL data_transfer;
766
767
DATAEND_TAG ->
768
!--------------------------------------------------------------!
769
! All records have been transferred. Terminate the
!
770
! data-transfer regime now.
!
771
!--------------------------------------------------------------!
772
773
status := FTM_TRANSFER_END_REQ_ ( cepi
774
, $dbl (TRANSFEREND_TAG) );
775
776
CALL check_status;
777
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -75
NonStop FTAM Programming Examples
778
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
ABORT_TAG ->
779
!--------------------------------------------------------------!
780
! If an abort I/O operation completes, exit the main control
!
781
! loop after returning from this routine.
!
782
!--------------------------------------------------------------!
783
784
remote_file_update_cmplt := TRUE;
785
786
OTHERWISE ->
787
!--------------------------------------------------------------!
788
! Display the invalid tag error message and abend the program. !
789
!--------------------------------------------------------------!
790
791
tempbuf ':=' "Invalid TAG" -> @text_ptr;
792
text_len := @text_ptr - @tempbuf;
793
CALL WRITE ( termnum, outbuf, text_len );
794
CALL APS_DISCARD_ ( cepi );
795
CALL ABEND;
796
797
END; --- end of CASE ---
798
799
END; --- ftam_io_cmpl ---
800
801
802 ?PAGE "proc FTAM_EVENT_RCVD"
803 !----------------------------------------------------------------------!
804 !
!
805 ! Name:
ftam_event_rcvd
!
806 !
!
807 ! Description: This procedure is called whenever an FTAM event
!
808 !
is received. It calls APS_STATUS to determine
!
809 !
which FTAM event has been received. Depending on
!
810 !
the event code that is returned, it calls the
!
811 !
appropriate FTM confirm or indication procedure.
!
812 !
It issues the next FTM request and another event-
!
813 !
receive request to receive the next FTAM event.
!
814 !
!
815 ! Input:
None
816 ! !
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -76
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
817 ! Output:
None
!
818 !
!
819 !-----------------------------------------------------------------------!
820
821 PROC ftam_event_rcvd;
822
823 BEGIN
824
825
826 ?PAGE "subproc INIT_CNF_OPEN_REQ"
827 !----------------------------------------------------------------------!
828 !
!
829 ! Name:
init_cnf_open_req
!
830 !
!
831 ! Description: This subprocedure is called when an initialize
!
832 !
confirm is received. It calls FTM_INITIALIZE_CNF_
!
833 !
and checks the error status and state result. It
!
834 !
then initializes parameters for the call to
!
835 !
FTM_FILE_OPEN_REQ_, makes the call, and returns
!
836 !
to the calling routine.
!
837 !
!
838 ! Input:
Initialize confirm
839 !
!
!
840 ! Output:
File-select/open request to remote responder
841 !
!
!
842 !----------------------------------------------------------------------!
843
844
SUBPROC init_cnf_open_req;
845
846
BEGIN
847
848
!--------------------------------------------------------------------!
849
! Retrieve the initialize-confirm data.
850
!--------------------------------------------------------------------!
851
852
error := FTM_INITIALIZE_CNF_ ( cepi
853
, state_result
854
, action_result
855
, local_appl
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -77
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
856
, responding_appl
857
, ! remote_ae_title !
858
, service_class
859
, func_units
860
, ! attr_groups !
861
, contents_type_list
862
, diag );
863
864
CALL check_error;
865
866
!--------------------------------------------------------------------!
867
! Check the state result and the action result.
868
!--------------------------------------------------------------------!
!
869
870
CALL check_action_diag;
871
IF ( state_result = ZFTM^VAL^STATE^FAILURE ) THEN
872
BEGIN
873
874
CALL bad_state;
END;
875
876
!--------------------------------------------------------------------!
877
! Check to make sure that the requested functional units have not !
878
! been negotiated down from what was requested. If the requested !
879
! functional units are not available, this application aborts the !
880
! association. !
881
!--------------------------------------------------------------------!
882
883
IF ( func_units.zread <> ZAPS^VAL^TRUE OR
884
func_units.zwrite <> ZAPS^VAL^TRUE OR
885
func_units.zgroup <> ZAPS^VAL^TRUE OR
886
func_units.zfileaccess <> ZAPS^VAL^TRUE ) THEN
887
888
889
BEGIN
tempbuf ':=' "Functional Units unavailable for the association"
-> @text_ptr;
890
text_len := @text_ptr - @tempbuf;
891
CALL WRITE ( termnum, outbuf, text_len );
892
893
action_result := ZFTM^VAL^ACTION^FAILURE;
894
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -78
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
895
status := FTM_U_ABORT_REQ_( cepi
896
, action_result
897
, ! diagnostic !
898
, $dbl (ABORT_TAG) );
899
900
!----------------------------------------------------------------!
901
! If the above abort request is sent to the remote system, then
!
902
! the calling main procedure sets the remote_file_update_cmplt
!
903
! flag, and the program is terminated. If the request is not sent!
904
! out, set the flag here and return to the main procedure.
905
!----------------------------------------------------------------!
!
906
907
IF status <> ZAPS^VAL^STATUS^OK THEN
908
BEGIN
909
remote_file_update_cmplt := TRUE;
910
END;
911
RETURN;
912
END;
913
914
!--------------------------------------------------------------------!
915
! Check to make sure that FTAM-2 is returned as negotiated
!
916
! contents-type-list. If it is available, set the contents-type
!
917
! to be used later in the FTM_FILE_OPEN_REQ_ call. If it is not,
!
918
! this application aborts the association.
!
919
!--------------------------------------------------------------------!
920
921
IF ( contents_type_list.zcntnts^type^list[0].zcntntstype.zobj^id =
922
923
[1,0,8571,5,2] ) THEN
BEGIN
924
contents_type.zid := ZFTM^VAL^CNTNTSTYPE^DOCTYPE;
925
contents_type.zdoctype.zdoctypename.znum^elements := 5;
926
contents_type.zdoctype.zdoctypename.zobj^id ':=' [1,0,8571,5,2];
927
contents_type.zdoctype.zuniversalclassispresent := ZAPS^VAL^PRESENT;
928
contents_type.zdoctype.zuniversalclass := ZFTM^VAL^UC^GRAPHIC^STRING;
929
contents_type.zdoctype.zmaxstringlenispresent := ZAPS^VAL^PRESENT;
930
contents_type.zdoctype.zmaxstringlen := $dbl (MAX_READ_COUNT);
931
contents_type.zdoctype.zstringsigispresent := ZAPS^VAL^PRESENT;
932
contents_type.zdoctype.zstringsig := ZFTM^VAL^STRINGSIG^NOTSIG;
933
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -79
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
934
!------------------------------------------------------------------!
935
! Set the remaining contents_type.zdoctype elements to
!
936
! ZAPS^VAL^ABSENT.
!
937
!------------------------------------------------------------------!
938
contents_type.zdoctype.zfileattrsispresent := ZAPS^VAL^ABSENT;
939
940
END
941
ELSE
942
BEGIN
943
tempbuf ':=' "Contents type unavailable for the association"
944
-> @text_ptr;
945
text_len := @text_ptr - @tempbuf;
946
CALL WRITE ( termnum, outbuf, text_len );
947
948
action_result := ZFTM^VAL^ACTION^FAILURE;
949
950
status := FTM_U_ABORT_REQ_ ( cepi
951
, action_result
952
, ! diagnostics !
953
, $dbl (ABORT_TAG) );
954
955
!-------------------------------------------------------------------!
956
! If the above abort request is sent to remote system, then
!
957
! calling the main procedure sets the remote_file_update_cmplt
!
958
! flag, and the program is terminated. If the request is not
!
959
! sent out, set the flag here and return to the main procedure.
!
960
!-------------------------------------------------------------------!
961
962
IF status <> ZAPS^VAL^STATUS^OK THEN
963
BEGIN
964
remote_file_update_cmplt := TRUE;
965
END;
966
RETURN;
967
END;
968
969
970
!--------------------------------------------------------------------!
971
! The following sections initialize the parameters for the
!
972
! FTM_FILE_OPEN_REQ_ procedure.
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -80
NonStop FTAM Programming Examples
973
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
!--------------------------------------------------------------------!
974
975
!--------------------------------------------------------------------!
976
! Initialize the remote-file-name parameter. The remote-file-name
!
977
! format is dependent on the remote system.
!
978
!--------------------------------------------------------------------!
979
980
remote_file.zlen := $occurs(remote_file_name);
981
remote_file.zb ':=' remote_file_name FOR remote_file.zlen BYTES;
982
983
!--------------------------------------------------------------------!
984
! If the remote file exists, it is selected and opened. If the file
!
985
! does not exist, the file-open request fails.
!
986
!--------------------------------------------------------------------!
987
988
file_status := ZFTM^VAL^FOPEN^OLD;
989
990
!--------------------------------------------------------------------!
991
! Set up the following remote file-access parameter required for
!
992
! this application: insert.
!
993
!--------------------------------------------------------------------!
994
995
requested_access.zread := ZAPS^VAL^FALSE;
996
requested_access.zinsert := ZAPS^VAL^TRUE;
997
requested_access.zreplace := ZAPS^VAL^FALSE;
998
requested_access.zextend := ZAPS^VAL^FALSE;
999
requested_access.zerase := ZAPS^VAL^FALSE;
1000
requested_access.zreadattr := ZAPS^VAL^FALSE;
1001
requested_access.zchngattr := ZAPS^VAL^FALSE;
1002
requested_access.zdelete := ZAPS^VAL^FALSE;
1003
1004
!--------------------------------------------------------------------!
1005
! Set up the following remote file process-mode parameter required
!
1006
! for this application: insert.
!
1007
!--------------------------------------------------------------------!
1008
1009
process_mode.zread := ZAPS^VAL^FALSE;
1010
process_mode.zinsert := ZAPS^VAL^TRUE;
1011
process_mode.zreplace := ZAPS^VAL^FALSE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -81
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1012
process_mode.zextend := ZAPS^VAL^FALSE;
1013
process_mode.zerase := ZAPS^VAL^FALSE;
1014
1015
!--------------------------------------------------------------------!
1016
! Issue the file-open request.
1017
!--------------------------------------------------------------------!
!
1018
1019
status := FTM_FILE_OPEN_REQ_ ( cepi
1020
, remote_file
1021
, file_status
1022
, requested_access
1023
, ! access_passwords !
1024
, ! initial_attr !
1025
, ! create_password !
1026
, process_mode
1027
, contents_type
1028
, ! account !
1029
, $dbl (FILEOPEN_TAG) );
1030
1031
CALL check_status;
1032
1033 END; --- init_cnf_open_req --1034
1035
1036
1037 ?PAGE "subproc OPEN_CNF_WRITE_REQ"
1038 !---------------------------------------------------------------------!
1039 !
!
1040 ! Name:
open_cnf_write_req
!
1041 !
!
1042 ! Description: This subprocedure is called when a file-open
!
1043 !
confirm is received. It calls FTM_FILE_OPEN_CNF_
!
1044 !
and checks the error status and state result. It
!
1045 !
then calls FTM_WRITE_REQ and returns to the calling
!
1046 !
routine.
!
1047 !
!
1048 ! Input:
File-select/open confirm
1049 !
!
!
1050 ! Output:
Write request sent to remote responder
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -82
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1051 !
!
1052 !---------------------------------------------------------------------!
1053
1054
SUBPROC open_cnf_write_req;
1055
1056
BEGIN
1057
1058
!------------------------------------------------------------------!
1059
! Retrieve the file-open confirm data.
1060
!------------------------------------------------------------------!
!
1061
1062
error := FTM_FILE_OPEN_CNF_ ( cepi
1063
, state_result
1064
, action_result
1065
, remote_file
1066
, ! initial_attr !
1067
, contents_type
1068
, diag );
1069
1070
CALL check_error;
1071
1072
!------------------------------------------------------------------!
1073
! Check the state result and the action result.
1074
!------------------------------------------------------------------!
!
1075
1076
CALL check_action_diag;
1077
IF ( state_result = ZFTM^VAL^STATE^FAILURE ) THEN
1078
BEGIN
1079
1080
CALL bad_state;
END;
1081
1082
!------------------------------------------------------------------!
1083
! Send a write-request primitive to the remote responder to
!
1084
! establish the data-transfer regime. Set up the required
!
1085
! parameters and call FTM_WRITE_REQ_.
!
1086
!------------------------------------------------------------------!
1087
1088
!------------------------------------------------------------------!
1089
! Use the insert operation to insert records in an FTAM-2 file.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -83
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1090
!------------------------------------------------------------------!
1091
1092
fadu_op := ZFTM^VAL^FADU^OP^INSERT;
1093
1094
!-----------------------------------------------------------------!
1095
! Specify the target FADU identity. Records can be inserted
!
1096
! only at the end of an FTAM-2 file.
!
1097
!-----------------------------------------------------------------!
1098
1099
fadu_id.zid := ZFTM^VAL^FADUID^BEGINEND;
1100
fadu_id.zbeginend := ZFTM^VAL^FADUID^END;
1101
1102
!-----------------------------------------------------------------!
1103
! Issue the write-request primitive.
1104
!-----------------------------------------------------------------!
!
1105
1106
status := FTM_WRITE_REQ_ ( cepi
1107
, fadu_op
1108
, fadu_id
1109
, $dbl (WRITE_TAG) );
1110
1111
CALL check_status;
1112
1113
END; --- open_cnf_write_req ---
1114
1115
1116
?PAGE "subproc TRANSEND_CNF_CLOSE_REQ"
1117
!--------------------------------------------------------------------!
1118
!
1119
! Name:
1120
!
!
1121
! Description: This subprocedure is called when a transfer-end
!
1122
!
confirm is received. It calls FTM_TRANSFER_END_CNF_
!
1123
!
and checks the error status and state result. It
!
1124
!
then calls FTM_FILE_CLOSE_REQ_ and returns to the
!
1125
!
calling routine.
!
1126
!
1127
! Input:
1128
!
!
transend_cnf_close_req
!
!
Transfer-end confirm
!
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -84
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1129
! Output:
File-deselect/close request to remote responder
!
1130
!
1131
!--------------------------------------------------------------------!
!
1132
1133
SUBPROC transend_cnf_close_req;
1134
1135
BEGIN
1136
1137
!-----------------------------------------------------------------!
1138
! Retrieve the transfer-end confirm data.
1139
!-----------------------------------------------------------------!
!
1140
1141
error := FTM_TRANSFER_END_CNF_ ( cepi
1142
, action_result
1143
, diag );
1144
1145
CALL check_error;
1146
1147
!-----------------------------------------------------------------!
1148
! Check the action result and display any diagnostic messages.
1149
!-----------------------------------------------------------------!
!
1150
1151
CALL check_action_diag;
1152
1153
!-----------------------------------------------------------------!
1154
! The transfer is now complete. Deselect and close the remote
!
1155
! file. The delete-action parameter specifies closing the file
!
1156
! without deleting it. The FTM_FILE_CLOSE_REQ_ handles both
!
1157
! deselecting and closing the file.
!
1158
!-----------------------------------------------------------------!
1159
1160
delete_action := ZFTM^VAL^CLOSE^NODELETE;
1161
1162
status := FTM_FILE_CLOSE_REQ_ ( cepi
1163
, delete_action
1164
, $dbl (FILECLOSE_TAG) );
1165
1166
CALL check_status;
1167
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -85
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1168
END; --- transend_cnf_close_req ---
1169
1170
1171
1172
?PAGE "subproc CLOSE_CNF_TERMINATE_REQ"
1173
!--------------------------------------------------------------------!
1174
!
1175
! Name:
1176
!
!
1177
! Description: This subprocedure is called when a file-close
!
1178
!
confirm is received. It calls FTM_FILE_CLOSE_CNF_
!
1179
!
and checks the error status and state result. It
!
1180
!
then calls FTM_TERMINATE_REQ_ and returns to the
!
1181
!
calling routine.
!
1182
!
1183
! Input:
1184
!
1185
! Output:
1186
!
1187
!--------------------------------------------------------------------!
!
close_cnf_terminate_req
!
!
File-deselect/close confirm
!
!
Association-termination request to remote responder
!
!
1188
1189
SUBPROC close_cnf_terminate_req;
1190
1191
BEGIN
1192
1193
!-----------------------------------------------------------------!
1194
! Retrieve the file-close confirm data.
1195
!-----------------------------------------------------------------!
!
1196
1197
error := FTM_FILE_CLOSE_CNF_ ( cepi
1198
, action_result
1199
, diag );
1200
1201
CALL check_error;
1202
1203
!-----------------------------------------------------------------!
1204
! Check the action result and display any diagnostic messages.
1205
-!
!-------------------------------------------------------------------
1206
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -86
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1207
CALL check_action_diag;
1208
1209
!-------------------------------------------------------------------!
1210
! The file has been closed. The association can be terminated.
1211
!-------------------------------------------------------------------!
!
1212
1213
status := FTM_TERMINATE_REQ_ ( cepi
1214
, $dbl (TERMINATE_TAG) );
1215
1216
CALL check_status;
1217
1218
END; --- close_cnf_terminate_req ---
1219
1220
?PAGE "Continue proc FTAM_EVENT_RCVD"
1221
1222
!--------------------------------------------------------------------!
1223
! MAIN BODY of ftam_event_rcvd procedure
1224
!--------------------------------------------------------------------!
!
1225
1226
!-----------------------------------------------------------------!
1227
! An event-receive call is completed. Retrieve the event code
!
1228
! from APS.
!
1229
!-----------------------------------------------------------------!
1230
1231
error := APS_STATUS_ ( cepi
1232
, event_code );
1233
1234
CALL check_error;
1235
1236
!-----------------------------------------------------------------!
1237
! Process the event that was received.
1238
!-----------------------------------------------------------------!
1239
1240
CASE event_code OF
1241
BEGIN
1242
1243
ZFTM^VAL^EVT^INITIALIZE^CNF ->
CALL init_cnf_open_req;
1244
1245
ZFTM^VAL^EVT^FILEOPEN^CNF ->
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -87
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1246
CALL open_cnf_write_req;
1247
1248
1249
ZFTM^VAL^EVT^TRANSEND^CNF ->
CALL transend_cnf_close_req;
1250
1251
1252
ZFTM^VAL^EVT^FILECLOSE^CNF ->
CALL close_cnf_terminate_req;
1253
1254
ZFTM^VAL^EVT^TERMINATE^CNF ->
1255
1256
!------------------------------------------------------------!
1257
! Retrieve the terminate-confirm data. The charging
!
1258
! parameter conveys information related to the cost charged
!
1259
! to the account. This parameter is present only if the
!
1260
! account parameter was provided by the FTM_INITIALIZE_REQ_
!
1261
! procedure call. Set the flags to indicate that the file
!
1262
! update completed successfully.
!
1263
!------------------------------------------------------------!
1264
1265
error := FTM_TERMINATE_CNF_ ( cepi
1266
, !charging! );
1267
1268
CALL check_error;
1269
1270
remote_file_update_cmplt := TRUE;
1271
file_update_failed := FALSE;
1272
1273
ZFTM^VAL^EVT^PABORT^IND ->
1274
1275
!------------------------------------------------------------!
1276
! Retrieve the provider-abort indication data. Check the
!
277
! action result and display any diagnostic messages. Then
!
1278
! set the flag to indicate that the file update is complete. !
1279
!------------------------------------------------------------!
1280
1281
error := FTM_P_ABORT_IND_ ( cepi
1282
, action_result
1283
, diag );
1284
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -88
NonStop FTAM Programming Examples
1285
CALL check_error;
1286
CALL check_action_diag;
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1287
1288
tempbuf ':=' "The association has been aborted" -> @text_ptr;
1289
text_len := @text_ptr - @tempbuf;
1290
CALL WRITE ( termnum, outbuf, text_len );
1291
1292
remote_file_update_cmplt := TRUE;
1293
1294
ZFTM^VAL^EVT^UABORT^IND ->
1295
1296
!------------------------------------------------------------!
1297
! Retrieve the user-abort indication data. Check the action
!
1298
! result and display any diagnostic messages. Then set the
!
1299
! flag to indicate that the file update is complete.
!
1300
!------------------------------------------------------------!
1301
1302
error := FTM_U_ABORT_IND_ ( cepi
1303
, action_result
1304
, diag );
1305
1306
CALL check_error;
1307
CALL check_action_diag;
1308
1309
tempbuf ':=' "The association has been aborted" -> @text_ptr;
1310
text_len := @text_ptr - @tempbuf;
1311
CALL WRITE ( termnum, outbuf, text_len );
1312
1313
remote_file_update_cmplt := TRUE;
1314
1315
ZFTM^VAL^EVT^CANCEL^IND ->
1316
1317
!------------------------------------------------------------!
1318
! The remote system has cancelled the transfer. Call
!
1319
! CANCEL_IND_ to get the action result and diagnostics and
!
1320
! CANCEL_RSP_ to acknowledge the indication from the remote
!
1321
! system. This terminates the data-transfer regime.
!
1322
!------------------------------------------------------------!
1323
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -89
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1324
error := FTM_CANCEL_IND_ ( cepi
1325
, action_result
1326
, diag );
1327
1328
CALL check_error;
1329
CALL check_action_diag;
1330
1331
tempbuf ':=' "The data transfer has been cancelled" -> @text_ptr;
1332
text_len := @text_ptr - @tempbuf;
1333
CALL WRITE ( termnum, outbuf, text_len );
1334
1335
status := FTM_CANCEL_RSP_ ( cepi
1336
, ! action_result !
1337
, ! diag ! );
1338
1339
CALL check_status;
1340
1341
remote_file_update_cmplt := TRUE;
1342
1343
OTHERWISE -> ! Unknown event !
1344
1345
tempbuf ':=' "Invalid Event" -> @text_ptr;
1346
text_len := @text_ptr - @tempbuf;
1347
CALL WRITE ( termnum, outbuf, text_len );
1348
CALL APS_DISCARD_ ( cepi );
1349
CALL ABEND;
1350
1351
END;
1352
1353
!------------------------------------------------------------------!
1354
! If the file update is not complete, issue another
!
1355
! APS_EVENT_RECEIVE_ to receive the next event.
!
1356
!------------------------------------------------------------------!
1357
1358
IF ( remote_file_update_cmplt = FALSE ) THEN
1359
BEGIN
1360
status := APS_EVENT_RECEIVE_ ( cepi
1361
, ! WAIT_FOREVER !
1362
, $dbl (EVENTREC_TAG) );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -90
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1363
1364
CALL check_status;
1365
END;
1366
1367
END; --- ftam_event_rcvd ---
1368
1369
1370
?PAGE "proc DATA_TRANSFER"
1371
!--------------------------------------------------------------------!
1372
!
1373
! Name:
1374
!
!
1375
! Description: This procedure is called when a Guardian read or
!
1376
!
FTM data request completes. It determines whether
!
1377
!
another data request can be sent to the remote file,
!
1378
!
or the data must be held until the I/O completion
!
1379
!
for the previous call to FTM_DATA_REQ_ or the
!
1380
!
Guardian read request is received.
!
1381
!
1382
! Input:
1383
!
1384
! Output:
1385
!
1386
!--------------------------------------------------------------------!
!
data_transfer
!
!
None
!
!
File records being sent to remote responder
!
!
1387
1388
PROC data_transfer;
1389
1390
BEGIN
1391
1392
!----------------------------------------------------------------!
1393
! When all records have been sent and there are no outstanding
!
1394
! I/O operations, notify the remote system that all data has
!
1395
! been sent.
!
1396
!----------------------------------------------------------------!
1397
1398
IF ( records = MAX_RECORDS AND remote_io_cmplt ) THEN
1399
BEGIN
1400
!--------------------------------------------------------------!
1401
! Issue the data-end primitive.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -91
!
NonStop FTAM Programming Examples
1402
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
!--------------------------------------------------------------!
1403
1404
status := FTM_DATA_END_REQ_ ( cepi
1405
, ! action_result !
1406
, ! diag !
1407
, $dbl (DATAEND_TAG) );
1408
1409
CALL check_status;
1410
RETURN;
1411
END;
1412
1413
!----------------------------------------------------------------!
1414
! Once both the local read from the file system and the previous !
1415
! FTM data request have completed, issue the next data request.
1416
!----------------------------------------------------------------!
!
1417
1418
IF ( remote_io_cmplt AND local_read_io_cmplt ) THEN
1419
BEGIN
1420
!--------------------------------------------------------------!
1421
! The following sections initialize the data buffer
!
1422
! that contains the data to be transferred to the remote
!
1423
! system. The buffer contains a data header, a data-element
!
1424
! header, and the data to be transferred.
!
1425
!--------------------------------------------------------------!
1426
1427
!--------------------------------------------------------------!
1428
! Initialize a pointer to the data header. Then set the number !
1429
! of data elements that follow. Only a single data element is
!
1430
! used in this example.
!
1431
!--------------------------------------------------------------!
1432
1433
@data_hdr_ptr := @remote_buffer;
1434
data_hdr_ptr.znum^elements := 1;
1435
1436
!--------------------------------------------------------------!
1437
!Initialize a pointer to the data-element header. Then set the !
1438
! length of the data to be transferred and the type of data to !
1439
! be transferred. The data length is returned from the local
1440
!file-system read. The data type is set to text in this example.!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -92
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1441
!--------------------------------------------------------------!
1442
1443
@element_hdr_ptr := @data_hdr_ptr + $udbl ($len (data_hdr_ptr));
1444
element_hdr_ptr.zlen := $dbl ( buf_count_transferred );
1445
element_hdr_ptr.ztype := ZFTM^VAL^DE^TEXT;
1446
1447
!--------------------------------------------------------------!
1448
! Initialize a pointer to the data portion of the buffer
!
1449
! that follows the data header and data-element header. Copy
!
1450
! the data from the local read buffer into the data buffer.
!
1451
!--------------------------------------------------------------!
1452
1453
@data_ptr := @element_hdr_ptr + $udbl ($len (element_hdr_ptr));
1454
data_ptr ':=' local_buffer FOR buf_count_transferred BYTES;
1455
1456
!--------------------------------------------------------------!
1457
! Issue the data-request primitive.
1458
!--------------------------------------------------------------!
!
1459
1460
status := FTM_DATA_REQ_ ( cepi
1461
, remote_buffer
1462
, $dbl (DATA_TAG) );
1463
1464
CALL check_status;
1465
1466
!--------------------------------------------------------------!
1467
! Indicate that an FTM data request is in progress.
1468
!--------------------------------------------------------------!
!
1469
1470
remote_io_cmplt := FALSE;
1471
1472
!--------------------------------------------------------------!
1473
! Update the number of records that have been read. If
!
1474
! the maximum number of records has been read, then return to
!
1475
! the main control loop and wait for an I/O operation or an
!
1476
! FTAM event to complete; otherwise, read another record
!
1477
! from the local Guardian file.
!
1478
!---------------------------------------------------------------!
1479
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -93
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1480
records := records + 1;
1481
IF ( records < MAX_RECORDS ) THEN
1482
BEGIN
1483
!------------------------------------------------------------!
1484
! Read the next record from the file.
1485
!------------------------------------------------------------!
!
1486
1487
CALL READX ( local_filenum
1488
, local_buffer
1489
, MAX_READ_COUNT
1490
, ! count_read - waited I/O only !
1491
, $dbl (READ_TAG) );
1492
IF <> THEN
1493
BEGIN
1494
CALL FILEINFO ( local_filenum, file_error );
1495
tempbuf ':=' "Local file error " -> @text_ptr;
1496
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1497
, $DBL ( file_error )
1498
, BASE );
1499
text_len := @text_ptr - @tempbuf;
1500
CALL WRITE ( termnum, outbuf, text_len );
1501
CALL APS_DISCARD_ ( cepi );
1502
CALL STOP;
1503
END;
1504
1505
!------------------------------------------------------------!
1506
! Indicate that a local file read is in progress.
1507
!------------------------------------------------------------!
1508
1509
local_read_io_cmplt := FALSE;
1510
1511
END;
1512
1513
END;
1514
1515
END; --- data_transfer ---
1516
1517
1518
?PAGE "proc CHECK_STATUS"
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -94
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1519
!--------------------------------------------------------------------!
1520
!
1521
! Name:
1522
!
!
1523
! Description: The following procedure checks status returned from
!
1524
!
a previous FTAM procedure call. It checks for
!
1525
!
NORETRY, RETRYLATER, or DISCARD. If status is OK,
!
1526
!
it returns to the main program; otherwise, it
!
1527
!
displays a message and aborts or discards the
!
1528
!
association.
!
1529
!
1530
! Input:
1531
!
1532
! Output:
1533
!
1534
!--------------------------------------------------------------------!
!
check_status
!
!
None
!
!
Error message to the terminal
!
!
1535
1536
PROC check_status;
1537
1538
BEGIN
1539
1540
!----------------------------------------------------------------!
1541
! Check for a valid status.
1542
!----------------------------------------------------------------!
!
1543
1544
IF ( status = ZAPS^VAL^STATUS^OK ) THEN
1545
BEGIN
1546
1547
RETURN;
END;
1548
1549
!----------------------------------------------------------------!
1550
! Get the error-code and error-subcode values if the status is
!
1551
! not OK.
!
1552
!----------------------------------------------------------------!
1553
1554
error := APS_STATUS_ ( cepi
1555
, ! event_code !
1556
, ! device_name !
1557
, error_code
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -95
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1558
, error_subcode
1559
, ! service_id !
1560
, ! diagnostic_buffer !
1561
, original_error_info );
1562
1563
CALL check_error;
1564
1565
!----------------------------------------------------------------!
1566
! Display the status code.
1567
!----------------------------------------------------------------!
!
1568
1569
tempbuf ':=' "STATUS # " -> @text_ptr;
1570
IF (status < 0) THEN
1571
BEGIN
1572
status := -status;
1573
text_ptr ':=' "-" -> @text_ptr;
1574
END;
1575
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1576
, $DBL ( status )
1577
, BASE );
1578
text_len := @text_ptr - @tempbuf;
1579
CALL WRITE ( termnum, outbuf, text_len );
1580
1581
!----------------------------------------------------------------!
1582
! Display the error code and subcode.
1583
!----------------------------------------------------------------!
1584
1585
tempbuf ':=' "ERROR CODE # " -> @text_ptr;
1586
IF ( error_code < 0) THEN
1587
BEGIN
1588
error_code := -error_code;
1589
text_ptr ':=' "-" -> @text_ptr;
1590
END;
1591
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1592
, $DBL ( error_code )
1593
, BASE );
1594
text_len := @text_ptr - @tempbuf;
1595
CALL WRITE ( termnum, outbuf, text_len );
1596
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -96
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1597
tempbuf ':=' "ERROR SUBCODE # " -> @text_ptr;
1598
IF (error_subcode < 0) THEN
1599
BEGIN
1600
error_subcode := -error_subcode;
1601
text_ptr ':=' "-" -> @text_ptr;
1602
END;
1603
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1604
, $DBL ( error_subcode )
1605
, BASE );
1606
text_len := @text_ptr - @tempbuf;
1607
CALL WRITE ( termnum, outbuf, text_len );
1608
1609
!----------------------------------------------------------------!
1610
! Display the original error code and original error subcode.
1611
!----------------------------------------------------------------!
!
1612
1613
tempbuf ':=' "ORIGINAL ERROR INFO - " -> @text_ptr;
1614
text_len := @text_ptr - @tempbuf;
1615
CALL WRITE ( termnum, outbuf, text_len );
1616
1617
tempbuf ':=' " SERVICE ID # " -> @text_ptr;
1618
@text_ptr := @text_ptr
1619
+ DNUMOUT ( text_ptr
1620
, $DBL ( original_error_info.zerror.zservice^id )
1621
, BASE );
1622
text_len := @text_ptr - @tempbuf;
1623
CALL WRITE ( termnum, outbuf, text_len );
1624
1625
tempbuf ':=' " ERROR CODE # " -> @text_ptr;
1626
IF ( original_error_info.zerror.zerror^code < 0) THEN
1627
BEGIN
1628
original_error_info.zerror.zerror^code
1629
1630
:= -original_error_info.zerror.zerror^code;
text_ptr ':=' "-" -> @text_ptr;
1631
END;
1632
@text_ptr := @text_ptr
1633
+ DNUMOUT ( text_ptr
1634
, $DBL ( original_error_info.zerror.zerror^code )
1635
, BASE );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -97
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1636
text_len := @text_ptr - @tempbuf;
1637
CALL WRITE ( termnum, outbuf, text_len );
1638
1639
tempbuf ':=' " ERROR SUBCODE # " -> @text_ptr;
1640
IF ( original_error_info.zerror.zerror^subcode < 0) THEN
1641
BEGIN
1642
original_error_info.zerror.zerror^subcode
1643
1644
:= -original_error_info.zerror.zerror^subcode;
text_ptr ':=' "-" -> @text_ptr;
1645
END;
1646
@text_ptr := @text_ptr
1647
+ DNUMOUT ( text_ptr
1648
, $DBL ( original_error_info.zerror.zerror^subcode )
1649
, BASE );
1650
text_len := @text_ptr - @tempbuf;
1651
CALL WRITE ( termnum, outbuf, text_len );
1652
1653
1654
IF ( cepi = NOCEPI ) THEN
return;
1655
1656
!----------------------------------------------------------------!
1657
! Perform error handling, depending on the status value returned.
1658
! Additional application-specific error handling or recovery
!
1659
! could be implemented depending on application requirements.
!
1660
!----------------------------------------------------------------!
1661
1662
CASE status OF
1663
BEGIN
1664
1665
ZAPS^VAL^STATUS^NO^RETRY,
1666
ZAPS^VAL^STATUS^RETRY^LATER ->
1667
1668
!--------------------------------------------------------------!
1669
! The nowait I/O completion indicates an error was detected
!
1670
! and the association should be aborted. If an abort request
!
1671
! is in progress, do not issue another abort request.
!
1672
!--------------------------------------------------------------!
1673
1674
IF (tag <> $dbl (ABORT_TAG)) THEN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -98
NonStop FTAM Programming Examples
1675
1676
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
BEGIN
status := FTM_U_ABORT_REQ_ ( cepi
1677
, ! action_result !
1678
, ! diag !
1679
, $dbl (ABORT_TAG) );
1680
1681
!------------------------------------------------------------!
1682
! If the above abort request is sent to the remote system,
1683
!
! calling the main procedure sets the remote_file_update_cmplt flag,!
1684
! and the program is terminated. If the request is not sent
!
1685
! out, set the flag here and return to the main procedure.
!
1686
!------------------------------------------------------------!
1687
1688
IF ( status <> ZAPS^VAL^STATUS^OK ) THEN
1689
BEGIN
1690
1691
remote_file_update_cmplt := TRUE;
END;
1692
1693
tempbuf ':=' "The association has been aborted" -> @text_ptr;
1694
text_len := @text_ptr - @tempbuf;
1695
CALL WRITE ( termnum, outbuf, text_len );
1696
END;
1697
1698
1699
ZAPS^VAL^STATUS^DISCARD ->
1700
!--------------------------------------------------------------!
1701
! The operation failed because the association was lost.
!
1702
! Indicate that the file update completed with a failure.
!
1703
! The API context information for the association is discarded !
1704
! in the main processing loop for this application.
1705
!--------------------------------------------------------------!
1706
1707
remote_file_update_cmplt := TRUE;
1708
1709
OTHERWISE -> ! Unknown status value !
1710
1711
tempbuf ':=' "Unknown Status" -> @text_ptr;
1712
text_len := @text_ptr - @tempbuf;
1713
CALL WRITE ( termnum, outbuf, text_len );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -99
!
NonStop FTAM Programming Examples
1714
CALL APS_DISCARD_ ( cepi );
1715
CALL ABEND;
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1716
1717
END;
1718
1719
END; --- check_status ---
1720
1721
1722
?PAGE "proc CHECK_ERROR"
1723
!--------------------------------------------------------------------!
1724
!
1725
! Name:
1726
!
!
1727
! Description: The following procedure checks the error code
!
1728
!
returned from an FTM or APS procedure. If it
!
1729
!
detects an error, the procedure displays the error
!
1730
!
code, discards the association, and the program
!
1731
!
exits. Additional application-specific error
!
1732
!
handling or recovery could be implemented if
!
1733
!
required by an application.
!
1734
!
1735
! Input:
1736
!
1737
! Output:
1738
!
1739
!--------------------------------------------------------------------!
!
check_error
!
!
None
!
!
Error message to the terminal
!
!
1740
1741
PROC check_error;
1742
1743
BEGIN
1744
1745
!------------------------------------------------------------------!
1746
! Check for an error condition and display the error code.
1747
!------------------------------------------------------------------!
!
1748
1749
IF ( error <> ZAPS^ERR^OK ) THEN
1750
BEGIN
1751
!-----------------------------------------------------------------!
1752
! Display the error code.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 100
!
NonStop FTAM Programming Examples
1753
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
!-----------------------------------------------------------------!
1754
1755
tempbuf ':=' "ERROR # " -> @text_ptr;
1756
IF (error_code < 0) THEN
1757
BEGIN
1758
error_code := -error_code;
1759
text_ptr ':=' "-" -> @text_ptr;
1760
END;
1761
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1762
, $DBL ( error_code )
1763
, BASE );
1764
text_len := @text_ptr - @tempbuf;
1765
CALL WRITE ( termnum, outbuf, text_len);
1766
1767
tempbuf ':=' "The association has been aborted" -> @text_ptr;
1768
text_len := @text_ptr - @tempbuf;
1769
CALL WRITE ( termnum, outbuf, text_len );
1770
1771
!-----------------------------------------------------------------!
1772
! Discard the API context information for the association
!
1773
! and exit normally.
!
1774
!-----------------------------------------------------------------!
1775
1776
CALL APS_DISCARD_ ( cepi );
1777
CALL STOP;
1778
1779
END;
1780
1781
END; --- check_error ---
1782
1783
1784
?PAGE "proc CHECK_ACTION_DIAG"
1785
!--------------------------------------------------------------------!
1786
!
1787
! Name:
1788
!
!
1789
! Description: The following procedure determines whether the
!
1790
!
action requested of a remote responder was successful !
1791
!
or not. If not, the procedure displays the
!
check_action_diag
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 101
!
!
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1792
!
diagnostic message and error ID for each diagnostic
!
1793
!
message element, discards the association, and the
!
1794 !
program exits normally. Additional application-
!
1795 !
specific error handling or recovery could be
!
1796 !
implemented if required by an application.
!
1797 !
!
1798 ! Input:
None
!
1799 !
!
1800 ! Output:
Error messages to the terminal
1801 !
!
!
1802 !---------------------------------------------------------------------!
1803
1804
PROC check_action_diag;
1805
1806
BEGIN
1807
1808
INT i; ! index into diagnostic array !
1809
1810
!----------------------------------------------------------------!
1811
! Check the action result for failure and display diagnostic
!
1812
! messages.
!
1813
!----------------------------------------------------------------!
1814
1815
IF ( action_result = ZFTM^VAL^ACTION^FAILURE ) THEN
1816
BEGIN
1817
!--------------------------------------------------------------!
1818
! Display the number of diagnostic messages received.
1819
!--------------------------------------------------------------!
!
1820
1821
tempbuf ':=' "Following is a list of " -> @text_ptr;
1822
text_len := @text_ptr - @tempbuf;
1823
width := DNUMOUT ( tempbuf[text_len]
1824
, $DBL ( diag.zdiagcount )
1825
, BASE );
1826
tempbuf[text_len + width] ':=' " diagnostic elements -" -> @text_ptr;
1827
text_len := @text_ptr - @tempbuf;
1828
CALL WRITE ( termnum, outbuf, text_len );
1829
1830
!--------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 102
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1831
! Display the diagnostic message type and error ID for each
!
1832
! diagnostic message.
!
1833
!--------------------------------------------------------------!
1834
1835
FOR i := 0 TO diag.zdiagcount-1 DO
1836
BEGIN
1837
tempbuf ':=' " Diagnostic Type: " -> @text_ptr;
1838
text_len := @text_ptr - @tempbuf;
1839
width := DNUMOUT ( tempbuf[text_len]
1840
, $DBL ( diag.zdiagelems[i].zdiagtype )
1841
, BASE );
1842
text_len := text_len + width;
1843
CALL WRITE ( termnum, outbuf, text_len );
1844
1845
tempbuf ':=' " Error ID: " -> @text_ptr;
1846
text_len := @text_ptr - @tempbuf;
1847
width := DNUMOUT ( tempbuf[text_len]
1848
, $DBL ( diag.zdiagelems[i].zerrorid )
1849
, BASE );
1850
text_len := text_len + width;
1851
CALL WRITE ( termnum, outbuf, text_len );
1852
1853
IF ( diag.zdiagelems[i].zfurtherdetailsispresent = ZAPS^VAL^PRESENT )
1854
THEN
1855
BEGIN
1856
tempbuf ':=' " Details: " -> @text_ptr;
1857
text_len := @text_ptr - @tempbuf;
1858
tempbuf[text_len] ':=' diag.zdiagelems[i].zfurtherdetails.zb
1859
FOR diag.zdiagelems[i].zfurtherdetails.zlen BYTES;
1860
text_len := text_len + diag.zdiagelems[i].zfurtherdetails.zlen;
1861
1862
1863
CALL WRITE ( termnum, outbuf, text_len );
END;
END;
1864
1865
!--------------------------------------------------------------!
1866
! Discard the API context information for the association
!
1867
! and exit normally.
!
1868
!--------------------------------------------------------------!
1869
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 103
NonStop FTAM Programming Examples
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
1870
CALL APS_DISCARD_ ( cepi );
1871
tempbuf ':=' "Association discarded" -> @text_ptr;
1872
text_len := @text_ptr - @tempbuf;
1873
CALL WRITE ( termnum, outbuf, text_len );
1874
CALL STOP;
1875
1876
END;
1877
1878
END; --- check_action_diag ---
1879
1880
1881 ?PAGE "proc BAD_STATE"
1882 !---------------------------------------------------------------------!
1883 !
!
1884 ! Name:
bad_state
!
1885 !
!
1886 ! Description: The following procedure is called when an FTM
!
1887 !
confirm procedure returns a bad state result. The
!
1888 !
procedure displays an error message, discards the
!
1889 !
association, and abends the program. Additional
!
1890 !
application-specific error handling or recovery
!
1891 !
could be implemented, depending on application
!
1892 !
requirements.
!
1893 !
!
1894 ! Input:
None
1895 !
!
!
1896 ! Output:
Error message to terminal
1897 !
!
!
1898 !---------------------------------------------------------------------!
1899
1900
PROC bad_state;
1901
1902
BEGIN
1903
1904
!-----------------------------------------------------------------!
1905
! Display the invalid state-result error message. You might also
!
1906
! want to print out the diagnostic field to obtain more
!
1907
! information about the error condition.
!
1908
!-----------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 104
Example 1 in TAL—Updating a Remote File (in
Nowait Mode)
NonStop FTAM Programming Examples
1909
1910
tempbuf ':=' "BAD STATE # " -> @text_ptr;
1911
text_len := @text_ptr - @tempbuf;
1912
width := DNUMOUT ( tempbuf[text_len]
1913
, $DBL ( state_result )
1914
, BASE );
1915
tempbuf[text_len + width] ':=' " Association aborted" -> @text_ptr;
1916
text_len := @text_ptr - @tempbuf;
1917
CALL WRITE ( termnum, outbuf, text_len );
1918
1919
!-----------------------------------------------------------------!
1920
! Discard the API context information for the association
!
1921
! and abend the program.
!
1922
!-----------------------------------------------------------------!
1923
1924
CALL APS_DISCARD_ ( cepi );
1925
CALL ABEND;
1926
1927
END; -- bad_state --
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 105
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1 /*************************************************************************/
2 /*
*/
3 /* Example 2 in C - Moving an FTAM-3 File Between Two Remote Systems
*/
4 /* (in Wait Mode)
*/
5 /*
*/
6 /************************************************************************/
7 /*
*/
8 /* Program Name: EXCMOVF3
*/
9 /*
*/
10 /* Program Description:
*/
11 /*
*/
12 /* This program, in wait mode, moves an FTAM-3 file between two re-
*/
13 /* mote systems on an OSI network. The application initiates and
*/
14 /* manages the file transfer. It issues requests and receives
*/
15 /* indications and confirms from the two remote systems and acts on
*/
16 /* them accordingly. At the end of file transfer, the source file is
*/
17 /* deleted.
*/
18 /*
*/
19 /* The main procedure contains all of the code for establishing the
*/
20 /* required FTAM protocol regimes, managing the data transfer, and
*/
21 /* normally terminating each regime for both associations.
*/
22 /*
*/
23 /* Apart from the main procedure, there is a procedure to receive FTAM */
24 /* events, a general-purpose procedure used by error-handling
*/
25 /* routines to abort and discard associations, and five error-
*/
26 /* handling procedures that handle different types of errors:
*/
27 /*
*/
28 /*
get_event
A routine called after a request is sent
*/
29 /*
to a remote responder to wait for the
*/
30 /*
respective confirm. It also can
*/
31 /*
receive FTM indications.
*/
32 /*
33 /*
*/
abort_discard
A routine called by the error-handling
*/
34 /*
routines that is used to abort and
*/
35 /*
discard the associations.
*/
36 /*
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 106
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
37 /*
check_status
38 /*
A procedure that checks status returned
*/
by FTM procedure calls.
*/
39 /*
40 /*
*/
check_error
41 /*
A procedure that checks for errors
*/
returned by FTM procedure calls.
*/
42 /*
43 /*
*/
check_state
44 /*
A procedure that handles a failed state
*/
in the remote FTAM regime.
*/
45 /*
46 /*
*/
bad_event
47 /*
A procedure that handles unexpected
*/
FTAM events.
*/
48 /*
*/
49 /* check_action_diag
A routine that checks the action result
*/
50 /*
and diagnostic messages returned by an
*/
51 /*
FTM procedure.
*/
52 /*
*/
53 /* FTM request and response procedures return an I/O status value
*/
54 /* on the procedure call. The check_status procedure checks the
*/
55 /* results of the I/O operation. The FTM indication and confirm
*/
56 /* procedures return an error value indicating the outcome of the
*/
57 /* completed service. The procedure check_error checks the returned
*/
58 /* error code.
*/
59 /*
*/
60 /* This example is provided to illustrate FTAM programming concepts.
*/
61 /* It does not necessarily illustrate the recommended programming
*/
62 /* style for a real application, which might be more modularized to
*/
63 /* provide a higher level of top-down coding, for instance. To en-
*/
64 /* hance the illustration of FTAM programming concepts, this example
*/
65 /* demonstrates programming tasks in sequence, emphasizing a more
*/
66 /* linear approach to coding.
*/
67 /***********************************************************************/
68 /*
*/
69 /* NOTE : Before attempting to run this program, set the following
*/
70 /*
*/
items correctly:
71 /*
*/
72 /*
a) environmental variables
*/
73 /*
b) required parameters for the FTM_INITIALIZE_REQ_ call
*/
74 /*
*/
75 /***********************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 107
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
76
77 #pragma
nolist
78 #include
<stdioh>
79 #include
<stdlibh>
80 #include
<stringh>
81 #include
<talh>
82
83 /***********************************************************************/
84 /* Include
*/
85 /* - APS and FTM structure definitions and literals
*/
86 /* - External function declarations for FTM, APS, and Guardian
*/
87 /***********************************************************************/
88
89
#include
"zapsc"
/* APS DDL
*/
90
#include
"zftmc"
/* FTM DDL
*/
91
#include
"cextdecs
( FTM_INITIALIZE_REQ_
\
92
, FTM_INITIALIZE_CNF_
\
93
, FTM_OPEN_REQ_
\
94
, FTM_OPEN_CNF_
\
95
, FTM_SELECT_REQ_
\
96
, FTM_SELECT_CNF_
\
97
, FTM_DESELECT_REQ_
\
98
, FTM_DESELECT_CNF_
\
99
, FTM_DELETE_REQ_
\
100
, FTM_DELETE_CNF_
\
101
, FTM_CREATE_REQ_
\
102
, FTM_CREATE_CNF_
\
103
, FTM_CLOSE_REQ_
\
104
, FTM_CLOSE_CNF_
\
105
, FTM_BEGIN_GROUP_REQ_
\
106
, FTM_END_GROUP_REQ_
\
107
, FTM_READ_ATTRIB_REQ_
\
108
, FTM_READ_ATTRIB_CNF_
\
109
, FTM_CHANGE_ATTRIB_REQ_ \
110
, FTM_CHANGE_ATTRIB_CNF_ \
111
, FTM_WRITE_REQ_
\
112
, FTM_READ_REQ_
\
113
, FTM_DATA_IND_
\
114
, FTM_DATA_REQ_
\
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 108
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
115
, FTM_DATA_END_REQ_
\
116
, FTM_DATA_END_IND_
\
117
, FTM_TRANSFER_END_REQ_
\
118
, FTM_TRANSFER_END_CNF_
\
119
, FTM_TERMINATE_REQ_
\
120
, FTM_TERMINATE_CNF_
\
121
, FTM_CANCEL_IND_
\
122
, FTM_CANCEL_REQ_
\
123
, FTM_CANCEL_RSP_
\
124
, FTM_CANCEL_CNF_
\
125
, FTM_P_ABORT_IND_
\
126
, FTM_U_ABORT_IND_
\
127
, FTM_U_ABORT_REQ_
\
128
, APS_INITIALIZE_
\
129
, APS_STATUS_
\
130
, APS_EVENT_RECEIVE_
\
131
, APS_DISCARD_ ) "
132 #pragma
list
133
134 /**********************************************************************/
135 /* Global data declarations */
136 /**********************************************************************/
137
138 /**********************************************************************/
139 /* Environment-specific fields
*/
140 /* You will need to change these fields to reflect your FTAM
*/
141 /* environment. src_filename and dst_filename must be valid file
*/
142 /* names for the respective source and remote systems. In this
*/
143 /* example, src-file and dst_file are Guardian files.
*/
144 /**********************************************************************/
145
146 #define
local_appl_name
"APPL1"
147 #define
src_appl_name
"APPL2"
148 #define
dst_appl_name
"APPL3"
149 #define
init_id
"initid"
150 #define
password
"aaa"
151 #define
charge_account
"12345"
152 #define
manager_name
"$APMGR "
153 #define
src_filename
"$VOLUME.SUBVOL.SRCFILE"
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 109
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
154 #define
dst_filename
"$VOLUME.SUBVOL.DSTFILE"
155
156 #define
num_elem
5
157
158 int
ftam_doc_type[num_elem] = {1,0,8571,5,3};
159 int
ap_title[num_elem]
= {1,3,9999,1,7};
160 int
src_ap_title[num_elem]
= {1,3,9999,1,7};
161 int
dst_ap_title[num_elem]
= {1,3,9999,1,7};
162
163 long
ae_qualifier
= 0;
164 long
src_ae_qualifier
= 1;
165 long
dst_ae_qualifier
= 1;
166
167 /**********************************************************************/
168 /* Miscellaneous constants
*/
169 /**********************************************************************/
170 #define
ANYEVENT
171 #define
MAX_BUF
172 #define
NOCEPI
173 #define
WAIT_FOREVER
-1
/* Wait for receipt of any FTAM event */
1000
/* Buffer size used for receiving data*/
-1
-1L
/* Uninitialized or invalid CEPI.
*/
/* Wait indefinitely for FTAM event
*/
174
175 #define
FALSE
0
176 #define
TRUE
1
177
178 /**********************************************************************/
179 /* Miscellaneous variables */
180 /**********************************************************************/
181
182 int
src_cepi = NOCEPI;
/* CEPI for source file associations */
183 int
dst_cepi = NOCEPI;
/* CEPI for destination file assoc.
*/
184 int
wait_mode;
/* Wait or nowait mode
*/
185 long
threshold;
/* Error threshold used in groups
*/
186 int
event;
/* FTAM event code
*/
187 int
dst_event;
/* FTAM destination event code
*/
188
189 /**********************************************************************/
190 /* Boolean control variables
*/
191 /**********************************************************************/
192
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 110
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
193 int
src_con_established = FALSE;
/* Src association existence flag */
194 int
dst_con_established = FALSE;
/* Dst association existence flag */
195
196 /**********************************************************************/
197 /* Error-handling variables
*/
198 /**********************************************************************/
199
200 int
status;
/* Used for I/O request calls
*/
201 int
error;
/* Used for confirm calls
*/
202 int
error_code;
/* Returns error code
*/
203 int
error_subcode;
/* Returns error subcode
*/
204
205 /**********************************************************************/
206 /* Variables used by the FTM procedures
*/
207 /**********************************************************************/
208
209 long
state_result;
/* Result of regime transition
*/
210 long
action_result;
/* Result of requested service
*/
211 long
override;
/* Used for the create request
*/
212 long
dst_fadu_op;
/* Operation performed on file
*/
213 long
src_start_position;
/* Used to step thru src. data
*/
214 char
data_value[MAX_BUF];
/* Buffer used to retrieve data
*/
215 long
src_more_data;
/* TRUE = more data to retrieve
*/
216 long
src_next_position;
/* Used to step thru src. data
*/
217
218 /**********************************************************************/
219 /* Structures used by the FTM procedures
*/
220 /**********************************************************************/
221
222 zaps_ddl_filename_def
aplmgr_name;
223 zaps_ddl_appl_addr_def
src_appl;
224 zaps_ddl_appl_addr_def
dst_appl;
225 zaps_ddl_appl_addr_def
local_appl;
226 zaps_ddl_ae_title_def
ae_title;
227 zaps_ddl_ae_title_def
src_ae_title;
228 zaps_ddl_ae_title_def
dst_ae_title;
229 zftm_ddl_func_units_def
func_units;
230 zftm_ddl_attr_groups_def
attr_groups;
231 zftm_ddl_cntnts_list_def
contents_type_list;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G -111
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
232 zaps_ddl_char32_def
initiator_id;
233 zaps_ddl_char32_def
account;
234 zaps_ddl_char32_def
filestore_password;
235 zftm_ddl_func_units_def
src_func_units;
236 zftm_ddl_func_units_def
dst_func_units;
237 zftm_ddl_attr_groups_def
src_attr_groups;
238 zftm_ddl_attr_groups_def
dst_attr_groups;
239 zftm_ddl_cntnts_list_def
src_contents_type_list;
240 zftm_ddl_cntnts_list_def
dst_contents_type_list;
241 zftm_ddl_diagnostic_def
diag;
242 zaps_ddl_char128_def
src_file;
243 zaps_ddl_original_error_def
original_error_info;
244 zftm_ddl_requested_access_def
requested_access;
245 zftm_ddl_access_passwds_def
access_passwords;
246 zftm_ddl_attr_names_def
attr_names;
247 zftm_ddl_proc_mode_def
process_mode;
248 zftm_ddl_read_attr_def
file_attr;
249 zftm_ddl_cntnts_type_def
contents_type;
250 zftm_ddl_create_attr_def
initial_attr;
251 zftm_ddl_fadu_id_def
dst_fadu_id;
252 zftm_ddl_fadu_id_def
src_fadu_id;
253 zftm_ddl_access_cntxt_def
access_context;
254 zftm_ddl_charging_def
src_charging;
255 zftm_ddl_charging_def
dst_charging;
256 zftm_ddl_change_attr_def
change_attr;
257
258
259 /**********************************************************************/
260 /* End global data declarations
*/
261 /**********************************************************************/
262
263 /**********************************************************************/
264 /* Local function declarations
*/
265 /**********************************************************************/
266
267 void
get_event ( int *expected_event, int cepi );
268 void
check_status ( int cepi );
269 void
check_error ();
270 void
check_state ();
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 112
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
271 void
bad_event ( int event, int cepi );
272 void
check_action_diag ();
273 void
abort_discard ();
274
275
276 #pragma PAGE "MOVEFILE"
277 /**********************************************************************/
278 /*
*/
279 /* Name:
movefile
*/
280 /*
*/
281 /* Description: The movefile program, written in wait mode, moves a
*/
282 /*
file between two systems on an OSI network. This
*/
283 /*
application initiates and manages the file transfer.
*/
284 /*
*/
285 /* Inputs:
None
286 /*
*/
*/
287 /* Outputs:
None
288 /*
*/
*/
289 /**********************************************************************/
290
291 main ()
292
293 {
294
295
/********************************************************************/
296
/* Allocate and initialize a segment used by the FTM and APS
*/
297
/* procedures.
*/
298
/********************************************************************/
299
300
error = APS_INITIALIZE_ ( /* swapvol */ );
301
if ( error != ZAPS_ERR_OK )
302
{
303
printf ( "Initialization of the FTAM/APS segment failed\n" );
304
exit (EXIT_SUCCESS);
305
}
306
307
/*******************************************************************/
308
/* Establish the source-file FTAM regime.
309
/*******************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 113
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
310
311
/*******************************************************************/
312
/* The following sections initialize the various parameters
*/
313
/* for the FTM_INITIALIZE_REQ_ procedure.
*/
314
/*******************************************************************/
315
316
/*******************************************************************/
317
/* Set the wait mode for the association to wait and initialize
*/
318
/* the APLMGR process name.
*/
319
/*******************************************************************/
320
321
wait_mode = ZAPS_VAL_WAITED;
322
memcpy (&aplmgr_name, manager_name, strlen (manager_name));
323
324
/*******************************************************************/
325
/* Supply the remote and local OSI addresses or common names. This */
326
/* application uses the common name. Set the length fields of the
*/
327
/* OSI addresses to 0.
*/
328
/*******************************************************************/
329
330
src_appl.zpsap.zpsel.zlen = 0;
331
src_appl.zpsap.zssel.zlen = 0;
332
src_appl.zpsap.ztsel.zlen = 0;
333
src_appl.zpsap.znsap.zlen = 0;
334
src_appl.zappl_name.zlen = strlen (src_appl_name);
335
memcpy (src_appl.zappl_name.u_zc.zb, src_appl_name,
336
src_appl.zappl_name.zlen);
337
338
dst_appl.zpsap.zpsel.zlen = 0;
339
dst_appl.zpsap.zssel.zlen = 0;
340
dst_appl.zpsap.ztsel.zlen = 0;
341
dst_appl.zpsap.znsap.zlen = 0;
342
dst_appl.zappl_name.zlen = strlen (dst_appl_name);
343
memcpy (dst_appl.zappl_name.u_zc.zb, dst_appl_name,
344
dst_appl.zappl_name.zlen);
345
346
local_appl.zpsap.zpsel.zlen = 0;
347
local_appl.zpsap.zssel.zlen = 0;
348
local_appl.zpsap.ztsel.zlen = 0;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 114
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
349
local_appl.zpsap.znsap.zlen = 0;
350
local_appl.zappl_name.zlen = strlen (local_appl_name);
351
memcpy (local_appl.zappl_name.u_zc.zb, local_appl_name,
352
local_appl.zappl_name.zlen);
353
354
355
/*******************************************************************/
356
/* The ae_title and src_ae_title parameters are optional
*/
357
/* parameters supplied for example only.
*/
358
/*******************************************************************/
359
360
ae_title.zae_title_type = ZAPS_VAL_AE_TITLE_FORMAT2;
361
ae_title.zae_title_format2.zae_qualifier_ispresent =
362
ZAPS_VAL_PRESENT;
363
ae_title.zae_title_format2.zae_qualifier = ae_qualifier;
364
ae_title.zae_title_format2.zap_title.znum_elements = num_elem;
365
memcpy (ae_title.zae_title_format2.zap_title.zobj_id,
366
ap_title, sizeof (ap_title) );
367
368
src_ae_title.zae_title_type = ZAPS_VAL_AE_TITLE_FORMAT2;
369
src_ae_title.zae_title_format2.zae_qualifier_ispresent =
370
ZAPS_VAL_PRESENT;
371
src_ae_title.zae_title_format2.zae_qualifier = src_ae_qualifier;
372
src_ae_title.zae_title_format2.zap_title.znum_elements = num_elem;
373
memcpy (src_ae_title.zae_title_format2.zap_title.zobj_id,
374
src_ap_title, sizeof (src_ap_title) );
375
376
377
/*******************************************************************/
378
/* Select the functional units required of the source system for
*/
379
/* moving the file: read, limited file management (required to
*/
380
/* read files, read file attributes, and delete files), and
*/
381
/* grouping (required for the file-transfer service class).
*/
382
/*******************************************************************/
383
384
func_units.zread
= ZAPS_VAL_TRUE;
385
func_units.zwrite
= ZAPS_VAL_FALSE;
386
func_units.zfileaccess
= ZAPS_VAL_FALSE;
387
func_units.zfilemgmt
= ZAPS_VAL_TRUE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 115
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
388
func_units.zfilemgmtenhanced
= ZAPS_VAL_FALSE;
389
func_units.zgroup
= ZAPS_VAL_TRUE;
390
func_units.zfadulock
= ZAPS_VAL_FALSE;
391
func_units.zrecovery
= ZAPS_VAL_FALSE;
392
func_units.zrestart
= ZAPS_VAL_FALSE;
393
394
/*******************************************************************/
395
/* Select the required attribute groups. Since this application
*/
396
/* reads the source-file attributes, all supported groups are
*/
397
/* selected. (The private group is not supported.)
*/
398
/*******************************************************************/
399
400
attr_groups.zstorage = ZAPS_VAL_TRUE;
401
attr_groups.zsecurity = ZAPS_VAL_TRUE;
402
attr_groups.zprivate = ZAPS_VAL_FALSE;
403
404
/*******************************************************************/
405
/* Set up the contents-type-list to request a document of
*/
406
/* type FTAM-3.
*/
407
/*******************************************************************/
408
409
contents_type_list.zcount = 1;
410
contents_type_list.zcntnts_type_ispresent = ZAPS_VAL_PRESENT;
411
contents_type_list.zcntnts_type_list[0].zid =
412
413
414
ZFTM_VAL_CNTNTSLIST_DOCNAME;
contents_type_list.zcntnts_type_list[0].u_zcntntstype.zcntntstype.
znum_elements = num_elem;
415 memcpy(contents_type_list.zcntnts_type_list[0].u_zcntntstype.zcntntstype.
416
zobj_id, ftam_doc_type, sizeof (ftam_doc_type) );
417
418
419
/*******************************************************************/
420
/* Initialize the initiator-ID, filestore-password, and account
*/
421
/* parameters according to the requirements of the remote system.
*/
422
/* The initialization shown here is for example only.
*/
423
/*******************************************************************/
424
425
filestore_password.zlen = strlen (password);
426 memcpy ( filestore_password.u_zc.zb, password, filestore_password.zlen);
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 116
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
427
428
initiator_id.zlen = strlen (init_id);
429
memcpy ( initiator_id.u_zc.zb, init_id, initiator_id.zlen);
430
431
account.zlen = strlen (charge_account);
432
memcpy ( account.u_zc.zb, charge_account, account.zlen);
433
434
status = FTM_INITIALIZE_REQ_ ( (int *) &src_cepi
435
, (int *) &aplmgr_name
436
, (int *) &src_appl
437
, wait_mode
438
, (int *) &local_appl
439
, (int *) &ae_title
440
, (int *) &src_ae_title
441
, /*service_class defaults to transfer*/
442
, (int *) &func_units
443
, (int *) &attr_groups
444
, (int *) &contents_type_list
445
, (int *) &initiator_id
446
, (int *) &account
447
, (int *) &filestore_password );
448
449
check_status ( src_cepi );
450
451
event = ZFTM_VAL_EVT_INITIALIZE_CNF;
452
get_event ( &event, src_cepi );
453
454
/*******************************************************************/
455
/* The optional output parameters for local_appl, src_appl, and
*/
456
/* src_ae_title are supplied to the confirm procedure for example
*/
457
/* only. The application returns the OSI addresses in the
*/
458
/* local_appl and src_appl parameters, and the AE title of the
*/
459
/* source responder in the src_ae_title parameter.
*/
460
/*******************************************************************/
461
462
error = FTM_INITIALIZE_CNF_ ( src_cepi
463
, (long *) &state_result
464
, (long *) &action_result
465
, (int *) &local_appl
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 117
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
466
, (int *) &src_appl
467
, (int *) &src_ae_title
468
, /* src_service_class */
469
, (int *) &src_func_units
470
, (int *) &src_attr_groups
471
, (int *) &src_contents_type_list
472
, (int *) &diag );
473
474
check_error ();
475
check_action_diag ();
476
check_state ();
477
478
/********************************************************************/
479
/* The source association has been established. Set the flag used in*/
480
/* error processing to determine whether a source association exists.*/
481
/********************************************************************/
482
483
src_con_established = TRUE;
484
485
/*******************************************************************/
486
/* Verify that the functional units have not been negotiated down
*/
487
/* from what was requested. If the requested functional units are
*/
488
/* not available, abort the association and exit. Additional
*/
489
/* application-specific error handling or recovery could be
*/
490
/* implemented if required by an application.
*/
491
/*******************************************************************/
492
493
if ( src_func_units.zread != ZAPS_VAL_TRUE ||
494
src_func_units.zfilemgmt != ZAPS_VAL_TRUE ||
495
src_func_units.zgroup != ZAPS_VAL_TRUE )
496
{
497
printf ("Functional units unavailable on source association\n" );
498
abort_discard ();
499
exit(EXIT_SUCCESS);
500
}
501
502
/*******************************************************************/
503
/* Verify that the attribute groups have not been negotiated down
*/
504
/* from what was requested. If the requested attribute groups are
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 118
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
505
/* not available, then abort the association and exit. Additional
*/
506
/* application-specific error handling or recovery could be
*/
507
/* implemented if required by an application.
*/
508
/*******************************************************************/
509
510
if ( src_attr_groups.zstorage != ZAPS_VAL_TRUE ||
511
src_attr_groups.zsecurity != ZAPS_VAL_TRUE )
512
{
513
printf ("Attribute groups unavailable on source association\n" );
514
abort_discard ();
515
exit(EXIT_SUCCESS);
516
}
517
518
/*******************************************************************/
519
/* Establish the destination-file FTAM regime.
520
/*******************************************************************/
*/
521
522
/*******************************************************************/
523
/* Set the optional parameter dst_ae_title.
524
/*******************************************************************/
*/
525
526
dst_ae_title.zae_title_type = ZAPS_VAL_AE_TITLE_FORMAT2;
527
dst_ae_title.zae_title_format2.zae_qualifier_ispresent =
528
ZAPS_VAL_PRESENT;
529
dst_ae_title.zae_title_format2.zae_qualifier = dst_ae_qualifier;
530
dst_ae_title.zae_title_format2.zap_title.znum_elements = num_elem;
531
memcpy (dst_ae_title.zae_title_format2.zap_title.zobj_id,
532
dst_ap_title, sizeof (dst_ap_title) );
533
534
535
/*******************************************************************/
536
/* Specify the functional units required of the destination system */
537
/* to write to a file: write, limited file management (required
*/
538
/* for enhanced file management), enhanced file management
*/
539
/* (required to change file attributes) and grouping (required by
*/
540
/* the file-transfer service class).
*/
541
/*******************************************************************/
542
543
func_units.zread
= ZAPS_VAL_FALSE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 119
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
544
func_units.zwrite
= ZAPS_VAL_TRUE;
545
func_units.zfilemgmt
546
func_units.zfilemgmtenhanced = ZAPS_VAL_TRUE;
547
func_units.zgroup
= ZAPS_VAL_TRUE;
= ZAPS_VAL_TRUE;
548
549
/*******************************************************************/
550
/* Set the wait mode for the association to waited.
551
/*******************************************************************/
*/
552
553
wait_mode = ZAPS_VAL_WAITED;
554
555
status = FTM_INITIALIZE_REQ_ ( (int *) &dst_cepi
556
, (int *) &aplmgr_name
557
, (int *) &dst_appl
558
, wait_mode
559
, (int *) &local_appl
560
, (int *) &ae_title
561
, (int *) &dst_ae_title
562
, /* service_class defaults to transfer*/
563
, (int *) &func_units
564
, (int *) &attr_groups
565
, (int *) &contents_type_list
566
, (int *) &initiator_id
567
, (int *) &account
568
, (int *) &filestore_password );
569
570
check_status ( dst_cepi );
571
572
event = ZFTM_VAL_EVT_INITIALIZE_CNF;
573
get_event ( &event, dst_cepi );
574
575
error = FTM_INITIALIZE_CNF_ ( dst_cepi
576
, (long *) &state_result
577
, (long *) &action_result
578
, (int *) &local_appl
579
, (int *) &dst_appl
580
, (int *) &dst_ae_title
581
, /* dst_service_class */
582
, (int *) &dst_func_units
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 120
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
583
, (int *) &dst_attr_groups
584
, (int *) &dst_contents_type_list
585
, (int *) &diag );
586
587
check_error ();
588
check_action_diag ();
589
check_state ();
590
591
/*******************************************************************/
592
/* The destination association has been established. Set the flag
*/
593
/* used in error processing to determine whether an association
*/
594
/* exists.
*/
595
/*******************************************************************/
596
597
dst_con_established = TRUE;
598
599
/*******************************************************************/
600
/* Verify that the functional units have not been negotiated down
*/
601
/* from what was requested. If the requested functional units are
*/
602
/* not available, abort both associations and exit. Additional
*/
603
/* application-specific error handling or recovery could be
*/
604
/* implemented if required by an application.
*/
605
/*******************************************************************/
606
if ( dst_func_units.zwrite != ZAPS_VAL_TRUE ||
607
dst_func_units.zgroup != ZAPS_VAL_TRUE ||
608
dst_func_units.zfilemgmt != ZAPS_VAL_TRUE ||
609
dst_func_units.zfilemgmtenhanced != ZAPS_VAL_TRUE )
610
{
611
printf ("Functional units unavailable on destination association\n" );
612
613
abort_discard ();
614
exit(EXIT_SUCCESS);
615
}
616
617
/*******************************************************************/
618
/* Verify that the attribute groups have not been negotiated down
*/
619
/* from what was requested. If the requested attribute groups are
*/
620
/* not available, abort both associations and exit. Additional
*/
621
/* application-specific error handling or recovery could be
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 121
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
622
/* implemented if required by an application.
623
/*******************************************************************/
624
if ( dst_attr_groups.zstorage != ZAPS_VAL_TRUE ||
625
dst_attr_groups.zsecurity != ZAPS_VAL_TRUE )
626
627
*/
{
printf ("Attribute groups unavailable on destination association\n" );
628
629
abort_discard ();
630
exit(EXIT_SUCCESS);
631
}
632
633
/*******************************************************************/
634
/* Set the document type in the contents_type structure to FTAM-3. */
635
/*******************************************************************/
636
637
contents_type.zid = ZFTM_VAL_CNTNTSTYPE_DOCTYPE;
638contents_type.u_zcntntstype.zdoctype.zdoctypename.znum_elements= num_elem;
639
memcpy( contents_type.u_zcntntstype.zdoctype.zdoctypename.zobj_id,
640
ftam_doc_type, sizeof (ftam_doc_type) );
641
642
/*******************************************************************/
643
/* Set MSL to present and set string length to 512 bytes.
644
/*******************************************************************/
*/
645
646
647
648
contents_type.u_zcntntstype.zdoctype.zmaxstringlenispresent
= ZAPS_VAL_PRESENT;
contents_type.u_zcntntstype.zdoctype.zmaxstringlen = 512;
649
650
/*******************************************************************/
651
/* Set the remaining elements of document type to ZAPS_VAL_ABSENT. */
652
/*******************************************************************/
653
654
655
656
657
658
659
contents_type.u_zcntntstype.zdoctype.zuniversalclassispresent
= ZAPS_VAL_ABSENT;
contents_type.u_zcntntstype.zdoctype.zstringsigispresent
= ZAPS_VAL_ABSENT;
contents_type.u_zcntntstype.zdoctype.zfileattrsispresent
= ZAPS_VAL_ABSENT;
660
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 122
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
661
/*******************************************************************/
662
/* Establish the source-file file-selection and file-open regimes. */
663
/*******************************************************************/
664
665
/*******************************************************************/
666
/* Use the FTM procedures FTM_SELECT_REQ_, FTM_READ_ATTRIB_REQ_,
667
/* and FTM_OPEN_REQ_ to select the file, read the file attributes, */
668
/* and open the source file. These three requests are processed as */
669
/* a group. Initialize all necessary parameters.
670
/*******************************************************************/
*/
*/
671
672
/*******************************************************************/
673
/* Initialize parameters for the FTM_SELECT_REQ_ procedure call.
674
/*******************************************************************/
*/
675
676
/*******************************************************************/
677
/* Initialize the file name according to the remote system
*/
678
/* requirements.
*/
679
/*******************************************************************/
680
681
src_file.zlen = strlen (src_filename);
682
memcpy ( src_file.u_zc.zb, src_filename, src_file.zlen );
683
684
/*******************************************************************/
685
/* Set the requested_access parameter to provide this
686
/* application with read, read-attribute, and delete access on the */
687
/* remote source file that is being moved.
688
/*******************************************************************/
*/
*/
689
690
requested_access.zread = ZAPS_VAL_TRUE;
691
requested_access.zinsert = ZAPS_VAL_FALSE;
692
requested_access.zreplace = ZAPS_VAL_FALSE;
693
requested_access.zextend = ZAPS_VAL_FALSE;
694
requested_access.zerase = ZAPS_VAL_FALSE;
695
requested_access.zreadattr = ZAPS_VAL_TRUE;
696
requested_access.zchngattr = ZAPS_VAL_FALSE;
697
requested_access.zdelete = ZAPS_VAL_TRUE;
698
699
/*******************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 123
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
700
/* Provide the access password for each action to be performed on
*/
701
/* the file.
*/
702
/*******************************************************************/
703
704
access_passwords.zreadpasswd.zlen = strlen (password);
705
memcpy(access_passwords.zreadpasswd.u_zc.zb, password,
706
access_passwords.zreadpasswd.zlen);
707
access_passwords.zinsertpasswd.zlen = 0;
708
access_passwords.zreplacepasswd.zlen = 0;
709
access_passwords.zextendpasswd.zlen = 0;
710
access_passwords.zerasepasswd.zlen = 0;
711
access_passwords.zreadattrpasswd.zlen = strlen (password);
712
memcpy ( access_passwords.zreadattrpasswd.u_zc.zb, password,
713
access_passwords.zreadattrpasswd.zlen );
714
access_passwords.zchngattrpasswd.zlen = 0;
715
access_passwords.zdeletepasswd.zlen = strlen (password);
716
memcpy (access_passwords.zdeletepasswd.u_zc.zb, password,
717
access_passwords.zdeletepasswd.zlen );
718
719
720
/*******************************************************************/
721
/* Initialize parameters for the FTM_READ_ATTRIB_REQ_ procedure
*/
722
/* call.
*/
723
/*******************************************************************/
724
725
/*******************************************************************/
726
/* Indicate which file attributes from the kernel and negotiated
*/
727
/* attribute groups are requested. This application requests all
*/
728
/* kernel attributes, the file-availability and future-filesize
*/
729
/* atttributes from the storage group, and access control from the */
730
/* security group.
731
/*******************************************************************/
732
733
/* kernel group */
734
attr_names.zfilename = ZAPS_VAL_TRUE;
735
attr_names.zpermittedactions = ZAPS_VAL_TRUE;
736
attr_names.zcntntstype = ZAPS_VAL_TRUE;
737
738
/* Storage group */
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 124
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
739
740
/*******************************************************************/
741
/* Set file availability and future filesize to ZAPS_VAL_TRUE.
742
/*******************************************************************/
*/
743
744
attr_names.zfileavlblty
= ZAPS_VAL_TRUE;
745
attr_names.zfuturefilesize = ZAPS_VAL_TRUE;
746
747
/*******************************************************************/
748
/* Set remaining storage attributes to ZAPS_VAL_FALSE.
749
/*******************************************************************/
*/
750
751
attr_names.zstorageaccount = ZAPS_VAL_FALSE;
752
attr_names.zcreation
= ZAPS_VAL_FALSE;
753
attr_names.zlastmod
= ZAPS_VAL_FALSE;
754
attr_names.zlastreadaccess = ZAPS_VAL_FALSE;
755
attr_names.zlastattrmod
= ZAPS_VAL_FALSE;
756
attr_names.zcreatorid
= ZAPS_VAL_FALSE;
757
attr_names.zlastmodid
= ZAPS_VAL_FALSE;
758
attr_names.zlastreaderid
= ZAPS_VAL_FALSE;
759
attr_names.zlastattrmodid
= ZAPS_VAL_FALSE;
760
attr_names.zfilesize
= ZAPS_VAL_FALSE;
761
762
/* security group */
763
764
/*******************************************************************/
765
/* Set access control to ZAPS_VAL_TRUE.
766
/*******************************************************************/
*/
767
768
attr_names.zaccesscntrl = ZAPS_VAL_TRUE;
769
770
/*******************************************************************/
771
/* Set remaining security attributes to ZAPS_VAL_FALSE. */
772
/*******************************************************************/
773
774
attr_names.zlegalqualif = ZAPS_VAL_FALSE;
775
776
777
/* private attributes group is not supported /*
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 125
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
778
attr_names.zprivateuse = ZAPS_VAL_FALSE;
779
780
/*******************************************************************/
781
/* Initialize parameters for the to FTM_OPEN_REQ_ procedure call.
782
/*******************************************************************/
*/
783
784
/*******************************************************************/
785
/* Set up the processing mode to perform a read action on the file.*/
786
/*******************************************************************/
787
788
process_mode.zread = ZAPS_VAL_TRUE;
789
process_mode.zinsert = ZAPS_VAL_FALSE;
790
process_mode.zreplace = ZAPS_VAL_FALSE;
791
process_mode.zextend = ZAPS_VAL_FALSE;
792
process_mode.zerase = ZAPS_VAL_FALSE;
793
794
795
/*******************************************************************/
796
/* Initialize the threshold for the begin-group request to
*/
797
/* indicate that all three services (select, read-attributes,
*/
798
/* and open) must be successful for the group to succeed.
*/
799
/*******************************************************************/
800
801
threshold = 3;
802
803
status = FTM_BEGIN_GROUP_REQ_ ( src_cepi
804
, threshold );
805
806
check_status ( src_cepi );
807
808
status = FTM_SELECT_REQ_ ( src_cepi
809
, (int *) &src_file
810
, (int *) &requested_access
811
, (int *) &access_passwords
812
, (int *) &account );
813
check_status ( src_cepi );
814
815
816
status = FTM_READ_ATTRIB_REQ_ ( src_cepi
, (int *) &attr_names );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 126
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
817
check_status ( src_cepi );
818
819
status = FTM_OPEN_REQ_ ( src_cepi
820
, (int *) &process_mode
821
, (int *) &contents_type );
822
check_status ( src_cepi );
823
824
status= FTM_END_GROUP_REQ_ ( src_cepi );
825
check_status ( src_cepi );
826
827
/*******************************************************************/
828
/* Call the following procedures to process the confirms returned
*/
829
/* by each request. The begin-group and end-group requests do not
*/
830
/* have separate confirm functions because no values are returned
*/
831
/* in the corresponding responses. If successful, however, they
*/
832
/* result in a confirm event. Call a get-event for each.
*/
833
/******************************************************************/
834
835
event = ZFTM_VAL_EVT_BEGINGROUP_CNF;
836
get_event ( &event, src_cepi );
837
838
event = ZFTM_VAL_EVT_SELECT_CNF;
839
get_event ( &event, src_cepi );
840
error = FTM_SELECT_CNF_ ( src_cepi
841
, (long *) &state_result
842
, (long *) &action_result
843
, (int *) &src_file
844
, (int *) &diag );
845
check_error ();
846
check_action_diag ();
847
check_state ();
848
849
event = ZFTM_VAL_EVT_READATTR_CNF;
850
get_event ( &event, src_cepi );
851
error = FTM_READ_ATTRIB_CNF_ ( src_cepi
852
, (long *) &action_result
853
, (int *) &file_attr
854
, (int *) &diag );
855
check_error ();
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 127
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
856
check_action_diag ();
857
858
event = ZFTM_VAL_EVT_OPEN_CNF;
859
get_event ( &event, src_cepi );
860
error = FTM_OPEN_CNF_ ( src_cepi
861
, (long *) &state_result
862
, (long *) &action_result
863
, (int *) &contents_type
864
, (int *) &diag );
865
check_error ();
866
check_action_diag ();
867
check_state ();
868
869
event = ZFTM_VAL_EVT_ENDGROUP_CNF;
870
get_event ( &event, src_cepi );
871
872
/*******************************************************************/
873
/* Establish the destination-file file-selection and file-open
*/
874
/* regimes.
*/
875
/*******************************************************************/
876
877
/*******************************************************************/
878
/* Use the FTM_CREATE_REQ_ and FTM_OPEN_REQ_ procedure calls to
*/
879
/* create and open the file on the destination system. Send these
*/
880
/* two requests out as a group. Initialize all necessary
*/
881
/* parameters for the create and open procedures.
*/
882
/*******************************************************************/
883
884
/*******************************************************************/
885
/* Initialize parameters for the call to FTM_CREATE_REQ_.
886
/*******************************************************************/
*/
887
888
/*******************************************************************/
889
/* Set up the initial file attributes for the file to be created.
890
/*******************************************************************/
891
892
/*Kernel Group */
893
initial_attr.zfilename.zlen = strlen (dst_filename);
894
memcpy (initial_attr.zfilename.u_zc.zb, dst_filename,
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 128
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
895
initial_attr.zfilename.zlen);
896
initial_attr.zcntntstypevalue.zid = ZFTM_VAL_CNTNTSTYPE_DOCTYPE;
897
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.zdoctypename.
898
znum_elements = num_elem;
899 memcpy(initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.zdoctypename.
900
zobj_id, ftam_doc_type, sizeof (ftam_doc_type));
901
902
903
904
905
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
zuniversalclassispresent = ZAPS_VAL_ABSENT;
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
zmaxstringlenispresent = file_attr.zcntntstypevalue.
906
u_zcntntstype.zdoctype.
907
zmaxstringlenispresent;
908
909
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
zmaxstringlen
= file_attr.zcntntstypevalue.
910
u_zcntntstype.zdoctype.
911
zmaxstringlen;
912
913
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
zstringsigispresent
= file_attr.zcntntstypevalue.
914
u_zcntntstype.zdoctype.
915
zstringsigispresent;
916
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
917
zstringsig
= file_attr.zcntntstypevalue.
918
u_zcntntstype.zdoctype.
919
zstringsig;
920
921
initial_attr.zcntntstypevalue.u_zcntntstype.zdoctype.
zfileattrsispresent
= ZAPS_VAL_ABSENT;
922
923
/*Storage group */
924
initial_attr.zstorageaccountispresent = ZAPS_VAL_ABSENT;
925
initial_attr.zfileavlbltyattrispresent = ZAPS_VAL_PRESENT;
926
initial_attr.zfileavlbltyattr.zid = ZFTM_VAL_ATTR_ISPRESENT;
927
initial_attr.zfileavlbltyattr.zfileavlblty =
928
ZFTM_VAL_FILEAVLBLTY_IMMED;
929
initial_attr.zfuturefilesizeispresent = ZAPS_VAL_PRESENT;
930
initial_attr.zfuturefilesize.zid = ZFTM_VAL_ATTR_ISPRESENT;
931
initial_attr.zfuturefilesize.zfilesize = file_attr.
932
933
zfuturefilesize.zfilesize;
initial_attr.zpermittedactions = file_attr.zpermittedactions;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 129
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
934
935
/*Security group */
936
initial_attr.zaccesscntrlattrispresent = ZAPS_VAL_PRESENT;
937
938
/*******************************************************************/
939
/* Set the next two attributes to allow write and change-
*/
940
/* attribute capabilities during the move. The procedure
*/
941
/* applies the original attributes that were read from the
*/
942
/* source file to the destination file after the move is
*/
943
/* complete.
*/
944
/*******************************************************************/
945
946
initial_attr.zaccesscntrlattr.zid = ZFTM_VAL_ATTR_ISPRESENT;
947
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zreplace
948
949
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zread
950
951
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zinsert
952
953
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zerase
954
955
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zdelete
956
957
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zchngattr
958
959
= ZAPS_VAL_TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zconcurrencyispresent
960
961
= ZAPS_VAL_ABSENT;
initial_attr.zaccesscntrlattr.zaccesscntrl.zidentityispresent
962
963
= ZAPS_VAL_ABSENT;
initial_attr.zaccesscntrlattr.zaccesscntrl.zpasswdsispresent
964
965
= ZAPS_VAL_ABSENT;
initial_attr.zaccesscntrlattr.zaccesscntrl.zlocationispresent
966
967
= ZAPS_VAL_ABSENT;
initial_attr.zlegalqualifispresent = ZAPS_VAL_ABSENT;
968
969
/*******************************************************************/
970
/* Specify that the application is to delete the named file if it
*/
971
/* exists and create a new file using the attributes specified in
*/
972
/* the initial_attr parameter.
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 130
NonStop FTAM Programming Examples
973
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
/*******************************************************************/
974
975
override = ZFTM_VAL_OVR_CREATE_NEW;
976
977
/*******************************************************************/
978
/* Set the requested_access parameter to provide replace and
*/
979
/* change-attribute access on the file.
*/
980
/*******************************************************************/
981
982
requested_access.zread = ZAPS_VAL_FALSE;
983
requested_access.zreplace = ZAPS_VAL_TRUE;
984
requested_access.zreadattr = ZAPS_VAL_FALSE;
985
requested_access.zchngattr = ZAPS_VAL_TRUE;
986
requested_access.zdelete = ZAPS_VAL_FALSE;
987
988
/*******************************************************************/
989
/* Provide the access password for each action to be performed on
*/
990
/* the file.
*/
991
/*******************************************************************/
992
993
access_passwords.zreadpasswd.zlen = 0;
994
access_passwords.zinsertpasswd.zlen = 0;
995
access_passwords.zreplacepasswd.zlen = strlen (password);
996
memcpy (access_passwords.zreplacepasswd.u_zc.zb, password,
997
access_passwords.zreplacepasswd.zlen );
998
access_passwords.zextendpasswd.zlen = 0;
999
access_passwords.zerasepasswd.zlen = 0;
1000
access_passwords.zreadattrpasswd.zlen = 0;
1001
access_passwords.zchngattrpasswd.zlen = strlen (password);
1002
memcpy (access_passwords.zchngattrpasswd.u_zc.zb, password,
1003
access_passwords.zchngattrpasswd.zlen );
1004
access_passwords.zdeletepasswd.zlen = 0;
1005
1006
/*******************************************************************/
1007
/* Initialize parameters for the FTM_OPEN_REQ_ procedure call. */
1008
/*******************************************************************/
1009
1010
/*******************************************************************/
1011
/* Set up the processing mode to perform a replace action on the
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 131
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1012
/* file.
*/
1013
/*******************************************************************/
1014
1015
process_mode.zread = ZAPS_VAL_FALSE;
1016
process_mode.zinsert = ZAPS_VAL_FALSE;
1017
process_mode.zreplace = ZAPS_VAL_TRUE;
1018
process_mode.zextend = ZAPS_VAL_FALSE;
1019
process_mode.zerase = ZAPS_VAL_FALSE;
1020
1021
/*******************************************************************/
1022
/* Initialize the threshold for the begin-group request to specify */
1023
/* that both services (create and open) must be successful for the */
1024
/* group to succeed.
1025
/*******************************************************************/
*/
1026
1027
threshold = 2;
1028
1029
status = FTM_BEGIN_GROUP_REQ_ ( dst_cepi
1030
1031
, threshold );
check_status ( dst_cepi );
1032
1033
status = FTM_CREATE_REQ_ ( dst_cepi
1034
, (int *) &initial_attr
1035
, override
1036
, (int *) &filestore_password
1037
, (int *) &requested_access
1038
, (int *) &access_passwords
1039
, (int *) &account );
1040
check_status ( dst_cepi );
1041
1042
status = FTM_OPEN_REQ_ ( dst_cepi
1043
, (int *) &process_mode
1044
, (int *) &contents_type );
1045
check_status ( dst_cepi );
1046
1047
status = FTM_END_GROUP_REQ_ ( dst_cepi );
1048
check_status ( dst_cepi );
1049
1050
/*******************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 132
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1051
/* Call the following procedures to process the confirms returned
*/
1052
/* by each request. The begin-group and end-group requests do not
*/
1053
/* have separate confirm functions but, if successful, they
*/
1054
/* result in confirm events. Call a get_event for each.
*/
1055
/*******************************************************************/
1056
1057
event = ZFTM_VAL_EVT_BEGINGROUP_CNF;
1058
get_event ( &event, dst_cepi );
1059
1060
event = ZFTM_VAL_EVT_CREATE_CNF;
1061
get_event ( &event, dst_cepi );
1062
1063
error = FTM_CREATE_CNF_ ( dst_cepi
1064
, (long *) &state_result
1065
, (long *) &action_result
1066
, (int *) &initial_attr
1067
, (int *) &diag );
1068
check_error ();
1069
check_action_diag ();
1070
check_state ();
1071
1072
event = ZFTM_VAL_EVT_OPEN_CNF;
1073
get_event ( &event, dst_cepi );
1074
1075
error = FTM_OPEN_CNF_ ( dst_cepi
1076
, (long *) &state_result
1077
, (long *) &action_result
1078
, (int *) &contents_type
1079
, (int *) &diag );
1080
check_error ();
1081
check_action_diag ();
1082
check_state ();
1083
1084
event = ZFTM_VAL_EVT_ENDGROUP_CNF;
1085
get_event ( &event, dst_cepi );
1086
1087
/*******************************************************************/
1088
/* Establish the source-file and destination-file data-transfer
*/
1089
/* regimes.
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 133
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1090
/*******************************************************************/
1091
1092
/*******************************************************************/
1093
/* Initialize parameters for the FTM_WRITE_REQ_ and FTM_READ_REQ_
*/
1094
/* procedures.
*/
1095
/*******************************************************************/
1096
1097
/*******************************************************************/
1098
/* Set the dst_fadu_op parameter to replace the destination-file
*/
1099
/* contents.
*/
1100
/*******************************************************************/
1101
1102
dst_fadu_op = ZFTM_VAL_FADU_OP_REPLACE;
1103
1104
/*******************************************************************/
1105
/* To establish a position at the beginning of an FTAM-3 type
*/
1106
/* file, specify a FADU of "first."
*/
1107
/*******************************************************************/
1108
1109
dst_fadu_id.zid = ZFTM_VAL_FADUID_FIRSTLAST;
1110
dst_fadu_id.u_zfaduid.zfirstlast = ZFTM_VAL_FADUID_FIRST;
1111
1112
src_fadu_id.zid = ZFTM_VAL_FADUID_FIRSTLAST;
1113
src_fadu_id.u_zfaduid.zfirstlast = ZFTM_VAL_FADUID_FIRST;
1114
1115
/*******************************************************************/
1116
/* The access context for an FTAM-3 type file is always
*/
1117
/* "unstructured access."
*/
1118
/*******************************************************************/
1119
1120
access_context.zcntxt = ZFTM_VAL_ACCESSCNTXT_UA;
1121
access_context.zlevelnumispresent = ZAPS_VAL_ABSENT;
1122
1123
status = FTM_WRITE_REQ_ ( dst_cepi
1124
, dst_fadu_op
1125
, (int *) &dst_fadu_id );
1126
check_status ( dst_cepi );
1127
1128
status = FTM_READ_REQ_ ( src_cepi
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 134
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1129
, (int *) &src_fadu_id
1130
, (int *) &access_context );
1131
check_status ( src_cepi );
1132
1133
/*******************************************************************/
1134
/* Wait for a data indication from the source association. As each */
1135
/* indication is received, call FTM_DATA_IND_ to retrieve the data */
1136
/* and then FTM_DATA_REQ_ to send the data to the destination
*/
1137
/* system.
*/
1138
/*
*/
1139
/* Repeat this process until a data-end indication arrives from
*/
1140
/* the source or a cancel or abort indication is received from
*/
1141
/* either system.
*/
1142
/*******************************************************************/
1143
1144
do
1145
{
1146
1147
/*****************************************************************/
1148
/* Wait for either a data indication, a data-end indication, or
*/
1149
/* a cancel indication from the source system. Set event to
*/
1150
/* ANYEVENT since more than one event code is valid.
*/
1151
/*****************************************************************/
1152
1153
event = ANYEVENT;
1154
get_event ( &event, src_cepi );
1155
1156
switch ( event )
1157
{
1158
case ZFTM_VAL_EVT_DATA_IND :
1159
1160
src_more_data = 1;
1161
src_start_position = 0;
1162
1163
while ( src_more_data != 0 )
1164
{
1165
/************************************************************/
1166
/* Call FTM_DATA_IND_ to read data from the source system.
1167
/************************************************************/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 135
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1168
1169
error = FTM_DATA_IND_ ( src_cepi
1170
, (long) MAX_BUF
1171
, (char *) &data_value
1172
, (long *) &src_more_data
1173
, (long *) &src_next_position
1174
, src_start_position );
1175
check_error ();
1176
1177
/************************************************************/
1178
/* Call FTM_DATA_REQ_ to write data to the remote system.
1179
/************************************************************/
*/
1180
1181
status = FTM_DATA_REQ_ ( dst_cepi
1182
, (char *) &data_value );
1183
check_status ( dst_cepi );
1184
1185
1186
1187
src_start_position = src_next_position;
}
break;
1188
1189
case ZFTM_VAL_EVT_DATAEND_IND :
1190
1191
/*************************************************************/
1192
/* Call the data-end indication procedure to check the error */
1193
/* status and action result. Then call FTM_DATA_END_REQ_
*/
1194
/* to notify the destination system that the data transfer
*/
1195
/* has ended.
*/
1196
/*************************************************************/
1197
1198
error = FTM_DATA_END_IND_ ( src_cepi
1199
, (long *) &action_result
1200
, (int *) &diag );
1201
check_error ();
1202
check_action_diag ();
1203
1204
1205
1206
status = FTM_DATA_END_REQ_ ( dst_cepi
, action_result );
check_status ( dst_cepi );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 136
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1207
break;
1208
1209
case ZFTM_VAL_EVT_CANCEL_IND :
1210
1211
/*************************************************************/
1212
/* The source system has cancelled the transfer. Call the
*/
1213
/* indication procedure to get the error and action result,
*/
1214
/* and then send a response to the source system. Finally,
*/
1215
/* send a cancel request to the destination system and wait
*/
1216
/* for the confirm. This terminates the data-transfer
*/
1217
/* regimes. Additional application-specific error handling
*/
1218
/* could be implemented if required by an application.
*/
1219
/*************************************************************/
1220
1221
error = FTM_CANCEL_IND_ ( src_cepi
1222
, (long *) &action_result
1223
, (int *) &diag );
1224
check_error ();
1225
check_action_diag ();
1226
1227
status = FTM_CANCEL_RSP_ ( src_cepi
1228
1229
, /* action_result */ );
check_status ( src_cepi );
1230
1231
status = FTM_CANCEL_REQ_ ( dst_cepi
1232
, action_result
1233
, (int *) &diag );
1234
check_status ( dst_cepi );
1235
1236
event = ZFTM_VAL_EVT_CANCEL_CNF;
1237
get_event ( &event, dst_cepi );
1238
1239
error = FTM_CANCEL_CNF_ ( dst_cepi
1240
, (long *) &action_result
1241
, (int *) &diag );
1242
check_error ();
1243
check_action_diag ();
1244
1245
break;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 137
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1246
1247
default :
1248
bad_event ( event, src_cepi );
1249
}
1250
1251
}
1252
while ( event == ZFTM_VAL_EVT_DATA_IND );
1253
1254
/*End of file transfer loop */
1255
1256
1257
/*******************************************************************/
1258
/* Issue an FTM_TRANSFER_END_REQ_ call to the source and
*/
1259
/* destination systems and wait for the respective confirms. This
*/
1260
/* terminates the data-transfer regime for each association.
*/
1261
/*******************************************************************/
1262
1263
/*******************************************************************/
1264
/* When a cancel occurs, the data-transfer regime is terminated.
*/
1265
/* Skip the next section if a cancel took place.
*/
1266
/*******************************************************************/
1267
1268
if ( event != ZFTM_VAL_EVT_CANCEL_CNF )
1269
{
1270
1271
/*****************************************************************/
1272
/* Terminate the source-file data-transfer regime.
1273
/*****************************************************************/
1274
1275
status = FTM_TRANSFER_END_REQ_ ( src_cepi );
1276
check_status ( src_cepi );
1277
1278
event = ZFTM_VAL_EVT_TRANSEND_CNF;
1279
get_event ( &event, src_cepi );
1280
1281
error = FTM_TRANSFER_END_CNF_ ( src_cepi
1282
, (long *) &action_result
1283
, (int *) &diag );
1284
check_error ();
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 138
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1285
check_action_diag ();
1286
1287
/*****************************************************************/
1288
/* Terminate the destination-file data-transfer regime.
1289
/*****************************************************************/
*/
1290
1291
status = FTM_TRANSFER_END_REQ_ ( dst_cepi );
1292
check_status ( dst_cepi );
1293
1294
event = ZFTM_VAL_EVT_TRANSEND_CNF;
1295
get_event ( &event, dst_cepi );
1296
1297
error = FTM_TRANSFER_END_CNF_ ( dst_cepi
1298
, (long *) &action_result
1299
, (int *) &diag );
1300
check_error ();
1301
check_action_diag ();
1302
}
1303
1304
1305
/*******************************************************************/
1306
/* Terminate the destination-file file-open and file-selection
*/
1307
/* regimes.
*/
1308
/*******************************************************************/
1309
1310
/*******************************************************************/
1311
/* Close the file on the destination system, change the attributes,*/
1312
/* and then deselect the file. These three primitives must also
*/
1313
/* be grouped since the transfer class was negotiated for the
*/
1314
/* association.
*/
1315
/*******************************************************************/
1316
1317
/*******************************************************************/
1318
/* Set the following parameters so the destination file attributes */
1319
/* match the source file.
1320
/*******************************************************************/
1321
1322
change_attr.zattrsarepresent = ZAPS_VAL_PRESENT;
1323
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 139
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1324
if ( file_attr.zaccesscntrlattrispresent == ZAPS_VAL_PRESENT )
1325
{
1326
change_attr.zaccesscntrlispresent = ZAPS_VAL_PRESENT;
1327
change_attr.zaccesscntrl.zid = ZFTM_VAL_ATTR_ISPRESENT;
1328
change_attr.zaccesscntrl.zinsertispresent = ZAPS_VAL_PRESENT;
1329
change_attr.zaccesscntrl.zinsertvalues = file_attr.
1330
zaccesscntrlattr.zaccesscntrl;
1331
}
1332
else
1333
{
1334
1335
change_attr.zaccesscntrlispresent = ZAPS_VAL_ABSENT;
}
1336
1337
/******************************************************************/
1338
/* Initialize the threshold for the begin-group request so
*/
1339
/* that all three services (close, change attributes, and
*/
1340
/* deselect) must be successful for the group to succeed.
*/
1341
/******************************************************************/
1342
1343
threshold = 3;
1344
status = FTM_BEGIN_GROUP_REQ_ ( dst_cepi
1345
1346
, threshold );
check_status ( dst_cepi );
1347
1348
status = FTM_CLOSE_REQ_ ( dst_cepi );
1349
check_status ( dst_cepi );
1350
1351
status = FTM_CHANGE_ATTRIB_REQ_ ( dst_cepi
1352
1353
, (int *) &change_attr );
check_status ( dst_cepi );
1354
1355
status = FTM_DESELECT_REQ_ ( dst_cepi );
1356
check_status ( dst_cepi );
1357
1358
status = FTM_END_GROUP_REQ_ ( dst_cepi );
1359
check_status ( dst_cepi );
1360
1361
/*******************************************************************/
1362
/* Call the following procedures to process the confirms returned
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 140
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1363
/* in response to each request. The begin-group and end-group
*/
1364
/* requests do not have separate confirm procedures but, if
*/
1365
/* successful, they result in confirm events. Call get-event
*/
1366
/* for each.
*/
1367
/*******************************************************************/
1368
1369
event = ZFTM_VAL_EVT_BEGINGROUP_CNF;
1370
get_event ( &event, dst_cepi );
1371
1372
event = ZFTM_VAL_EVT_CLOSE_CNF;
1373
get_event ( &event, dst_cepi );
1374
1375
error = FTM_CLOSE_CNF_ ( dst_cepi
1376
, (long *) &action_result
1377
, (int *) &diag );
1378
check_error ();
1379
check_action_diag ();
1380
1381
event = ZFTM_VAL_EVT_CHANGEATTR_CNF;
1382
get_event ( &event, dst_cepi );
1383
1384
error = FTM_CHANGE_ATTRIB_CNF_ ( dst_cepi
1385
, (long *) &action_result
1386
, (int *) &change_attr
1387
, (int *) &diag );
1388
check_error ();
1389
check_action_diag ();
1390
1391
event = ZFTM_VAL_EVT_DESELECT_CNF;
1392
get_event ( &event, dst_cepi );
1393
1394
/*******************************************************************/
1395
/* The charging parameter is used to convey information about costs*/
1396
/* attributed to the account. This parameter should be used only
*/
1397
/* if the account parameter was used in FTM_CREATE_REQ_. The
*/
1398
/* information returned in the charging parameter is not used in
*/
1399
/* this example.
*/
1400
/*******************************************************************/
1401
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 141
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1402
error = FTM_DESELECT_CNF_ ( dst_cepi
1403
, (long *) &action_result
1404
, (int *) &dst_charging
1405
, (int *) &diag );
1406
check_error ();
1407
check_action_diag ();
1408
1409
event = ZFTM_VAL_EVT_ENDGROUP_CNF;
1410
get_event ( &event, dst_cepi );
1411
1412
1413
/*******************************************************************/
1414
/* Terminate the source-file file-open and file-selection regimes. */
1415
/*******************************************************************/
1416
1417
1418
/*******************************************************************/
1419
/* Issue a close and delete request for the source file. The
*/
1420
/* delete is used since this example is moving the file, not
*/
1421
/* simply copying it.
*/
1422
/*******************************************************************/
1423
1424
/*******************************************************************/
1425
/* Initialize the threshold for the begin-group request to
*/
1426
/* indicate that both services (close and delete) must be
*/
1427
/* successful for the group to succeed.
*/
1428
/*******************************************************************/
1429
1430
threshold = 2;
1431
status = FTM_BEGIN_GROUP_REQ_ ( src_cepi
1432
1433
, threshold );
check_status ( src_cepi );
1434
1435
status = FTM_CLOSE_REQ_ ( src_cepi );
1436
check_status ( src_cepi );
1437
1438
status = FTM_DELETE_REQ_ ( src_cepi );
1439
check_status ( src_cepi );
1440
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 142
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1441
status = FTM_END_GROUP_REQ_ ( src_cepi );
1442
check_status ( src_cepi );
1443
1444
/*******************************************************************/
1445
/* Call the following procedures to process the confirms returned
*/
1446
/* in response to each request. The begin-group and end-group
*/
1447
/* requests do not have separate confirm functions but, if
*/
1448
/* successful, they result in confirm events. Call get-event
*/
1449
/* for each.
*/
1450
/*******************************************************************/
1451
1452
event = ZFTM_VAL_EVT_BEGINGROUP_CNF;
1453
get_event ( &event, src_cepi );
1454
1455
event = ZFTM_VAL_EVT_CLOSE_CNF;
1456
get_event ( &event, src_cepi );
1457
error = FTM_CLOSE_CNF_ ( src_cepi
1458
, (long *) &action_result
1459
, (int *) &diag );
1460
check_error ();
1461
check_action_diag ();
1462
1463
event = ZFTM_VAL_EVT_DELETE_CNF;
1464
get_event ( &event, src_cepi );
1465
1466
/*******************************************************************/
1467
/* The charging parameter is used to convey information about costs*/
1468
/* attributed to the account. This parameter should be used only
*/
1469
/* if the account parameter was used in FTM_SELECT_REQ_. The
*/
1470
/* information returned in the charging parameter is not used in
*/
1471
/* this example.
*/
1472
/*******************************************************************/
1473
1474
error = FTM_DELETE_CNF_ ( src_cepi
1475
, (long *) &action_result
1476
, (int *) &src_charging
1477
, (int *) &diag );
1478
check_error ();
1479
check_action_diag ();
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 143
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1480
1481
event = ZFTM_VAL_EVT_ENDGROUP_CNF;
1482
get_event ( &event, src_cepi );
1483
1484
1485
/*******************************************************************/
1486
/* Terminate the source-file FTAM regime.
1487
/*******************************************************************/
*/
1488
1489
status = FTM_TERMINATE_REQ_ ( src_cepi );
1490
check_status ( src_cepi );
1491
1492
event = ZFTM_VAL_EVT_TERMINATE_CNF;
1493
get_event ( &event, src_cepi );
1494
1495
/*******************************************************************/
1496
/* The charging parameter is used to convey information about costs*/
1497
/* attributed to the account. This parameter should be used only
*/
1498
/* if the account parameter was used in FTM_INITIALIZE_REQ_.
*/
1499
/* The information returned in the charging parameter is not used
*/
1500
/* in this example.
*/
1501
/*******************************************************************/
1502
1503
error = FTM_TERMINATE_CNF_ ( src_cepi
1504
1505
, (int *) &src_charging );
check_error ();
1506
1507
/*******************************************************************/
1508
/* Terminate the destination-file FTAM regime.
1509
/*******************************************************************/
1510
1511
status = FTM_TERMINATE_REQ_ ( dst_cepi );
1512
check_status ( dst_cepi );
1513
1514
event = ZFTM_VAL_EVT_TERMINATE_CNF;
1515
get_event ( &event, dst_cepi );
1516
1517
1518
error = FTM_TERMINATE_CNF_ ( dst_cepi
, /* (int *) &dst_charging */ );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 144
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1519
1520
check_error ();
1521
1522
/*******************************************************************/
1523
/* Discard the API context information for the source association. */
1524
/*******************************************************************/
1525
1526
status = APS_DISCARD_ ( src_cepi );
1527
check_status ( src_cepi );
1528
1529
/*******************************************************************/
1530
/* Discard the API context information for the destination
*/
1531
/* association.
*/
1532
/*******************************************************************/
1533
1534
status = APS_DISCARD_ ( dst_cepi );
1535
check_status ( dst_cepi );
1536
1537
/*******************************************************************/
1538
/* Display a message to the terminal that the program completed
*/
1539
/* successfully.
*/
1540
/*******************************************************************/
1541
1542
printf ( "File move complete\n" );
1543
1544 } /*** MOVEFILE ***/
1545
1546
1547 #pragma PAGE "GET_EVENT"
1548 /*********************************************************************/
1549 /*
*/
1550 /* Name:
get_event
*/
1551 /*
*/
1552 /* Description: The get_event procedure gets an available event.
*/
1553 /*
It verifies that the event is the expected event
*/
1554 /*
and that there are no errors associated with it.
*/
1555 /*
If an unexpected event is received, it calls
*/
1556 /*
bad_event to process the error.
*/
1557 /*
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 145
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1558 /* Input:
Expected_event, the event that the procedure
*/
1559 /*
expects to receive on the association
*/
1560 /*
*/
1561 /*
CEPI identifying the association that carries the
*/
1562 /*
event
*/
1563 /*
*/
1564 /* Output:
Expected_event, which contains the value of
*/
1565 /*
the received event
*/
1566 /*********************************************************************/
1567
1568 void get_event ( expected_event, cepi )
1569
1570 int
*expected_event;
1571 int
cepi;
1572
1573 {
1574
int
event_code;
1575
1576
/*****************************************************************/
1577
/* Wait for an event to be received.
1578
/*****************************************************************/
*/
1579
1580
status = APS_EVENT_RECEIVE_ ( cepi, WAIT_FOREVER );
1581
1582
if ( status != ZAPS_VAL_STATUS_EVENT )
1583
{
1584
/****************************************************************/
1585
/* A bad status has been received.
1586
/****************************************************************/
*/
1587
1588
1589
check_status ( cepi );
}
1590
1591
/******************************************************************/
1592
/* Get the event code.
1593
/******************************************************************/
1594
1595
1596
error = APS_STATUS_ ( cepi
, (int *) &event_code );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 146
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1597
check_error ();
1598
1599
/*****************************************************************/
1600
/* Verify that the expected event was received. If the expected
*/
1601
/* event = ANYEVENT, then any event code is valid.
*/
1602
/*****************************************************************/
1603
1604
if ( event_code != *expected_event &&
1605
1606
*expected_event != ANYEVENT )
{
1607
1608
bad_event ( event_code, cepi );
}
1609
1610
/*****************************************************************/
1611
/* Return the received event code to the caller.
1612
/*****************************************************************/
1613
if ( *expected_event == ANYEVENT )
1614
{
1615
1616
*/
*expected_event = event_code;
}
1617
1618 } /*** get_event ***/
1619
1620
1621 #pragma PAGE "CHECK_STATUS"
1622 /**********************************************************************/
1623 /*
*/
1624 /* Name:
check_status
*/
1625 /*
*/
1626 /* Description: The check_status procedure checks the status
*/
1627 /*
returned from an FTM or APS procedure call. It
*/
1628 /*
checks for NORETRY, RETRYLATER, and DISCARD. If
*/
1629 /*
status is OK, it returns control to the main
*/
1630 /*
program; otherwise, it discards the associations
*/
1631 /*
and exits the program.
*/
1632 /*
*/
1633 /* Input:
CEPI identifying the association whose status is
*/
1634 /*
being checked
*/
1635 /*
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 147
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1636 /* Output:
Error messages to terminal
1637 /*
*/
*/
1638 /*********************************************************************/
1639
1640 void check_status ( cepi )
1641
1642 int cepi;
1643
1644 {
1645
1646
/*******************************************************************/
1647
/* Check for a good status.
1648
/*******************************************************************/
*/
1649
1650
if ( status == ZAPS_VAL_STATUS_OK )
1651
{
1652
return;
1653
}
1654
1655
/*******************************************************************/
1656
/* Get the error code and error subcode.
1657
/*******************************************************************/
*/
1658
1659
error = APS_STATUS_ ( cepi
1660
, /* event_code */
1661
, /* device_name */
1662
, (int *) &error_code
1663
, (int *) &error_subcode
1664
, /* service_id */
1665
, /* diagnostic_buffer */
1666
, (int *) &original_error_info );
1667
1668
check_error ();
1669
1670
/*******************************************************************/
1671
/* Display the status code.
1672
/*******************************************************************/
1673
1674
printf ( "STATUS : %d ",status );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 148
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1675
1676
/*******************************************************************/
1677
/* Display the error code and subcode.
1678
/*******************************************************************/
*/
1679
1680
printf ( "ERROR CODE : %d ERROR SUBCODE : %d\n",
1681
error_code, error_subcode );
1682
1683
/********************************************************************/
1684
/* Display the original error code and error subcode.
1685
/********************************************************************/
*/
1686
1687
printf ("ORIGINAL ERROR INFO -\n");
1688
printf (" SERVICE ID : %d\n", original_error_info.zerror.zservice_id );
1689
printf (" ERROR CODE : %d\n", original_error_info.zerror.zerror_code );
1690
printf (" ERROR SUBCODE : %d\n",
1691
original_error_info.zerror.zerror_subcode );
1692
1693
/*******************************************************************/
1694
/* Perform error handling, depending on the status value returned. */
1695
/* Additional application-specific error handling or recovery
*/
1696
/* could be implemented depending on application requiremen
*/
1697
/*******************************************************************/
1698
1699
switch ( status )
1700
{
1701
1702
case ZAPS_VAL_STATUS_NO_RETRY:
1703
case ZAPS_VAL_STATUS_RETRY_LATER:
1704
1705
{
1706
/**************************************************************/
1707
/* The status indicates an error was detected. This
*/
1708
/* application aborts both associations and exits.
*/
1709
/**************************************************************/
1710
1711
abort_discard ();
1712
exit (EXIT_SUCCESS);
1713
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 149
NonStop FTAM Programming Examples
1714
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
}
1715
1716
case ZAPS_VAL_STATUS_DISCARD:
1717
{
1718
/**************************************************************/
1719
/* A status of DISCARD returned on an FTM request indicates
*/
1720
/* that the association associated with that CEPI has been
*/
1721
/* lost. Set the appropriate control flag to indicate the
*/
1722
/* association is lost and call abort_discard to abort the
*/
1723
/* other association.
*/
1724
/**************************************************************/
1725
1726
/* Determine which CEPI has been lost. */
1727
if ( cepi == src_cepi )
1728
{
1729
src_con_established = -1;
1730
}
1731
else
1732
{
1733
dst_con_established = -1;
1734
}
1735
1736
abort_discard ();
1737
1738
exit (EXIT_SUCCESS);
1739
1740
}
1741
1742
default: /* unknown status value */
1743
1744
printf ("Unknown status\n");
1745
exit (EXIT_FAILURE);
1746
1747
}
1748
1749 } /*** check_status ***/
1750
1751
1752 #pragma PAGE "CHECK_ERROR"
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 150
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1753 /*********************************************************************/
1754 /*
*/
1755 /* Name:
check_error
*/
1756 /*
*/
1757 /* Description: The check_error procedure checks error codes
*/
1758 /*
returned by FTM procedure calls. If an error
*/
1759 /*
code indicates that an error occurred, this
*/
1760 /*
procedure displays a message, then aborts the
*/
1761 /*
associations to the two remote systems and exits
*/
1762 /*
the program.
*/
1763 /*
*/
1764 /* Input:
None
1765 /*
*/
*/
1766 /* Output:
Error messages to terminal
1767 /*
*/
*/
1768 /*********************************************************************/
1769
1770
void check_error ()
1771
1772
{
1773
1774
/*******************************************************************/
1775
/* Check for an error condition.
1776
/*******************************************************************/
*/
1777
1778
if ( error != ZAPS_ERR_OK )
1779
{
1780
1781
/*****************************************************************/
1782
/* Display the error code.
1783
/*****************************************************************/
*/
1784
1785
printf ( "ERROR # %d\n", error );
1786
printf ( "Association discarded\n" );
1787
1788
/*****************************************************************/
1789
/* Abort both associations and exit the program.
1790
/*****************************************************************/
1791
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 151
*/
NonStop FTAM Programming Examples
1792
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
abort_discard ();
1793
1794
exit (EXIT_SUCCESS);
1795
1796
}
1797
1798 } /*** check_error ***/
1799
1800
1801 #pragma PAGE "CHECK_STATE"
1802 /*********************************************************************/
1803 /*
*/
1804 /* Name:
check_state
*/
1805 /*
*/
1806 /* Description: The check_state procedure checks for a state
*/
1807 /*
result of failure on an FTM confirm. If the
*/
1808 /*
the state result is failure, this procedure
*/
1809 /*
displays an error message, calls abort_discard,
*/
1810 /*
and exits the program.
*/
1811 /*
*/
1812 /* Input:
None
1813 /*
*/
*/
1814 /* Output:
Error message to terminal
1815 /*
*/
*/
1816 /*********************************************************************/
1817
1818
void check_state ()
1819
1820
{
1821
if ( state_result == ZFTM_VAL_STATE_FAILURE )
1822
{
1823
printf ( "Bad state result received\n");
1824
printf ( "Associations discarded\n");
1825
1826
abort_discard ();
1827
1828
1829
1830
exit (EXIT_SUCCESS);
}
} /*** check_state ***/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 152
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1831
1832
1833 #pragma PAGE "BAD_EVENT"
1834 /*********************************************************************/
1835 /*
*/
1836 /* Name:
bad_event
*/
1837 /*
*/
1838 /* Description: The bad_event procedure is called when an
*/
1839 /*
unexpected event is received from one of the
*/
1840 /*
associations. The event can be an abort indication.
*/
1841 /*
If an abort is received, the procedure aborts the
*/
1842 /*
other association; any other event results in
*/
1843 /*
aborts of both associations.
*/
1844 /*
*/
1845 /* Input:
Event received on the association
1846 /*
*/
*/
1847 /*
CEPI identifying the association that carried the
*/
1848 /*
event
*/
1849 /*
*/
1850 /* Output:
Error messages to terminal
1851 /*
*/
*/
1852 /*********************************************************************/
1853
1854
void bad_event ( event, cepi )
1855
1856
int event;
1857
int cepi;
1858
1859
{
1860
1861
/*******************************************************************/
1862
/* If an abort indication is received on one of the two
*/
1863
/* associations, the other must be aborted. Any other event
*/
1864
/* requires that both associations be aborted.
*/
1865
/*******************************************************************/
1866
1867
if ( event == ZFTM_VAL_EVT_PABORT_IND )
1868
{
1869
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 153
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1870
/*****************************************************************/
1871
/* Retrieve the action result and diagnostic messages for the
*/
1872
/* P-abort.
*/
1873
/*****************************************************************/
1874
error = FTM_P_ABORT_IND_ ( cepi
1875
, (long *) &action_result
1876
, (int *) &diag );
1877
check_error ();
1878
check_action_diag ();
1879
1880
/*****************************************************************/
1881
/* Determine which association was aborted and then abort the
*/
1882
/* other.
*/
1883
/*****************************************************************/
1884
1885
if ( cepi == src_cepi && dst_con_established )
1886
{
1887
status = FTM_U_ABORT_REQ_ ( dst_cepi
1888
, /* action_result */
1889
, /* diagnostics */ );
1890
check_status ( dst_cepi );
1891
}
1892
else if ( cepi == dst_cepi && src_con_established )
1893
{
1894
status = FTM_U_ABORT_REQ_ ( src_cepi
1895
, /* action_result */
1896
, /* diagnostics */ );
1897
check_status ( src_cepi );
1898
}
1899
}
1900
else
1901
{
1902
1903
/*****************************************************************/
1904
/* The unexpected event was not an abort indication. Issue an
*/
1905
/* abort for both associations.
*/
1906
/*****************************************************************/
1907
1908
if ( src_con_established )
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 154
NonStop FTAM Programming Examples
1909
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
{
1910
status = FTM_U_ABORT_REQ_ ( src_cepi
1911
, /* action_result */
1912
, /* diagnostics */ );
1913
check_status ( src_cepi );
1914
}
1915
if ( dst_con_established )
1916
{
1917
status = FTM_U_ABORT_REQ_ ( dst_cepi
1918
, /* action_result */
1919
, /* diagnostics */ );
1920
check_status ( dst_cepi );
1921
1922
}
}
1923
1924
/*******************************************************************/
1925
/* Verify that a CEPI exists, and if it does, discard it.
1926
/*******************************************************************/
*/
1927
1928
if ( src_cepi != NOCEPI )
1929
{
1930
1931
status = APS_DISCARD_ ( src_cepi );
}
1932
1933
if ( dst_cepi != NOCEPI )
1934
{
1935
1936
status = APS_DISCARD_ ( dst_cepi );
}
1937
1938
/*******************************************************************/
1939
/* Display a message to the terminal and exit the program.
1940
/*******************************************************************/
1941
1942
printf ( "Unexpected event received\n");
1943
printf ( "Associations discarded\n");
1944
1945
exit (EXIT_SUCCESS);
1946
1947 } /*** bad_event ***/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 155
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
1948
1949
1950 #pragma PAGE "CHECK_ACTION_DIAG"
1951 /*********************************************************************/
1952 /*
*/
1953 /* Name:
check_action_diag
*/
1954 /*
*/
1955 /* Description: The check_action_diag procedure determines whether
*/
1956 /*
the action requested of a remote responder was
*/
1957 /*
successful or not. If not, the procedure displays
*/
1958 /*
the diagnostic message type and error ID for each
*/
1959 /*
diagnostic message element, calls abort_discard, and */
1960 /*
ends the program. Additional application-specific
*/
1961 /*
error handling or recovery could be implemented if
*/
1962 /*
required by an application.
*/
1963 /*
*/
1964 /* Input:
None
*/
1965 /*
*/
1966 /* Output:
Error message to terminal
*/
1967 /*
*/
1968 /*********************************************************************/
1969
1970 void check_action_diag ()
1971
1972 {
1973
1974
int i;
1975
1976
/*******************************************************************/
1977
/* Check action_result for failure and display diagnostic
*/
1978
/* messages.
*/
1979
/*******************************************************************/
1980
1981
if ( action_result == ZFTM_VAL_ACTION_FAILURE )
1982
{
1983
1984
printf ( "Following is a list of %d diagnostic elements -\n"
, diag.zdiagcount );
1985
1986
for ( i = 0; i < diag.zdiagcount; i++ )
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 156
NonStop FTAM Programming Examples
1987
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
{
1988
printf (" Diagnostic Type: %ld\n", diag.zdiagelems[i].zdiagtype );
1989
printf (" Error ID: %ld\n", diag.zdiagelems[i].zerrorid );
1990
if (diag.zdiagelems[i].zfurtherdetailsispresent == ZAPS_VAL_PRESENT)
1991
printf (" Details: %s\n",
1992
diag.zdiagelems[i].zfurtherdetails.u_zc.zb );
1993
}
1994
1995
/****************************************************************/
1996
/* Abort both associations and exit the program.
1997
/****************************************************************/
*/
1998
1999
abort_discard ();
2000
printf ( "Association discarded\n" );
2001
exit (EXIT_SUCCESS);
2002
2003
}
2004
2005
} /*** check_action_diag ***/
2006
2007
2008 #pragma PAGE "ABORT_DISCARD"
2009 /*********************************************************************/
2010 /*
*/
2011 /* Name:
abort_discard
*/
2012 /*
*/
2013 /* Description: The abort_discard procedure aborts and discards
*/
2014 /*
*/
valid associations and CEPIs.
2015 /*
*/
2016 /* Input:
None
2017 /*
*/
*/
2018 /* Output:
None
2019 /*
*/
*/
2020 /*********************************************************************/
2021
2022
void abort_discard ()
2023
2024
{
2025
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 157
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
2026
/*******************************************************************/
2027
/* Initialize the parameters for the U-abort request.
2028
/*******************************************************************/
*/
2029
2030
2031
/*******************************************************************/
2032
/* Send a failed action result since the following diagnostic
*/
2033
/* message type is set to "permanent."
*/
2034
/*******************************************************************/
2035
2036
action_result = ZFTM_VAL_ACTION_FAILURE;
2037
2038
2039
/*******************************************************************/
2040
/* The following code demonstrates how to set the diagnostic para -*/
2041
/* meter for an FTM_U_ABORT_REQ_ call. The diagnostic values set
*/
2042
/* here are for example only; a real application might be more
*/
2043
/* specific, for instance, in the error code. Here, type is set
*/
2044
/* to "permanent"; error code is set to "no reason"; observer
*/
2045
/* of the error is this application; and the source of the error
*/
2046
/* is not categorized.
*/
2047
/*******************************************************************/
2048
2049
diag.zdiagcount = 1;
2050
diag.zdiagelemsispresent = ZAPS_VAL_TRUE;
2051
diag.zdiagelems[0].zdiagtype = ZFTM_VAL_DIAG_PERMANENT;
2052
diag.zdiagelems[0].zerrorid = ZFTM_DIAG_NO_REASON;
2053
diag.zdiagelems[0].zerrorobserver = ZFTM_VAL_ENTITYREF_INITFSRVUSR;
2054
diag.zdiagelems[0].zerrorsource = ZFTM_VAL_ENTITYREF_NOCATPOSS;
2055
diag.zdiagelems[0].zsuggesteddelayispresent = ZAPS_VAL_FALSE;
2056
diag.zdiagelems[0].zfurtherdetailsispresent = ZAPS_VAL_FALSE;
2057
2058
/*******************************************************************/
2059
/* Abort the source association if it exists.
2060
/*******************************************************************/
2061
2062
if ( src_con_established )
2063
{
2064
status = FTM_U_ABORT_REQ_ ( src_cepi
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 158
*/
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2065
, action_result
2066
, (int *) &diag );
2067
if (status != ZAPS_VAL_STATUS_OK)
2068
{
2069
printf ("Abort of the source association failed\n");
2070
}
2071
2072
}
2073
2074
/*******************************************************************/
2075
/* Abort the destination association if it exists.
2076
/*******************************************************************/
*/
2077
2078
if ( dst_con_established )
2079
{
2080
status = FTM_U_ABORT_REQ_ ( dst_cepi
2081
, action_result
2082
, (int *) &diag );
2083
if ( status != ZAPS_VAL_STATUS_OK)
2084
{
2085
printf ("Abort of the destination association failed\n");
2086
}
2087
2088
}
2089
2090
/*******************************************************************/
2091
/* Discard the API context information for each CEPI.
2092
/*******************************************************************/
2093
2094
if ( src_cepi != NOCEPI )
2095
{
2096
2097
APS_DISCARD_ ( src_cepi );
}
2098
2099
if ( dst_cepi != NOCEPI )
2100
{
2101
2102
APS_DISCARD_ ( dst_cepi );
}
2103
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 159
*/
NonStop FTAM Programming Examples
Example 2 in C—Moving a File Between Two
Remote Systems (in Wait Mode)
2104 } /*** abort_discard ***/
2105
2106
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 160
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1
!-----------------------------------------------------------------------!
2
!
!
3
! Example 2 in TAL - Moving an FTAM-3 File Between Two Remote Systems
!
4
! (in Wait Mode)
!
5
!
!
6
!-----------------------------------------------------------------------!
7
!
!
8
! Program Name : EXTMOVF3
!
9
!
!
10 ! Program Description :
!
11 !
!
12 ! This program, in wait mode, moves an FTAM-3 file between two remote
!
13 ! systems on an OSI network. The application initiates and manages the
!
14 ! file transfer. It issues requests and receives indications and
!
15 ! confirms from the two remote systems and acts on them accordingly.
!
16 ! At the end of the file transfer, the source file is deleted.
!
17 !
!
18 ! The main procedure contains all of the code for establishing the
!
19 ! required FTAM protocol regimes, managing the data transfer, and
!
20 ! normally terminating each regime for both associations.
!
21 !
!
22 ! Apart from the main procedure, there is a procedure to receive FTAM
!
23 ! events, a general-purpose procedure used by error-handling
!
24 ! routines to abort and discard associations, and five error-
!
25 ! handling procedures that handle different types of errors:
!
26 !
!
27 !
get_event
A routine called after a request is sent
!
28 !
to a remote responder to wait for the
!
29 !
respective confirm. It also can
!
30 !
receive FTM indications.
!
31 !
32 !
!
abort_discard
A routine called by the error-handling
!
33 !
routines that is used to abort and discard
!
34 !
associations.
!
35 !
36 !
!
check_status
A procedure that checks status returned
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 161
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
37 !
by FTM procedure calls.
38 !
39 !
!
check_error
40 !
A procedure that checks for errors
!
returned by FTM procedure calls.
!
41 !
42 !
!
check_state
43 !
A procedure that handles a failed state
!
in the remote FTAM regime.
!
44 !
45 !
!
bad_event
46 !
A procedure that handles unexpected
!
FTAM events.
!
47 !
48 !
!
!
check_action_diag
A routine that checks the action result
!
49 !
and diagnostic messages returned by an
!
50 !
FTM procedure.
!
51 !
!
52 ! FTM request and response procedures return an I/O status value
!
53 ! on the procedure call. The check_status procedure checks the
!
54 ! results of the I/O operation. The FTM indication and confirm
!
55 ! procedures return an error value indicating the outcome of the
!
56 ! completed service. The procedure check_error checks the returned
!
57 ! error code.
!
58 !
!
59 ! This example is provided to illustrate FTAM programming concepts.
!
60 ! It does not necessarily illustrate the recommended programming
!
61 ! style for a real application, which might be more modularized to
!
62 ! provide a higher level of top-down coding, for instance. To en-
!
63 ! hance the illustration of FTAM programming concepts, this example
!
64 ! demonstrates programming tasks in sequence, emphasizing a more
!
65 ! linear approach to coding.
!
66 !-----------------------------------------------------------------------!
67 !
!
68 ! NOTE : Before attempting to run this program, set the following
!
69 !
!
items correctly:
70 !
!
71 !
a) environmental variables
!
72 !
b) required parameters for the FTM_INITIALIZE_REQ_ call
!
73 !
!
74 !-----------------------------------------------------------------------!
75
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 162
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
76
77 !-----------------------------------------------------------------------!
78 ! Source in the FTM and APS structure definitions and literals from
!
79 ! the appropriate volume and subvolume.
!
80 !-----------------------------------------------------------------------!
81
82 ?nolist, source zftmtal
! FTM DDL !
83 ?list
84 ?nolist, source zapstal
! APS DDL !
85 ?list
86 ?NOMAP
87 ?NOCODE
88 !-----------------------------------------------------------------------!
89 ! Global data declarations
!
90 !-----------------------------------------------------------------------!
91
92 !-----------------------------------------------------------------------!
93 ! Macro for word addressing
!
94 !-----------------------------------------------------------------------!
95
96 DEFINE SADDR( x ) = (@x '<<' 1)#; ! String address of word object
!
97
98 !-----------------------------------------------------------------------!
99 ! Miscellaneous literals
!
100!-----------------------------------------------------------------------!
101
102
LITERAL ANYEVENT
= -1;
! Wait for receipt of any FTAM event
!
103
LITERAL MAX_BUF
= 1000;
! Buffer size used for receiving data !
104
LITERAL NOCEPI
= -1;
! Uninitialized or invalid CEPI
!
105
LITERAL WAIT_FOREVER = -1D;
! Wait indefinitely for FTAM event
!
106
LITERAL NUM_ELEM
= 5;
! No. of elements in ae-title/doc-type!
107
LITERAL BASE
= 10;
! Base parameter for Guardian DNUMOUT !
109 LITERAL FALSE
= 0;
! Implies false condition
!
110 LITERAL TRUE
= 1;
! Implies true condition
!
108
111
112 !----------------------------------------------------------------------!
113 ! Environment-specific fields
!
114 !
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 163
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
115 ! You will need to change these fields to reflect your FTAM
!
116 ! environment. src_filename and dst_filename must be valid file
!
117 ! names for the respective source and remote systems. In this example, !
118 ! src_file and dst_file are Guardian files.
!
119 !
!
120 ! When changing these values, you might also need to change the
!
121 ! length of the corresponding variables (array size).
!
122 !----------------------------------------------------------------------!
123
124
STRING .EXT
local_appl_name[0:4]
:= "APPL1";
125
STRING .EXT
src_appl_name[0:4]
:= "APPL2";
126
STRING .EXT
dst_appl_name[0:4]
:= "APPL3";
127
STRING .EXT
init_id[0:5]
:= "initid";
128
STRING .EXT
password[0:2]
:= "aaa";
129
STRING .EXT
charge_account[0:4]
:= "12345";
130
STRING .EXT
manager_name[0:23]
:= "$APMGR ";
131
STRING .EXT
src_filename[0:21]
:= "$VOLUME.SUBVOL.SRCFILE";
132
STRING .EXT
dst_filename[0:21]
:= "$VOLUME.SUBVOL.DSTFILE";
133
134 INT
.EXT
ftam_doc_type[0:NUM_ELEM-1] := [1,0,8571,5,3];
135 INT
.EXT
ap_title[0:NUM_ELEM-1]
:= [1,3,9999,1,7];
136 INT
.EXT
src_ap_title[0:NUM_ELEM-1]
:= [1,3,9999,1,7];
137 INT
.EXT
dst_ap_title[0:NUM_ELEM-1]
:= [1,3,9999,1,7];
139 INT (32)
ae_qualifier
:= 0d;
140 INT (32)
src_ae_qualifier
:= 1d;
141 INT (32)
dst_ae_qualifier
:= 1d;
138
142
143 !----------------------------------------------------------------------!
144 ! Miscellaneous variables
!
145 !----------------------------------------------------------------------!
146
147 INT
src_cepi := NOCEPI;
! CEPI for source file association !
148 INT
dst_cepi := NOCEPI;
! CEPI for destination file assoc. !
149 INT
wait_mode;
! Wait or nowait mode
!
150 INT(32) threshold;
! Error threshold used in groups
!
151 INT
event;
! FTAM event code
!
152 INT
dst_event;
! FTAM destination event code
!
153 INT
width;
! Used for DNUMOUT calls
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 164
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
154
155 !----------------------------------------------------------------------!
156 ! Boolean control variables
!
157 !----------------------------------------------------------------------!
158
159 INT src_con_established := FALSE; ! Src association existence flag
!
160 INT dst_con_established := FALSE; ! Dst association existence flag
!
161
162 !----------------------------------------------------------------------!
163 ! Error-handling variables
!
164 !----------------------------------------------------------------------!
165
166 INT
status;
! Used for I/O request calls
!
167 INT
error;
! Used for confirm calls
!
168 INT
error_code;
! Returns error number
!
169 INT
error_subcode;
! Returns error subcode
!
170
171 !----------------------------------------------------------------------!
172 ! Variables used by the FTM procedures
!
173 !----------------------------------------------------------------------!
174
175 INT(32) state_result;
! Result of regime transition
!
176 INT(32) action_result;
! Result of requested service
!
177 INT(32) override;
! Used for the create request
!
178 INT(32) dst_fadu_op;
! Operation performed on file
!
179 INT(32) src_start_position;
! Used to step through src. data
!
180 STRING .EXT data_value_ptr[0:MAX_BUF-1];! Buffer used to retrieve data !
181 INT(32) src_more_data;
! Gives number of bytes left
!
182 INT(32) src_next_position;
! Used to step through src. data
!
183
184
185 !----------------------------------------------------------------------!
186 ! Structures used by the FTM procedures
!
187 !----------------------------------------------------------------------!
188
189 STRUCT .EXT
aplmgr_name
( ZAPS^DDL^FILENAME^DEF );
190 STRUCT .EXT
src_appl
( ZAPS^DDL^APPL^ADDR^DEF );
191 STRUCT .EXT
dst_appl
( ZAPS^DDL^APPL^ADDR^DEF );
192 STRUCT .EXT
local_appl
( ZAPS^DDL^APPL^ADDR^DEF );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 165
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
193 STRUCT .EXT
ae_title
( ZAPS^DDL^AE^TITLE^DEF );
194 STRUCT .EXT
src_ae_title
( ZAPS^DDL^AE^TITLE^DEF );
195 STRUCT .EXT
dst_ae_title
( ZAPS^DDL^AE^TITLE^DEF );
196 STRUCT .EXT
func_units
( ZFTM^DDL^FUNC^UNITS^DEF );
197 STRUCT .EXT
attr_groups
( ZFTM^DDL^ATTR^GROUPS^DEF );
198 STRUCT .EXT
contents_type_list
( ZFTM^DDL^CNTNTS^LIST^DEF );
199 STRUCT .EXT
initiator_id
( ZAPS^DDL^CHAR32^DEF );
200 STRUCT .EXT
account
( ZAPS^DDL^CHAR32^DEF );
201 STRUCT .EXT
filestore_password
( ZAPS^DDL^CHAR32^DEF );
202 STRUCT .EXT
src_func_units
( ZFTM^DDL^FUNC^UNITS^DEF );
203 STRUCT .EXT
dst_func_units
( ZFTM^DDL^FUNC^UNITS^DEF );
204 STRUCT .EXT
src_attr_groups
( ZFTM^DDL^ATTR^GROUPS^DEF );
205 STRUCT .EXT
dst_attr_groups
( ZFTM^DDL^ATTR^GROUPS^DEF );
206 STRUCT .EXT
src_contents_type_list ( ZFTM^DDL^CNTNTS^LIST^DEF );
207 STRUCT .EXT
dst_contents_type_list ( ZFTM^DDL^CNTNTS^LIST^DEF );
208 STRUCT .EXT
diag
( ZFTM^DDL^DIAGNOSTIC^DEF );
209 STRUCT .EXT
src_file
( ZAPS^DDL^CHAR128^DEF );
210 STRUCT .EXT
original_error_info
( ZAPS^DDL^ORIGINAL^ERROR^DEF );
211 STRUCT .EXT
requested_access
( ZFTM^DDL^REQUESTED^ACCESS^DEF );
212 STRUCT .EXT
access_passwords
( ZFTM^DDL^ACCESS^PASSWDS^DEF );
213 STRUCT .EXT
attr_names
( ZFTM^DDL^ATTR^NAMES^DEF );
214 STRUCT .EXT
process_mode
( ZFTM^DDL^PROC^MODE^DEF );
215 STRUCT .EXT
file_attr
( ZFTM^DDL^READ^ATTR^DEF );
216 STRUCT .EXT
contents_type
( ZFTM^DDL^CNTNTS^TYPE^DEF );
217 STRUCT .EXT
initial_attr
( ZFTM^DDL^CREATE^ATTR^DEF );
218 STRUCT .EXT
dst_fadu_id
( ZFTM^DDL^FADU^ID^DEF );
219 STRUCT .EXT
src_fadu_id
( ZFTM^DDL^FADU^ID^DEF );
220 STRUCT .EXT
access_context
( ZFTM^DDL^ACCESS^CNTXT^DEF );
221 STRUCT .EXT
src_charging
( ZFTM^DDL^CHARGING^DEF );
222 STRUCT .EXT
dst_charging
( ZFTM^DDL^CHARGING^DEF );
223 STRUCT .EXT
change_attr
( ZFTM^DDL^CHANGE^ATTR^DEF );
224
225
226 !----------------------------------------------------------------------!
227 ! Variables used for startup-message processing
!
228 !----------------------------------------------------------------------!
229
230 STRUCT .STARTUP;
231
BEGIN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 166
NonStop FTAM Programming Examples
232
INT msg_code;
233
INT default_vol [0:7];
234
INT infile [0:11];
235
INT outfile [0:11];
236
STRING params [0:131];
237
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
END;
238
239 INT .receive [0:11] := ["$RECEIVE",8*[" "]];
240
241 !----------------------------------------------------------------------!
242 ! Variables used for local terminal I/O processing
!
243 !----------------------------------------------------------------------!
244
245 INT fn := -1;
246 INT termname [0:11];
247 INT termnum;
248 INT text_len;
249 INT .outbuf [0:133];
250 STRING .tempbuf := SADDR(outbuf);
251 STRING .text_ptr;
252
253 !----------------------------------------------------------------------!
254 ! End global data declarations !
255 !----------------------------------------------------------------------!
256
257
258 !----------------------------------------------------------------------!
259 !External function declarations for FTM, APS, and Guardian procedures
!
260 !----------------------------------------------------------------------!
261
262 ?nolist, source extdecs0
( FTM_INITIALIZE_REQ_
263 ?
, FTM_INITIALIZE_CNF_
264 ?
, FTM_OPEN_REQ_
265 ?
, FTM_OPEN_CNF_
266 ?
, FTM_SELECT_REQ_
267 ?
, FTM_SELECT_CNF_
268 ?
, FTM_DESELECT_REQ_
269 ?
, FTM_DESELECT_CNF_
270 ?
, FTM_DELETE_REQ_
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 167
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
271 ?
, FTM_DELETE_CNF_
272 ?
, FTM_CREATE_REQ_
273 ?
, FTM_CREATE_CNF_
274 ?
, FTM_CLOSE_REQ_
275 ?
, FTM_CLOSE_CNF_
276 ?
, FTM_BEGIN_GROUP_REQ_
277 ?
, FTM_END_GROUP_REQ_
278 ?
, FTM_READ_ATTRIB_REQ_
279 ?
, FTM_READ_ATTRIB_CNF_
280 ?
, FTM_CHANGE_ATTRIB_REQ_
281 ?
, FTM_CHANGE_ATTRIB_CNF_
282 ?
, FTM_WRITE_REQ_
283 ?
, FTM_READ_REQ_
284 ?
, FTM_DATA_IND_
285 ?
, FTM_DATA_REQ_
286 ?
, FTM_DATA_END_REQ_
287 ?
, FTM_DATA_END_IND_
288 ?
, FTM_TRANSFER_END_REQ_
289 ?
, FTM_TRANSFER_END_CNF_
290 ?
, FTM_TERMINATE_REQ_
291 ?
, FTM_TERMINATE_CNF_
292 ?
, FTM_CANCEL_IND_
293 ?
, FTM_CANCEL_REQ_
294 ?
, FTM_CANCEL_RSP_
295 ?
, FTM_CANCEL_CNF_
296 ?
, FTM_P_ABORT_IND_
297 ?
, FTM_U_ABORT_IND_
298 ?
, FTM_U_ABORT_REQ_
299 ?
, APS_INITIALIZE_
300 ?
, APS_STATUS_
301 ?
, APS_EVENT_RECEIVE_
302 ?
, APS_DISCARD_
303 ?
, ABEND
304 ?
, STOP
305 ?
, WRITE
306 ?
, READ
307 ?
, OPEN
308 ?
, CLOSE
309 ?
, MYTERM
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 168
NonStop FTAM Programming Examples
310 ?
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
, DNUMOUT )
311 ?list
312
313 !----------------------------------------------------------------------!
314 ! Forward declarations
!
315 !----------------------------------------------------------------------!
316
317 PROC get_event ( expected_event, cepi );
318
INT .EXT expected_event;
319
INT cepi;
320 FORWARD;
321
322 PROC check_status ( cepi );
323
INT cepi;
324 FORWARD;
325
326 PROC check_error;
327 FORWARD;
328
329 PROC check_state;
330 FORWARD;
331
332 PROC bad_event ( event, cepi );
333
INT .EXT event;
334
INT cepi;
335 FORWARD;
336
337 PROC check_action_diag;
338 FORWARD;
339
340 PROC abort_discard;
341 FORWARD;
342
343
344 ?PAGE "MOVEFILE"
345 !----------------------------------------------------------------------!
346 !
!
347 ! Name:
movefile
348 !
!
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 169
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
349 ! Description: The movefile program written in wait mode moves a
!
350 !
file between two systems on an OSI network. This
!
351 !
application initiates and manages the file transfer.
!
352 !
!
353 ! Inputs:
None
354 !
!
!
355 ! Outputs:
None
356 !
!
!
357 !----------------------------------------------------------------------!
358
359 PROC movefile MAIN;
360
361 BEGIN
362
363
!------------------------------------------------------------------!
364
! Get the process startup message and open the terminal for output.!
365
!------------------------------------------------------------------!
366
367
CALL MYTERM ( termname );
368
CALL OPEN ( termname, termnum );
369
370
CALL OPEN ( receive, fn );
371
IF <> THEN
372
BEGIN
373
tempbuf ':=' "$RECEIVE open error" -> @text_ptr;
374
text_len := @text_ptr - @tempbuf;
375
CALL WRITE ( termnum, outbuf, text_len );
376
CALL STOP;
377
END;
378
379
CALL READ ( fn, startup, $len(startup));
380
IF <> THEN
381
BEGIN
382
tempbuf ':=' "$RECEIVE read error" -> @text_ptr;
383
text_len := @text_ptr - @tempbuf;
384
CALL WRITE ( termnum, outbuf, text_len );
385
CALL STOP;
386
END;
387
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 170
NonStop FTAM Programming Examples
388
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
CALL CLOSE ( fn );
389
390
!------------------------------------------------------------------!
391
! Allocate and initialize a segment used by the FTM and APS
!
392
! procedures.
!
393
!------------------------------------------------------------------!
394
395
error := APS_INITIALIZE_ ( ! swapvol ! );
396
IF ( error <> ZAPS^ERR^OK ) THEN
397
BEGIN
398
tempbuf ':=' "Initialization of the FTAM/APS segment failed"
399
-> @text_ptr;
400
text_len := @text_ptr - @tempbuf;
401
CALL WRITE ( termnum, outbuf, text_len );
402
CALL STOP;
403
END;
404
405
406
!------------------------------------------------------------------!
407
! Establish the source-file FTAM regime.
408
!------------------------------------------------------------------!
!
409
410
!------------------------------------------------------------------!
411
! The following sections initialize the various parameters
!
412
! for the FTM_INITIALIZE_REQ_ procedure.
!
413
!------------------------------------------------------------------!
414
415
!------------------------------------------------------------------!
416
! Set the wait mode for the association to wait and initialize the !
417
! APLMGR process name.
418
!------------------------------------------------------------------!
!
419
420
wait_mode := ZAPS^VAL^WAITED;
421
aplmgr_name ':=' manager_name FOR $occurs (manager_name) BYTES;
422
423
!------------------------------------------------------------------!
424
! Supply the remote and local OSI addresses or common names.
!
425
! This application uses the common name. Set the length fields of
!
426
! the OSI addresses to 0.
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 171
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
427
!------------------------------------------------------------------!
428
429
src_appl.zpsap.zpsel.zlen := 0;
430
src_appl.zpsap.zssel.zlen := 0;
431
src_appl.zpsap.ztsel.zlen := 0;
432
src_appl.zpsap.znsap.zlen := 0;
433
src_appl.zappl^name.zlen
434
src_appl.zappl^name.zb
:= $occurs(src_appl_name);
':=' src_appl_name FOR
435
src_appl.zappl^name.zlen BYTES;
436
437
dst_appl.zpsap.zpsel.zlen := 0;
438
dst_appl.zpsap.zssel.zlen := 0;
439
dst_appl.zpsap.ztsel.zlen := 0;
440
dst_appl.zpsap.znsap.zlen := 0;
441
dst_appl.zappl^name.zlen
442
dst_appl.zappl^name.zb
443
dst_appl.zappl^name.zlen BYTES;
:= $occurs(dst_appl_name);
':=' dst_appl_name FOR
444
445
local_appl.zpsap.zpsel.zlen := 0;
446
local_appl.zpsap.zssel.zlen := 0;
447
local_appl.zpsap.ztsel.zlen := 0;
448
local_appl.zpsap.znsap.zlen := 0;
449
local_appl.zappl^name.zlen
450
local_appl.zappl^name.zb
451
local_appl.zappl^name.zlen BYTES;
:= $occurs (local_appl_name);
':=' local_appl_name FOR
452
453
!------------------------------------------------------------------!
454
! The ae_title and src_ae_title parameters are optional parameters !
455
! supplied for example only.
456
!------------------------------------------------------------------!
!
457
458
ae_title.zae^title^type := zaps^val^ae^title^format2;
459
ae_title.zae^title^format2.zae^qualifier^ispresent :=
460
ZAPS^VAL^PRESENT;
461
ae_title.zae^title^format2.zae^qualifier := ae_qualifier;
462
ae_title.zae^title^format2.zap^title.znum^elements := NUM_ELEM;
463
ae_title.zae^title^format2.zap^title.zobj^id ':='
464
ap_title FOR NUM_ELEM WORDS;
465
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 172
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
466
src_ae_title.zae^title^type := zaps^val^ae^title^format2;
467
src_ae_title.zae^title^format2.zae^qualifier^ispresent :=
468
ZAPS^VAL^PRESENT;
469
src_ae_title.zae^title^format2.zae^qualifier := src_ae_qualifier;
470
src_ae_title.zae^title^format2.zap^title.znum^elements := NUM_ELEM;
471
src_ae_title.zae^title^format2.zap^title.zobj^id ':='
472
src_ap_title FOR NUM_ELEM WORDS;
473
474
475
!------------------------------------------------------------------!
476
! Select the functional units required of the source system for
477
! moving the file: read, limited file management (required to read !
478
! files, file attributes, and delete files), and grouping
!
479
! (required for the file-transfer service class).
!
480
!------------------------------------------------------------------!
!
481
482
func_units.zread
:= ZAPS^VAL^TRUE;
483
func_units.zwrite
:= ZAPS^VAL^FALSE;
484
func_units.zfileaccess
:= ZAPS^VAL^FALSE;
485
func_units.zfilemgmt
:= ZAPS^VAL^TRUE;
486
func_units.zfilemgmtenhanced := ZAPS^VAL^FALSE;
487
func_units.zgroup
:= ZAPS^VAL^TRUE;
488
func_units.zfadulock
:= ZAPS^VAL^FALSE;
489
func_units.zrecovery
:= ZAPS^VAL^FALSE;
490
func_units.zrestart
:= ZAPS^VAL^FALSE;
491
492
!------------------------------------------------------------------!
493
! Select the required attribute groups. Since this application
!
494
! reads the source-file attributes, all supported groups
!
495
! are selected. (The private group is not supported.)
!
496
!------------------------------------------------------------------!
497
498
attr_groups.zstorage := ZAPS^VAL^TRUE;
499
attr_groups.zsecurity := ZAPS^VAL^TRUE;
500
attr_groups.zprivate := ZAPS^VAL^FALSE;
501
502
!------------------------------------------------------------------!
503
! Set up the contents-type-list to request a document of
!
504
! type FTAM-3.
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 173
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
505
!------------------------------------------------------------------!
506
507
contents_type_list.zcount := 1;
508
contents_type_list.zcntnts^type^ispresent := ZAPS^VAL^PRESENT;
509contents_type_list.zcntnts^type^list[0].zid:= ZFTM^VAL^CNTNTSLIST^DOCNAME;
510
contents_type_list.zcntnts^type^list[0].zcntntstype.znum^elements
511
:= NUM_ELEM;
512 contents_type_list.zcntnts^type^list[0].zcntntstype.zobj^id ':='
513
ftam_doc_type FOR NUM_ELEM WORDS;
514
515
!------------------------------------------------------------------!
516
! Initialize the initiator-ID, filestore-password, and account
!
517
! parameters according to the requirements of the remote system.
!
518
! The initialization shown here is for example only.
!
519
!------------------------------------------------------------------!
520
521
initiator_id.zlen := $occurs (init_id);
522
initiator_id.zb ':=' init_id FOR initiator_id.zlen BYTES;
523
filestore_password.zlen := $occurs (password);
524
filestore_password.zb ':=' password FOR filestore_password.zlen BYTES;
525
account.zlen := $occurs (charge_account);
526
account.zb ':=' charge_account FOR account.zlen BYTES;
527
528
status := FTM_INITIALIZE_REQ_ ( src_cepi
529
, aplmgr_name
530
, src_appl
531
, wait_mode
532
, local_appl
533
, ae_title
534
, src_ae_title
535
, ! service_class defaults to transfer !
536
, func_units
537
, attr_groups
538
, contents_type_list
539
, initiator_id
540
, account
541
, filestore_password );
542
543
CALL check_status ( src_cepi );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 174
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
544
545
event := ZFTM^VAL^EVT^INITIALIZE^CNF;
546
CALL get_event ( event, src_cepi );
547
548
!------------------------------------------------------------------!
549
! The optional output parameters for local_appl, src_appl, and !
550
! src_ae_title are supplied to the confirm procedure for example !
551
! only. The application returns the OSI addresses in the local_appl !
552
! src_appl parameters, and the AE title of the source responder, in !
553
! the src_ae_title parameter. !
554
!------------------------------------------------------------------!
555
556
error := FTM_INITIALIZE_CNF_ ( src_cepi
557
, state_result
558
, action_result
559
, local_appl
560
, src_appl
561
, src_ae_title
562
, !src_service_class defaults to transfer!
563
, src_func_units
564
, src_attr_groups
565
, src_contents_type_list
566
, diag );
567
568
CALL check_error;
569
CALL check_action_diag;
570
CALL check_state;
571
572
!------------------------------------------------------------------!
573
! The source association has been established. Set the flag that
!
574
! is used in error processing to determine whether a source
!
575
! association exists.
!
576
!------------------------------------------------------------------!
577
578
src_con_established := TRUE;
579
580
!------------------------------------------------------------------!
581
! Verify that the functional units have not been negotiated down
!
582
! from what was requested. If the requested functional units are
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 175
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
583
! not available, discard the association and exit. Additional
!
584
! application-specific error handling or recovery could be
!
585
! implemented if required by an application.
!
586
!------------------------------------------------------------------!
587
IF ( src_func_units.zread <> ZAPS^VAL^TRUE OR
588
src_func_units.zfilemgmt <> ZAPS^VAL^TRUE OR
589
src_func_units.zgroup <> ZAPS^VAL^TRUE ) THEN
590
BEGIN
591
tempbuf ':=' "Functional units unavailable on source association"
592
-> @text_ptr;
593
text_len := @text_ptr - @tempbuf;
594
CALL WRITE ( termnum, outbuf, text_len );
595
596
CALL abort_discard;
597
CALL STOP;
598
END;
599
600
!------------------------------------------------------------------!
601
! Verify that the attribute groups have not been negotiated down
!
602
! from what was requested. If the requested attribute groups are
!
603
! not available, discard the association and exit. Additional
!
604
! application-specific error handling or recovery could be
!
605
! implemented if required by an application.
!
606
!------------------------------------------------------------------!
607
IF ( src_attr_groups.zstorage <> ZAPS^VAL^TRUE OR
608
src_attr_groups.zsecurity <> ZAPS^VAL^TRUE ) THEN
609
BEGIN
610
tempbuf ':=' "Attribute groups unavailable on source association"
611
-> @text_ptr;
612
text_len := @text_ptr - @tempbuf;
613
CALL WRITE ( termnum, outbuf, text_len );
614
615
CALL abort_discard;
616
CALL STOP;
617
END;
618
619
!------------------------------------------------------------------!
620
! Establish the destination-file FTAM regime.
621
!------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 176
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
622
623
!------------------------------------------------------------------!
624
! Set the optional parameter dst_ae_title.
625
!------------------------------------------------------------------!
!
626
627
dst_ae_title.zae^title^type := zaps^val^ae^title^format2;
628
dst_ae_title.zae^title^format2.zae^qualifier^ispresent :=
629
ZAPS^VAL^PRESENT;
630
dst_ae_title.zae^title^format2.zae^qualifier := dst_ae_qualifier;
631
dst_ae_title.zae^title^format2.zap^title.znum^elements := NUM_ELEM;
632
dst_ae_title.zae^title^format2.zap^title.zobj^id ':='
633
dst_ap_title FOR NUM_ELEM WORDS;
634
635
!------------------------------------------------------------------!
636
! Specify the functional units required of the destination system
637
! to write to a file: write, limited file management (required for !
638
! enhanced file management), enhanced file management (required
!
639
! to change file attributes) and grouping (required by the file-
!
640
! transfer service class).
!
641
!------------------------------------------------------------------!
!
642
643
func_units.zread := ZAPS^VAL^FALSE;
644
func_units.zwrite := ZAPS^VAL^TRUE;
645
func_units.zfilemgmt := ZAPS^VAL^TRUE;
646
func_units.zfilemgmtenhanced := ZAPS^VAL^TRUE;
647
func_units.zgroup := ZAPS^VAL^TRUE;
648
649
!------------------------------------------------------------------!
650
! Set the wait mode for the association to wait mode.
651
!------------------------------------------------------------------!
652
653
wait_mode := ZAPS^VAL^WAITED;
654
655
status := FTM_INITIALIZE_REQ_ ( dst_cepi
656
, aplmgr_name
657
, dst_appl
658
, wait_mode
659
, local_appl
660
, ae_title
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 177
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
661
, dst_ae_title
662
, ! service_class defaults to transfer !
663
, func_units
664
, attr_groups
665
, contents_type_list
666
, initiator_id
667
, account
668
, filestore_password );
669
670
CALL check_status ( dst_cepi );
671
672
event := ZFTM^VAL^EVT^INITIALIZE^CNF;
673
CALL get_event ( event, dst_cepi );
674
675
error := FTM_INITIALIZE_CNF_ ( dst_cepi
676
, state_result
677
, action_result
678
, local_appl
679
, dst_appl
680
, dst_ae_title
681
, ! dst_service_class !
682
, dst_func_units
683
, dst_attr_groups
684
, dst_contents_type_list
685
, diag );
686
687
CALL check_error;
688
CALL check_action_diag;
689
CALL check_state;
690
691
!------------------------------------------------------------------!
692
! The destination association has been established. Set the flag
!
693
! that is used in error processing to determine whether an
!
694
! association exists.
!
695
!------------------------------------------------------------------!
696
697
dst_con_established := TRUE;
698
699
!------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 178
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
700
! Verify that the functional units have not been negotiated down
!
701
! from what was requested. If the requested functional units are
!
702
! not available, discard both associations and exit. Additional
!
703
! application-specific error handling or recovery could be
!
704
! implemented if required by an application.
!
705
!------------------------------------------------------------------!
706
IF ( dst_func_units.zwrite <> ZAPS^VAL^TRUE OR
707
dst_func_units.zgroup <> ZAPS^VAL^TRUE OR
708
dst_func_units.zfilemgmt <> ZAPS^VAL^TRUE OR
709
dst_func_units.zfilemgmtenhanced <> ZAPS^VAL^TRUE ) THEN
710
BEGIN
711
tempbuf ':=' "Functional units unavailable on destination association"
712
-> @text_ptr;
713
text_len := @text_ptr - @tempbuf;
714
CALL WRITE ( termnum, outbuf, text_len );
715
716
CALL abort_discard;
717
CALL STOP;
718
END;
719
720
!------------------------------------------------------------------!
721
! Verify that the attribute groups have not been negotiated down
!
722
! from what was requested. If the requested attribute groups are
!
723
! not available, discard both associations and exit. Additional
!
724
! application-specific error handling or recovery could be
!
725
! implemented if required by an application.
!
726
!------------------------------------------------------------------!
727
IF ( dst_attr_groups.zstorage <> ZAPS^VAL^TRUE OR
728
729
730
dst_attr_groups.zsecurity <> ZAPS^VAL^TRUE ) THEN
BEGIN
tempbuf ':=' "Attribute groups unavailable on destination association"
731
-> @text_ptr;
732
text_len := @text_ptr - @tempbuf;
733
CALL WRITE ( termnum, outbuf, text_len );
734
735
736
737
CALL abort_discard;
CALL STOP;
END;
738
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 179
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
739
!------------------------------------------------------------------!
740
! Set the document type in the contents_type structure to FTAM-3.
741
!------------------------------------------------------------------!
742
contents_type.zid := ZFTM^VAL^CNTNTSTYPE^DOCTYPE;
743
contents_type.zdoctype.zdoctypename.znum^elements := NUM_ELEM;
744
contents_type.zdoctype.zdoctypename.zobj^id ':=' ftam_doc_type FOR
745
!
NUM_ELEM WORDS;
746
747
!------------------------------------------------------------------!
748
! Set MSL to present and set to length to 512 bytes.
749
!------------------------------------------------------------------!
750
contents_type.zdoctype.zmaxstringlenispresent := ZAPS^VAL^PRESENT;
751
contents_type.zdoctype.zmaxstringlen := 512D;
!
752
753
!------------------------------------------------------------------!
754
! Set the remaining contents_type.zdoctype elements to
!
755
! ZAPS^VAL^ABSENT.
!
756
!------------------------------------------------------------------!
757
contents_type.zdoctype.zuniversalclassispresent := ZAPS^VAL^ABSENT;
758
contents_type.zdoctype.zstringsigispresent := ZAPS^VAL^ABSENT;
759
contents_type.zdoctype.zfileattrsispresent := ZAPS^VAL^ABSENT;
760
761
!------------------------------------------------------------------!
762
! Establish the source-file file-selection and file-open regimes.
763
!------------------------------------------------------------------!
!
764
765
!------------------------------------------------------------------!
766
! Use the FTM procedures FTM_SELECT_REQ_, FTM_READ_ATTRIB_REQ_,
!
767
! and FTM_OPEN_REQ_ to select the file, read the file attributes,
!
768
! and open the source file. These three requests are processed as
!
769
! a group. Initialize all necessary parameters.
!
770
!------------------------------------------------------------------!
771
772
!------------------------------------------------------------------!
773
! Initialize the parameters for the FTM_SELECT_REQ_ procedure call.!
774
!------------------------------------------------------------------!
775
776
!------------------------------------------------------------------!
777
! Initialize the file name according to the remote system
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 180
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
778
! requirements.
!
779
!------------------------------------------------------------------!
780
781
src_file.zlen := $occurs ( src_filename );
782
src_file.zb ':=' src_filename FOR src_file.zlen BYTES;
783
784
!------------------------------------------------------------------!
785
! Set the requested_access parameter to provide this application
!
786
! with read, read-attribute, and delete access on the remote
!
787
! source file that is being moved.
!
788
!------------------------------------------------------------------!
789
790
requested_access.zread
:= ZAPS^VAL^TRUE;
791
requested_access.zinsert
:= ZAPS^VAL^FALSE;
792
requested_access.zreplace
:= ZAPS^VAL^FALSE;
793
requested_access.zextend
:= ZAPS^VAL^FALSE;
794
requested_access.zerase
:= ZAPS^VAL^FALSE;
795
requested_access.zreadattr := ZAPS^VAL^TRUE;
796
requested_access.zchngattr := ZAPS^VAL^FALSE;
797
requested_access.zdelete
:= ZAPS^VAL^TRUE;
798
799
!------------------------------------------------------------------!
800
! Provide the access password for each action to be performed
!
801
! on the file.
!
802
!------------------------------------------------------------------!
803
804
access_passwords.zreadpasswd.zlen := $occurs (password);
805
access_passwords.zreadpasswd.zb ':=' password FOR
806
access_passwords.zreadpasswd.zlen BYTES;
807
access_passwords.zinsertpasswd.zlen := 0;
808
access_passwords.zreplacepasswd.zlen := 0;
809
access_passwords.zextendpasswd.zlen := 0;
810
access_passwords.zerasepasswd.zlen := 0;
811
access_passwords.zreadattrpasswd.zlen := $occurs (password);
812
access_passwords.zreadattrpasswd.zb ':=' password FOR
813
access_passwords.zreadattrpasswd.zlen BYTES;
814
access_passwords.zchngattrpasswd.zlen := 0;
815
access_passwords.zdeletepasswd.zlen := $occurs (password);
816
access_passwords.zdeletepasswd.zb ':=' password FOR
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 181
NonStop FTAM Programming Examples
817
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
access_passwords.zdeletepasswd.zlen BYTES;
818
819
!------------------------------------------------------------------!
820
!Initialize parameters for the FTM_READ_ATTRIB_REQ_ procedure call.!
821
!------------------------------------------------------------------!
822
823
!------------------------------------------------------------------!
824
! Indicate which file attributes from the kernel and negotiated
!
825
! attribute groups are requested. This application requests all
!
826
! kernel attributes, the file availability and future filesize
!
827
! attributes from the storage group, and access control from the
!
828
! security group.
!
829
!------------------------------------------------------------------!
830
831
! Kernel group !
832
attr_names.zfilename
833
attr_names.zpermittedactions := ZAPS^VAL^TRUE;
834
attr_names.zcntntstype
:= ZAPS^VAL^TRUE;
:= ZAPS^VAL^TRUE;
835
836
! Storage group !
837
!------------------------------------------------------------------!
838
! Set the file-availability and future-filesize attributes to
!
839
! ZAPS^VAL^TRUE.
!
840
!------------------------------------------------------------------!
841
842
attr_names.zfileavlblty := ZAPS^VAL^TRUE;
843
attr_names.zfuturefilesize := ZAPS^VAL^TRUE;
844
845
!------------------------------------------------------------------!
846
! Set the remaining storage attributes to ZAPS^VAL^FALSE.
847
!------------------------------------------------------------------!
848
849
attr_names.zstorageaccount := ZAPS^VAL^FALSE;
850
attr_names.zcreation
:= ZAPS^VAL^FALSE;
851
attr_names.zlastmod
:= ZAPS^VAL^FALSE;
852
attr_names.zlastreadaccess := ZAPS^VAL^FALSE;
853
attr_names.zlastattrmod
:= ZAPS^VAL^FALSE;
854
attr_names.zcreatorid
:= ZAPS^VAL^FALSE;
855
attr_names.zlastmodid
:= ZAPS^VAL^FALSE;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 182
!
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
856
attr_names.zlastreaderid
:= ZAPS^VAL^FALSE;
857
attr_names.zlastattrmodid
:= ZAPS^VAL^FALSE;
858
attr_names.zfilesize
:= ZAPS^VAL^FALSE;
859
860
! security group !
861
!------------------------------------------------------------------!
862
! Set access control to ZAPS^VAL^TRUE.
863
!------------------------------------------------------------------!
!
864
865
attr_names.zaccesscntrl := ZAPS^VAL^TRUE;
866
867
!------------------------------------------------------------------!
868
! Set the remaining security attribute to ZAPS^VAL^FALSE.
869
!------------------------------------------------------------------!
!
870
871
attr_names.zlegalqualif := ZAPS^VAL^FALSE;
872
873
874
! private attributes group is not supported !
875
attr_names.zprivateuse := ZAPS^VAL^FALSE;
876
877
!------------------------------------------------------------------!
878
! Initialize the parameters for the FTM_OPEN_REQ_ procedure call.
879
!------------------------------------------------------------------!
!
880
881
!------------------------------------------------------------------!
882
! Set up the processing mode to perform a read action on the file. !
883
!------------------------------------------------------------------!
884
885
process_mode.zread := ZAPS^VAL^TRUE;
886
process_mode.zinsert := ZAPS^VAL^FALSE;
887
process_mode.zreplace := ZAPS^VAL^FALSE;
888
process_mode.zextend := ZAPS^VAL^FALSE;
889
process_mode.zerase := ZAPS^VAL^FALSE;
890
891
892
!------------------------------------------------------------------!
893
! Initialize the threshold for the begin-group request to indicate !
894
! that all three services (select, read-attributes, and open) must !
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 183
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
895
! be successful for the group to succeed.
!
896
!------------------------------------------------------------------!
897
898
threshold := 3D;
899
900
status := FTM_BEGIN_GROUP_REQ_ ( src_cepi
901
, threshold );
902
903
CALL check_status ( src_cepi );
904
905
status := FTM_SELECT_REQ_ ( src_cepi
906
, src_file
907
, requested_access
908
, access_passwords
909
, account );
910
CALL check_status ( src_cepi );
911
912
status := FTM_READ_ATTRIB_REQ_ ( src_cepi
913
, attr_names );
914
915
CALL check_status ( src_cepi );
916
917
status := FTM_OPEN_REQ_ ( src_cepi
918
, process_mode
919
, contents_type );
920
CALL check_status ( src_cepi );
921
922
status := FTM_END_GROUP_REQ_ ( src_cepi );
923
CALL check_status ( src_cepi );
924
925
!------------------------------------------------------------------!
926
! Call the following procedures to process the confirms returned
!
927
! by each request. The begin-group and end-group requests
!
928
! have separate confirm functions because no values are returned
!
929
! in the corresponding responses; if successful, however, they
!
930
! result in confirm events. Call a get-event for each.
!
931
!------------------------------------------------------------------!
932
event := ZFTM^VAL^EVT^BEGINGROUP^CNF;
933
CALL get_event ( event, src_cepi );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 184
do not
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
934
935
event := ZFTM^VAL^EVT^SELECT^CNF;
936
CALL get_event ( event, src_cepi );
937
error := FTM_SELECT_CNF_ ( src_cepi
938
, state_result
939
, action_result
940
, src_file
941
, diag );
942
CALL check_error;
943
CALL check_action_diag;
944
CALL check_state;
945
946
event := ZFTM^VAL^EVT^READATTR^CNF;
947
CALL get_event ( event, src_cepi );
948
error := FTM_READ_ATTRIB_CNF_ ( src_cepi
949
, action_result
950
, file_attr
951
, diag );
952
CALL check_error;
953
CALL check_action_diag;
954
955
event := ZFTM^VAL^EVT^OPEN^CNF;
956
CALL get_event ( event, src_cepi );
957
error := FTM_OPEN_CNF_ ( src_cepi
958
, state_result
959
, action_result
960
, contents_type
961
, diag );
962
963
CALL check_error;
964
CALL check_action_diag;
965
CALL check_state;
966
967
event := ZFTM^VAL^EVT^ENDGROUP^CNF;
968
CALL get_event ( event, src_cepi );
969
970
!------------------------------------------------------------------!
971
! Establish the destination file-selection and file-open regimes.
972
!------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 185
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
973
974
!------------------------------------------------------------------!
975
! Use the FTM_CREATE_REQ_ and FTM_OPEN_REQ_ procedure calls to
!
976
! create and open the file on the destination system. Send these
!
977
! two requests out as a group. Initialize all necessary parameters !
978
! for the create and open procedures.
979
!------------------------------------------------------------------!
!
980
981
!------------------------------------------------------------------!
982
! Initialize the parameters for the call to FTM_CREATE_REQ_.
983
!------------------------------------------------------------------!
!
984
985
986
!------------------------------------------------------------------!
987
! Set up the initial file attributes for the file to be created.
988
!------------------------------------------------------------------!
!
989
990
! Kernel Group !
991
initial_attr.zfilename.zlen := $occurs (dst_filename);
992
initial_attr.zfilename.zb ':=' dst_filename FOR
993
initial_attr.zfilename.zlen BYTES;
994
initial_attr.zpermittedactions ':=' file_attr.zpermittedactions
995
FOR 1 ELEMENTS;
996
initial_attr.zcntntstypevalue.zid := ZFTM^VAL^CNTNTSTYPE^DOCTYPE;
997
initial_attr.zcntntstypevalue.zdoctype.zdoctypename.znum^elements
998
999
:= NUM_ELEM;
initial_attr.zcntntstypevalue.zdoctype.zdoctypename.zobj^id
1000
1001
':=' ftam_doc_type FOR NUM_ELEM WORDS;
initial_attr.zcntntstypevalue.zdoctype.zuniversalclassispresent
1002
1003
:= ZAPS^VAL^ABSENT;
initial_attr.zcntntstypevalue.zdoctype.zmaxstringlenispresent
1004
:= file_attr.zcntntstypevalue.zdoctype.
1005
zmaxstringlenispresent;
1006
initial_attr.zcntntstypevalue.zdoctype.zmaxstringlen
1007
1008
1009
1010
1011
:= file_attr.zcntntstypevalue.zdoctype.
zmaxstringlen;
initial_attr.zcntntstypevalue.zdoctype.zstringsigispresent
:= file_attr.zcntntstypevalue.zdoctype.
zstringsigispresent;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 186
NonStop FTAM Programming Examples
1012
initial_attr.zcntntstypevalue.zdoctype.zstringsig
1013
:= file_attr.zcntntstypevalue.zdoctype.
1014
1015
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
zstringsig;
initial_attr.zcntntstypevalue.zdoctype.zfileattrsispresent
1016
:= ZAPS^VAL^ABSENT;
1017
1018
! Storage group !
1019
initial_attr.zstorageaccountispresent := ZAPS^VAL^ABSENT;
1020
initial_attr.zfileavlbltyattrispresent := ZAPS^VAL^PRESENT;
1021
initial_attr.zfileavlbltyattr.zid := ZFTM^VAL^ATTR^ISPRESENT;
1022initial_attr.zfileavlbltyattr.zfileavlblty := ZFTM^VAL^FILEAVLBLTY^IMMED;
1023
initial_attr.zfuturefilesizeispresent := ZAPS^VAL^PRESENT;
1024
initial_attr.zfuturefilesize.zid := ZFTM^VAL^ATTR^ISPRESENT;
1025
initial_attr.zfuturefilesize.zfilesize := file_attr.
1026
zfuturefilesize.zfilesize;
1027
1028
! Security Group !
1029
initial_attr.zaccesscntrlattrispresent := ZAPS^VAL^PRESENT;
1030
1031
!------------------------------------------------------------------!
1032
! Set the next two attributes to allow write and change-attribute
!
1033
! capabilities during the move. The procedure applies the
!
1034
! original attributes that were read from the source file to the
!
1035
! destination file after the move is complete.
!
1036
!------------------------------------------------------------------!
1037
1038
initial_attr.zaccesscntrlattr.zid := ZFTM^VAL^ATTR^ISPRESENT;
1039
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zreplace :=
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
ZAPS^VAL^TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zchngattr :=
ZAPS^VAL^TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zread :=
ZAPS^VAL^TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zactionlist.zdelete :=
ZAPS^VAL^TRUE;
initial_attr.zaccesscntrlattr.zaccesscntrl.zconcurrencyispresent :=
ZAPS^VAL^ABSENT;
initial_attr.zaccesscntrlattr.zaccesscntrl.zidentityispresent :=
ZAPS^VAL^ABSENT;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 187
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1051
initial_attr.zaccesscntrlattr.zaccesscntrl.zpasswdsispresent :=
1052
1053
ZAPS^VAL^ABSENT;
initial_attr.zaccesscntrlattr.zaccesscntrl.zlocationispresent :=
1054
1055
ZAPS^VAL^ABSENT;
initial_attr.zlegalqualifispresent := ZAPS^VAL^ABSENT;
1056
1057
!------------------------------------------------------------------!
1058
! Specify that the application is to delete the named file if it
!
1059
! exists and create a new file using the attributes specified in
!
1060
! the initial_attr parameter.
!
1061
!------------------------------------------------------------------!
1062
1063
override := ZFTM^VAL^OVR^CREATE^NEW;
1064
1065
1066
!------------------------------------------------------------------!
1067
! Set the requested_access parameter to provide replace and
!
1068
! change attribute access on the file.
!
1069
!------------------------------------------------------------------!
1070
1071
requested_access.zread
:= ZAPS^VAL^FALSE;
1072
requested_access.zreplace
:= ZAPS^VAL^TRUE;
1073
requested_access.zreadattr := ZAPS^VAL^FALSE;
1074
requested_access.zchngattr := ZAPS^VAL^TRUE;
1075
requested_access.zdelete
:= ZAPS^VAL^FALSE;
1076
1077
!------------------------------------------------------------------!
1078
! Provide the access password for each action to be performed on
!
1079
! the file.
!
1080
!------------------------------------------------------------------!
1081
1082
access_passwords.zreadpasswd.zlen
:= 0;
1083
access_passwords.zinsertpasswd.zlen
:= 0;
1084
access_passwords.zreplacepasswd.zlen
:= $occurs(password);
1085
access_passwords.zreplacepasswd.zb
1086
':=' password FOR
access_passwords.zreplacepasswd.zlen BYTES;
1087
access_passwords.zextendpasswd.zlen
:= 0;
1088
access_passwords.zerasepasswd.zlen
:= 0;
1089
access_passwords.zreadattrpasswd.zlen := 0;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 188
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1090
access_passwords.zchngattrpasswd.zlen := $occurs(password);
1091
access_passwords.zchngattrpasswd.zb ':=' password FOR
1092
1093
access_passwords.zchngattrpasswd.zlen BYTES;
access_passwords.zdeletepasswd.zlen
:= 0;
1094
1095
!------------------------------------------------------------------!
1096
! Initialize parameters for the FTM_OPEN_REQ_ procedure call.
1097
!------------------------------------------------------------------!
!
1098
1099
!------------------------------------------------------------------!
1100
!Set up the processing mode to perform a replace action on the file.!
1101
!------------------------------------------------------------------!
1102
1103
process_mode.zread
:= ZAPS^VAL^FALSE;
1104
process_mode.zinsert
:= ZAPS^VAL^FALSE;
1105
process_mode.zreplace := ZAPS^VAL^TRUE;
1106
process_mode.zextend
:= ZAPS^VAL^FALSE;
1107
process_mode.zerase
:= ZAPS^VAL^FALSE;
1108
1109
!------------------------------------------------------------------!
1110
! Initialize the threshold for the begin-group request to specify
!
1111
! that both services (create and open) must be successful for the
!
1112
! group to succeed.
!
1113
!------------------------------------------------------------------!
1114
1115
threshold := 2D;
1116
1117
status := FTM_BEGIN_GROUP_REQ_ ( dst_cepi
1118
1119
, threshold );
CALL check_status ( dst_cepi );
1120
1121
status := FTM_CREATE_REQ_ ( dst_cepi
1122
, initial_attr
1123
, override
1124
, filestore_password
1125
, requested_access
1126
, access_passwords
1127
, account );
1128
CALL check_status ( dst_cepi );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 189
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1129
1130
status := FTM_OPEN_REQ_ ( dst_cepi
1131
, process_mode
1132
, contents_type );
1133
CALL check_status ( dst_cepi );
1134
1135
status := FTM_END_GROUP_REQ_ ( dst_cepi );
1136
CALL check_status ( dst_cepi );
1137
1138
!------------------------------------------------------------------!
1139
! Call the following procedures to process the confirms
!
1140
! returned by each request. The begin-group and end-group
!
1141
!requests do not have separate confirm function but, if successful,!
1142
! they result in confirm events. Call a get_event for each.
1143
!------------------------------------------------------------------!
1144
1145
event := ZFTM^VAL^EVT^BEGINGROUP^CNF;
1146
CALL get_event ( event, dst_cepi );
1147
1148
event := ZFTM^VAL^EVT^CREATE^CNF;
1149
CALL get_event ( event, dst_cepi );
1150
error := FTM_CREATE_CNF_ ( dst_cepi
1151
, state_result
1152
, action_result
1153
, initial_attr
1154
, diag );
1155
CALL check_error;
1156
1157
CALL check_action_diag;
1158
CALL check_state;
1159
1160
event := ZFTM^VAL^EVT^OPEN^CNF;
1161
CALL get_event ( event, dst_cepi );
1162
error := FTM_OPEN_CNF_ ( dst_cepi
1163
, state_result
1164
, action_result
1165
, contents_type
1166
, diag );
1167
CALL check_error;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 190
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1168
CALL check_action_diag;
1169
CALL check_state;
1170
1171
event := ZFTM^VAL^EVT^ENDGROUP^CNF;
1172
CALL get_event ( event, dst_cepi );
1173
1174
!------------------------------------------------------------------!
1175
! Establish the source-file and destination-file data-transfer
!
1176
! regimes.
!
1177
!------------------------------------------------------------------!
1178
1179
!------------------------------------------------------------------!
1180
! Initialize the parameters for the FTM_WRITE_REQ_ and
!
1181
! FTM_READ_REQ_ procedures.
!
1182
!------------------------------------------------------------------!
1183
1184
!------------------------------------------------------------------!
1185
! Set the dst_fadu_op parameter to replace the destination-file
!
1186
! contents.
!
1187
!------------------------------------------------------------------!
1188
1189
dst_fadu_op := ZFTM^VAL^FADU^OP^REPLACE;
1190
1191
!------------------------------------------------------------------!
1192
! To establish a position at the beginning of an FTAM-3 type file, !
1193
! specify a FADU of "first."
1194
!------------------------------------------------------------------!
!
1195
1196
dst_fadu_id.zid
:= ZFTM^VAL^FADUID^FIRSTLAST;
1197
dst_fadu_id.zfirstlast := ZFTM^VAL^FADUID^FIRST;
1198
1199
src_fadu_id.zid
:= ZFTM^VAL^FADUID^FIRSTLAST;
1200
src_fadu_id.zfirstlast := ZFTM^VAL^FADUID^FIRST;
1201
1202
!------------------------------------------------------------------!
1203
! The access context for an FTAM-3 file is always "unstructured
!
1204
! access."
!
1205
!------------------------------------------------------------------!
1206
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 191
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1207
access_context.zcntxt := ZFTM^VAL^ACCESSCNTXT^UA;
1208
access_context.zlevelnumispresent := ZAPS^VAL^ABSENT;
1209
1210
status := FTM_WRITE_REQ_ ( dst_cepi
1211
, dst_fadu_op
1212
, dst_fadu_id );
1213
CALL check_status ( dst_cepi );
1214
1215
status := FTM_READ_REQ_ ( src_cepi
1216
, src_fadu_id
1217
, access_context );
1218
CALL check_status ( src_cepi );
1219
1220
1221
!------------------------------------------------------------------!
1222
! Wait for a data indication from the source association. As each
!
1223
! indication is received, call FTM_DATA_IND_ to retrieve the data
!
1224
! and then FTM_DATA_REQ_ to send the data to the destination
!
1225
! system.
!
1226
!
!
1227
! Repeat this process until a data-end indication arrives from the !
1228
! source or a cancel or abort indication is received from either
!
1229
! system.
!
1230
!------------------------------------------------------------------!
1231
1232
DO
1233
BEGIN
1234
1235
!------------------------------------------------------------------!
1236
! Wait for either a data indication, a data-end indication, or a
!
1237
! cancel indication from the source system. Set event to ANYEVENT
!
1238
! since more than one event code is valid.
!
1239
!------------------------------------------------------------------!
1240
1241
event := ANYEVENT;
1242
CALL get_event ( event, src_cepi );
1243
1244
IF ( event = ZFTM^VAL^EVT^DATA^IND ) THEN
1245
BEGIN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 192
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1246
1247
src_more_data := 1D;
1248
src_start_position := 0D;
1249
1250
WHILE ( src_more_data <> 0D ) DO
1251
BEGIN
1252
!--------------------------------------------------------------!
1253
! Call FTM_DATA_IND_ to read data from the source system.
1254
!--------------------------------------------------------------!
!
1255
1256
error := FTM_DATA_IND_ ( src_cepi
1257
, $dbl(MAX_BUF)
1258
, data_value_ptr
1259
, src_more_data
1260
, src_next_position
1261
, src_start_position );
1262
CALL check_error;
1263
1264
!--------------------------------------------------------------!
1265
! Call FTM_DATA_REQ_ to write data to the remote system.
1266
!--------------------------------------------------------------!
!
1267
1268
status := FTM_DATA_REQ_ ( dst_cepi
1269
, data_value_ptr );
1270
CALL check_status ( dst_cepi );
1271
1272
1273
1274
src_start_position := src_next_position;
END;
END
1275
1276
1277
ELSE IF ( event = ZFTM^VAL^EVT^DATAEND^IND ) THEN
1278
BEGIN
1279
1280
!---------------------------------------------------------------!
1281
! Call the data-end indication procedure to check the error
!
1282
! status and action result. Then call FTM_DATA_END_REQ_
!
1283
! to notify the destination system that the data transfer has
!
1284
! ended.
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 193
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1285
!---------------------------------------------------------------!
1286
1287
error := FTM_DATA_END_IND_ ( src_cepi
1288
, action_result
1289
, diag );
1290
CALL check_error;
1291
CALL check_action_diag;
1292
1293
status := FTM_DATA_END_REQ_ ( dst_cepi
1294
, action_result );
1295
CALL check_status ( dst_cepi );
1296
1297
1298
END
1299
1300
1301
ELSE IF ( event = ZFTM^VAL^EVT^CANCEL^IND ) THEN
1302
BEGIN
1303
1304
!---------------------------------------------------------------!
1305
! The source system has cancelled the transfer. Call the
!
1306
! indication procedure to get the error and action result, and
!
1307
! then send a response to the source system. Finally, send a
!
1308
! cancel request to the destination system and wait for the
!
1309
! confirm. This terminates the data-transfer regimes.
!
1310
! Additional application-specific error handling could be
!
1311
! implemented if required by an application.
!
1312
!---------------------------------------------------------------!
1313
1314
error := FTM_CANCEL_IND_ ( src_cepi
1315
, action_result
1316
, diag );
1317
CALL check_error;
1318
CALL check_action_diag;
1319
1320
1321
1322
status := FTM_CANCEL_RSP_ ( src_cepi
, ! action_result ! );
CALL check_status ( src_cepi );
1323
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 194
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1324
status := FTM_CANCEL_REQ_ ( dst_cepi
1325
, action_result
1326
, diag );
1327
CALL check_status ( dst_cepi );
1328
1329
event := ZFTM^VAL^EVT^CANCEL^CNF;
1330
CALL get_event ( event, dst_cepi );
1331
error := FTM_CANCEL_CNF_ ( dst_cepi
1332
, action_result
1333
, diag );
1334
CALL check_error;
1335
CALL check_action_diag;
1336
1337
END
1338
1339
1340
ELSE
1341
BEGIN
1342
1343
CALL bad_event ( event, src_cepi );
END;
1344
1345
END
1346
UNTIL ( event <> ZFTM^VAL^EVT^DATA^IND );
1347
1348
! End of file-transfer loop !
1349
1350
1351
!------------------------------------------------------------------!
1352
! Issue an FTM_TRANSFER_END_REQ_ call to the source and destination!
1353
! systems and wait for the respective confirms. This terminates
!
1354
! the data-transfer regime for each association.
!
1355
!------------------------------------------------------------------!
1356
1357
!------------------------------------------------------------------!
1358
! When a cancel occurs, the data-transfer regime is terminated.
!
1359
! Skip the next section if a cancel took place.
!
1360
!------------------------------------------------------------------!
1361
1362
IF ( event <> ZFTM^VAL^EVT^CANCEL^CNF ) THEN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 195
NonStop FTAM Programming Examples
1363
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
BEGIN
1364
1365
!------------------------------------------------------------------!
1366
! Terminate the source-file data-transfer regime.
1367
!------------------------------------------------------------------!
!
1368
1369
status := FTM_TRANSFER_END_REQ_ ( src_cepi );
1370
CALL check_status ( src_cepi );
1371
1372
event := ZFTM^VAL^EVT^TRANSEND^CNF;
1373
CALL get_event ( event, src_cepi );
1374
error := FTM_TRANSFER_END_CNF_ ( src_cepi
1375
, action_result
1376
, diag );
1377
CALL check_error;
1378
CALL check_action_diag;
1379
1380
!------------------------------------------------------------------!
1381
! Terminate the destination-file data-transfer regime.
1382
!------------------------------------------------------------------!
!
1383
1384
status := FTM_TRANSFER_END_REQ_ ( dst_cepi );
1385
CALL check_status ( dst_cepi );
1386
1387
event := ZFTM^VAL^EVT^TRANSEND^CNF;
1388
CALL get_event ( event, dst_cepi );
1389
error := FTM_TRANSFER_END_CNF_ ( dst_cepi
1390
, action_result
1391
, diag );
1392
CALL check_error;
1393
CALL check_action_diag;
1394
1395
END;
1396
1397
1398
!------------------------------------------------------------------!
1399
!Terminate the destination-file file-open and file-selection regimes!
1400
!------------------------------------------------------------------!
1401
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 196
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1402
!------------------------------------------------------------------!
1403
! Close the file on the destination system, change the attributes, !
1404
! and then deselect the file. These three primitives must also
!
1405
! be grouped since the file-transfer service class was negotiated
!
1406
! for the association.
!
1407
!------------------------------------------------------------------!
1408
1409
!------------------------------------------------------------------!
1410
! Set the following parameters so the destination file attributes
!
1411
! match the source file.
!
1412
!------------------------------------------------------------------!
1413
1414
change_attr.zattrsarepresent := ZAPS^VAL^PRESENT;
1415
1416
IF ( file_attr.zaccesscntrlattrispresent = ZAPS^VAL^PRESENT ) THEN
1417
BEGIN
1418
change_attr.zaccesscntrlispresent := ZAPS^VAL^PRESENT;
1419
change_attr.zaccesscntrl ':=' file_attr.zaccesscntrlattr
1420
FOR 1 ELEMENTS;
1421
END
1422
ELSE
1423
BEGIN
1424
1425
change_attr.zaccesscntrlispresent := ZAPS^VAL^ABSENT;
END;
1426
1427
!------------------------------------------------------------------!
1428
! Initialize the threshold for the begin-group request to indicate !
1429
! that all three services (close, change attributes, and deselect) !
1430
! must be successful for the group to succeed.
1431
!------------------------------------------------------------------!
1432
1433
threshold := 3D;
1434
status := FTM_BEGIN_GROUP_REQ_ ( dst_cepi
1435
1436
, threshold );
CALL check_status ( dst_cepi );
1437
1438
status := FTM_CLOSE_REQ_ ( dst_cepi );
1439
CALL check_status ( dst_cepi );
1440
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 197
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1441
status := FTM_CHANGE_ATTRIB_REQ_ ( dst_cepi
1442
1443
, change_attr );
CALL check_status ( dst_cepi );
1444
1445
status := FTM_DESELECT_REQ_ ( dst_cepi );
1446
CALL check_status ( dst_cepi );
1447
1448
status := FTM_END_GROUP_REQ_ ( dst_cepi );
1449
CALL check_status ( dst_cepi );
1450
1451
1452
!------------------------------------------------------------------!
1453
! Call the following procedures to process the confirms returned
!
1454
! in response to each request. The begin-group and end-group
!
1455
! requests do not have separate confirm procedures, but if
!
1456
!successful, they result in confirm events. Call get_event for each.!
1457
!------------------------------------------------------------------!
1458
1459
event := ZFTM^VAL^EVT^BEGINGROUP^CNF;
1460
CALL get_event ( event, dst_cepi );
1461
1462
event := ZFTM^VAL^EVT^CLOSE^CNF;
1463
CALL get_event ( event, dst_cepi );
1464
error := FTM_CLOSE_CNF_ ( dst_cepi
1465
, action_result
1466
, diag );
1467
CALL check_error;
1468
CALL check_action_diag;
1469
1470
event := ZFTM^VAL^EVT^CHANGEATTR^CNF;
1471
CALL get_event ( event, dst_cepi );
1472
error := FTM_CHANGE_ATTRIB_CNF_ ( dst_cepi
1473
, action_result
1474
, change_attr
1475
, diag );
1476
CALL check_error;
1477
CALL check_action_diag;
1478
1479
event := ZFTM^VAL^EVT^DESELECT^CNF;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 198
NonStop FTAM Programming Examples
1480
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
CALL get_event ( event, dst_cepi );
1481
1482
!------------------------------------------------------------------!
1483
! The charging parameter is used to convey information about costs !
1484
! attributed to the account. This parameter should be used only
!
1485
! if the account parameter was used in the FTM_CREATE_REQ_ call.
!
1486
! The information returned in the charging parameter is not used
!
1487
! in this example.
!
1488
!------------------------------------------------------------------!
1489
1490
error := FTM_DESELECT_CNF_ ( dst_cepi
1491
, action_result
1492
, dst_charging
1493
, diag );
1494
CALL check_error;
1495
CALL check_action_diag;
1496
1497
event := ZFTM^VAL^EVT^ENDGROUP^CNF;
1498
CALL get_event ( event, dst_cepi );
1499
1500
1501
!------------------------------------------------------------------!
1502
! Terminate the source-file file-open and file-selection regimes.
1503
!------------------------------------------------------------------!
!
1504
1505
1506
!------------------------------------------------------------------!
1507
! Issue a close and delete request for the source file. The delete !
1508
! is used since this example is moving the file, not simply
!
1509
! copying it.
!
1510
!------------------------------------------------------------------!
1511
1512
!------------------------------------------------------------------!
1513
! Initialize the threshold for the begin-group request to indicate !
1514
! that both services (close and delete) must be successful for the !
1515
! group to succeed.
1516
!------------------------------------------------------------------!
1517
1518
threshold := 2D;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 199
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1519
1520
status := FTM_BEGIN_GROUP_REQ_ ( src_cepi
1521
1522
, threshold );
CALL check_status ( src_cepi );
1523
1524
status := FTM_CLOSE_REQ_ ( src_cepi );
1525
CALL check_status ( src_cepi );
1526
1527
status := FTM_DELETE_REQ_ ( src_cepi );
1528
CALL check_status ( src_cepi );
1529
1530
status := FTM_END_GROUP_REQ_ ( src_cepi );
1531
CALL check_status ( src_cepi );
1532
1533
!------------------------------------------------------------------!
1534
! Call the following procedures to process the confirms returned in!
1535
! response to each request. The begin-group and end-group requests !
1536
! do not have separate confirm functions, but if successful,
!
1537
! they result in confirm events. Call get_event for each.
!
1538
!------------------------------------------------------------------!
1539
1540
event := ZFTM^VAL^EVT^BEGINGROUP^CNF;
1541
CALL get_event ( event, src_cepi );
1542
1543
event := ZFTM^VAL^EVT^CLOSE^CNF;
1544
CALL get_event ( event, src_cepi );
1545
error := FTM_CLOSE_CNF_ ( src_cepi
1546
, action_result
1547
, diag );
1548
CALL check_error;
1549
CALL check_action_diag;
1550
1551
event := ZFTM^VAL^EVT^DELETE^CNF;
1552
CALL get_event ( event, src_cepi );
1553
1554
!------------------------------------------------------------------!
1555
! The charging parameter is used to convey information about costs !
1556
! attributed to the account. This parameter should be used only
!
1557
! if the account parameter was used in the FTM_SELECT_REQ_ call.
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 200
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1558
! The information returned in the charging parameter is not used
!
1559
! in this example.
!
1560
!------------------------------------------------------------------!
1561
1562
error := FTM_DELETE_CNF_ ( src_cepi
1563
, action_result
1564
, src_charging
1565
, diag );
1566
CALL check_error;
1567
CALL check_action_diag;
1568
1569
event := ZFTM^VAL^EVT^ENDGROUP^CNF;
1570
CALL get_event ( event, src_cepi );
1571
1572
!------------------------------------------------------------------!
1573
! Terminate the source-file FTAM regime.
1574
!------------------------------------------------------------------!
!
1575
1576
status := FTM_TERMINATE_REQ_ ( src_cepi );
1577
CALL check_status ( src_cepi );
1578
1579
event := ZFTM^VAL^EVT^TERMINATE^CNF;
1580
CALL get_event ( event, src_cepi );
1581
1582
!------------------------------------------------------------------!
1583
! The charging parameter is used to convey information about costs !
1584
! attributed to the account. This parameter should be used only if !
1585
! the account parameter was used in the FTM_INITIALIZE_REQ_ call.
!
1586
! The information returned in the charging parameter is not used
!
1587
! in this example.
!
1588
!------------------------------------------------------------------!
1589
1590
error := FTM_TERMINATE_CNF_ ( src_cepi
1591
, src_charging );
1592
1593
CALL check_error;
1594
1595
!------------------------------------------------------------------!
1596
! Terminate the destination-file FTAM regime.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 201
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1597
!------------------------------------------------------------------!
1598
1599
status := FTM_TERMINATE_REQ_ ( dst_cepi );
1600
CALL check_status ( dst_cepi );
1601
1602
event := ZFTM^VAL^EVT^TERMINATE^CNF;
1603
CALL get_event ( event, dst_cepi );
1604
1605
error := FTM_TERMINATE_CNF_ ( dst_cepi
1606
, ! charging ! );
1607
1608
CALL check_error;
1609
1610
!------------------------------------------------------------------!
1611
! Discard the API context information for the source association.
1612
!-------------------------------------------------------------------!
!
1613
1614
status := APS_DISCARD_ ( src_cepi );
1615
CALL check_status ( src_cepi );
1616
1617
1618
1619
!------------------------------------------------------------------!
! Discard the API context information for the destination association.!
!------------------------------------------------------------------!
1620
1621
status := APS_DISCARD_ ( dst_cepi );
1622
CALL check_status ( dst_cepi );
1623
1624
!------------------------------------------------------------------!
1625
! Display a message to the terminal that the program completed
!
1626
! successfully.
!
1627
!------------------------------------------------------------------!
1628
1629
tempbuf ':=' "File move complete" -> @text_ptr;
1630
text_len := @text_ptr - @tempbuf;
1631
CALL WRITE ( termnum, outbuf, text_len );
1632
1633 END; --- MOVEFILE --1634
1635
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 202
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1636 ?PAGE "GET_EVENT"
1637 !---------------------------------------------------------------------!
1638 !
!
1639 ! Name:
get_event
!
1640 !
!
1641 ! Description: The get_event procedure gets an available event. It
!
1642 !
verifies that the event is the expected event and
!
1643 !
that there are no errors associated with it. If an
!
1644 !
unexpected event is received, it calls bad_event to
!
1645 !
process the error.
!
1646 !
!
1647 ! Input:
Expected_event, the event that is expected to be
!
1648 !
received on the association
!
1649 !
!
1650 !
CEPI identifying the association that carries the
!
1651 !
event
!
1652 !
!
1653 ! Output:
expected_event, which contains the received event
1654 !
!
!
1655 !---------------------------------------------------------------------!
1656
1657 PROC get_event ( expected_event, cepi );
1658
1659 INT .EXT expected_event;
1660 INT cepi;
1661
1662 BEGIN
1663
INT event;
1664
INT .EXT event_code := $XADR(event);
1665
1666
!------------------------------------------------------------------!
1667
! Wait for an event to be received.
1668
!------------------------------------------------------------------!
!
1669
1670
status := APS_EVENT_RECEIVE_ ( cepi, WAIT_FOREVER );
1671
1672
IF ( status <> ZAPS^VAL^STATUS^EVENT ) THEN
1673
BEGIN
1674
!----------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 203
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1675
! A bad status has been received.
!
1676
!----------------------------------------------------------------!
1677
1678
1679
CALL check_status ( cepi );
END;
1680
1681
!------------------------------------------------------------------!
1682
! Get the event code.
1683
!------------------------------------------------------------------!
!
1684
1685
error := APS_STATUS_ ( cepi
1686
1687
, event_code );
CALL check_error;
1688
1689
!------------------------------------------------------------------!
1690
! Verify that the expected event was received. If the expected
!
1691
! event = ANYEVENT, then any event code is valid.
!
1692
!------------------------------------------------------------------!
1693
1694
IF ( event_code <> expected_event) AND
1695
( expected_event <> ANYEVENT ) THEN
1696
1697
1698
BEGIN
CALL bad_event ( event_code, cepi );
END;
1699
1700
!-----------------------------------------------------------------!
1701
! Return the received event code to the caller.
1702
!-----------------------------------------------------------------!
1703
IF ( expected_event = ANYEVENT ) THEN
1704
!
expected_event := event_code;
1705
1706 END; -- get_event -1707
1708
1709 ?PAGE "CHECK_STATUS"
1710 !---------------------------------------------------------------------!
1711 !
!
1712 ! Name:
check_status
1713 !
!
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 204
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1714 ! Description: The check_status procedure checks the status returned
!
1715 !
from an FTM or APS procedure call. It checks for
!
1716 !
NORETRY, RETRYLATER, and DISCARD. If status is OK,
!
1717 !
it returns control to the main program. If status
!
1718 !
is not OK, it displays a message, discards the
!
1719 !
associations and exits the program.
!
1720 !
!
1721 ! Input:
CEPI identifying the association whose status is
!
1722 !
being checked
!
1723 !
!
1724 ! Output:
Error messages to terminal
1725 !
!
!
1726 !---------------------------------------------------------------------!
1727
1728 PROC check_status ( cepi );
1729
1730 INT cepi;
1731
1732 BEGIN
1733
1734
!------------------------------------------------------------------!
1735
! Check for a good status.
1736
!------------------------------------------------------------------!
!
1737
1738
IF ( status = ZAPS^VAL^STATUS^OK ) THEN
1739
BEGIN
1740
1741
RETURN;
END;
1742
1743
!------------------------------------------------------------------!
1744
! Get the error code and error subcode values.
1745
!------------------------------------------------------------------!
1746
1747
error := APS_STATUS_ ( cepi
1748
, ! event_code !
1749
, ! device_name !
1750
, error_code
1751
, error_subcode
1752
, ! service_id !
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 205
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1753
, ! diagnostic_buffer !
1754
, original_error_info );
1755
1756
CALL check_error;
1757
1758
!------------------------------------------------------------------!
1759
! Display the status code.
1760
!------------------------------------------------------------------!
!
1761
1762
tempbuf ':=' "STATUS # " -> @text_ptr;
1763
IF (status < 0) THEN
1764
BEGIN
1765
status := -status;
1766
text_ptr ':=' "-" -> @text_ptr;
1767
END;
1768
1769
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1770
, $DBL ( status )
1771
, BASE );
1772
text_len := @text_ptr - @tempbuf;
1773
CALL WRITE ( termnum, outbuf, text_len );
1774
1775
!------------------------------------------------------------------!
1776
! Display the error code and subcode.
1777
!------------------------------------------------------------------!
1778
1779
tempbuf ':=' "ERROR # " -> @text_ptr;
1780
IF (error_code < 0) THEN
1781
BEGIN
1782
error_code := -error_code;
1783
text_ptr ':=' "-" -> @text_ptr;
1784
END;
1785
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1786
, $DBL ( error_code )
1787
, BASE );
1788
text_len := @text_ptr - @tempbuf;
1789
CALL WRITE ( termnum, outbuf, text_len );
1790
1791
tempbuf ':=' "ERROR SUBCODE # " -> @text_ptr;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 206
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
1792
IF (error_subcode < 0) THEN
1793
BEGIN
1794
error_subcode := -error_subcode;
1795
text_ptr ':=' "-" -> @text_ptr;
1796
END;
1797
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1798
, $DBL ( error_subcode )
1799
, BASE );
1800
text_len := @text_ptr - @tempbuf;
1801
CALL WRITE ( termnum, outbuf, text_len );
1802
1803
!------------------------------------------------------------------!
1804
! Display the original error code and original error subcode.
1805
!------------------------------------------------------------------!
!
1806
1807
tempbuf ':=' "ORIGINAL ERROR INFO - " -> @text_ptr;
1808
text_len := @text_ptr - @tempbuf;
1809
CALL WRITE ( termnum, outbuf, text_len );
1810
1811
tempbuf ':=' " SERVICE ID # " -> @text_ptr;
1812
@text_ptr := @text_ptr
1813
+ DNUMOUT ( text_ptr
1814
, $DBL ( original_error_info.zerror.zservice^id )
1815
, BASE );
1816
text_len := @text_ptr - @tempbuf;
1817
CALL WRITE ( termnum, outbuf, text_len );
1818
1819
tempbuf ':=' " ERROR CODE # " -> @text_ptr;
1820
IF ( original_error_info.zerror.zerror^code < 0) THEN
1821
BEGIN
1822
original_error_info.zerror.zerror^code
1823
1824
:= -original_error_info.zerror.zerror^code;
text_ptr ':=' "-" -> @text_ptr;
1825
END;
1826
@text_ptr := @text_ptr
1827
+ DNUMOUT ( text_ptr
1828
, $DBL ( original_error_info.zerror.zerror^code )
1829
, BASE );
1830
text_len := @text_ptr - @tempbuf;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 207
NonStop FTAM Programming Examples
1831
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
CALL WRITE ( termnum, outbuf, text_len );
1832
1833
tempbuf ':=' " ERROR SUBCODE # " -> @text_ptr;
1834
IF ( original_error_info.zerror.zerror^subcode < 0) THEN
1835
BEGIN
1836
original_error_info.zerror.zerror^subcode
1837
1838
:= -original_error_info.zerror.zerror^subcode;
text_ptr ':=' "-" -> @text_ptr;
1839
END;
1840
@text_ptr := @text_ptr
1841
+ DNUMOUT ( text_ptr
1842
, $DBL ( original_error_info.zerror.zerror^subcode )
1843
, BASE );
1844
text_len := @text_ptr - @tempbuf;
1845
CALL WRITE ( termnum, outbuf, text_len );
1846
1847
!------------------------------------------------------------------!
1848
! Perform error handling, depending on the status value returned.
1849
! Additional application-specific error handling or recovery could !
1850
! be implemented depending on application requirements.
1851
!------------------------------------------------------------------!
!
!
1852
1853
CASE status OF
1854
BEGIN
1855
1856
ZAPS^VAL^STATUS^NO^RETRY,
1857
ZAPS^VAL^STATUS^RETRY^LATER ->
1858
BEGIN
1859
1860
!--------------------------------------------------------------!
1861
! The status indicates an error was detected. This
!
1862
! application aborts both associations and exits the program.
!
1863
!--------------------------------------------------------------!
1864
1865
CALL abort_discard;
1866
1867
CALL STOP;
1868
1869
END;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 208
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1870
1871
ZAPS^VAL^STATUS^DISCARD ->
1872
BEGIN
1873
!---------------------------------------------------------------!
1874
! A status of DISCARD returned on an FTM request indicates
!
1875
! that the association associated with that CEPI has been
!
1876
! lost. Set the appropriate control flag to indicate the
!
1877
! association is lost and call abort_discard to abort the
!
1878
! other association.
!
1879
!---------------------------------------------------------------!
1880
1881
! Determine which association has been lost. !
1882
IF ( cepi = src_cepi ) THEN
1883
BEGIN
1884
src_con_established := FALSE;
1885
END
1886
ELSE
1887
BEGIN
1888
1889
dst_con_established := FALSE;
END;
1890
1891
CALL abort_discard;
1892
1893
CALL STOP;
1894
1895
END;
1896
1897
OTHERWISE -> ! unknown status value !
1898
1899
tempbuf ':=' "Unknown Status" -> @text_ptr;
1900
text_len := @text_ptr - @tempbuf;
1901
CALL WRITE ( termnum, outbuf, text_len );
1902
CALL ABEND;
1903
1904
END;
1905
1906 END; -- check_status -1907
1908
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 209
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1909 ?PAGE "CHECK_ERROR"
1910 !---------------------------------------------------------------------!
1911 !
!
1912 ! Name:
check_error
!
1913 !
!
1914 ! Description: The check_error procedure checks error codes
!
1915 !
returned by FTM procedure calls. If an error
!
1916 !
code indicates that an error occurred, this
!
1917 !
procedure displays a message, then aborts the
!
1918 !
associations to the two remote systems, and exits
!
1919 !
the program.
!
1920 !
!
1921 ! Input:
None
1922 !
!
!
1923 ! Output:
Error messages to terminal
1924 !
!
!
1925 !---------------------------------------------------------------------!
1926
1927 PROC check_error;
1928
1929 BEGIN
1930
1931
!------------------------------------------------------------------!
1932
! Check for an error condition.
1933
!------------------------------------------------------------------!
!
1934
1935
IF ( error <> ZAPS^ERR^OK ) THEN
1936
BEGIN
1937
1938
!---------------------------------------------------------------!
1939
! Display the error code.
1940
!---------------------------------------------------------------!
1941
1942
tempbuf ':=' "ERROR # " -> @text_ptr;
1943
IF (error_code < 0) THEN
1944
BEGIN
1945
error_code := -error_code;
1946
text_ptr ':=' "-" -> @text_ptr;
1947
END;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 210
!
NonStop FTAM Programming Examples
1948
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
@text_ptr := @text_ptr + DNUMOUT ( text_ptr
1949
, $DBL ( error_code )
1950
, BASE );
1951
text_len := @text_ptr - @tempbuf;
1952
CALL WRITE ( termnum, outbuf, text_len );
1953
1954
tempbuf ':=' "Association discarded"
1955
-> @text_ptr;
1956
text_len := @text_ptr - @tempbuf;
1957
CALL WRITE ( termnum, outbuf, text_len );
1958
1959
!------------------------------------------------------------------!
1960
! Abort both associations and exit the program.
1961
!------------------------------------------------------------------!
!
1962
1963
CALL abort_discard;
1964
1965
CALL STOP;
1966
1967
END;
1968
1969 END; -- check_error -1970
1971
1972 ?PAGE "CHECK_STATE"
1973 !---------------------------------------------------------------------!
1974 !
!
1975 ! Name:
check_state
!
1976 !
!
1977 ! Description: The check_state procedure checks for a state-result
!
1978 !
failure on an FTM confirm call. If the state result
!
1979 !
is "failure," this procedure displays an error message,!
1980 !
calls abort_discard, and exits the program.
1981 !
!
!
1982 ! Input:
None
1983 !
!
!
1984 ! Output:
Error message to terminal
1985 !
!
!
1986 !---------------------------------------------------------------------!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G- 211
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
1987
1988 PROC check_state;
1989
1990 BEGIN
1991
1992
!------------------------------------------------------------------!
1993
! Check the state-result parameter for a failure.
1994
!------------------------------------------------------------------!
!
1995
1996
IF ( state_result = ZFTM^VAL^STATE^FAILURE ) THEN
1997
BEGIN
1998
tempbuf ':=' "Bad state result received" -> @text_ptr;
1999
text_len := @text_ptr - @tempbuf;
2000
CALL WRITE ( termnum, outbuf, text_len );
2001
2002
tempbuf ':=' "Associations discarded" -> @text_ptr;
2003
text_len := @text_ptr - @tempbuf;
2004
CALL WRITE ( termnum, outbuf, text_len );
2005
2006
CALL abort_discard;
2007
2008
2009
CALL STOP;
END;
2010 END;
2011
2012
2013 ?PAGE "BAD_EVENT"
2014 !---------------------------------------------------------------------!
2015 !
!
2016 ! Name:
bad_event
!
2017 !
!
2018 ! Description: The bad_event procedure is called when an unexpected
!
2019 !
event is received from one of the associations. The
!
2020 !
event can be an abort indication. If an abort is
!
2021 !
received, the procedure aborts the other association;
!
2022 !
any other event results in aborts of both associations.!
2023 !
!
2024 ! Input:
Event received on the association
2025 !
!
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 212
NonStop FTAM Programming Examples
2026 !
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
CEPI identifying the association that carried the
2027 !
event
!
!
2028 !
!
2029 ! Output:
Error messages to terminal
2030 !
!
!
2031 !---------------------------------------------------------------------!
2032
2033 PROC bad_event ( event, cepi );
2034
2035 INT
.EXT event;
2036 INT
cepi;
2037
2038 BEGIN
2039
2040
!------------------------------------------------------------------!
2041
! If an abort indication is received on one of the two
!
2042
! associations, the other must be aborted. Any other event
!
2043
! requires that both associations be aborted.
!
2044
!------------------------------------------------------------------!
2045
2046
IF ( event = ZFTM^VAL^EVT^PABORT^IND ) THEN
2047
BEGIN
2048
!---------------------------------------------------------------!
2049
! Retrieve the action result and diagnostic messages for the
!
2050
! P-abort.
!
2051
!---------------------------------------------------------------!
2052
2053
error := FTM_P_ABORT_IND_ ( cepi
2054
, action_result
2055
, diag );
2056
CALL check_error;
2057
CALL check_action_diag;
2058
2059
!---------------------------------------------------------------!
2060
!Determine which association was aborted and then abort the other!
2061
!---------------------------------------------------------------!
2062
2063
IF ( cepi = src_cepi AND dst_con_established ) THEN
2064
BEGIN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 213
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2065
2066
status := FTM_U_ABORT_REQ_ ( dst_cepi
2067
, !action_result!
2068
, !diagnostics!);
2069
CALL check_status ( dst_cepi );
2070
2071
END
2072
ELSE IF ( cepi = dst_cepi AND src_con_established ) THEN
2073
BEGIN
2074
status := FTM_U_ABORT_REQ_ ( src_cepi
2075
, !action_result!
2076
, !diagnostics!);
2077
CALL check_status ( src_cepi );
2078
END;
2079
END
2080
ELSE
2081
BEGIN
2082
2083
!---------------------------------------------------------------!
2084
! The unexpected event was not an abort indication. Issue an
!
2085
! abort for both associations.
!
2086
!---------------------------------------------------------------!
2087
2088
IF ( src_con_established ) THEN
2089
BEGIN
2090
status := FTM_U_ABORT_REQ_ ( src_cepi
2091
, !action_result!
2092
, !diagnostics!);
2093
CALL check_status ( src_cepi );
2094
END;
2095
IF ( dst_con_established ) THEN
2096
BEGIN
2097
status := FTM_U_ABORT_REQ_ ( dst_cepi
2098
, !action_result!
2099
, !diagnostics!);
2100
2101
2102
CALL check_status ( dst_cepi );
END;
END;
2103
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 214
NonStop FTAM Programming Examples
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
2104
!------------------------------------------------------------------!
2105
! Verify that a CEPI exists, and if it does, discard it.
2106
!------------------------------------------------------------------!
!
2107
2108
IF ( src_cepi <> NOCEPI ) THEN
2109
BEGIN
2110
2111
CALL APS_DISCARD_ ( src_cepi );
END;
2112
2113
IF ( dst_cepi <> NOCEPI ) THEN
2114
BEGIN
2115
2116
CALL APS_DISCARD_ ( dst_cepi );
END;
2117
2118
!------------------------------------------------------------------!
2119
! Display a message to the terminal and exit the program.
2120
!------------------------------------------------------------------!
!
2121
2122
tempbuf ':=' "Unexpected event received" -> @text_ptr;
2123
text_len := @text_ptr - @tempbuf;
2124
CALL WRITE ( termnum, outbuf, text_len );
2125
2126
tempbuf ':=' "Associations discarded" -> @text_ptr;
2127
text_len := @text_ptr - @tempbuf;
2128
CALL WRITE ( termnum, outbuf, text_len );
2129
2130
CALL STOP;
2131
2132 END; -- bad_event -2133
2134
2135 ?PAGE "CHECK_ACTION_DIAG"
2136 !---------------------------------------------------------------------!
2137 !
!
2138 ! Name:
check_action_diag
!
2139 !
!
2140 ! Description: The check_action_diag procedure determines whether
!
2141 !
the action requested of a remote responder was
!
2142 !
successful or not. If not, the procedure displays
!
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 215
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2143 !
the diagnostic message type and error ID for each
!
2144 !
diagnostic message element, calls abort_discard, and
!
2145 !
ends the program. Additional application-specific
!
2146 !
error handling or recovery could be implemented if
!
2147 !
required by an application.
!
2148 !
!
2149 ! Input:
None
!
2150 !
!
2151 ! Output:
Error message to terminal
2152 !
!
!
2153 !---------------------------------------------------------------------!
2154
2155 PROC check_action_diag;
2156
2157 BEGIN
2158
2159
INT i; ! index into diagnostic array !
2160
2161
!------------------------------------------------------------------!
2162
! Check action_result for failure and display diagnostic
!
2163
! messages if action_result is a failure.
!
2164
!------------------------------------------------------------------!
2165
2166
IF ( action_result = ZFTM^VAL^ACTION^FAILURE ) THEN
2167
BEGIN
2168
tempbuf ':=' "Following is a list of " -> @text_ptr;
2169
text_len := @text_ptr - @tempbuf;
2170
width := DNUMOUT ( tempbuf[text_len]
2171
, $DBL ( diag.zdiagcount )
2172
, BASE );
2173
tempbuf[text_len + width] ':=' " diagnostic elements -" -> @text_ptr;
2174
text_len := @text_ptr - @tempbuf;
2175
CALL WRITE ( termnum, outbuf, text_len );
2176
2177
!---------------------------------------------------------------!
2178
! Display the diagnostic message type and error ID for each
!
2179
! diagnostic message.
!
2180
!---------------------------------------------------------------!
2181
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 216
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2182
FOR i := 0 TO diag.zdiagcount - 1 DO
2183
BEGIN
2184
tempbuf ':=' " Diagnostic Type: " -> @text_ptr;
2185
text_len := @text_ptr - @tempbuf;
2186
width := DNUMOUT ( tempbuf[text_len]
2187
, $DBL ( diag.zdiagelems[i].zdiagtype )
2188
, BASE );
2189
text_len := text_len + width;
2190
CALL WRITE ( termnum, outbuf, text_len );
2191
2192
tempbuf ':=' " Error ID: " -> @text_ptr;
2193
text_len := @text_ptr - @tempbuf;
2194
width := DNUMOUT ( tempbuf[text_len]
2195
, $DBL ( diag.zdiagelems[i].zerrorid )
2196
, BASE );
2197
text_len := text_len + width;
2198
CALL WRITE ( termnum, outbuf, text_len );
2199
2200
IF ( diag.zdiagelems[i].zfurtherdetailsispresent = ZAPS^VAL^PRESENT )
2201
THEN
2202
BEGIN
2203
tempbuf ':=' " Details: " -> @text_ptr;
2204
text_len := @text_ptr - @tempbuf;
2205
tempbuf[text_len] ':=' diag.zdiagelems[i].zfurtherdetails.zb
2206
FOR diag.zdiagelems[i].zfurtherdetails.zlen BYTES;
2207
text_len := text_len + diag.zdiagelems[i].zfurtherdetails.zlen;
2208
2209
CALL WRITE ( termnum, outbuf, text_len );
END;
2210
2211
END;
2212
2213
!---------------------------------------------------------------!
2214
! Abort both associations and exit the program.
2215
!---------------------------------------------------------------!
2216
2217
CALL abort_discard;
2218
tempbuf ':=' "Associations discarded" -> @text_ptr;
2219
text_len := @text_ptr - @tempbuf;
2220
CALL WRITE ( termnum, outbuf, text_len );
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 217
!
NonStop FTAM Programming Examples
2221
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
CALL STOP;
2222
2223
END;
2224
2225 END; --- check_action_diag --2226
2227
2228 ?PAGE "ABORT_DISCARD"
2229 !---------------------------------------------------------------------!
2230 !
!
2231 ! Name:
abort_discard
!
2232 !
!
2233 ! Description: The abort_discard procedure discards established
!
2234 !
!
associations.
2235 !
!
2236 ! Input:
None
2237 !
!
!
2238 ! Output:
None
2239 !
!
!
2240 !---------------------------------------------------------------------!
2241
2242 PROC abort_discard;
2243
2244 BEGIN
2245
2246
!------------------------------------------------------------------!
2247
! Initialize the parameters for the U-abort request.
2248
!------------------------------------------------------------------!
!
2249
2250
2251
!------------------------------------------------------------------!
2252
! Send a failed action result since the following diagnostic
!
2253
! message type is set to "permanent."
!
2254
!------------------------------------------------------------------!
2255
action_result := ZFTM^VAL^ACTION^FAILURE;
2256
2257
2258
!------------------------------------------------------------------!
2259 ! The following code demonstrates how to set the diagnostic parameter !
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 218
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2260
! for an FTM_U_ABORT_REQ_ call. The diagnostic values set here are !
2261
! for example only; a real application might be more specific, for !
2262
! instance, in the error code. Here, type is set to "permanent";
!
2263
! error code is set to "no reason"; observer of error is this
!
2264
! application, and source of error is not categorized.
!
2265
!------------------------------------------------------------------!
2266
2267
diag.zdiagcount := 1;
2268
diag.zdiagelemsispresent := ZAPS^VAL^TRUE;
2269
diag.zdiagelems.zdiagtype := ZFTM^VAL^DIAG^PERMANENT;
2270
diag.zdiagelems.zerrorid := ZFTM^DIAG^NO^REASON;
2271
diag.zdiagelems.zerrorobserver := ZFTM^VAL^ENTITYREF^INITFSRVUSR;
2272
diag.zdiagelems.zerrorsource := ZFTM^VAL^ENTITYREF^NOCATPOSS;
2273
diag.zdiagelems.zsuggesteddelayispresent := ZAPS^VAL^FALSE;
2274
diag.zdiagelems.zfurtherdetailsispresent := ZAPS^VAL^FALSE;
2275
2276
!------------------------------------------------------------------!
2277
! Abort the source association if it exists.
2278
!------------------------------------------------------------------!
!
2279
2280
IF ( src_con_established ) THEN
2281
BEGIN
2282
status := FTM_U_ABORT_REQ_ ( src_cepi
2283
, action_result
2284
, diag);
2285
IF (status <> ZAPS^VAL^STATUS^OK) THEN
2286
BEGIN
2287
tempbuf ':=' "Abort of the source association failed" -> @text_ptr;
2288
text_len := @text_ptr - @tempbuf;
2289
CALL WRITE ( termnum, outbuf, text_len );
2290
2291
END;
END;
2292
2293
!------------------------------------------------------------------!
2294
! Abort the destination association if it exists.
2295
!------------------------------------------------------------------!
2296
2297
IF ( dst_con_established ) THEN
2298
BEGIN
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 219
!
Example 2 in TAL—Moving a File Between Two
Remote Systems (in Wait Mode)
NonStop FTAM Programming Examples
2299
status := FTM_U_ABORT_REQ_ ( dst_cepi
2300
, action_result
2301
, diag);
2302
2303
IF (status <> ZAPS^VAL^STATUS^OK) THEN
2304
BEGIN
2305
tempbuf ':=' "Abort of the destination association failed"
2306
->@text_ptr;
2307
text_len := @text_ptr - @tempbuf;
2308
CALL WRITE ( termnum, outbuf, text_len );
2309
2310
END;
END;
2311
2312
!------------------------------------------------------------------!
2313
! Discard the API context information for each CEPI.
2314
!------------------------------------------------------------------!
2315
2316
IF ( src_cepi <> NOCEPI ) THEN
2317
BEGIN
2318
2319
CALL APS_DISCARD_ ( src_cepi );
END;
2320
2321
IF ( dst_cepi <> NOCEPI ) THEN
2322
BEGIN
2323
2324
CALL APS_DISCARD_ ( dst_cepi );
END;
2325
2326 END; -- abort_discard -2327
2328
2329
2330
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 220
!
NonStop FTAM Programming Examples
Translation Application Example
Translation Application Example
The following example program opens the responder and issues the Enable
Translation command. It then reads its $RECEIVE and processes all translation
requests.
To compile the program in native environment enter:
NMC/IN exctran1/o; runnable, symbols, winspect, extensions,
strict, runnamed, extensions
To compile the program in the TNS environment enter:
C /IN exctran1/o
Before running the example program, set the fixed environmental variables as follows.
param responder $xxx
Other environmental variables will be used to provide filenames to translate, for
example:
param incomingfilename \sys.$disc.transltd.filename
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 221
Translation Application Example
NonStop FTAM Programming Examples
1
/***********************************************************************/
2
/*
*/
3
/* Test Translation Application for D42 Changes to FTAM
*/
4
/*
*/
5
/***********************************************************************/
6
/*
*/
7
/*
*/
8
/* Program Name: exctran1
*/
9
/*
*/
10 /* Program Description:
*/
11 /*
*/
12 /* This program opens the Responder file and issues ‘enable
*/
13 /* translation’ command. It then reads its $RECEIVE and processes all
*/
14 /* translation requests.
*/
15 /*
*/
16 /* To compile in the Native environment:
*/
17 /* > NMC / IN exctran1/o; runnable, symbols, winspect,
*/
18 /*
*/
extensions, strict, runnamed, extensions
19 /*
*/
20 /* To compile in the TNS environment:
*/
21 /* > C /IN exctran1/o
*/
22 /*
*/
23 /***********************************************************************/
24 /*
*/
25 /* Note:Before running this program, correctly set the following:
*/
26 /*
*/
27 /*
a) fixed environment variables
*/
28 /*
> param responder "$xxx"
*/
29 /*
*/
30 /*
b) Any other environment variables will be used to provide
*/
31 /*
filenames to translate. For example:
*/
32 /*
> param incomingfilename
*/
33 /*
"\sys.$disc.transltd.filename"
34 /*
*/
*/
35 /***********************************************************************/
36 /* Change these to corresponding subvolumes on your system:
*/
37 #pragma
SSV0 "$system.system"
/* Look for C runtime here
*/
38 #pragma
SSV1 "$ftam.t6982d42"
/* Look for FTAM files here
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 222
Translation Application Example
NonStop FTAM Programming Examples
39 #pragma SSV2 "$d43rsc.zosiaps"
/* Look for OSI files here
*/
40 #pragma SSV3 "$d43rsc.zspidef"
/* Look for other SPI files
*/
41 #pragma SSV4 "$d43rsc.zsysdefs"
/* Look for Guardian files
*/
42 #ifndef _TNS_R_TARGET
/* NMC accepts on cmd line only*/
43 #pragma XMEM
44 #pragma RUNNABLE
45 #pragma SYMBOLS
46 #pragma INSPECT
47 #pragma STRICT
48 #pragma RUNNAMED
49 #else
50 #pragma fieldalign shared2
51 #endif
52 #include nolist
53 #include nolist
54 #include nolist
55 #include nolist
56 #include nolist
57 #include nolist
58 #include nolist
59 /***********************************************************************/
60 /* Source in
*/
61 /*-APS and FTAM structure definitions and literals
*/
62 /*-External function declarations for FTAM, APS, and Guardian
*/
63 /***********************************************************************/
64 #include "zspic" nolist/* SPI DDL*/
65 #include "zcomc" nolist/* COM DDL*/
66 #include "zapsc" nolist /* APS DDL*/
67 #include "zosac" nolist/* OSF DDL*/
68 #include "zftmc" nolist/* FTAM DDL*/
69 #include "zosfc" nolist/* OSF DDL*/
70 #include "zsysc( zsys_ddl_phandle \
71
, zsys_ddl_receiveinformation \
72
, system_messages_constant \
73
, zsys_ddl_smsg_open \
74
)" nolist /* Guardian defines*/
75 #include "cextdecs( DELAY \
76
, FILE_CLOSE_ \
77
, FILE_GETINFO_ \
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 223
Translation Application Example
NonStop FTAM Programming Examples
79
, FILE_GETRECEIVEINFO_ \
78
, FILE_OPEN_ \
80
, FILENAME_TO_OLDFILENAME_ \
81
, FILENAME_TO_PROCESSHANDLE_ \
82
, FNAMETOFNAME32 \
83
, OPENER_LOST_ \
84
, PROCESSHANDLE_COMPARE_ \
85
, PROCESSHANDLE_NULLIT_ \
86
, READUPDATEX \
87
, REPLYX \
88
, SIGNALTIMEOUT \
90
, SSINIT \
91
, SSGETTKN \
92
, SSPUTTKN \
93
, STRING_UPSHIFT, \
94
, TEXTTOSSID \
95
, WRITEREADX )" nolist \
96
/**********************************************************************/
97
/* Global Data Declarations
98
/**********************************************************************/
99
#define DOLLAR_RECEIV"$RECEIVE"
*/
100 #define ZSPI_QUAL".#ZSPI"
101 #define RESPONDER_PARAM"RESPONDER"
102 #define RETRY_OPEN_TIMEOUT_VALUE3000 /* 30 seconds*/
103 /**********************************************************************/
104 /* Miscellaneous Variables
*/
105 /**********************************************************************/
106 short sRcvFnum = -1;
/* $RECEIVE file number
*/
107 short sSpiFnum = -1;
/* Responder SPI file number */
108 short sLastError;
/* Last NSK error
109 short sOpenerCount = 0;
/* Count of openers (0 or 1) */
*/
110 short saSpiBuffer [(ZOSA_VAL_MAX_BUFLEN/2)]; /* SPI Buffer
*/
111 /*
The following should remain together, they are the opener
*/
112 /*
table used by the OPENER_LOST_ function.
*/
113 zsys_ddl_phandle_def
ResponderPhandle;
/* NULL or opener.
*/
114 zsys_ddl_phandle_def
BackupPhandle;
/* Always set to NULL
*/
115 /*
SSID (built in OpenResponderFile())
*/
116 zosf_val_ssid_def zosf_val_ssid;
117 /*
ZSPI_TKN_ERROR goes here...
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 224
*/
Translation Application Example
NonStop FTAM Programming Examples
118 zspi_ddl_error_def spi_error;
119
120 typedef short BOOL;
121 #define TRUE
-1
122 #define FALSE
0
123 #pragma PAGE
"OpenRcvFile"
124 /**********************************************************************/
125 /*
*/
126 /* Name: OpenRcvFile
*/
127 /*
*/
128 /* Desc: Opens the $RECEIVE file. Failure returns FALSE.
*/
129 /*
*/
130 /**********************************************************************/
131 BOOL OpenRcvFile (void)
132 {
133
sLastError = FILE_OPEN_ (DOLLAR_RECEIVE,
134
(short) strlen (DOLLAR_RECEIVE),
135
&sRcvFnum, , , , 1);
136
if (sLastError)
137
printf ("Error opening $RECEIVE: %d\n", sLastError);
138
return (sLastError == 0);
139 }
140
141
142 #pragma PAGE "OpenResponderFile"
143 /**********************************************************************/
144 /*
*/
145 /* Name: OpenResponderFile
*/
146 /*
*/
147 /* Desc: Opens the Responder process SPI port. Failure returns FALSE. */
148 /*
*/
149 /**********************************************************************/
150
BOOL OpenResponderFile (void)
151
{
152
char*zResponderParam,
153
zFilename [36];
154
shortsLen;
155
zsys_ddl_phandle_def ThisProcessHandle;
156
if (sSpiFnum == -1)/* If not already open, open it *
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 225
Translation Application Example
NonStop FTAM Programming Examples
157
{
158
zResponderParam = getenv (RESPONDER_PARAM);
159
if (!zResponderParam )/* If not already open, open it */
160
{
161
printf ("Required parameter ’%s’ missing.\n", RESPONDER_PARAM);
162
return FALSE;
163
}
164
165
166
167
/*
Save the probable phandle*/
168
FILENAME_TO_PROCESSHANDLE_ (zResponderParam,
169
(short) strlen (zResponderParam),
170
(short *) &ThisProcessHandle);
171
sprintf (zFilename, "%s%s", zResponderParam, ZSPI_QUAL);
172
sLastError = FILE_OPEN_ (zFilename, (short) strlen (zFilename),
173
&sSpiFnum);
174
if (sLastError)
175
{
176
printf ("Error opening Responder file (’%s’): %d\n",
177
zFilename, sLastError);
178
return FALSE;
179
}
180
}
189
else
190
memcpy (&ThisProcessHandle, &ResponderPhandle,
191
sizeof (ThisProcessHandle));
192
/* Build the SSID you always will use */
193
TEXTTOSSID (ZOSF_VAL_EXTERNAL_SSID, (short *) &zosf_val_ssid);
194
zosf_val_ssid.z_version = ZOSF_VAL_VERSION;
195
/* Build and send the ’Enable’ command */
196
SSINIT (saSpiBuffer, ZOSA_VAL_MIN_BUFLEN,
197
(short *) &zosf_val_ssid, ZSPI_VAL_CMDHDR,
198
ZOSF_CMD_ENABLE_XLATE, ZCOM_OBJ_PROCESS);
199
sLen = (short) sizeof (saSpiBuffer);
200
SSPUTTKN (saSpiBuffer, ZSPI_TKN_MAXRESP, (char *) &sLen);
201
SSGETTKN (saSpiBuffer, ZSPI_TKN_USEDLEN, (char *) &sLen);
202
WRITEREADX (sSpiFnum, (char *) saSpiBuffer, sLen,
203
(short) sizeof (saSpiBuffer), &sLen);
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 226
NonStop FTAM Programming Examples
Translation Application Example
204
FILE_GETINFO_ (sSpiFnum, (short *) &sLastError);
205
if (sLastError)
206
{
207
printf ("Error sending SPI command: %d\n", sLastError);
208
FILE_CLOSE_ (sSpiFnum);
209
sSpiFnum = -1;
210
return FALSE;
211
}
212
/* Check the results to make sure we were accepted */
213
SSPUTTKN (saSpiBuffer, ZSPI_TKN_RESET_BUFFER, (char *) &sLen);
214
SSGETTKN (saSpiBuffer, ZSPI_TKN_DATALIST);
215
SSGETTKN (saSpiBuffer, ZSPI_TKN_ERRLIST);
216
/* List errors. */
217
SSGETTKN (saSpiBuffer, ZSPI_TKN_ERROR, (char *) &spi_error);
218
sLastError = spi_error.z_error;
219
if (sLastError)
220
{
221
printf ("SPI Error returned from SPI command: %d\n",
222
sLastError);
223
FILE_CLOSE_ (sSpiFnum);
224
sSpiFnum = -1;
225
return FALSE;
226
}
227
/* Save the phandle globally */
228
memcpy (&ResponderPhandle, &ThisProcessHandle,
229
sizeof (ThisProcessHandle));
230
231
return TRUE;
}
232 #pragma PAGE "HandleSysMsg"
233 /**********************************************************************/
234 /*
*/
235 /*Name:
HandleSysMsg
*/
236 /*
*/
237 /*Description: Checks system message. Handles all forms
*/
238 /*
of failure of or close by responder by starting a timer*/
239 /*
Timer completion causes an attempt to reopen.
*/
240 /*
Open is checked for #ZSPI qualifier and only one open
*/
241 /*
by responder is allowed
*/
242 /*
*/
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 227
Translation Application Example
NonStop FTAM Programming Examples
242 /**********************************************************************/
243 void HandleSysMsg (short sLen)
244 {
245
zsys_ddl_smsg_open_def *OpenMsg;
246
zsys_ddl_receiveinformation_def ReceiveInfo;
247
short sIndex = -1,
248
sError = 0;
249
switch (saSpiBuffer [0])
250
{
251
/*No close message if processor failed.*/
252
case ZSYS_VAL_SMSG_CPUDOWN:
252
case ZSYS_VAL_SMSG_REMOTECPUDOWN:
253
case ZSYS_VAL_SMSG_NODEDOWN:
254
if (sSpiFnum < 0)
255
break;
256
while (sError == 0)
257
{
258
sError = OPENER_LOST_ ((char *) saSpiBuffer, sLen,
259
(short *) &ResponderPhandle,
260
&sIndex, 1,
261
(short) sizeof (ResponderPhandle) * 2);
262
switch (sError)
263
{
264
case 2:
265
printf ("Parameter Error on OPENER_LOST_\n");
266
sError = 0;
267
break;
268
case 3:
269
printf ("Bounds Error on OPENER_LOST_\n");
270
sError = 0;
271
break;
272
case 6:
273
sOpenerCount = 0;
274
/* Give responder time to do backup takeover...
275
DELAY (500);
276
/* The first call to OpenResponderFile(), causes an
*/
277
/* by to send a new translate request to the responder.
*/
278
/* If the attempt fails, the responder closes.
*/
279
if (OpenResponderFile())
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 228
*/
Translation Application Example
NonStop FTAM Programming Examples
280
printf ("Opener Backup Gone! Reestablished with " Primary.\n");
281
else
282
/* The second call to OpenResponderFile() tries to reopen*/
283
/* the responder. If open works, it will enable as well */
284
if (OpenResponderFile()) /* Try to open once */
285
printf ("Opener Backup Gone! Reestablished Open"
286
" with Primary.\n")
287
else
288
{
289
printf ("Opener Lost! Attempting to reopen"
290
"every %d seconds.\n",
291
RETRY_OPEN_TIMEOUT_VALUE / 100);
292
/* Only timer set! */
293
SIGNALTIMEOUT (RETRY_OPEN_TIMEOUT_VALUE);
294
}
295
break;
296
case 7:
297
printf("Invalid message code %d passed"
298
" to OPENER_LOST_\n",
299
saSpiBuffer [0]);
300
sError = 0;
301
break;
302
default: /* Includes zero */
303
break;
304
305
306
}
}
break;
307
/* Retry the open */
308
case ZSYS_VAL_SMSG_TIMESIGNAL:
309
/* If open fails, set another timer */
310
if (OpenResponderFile())
311
printf ("Reestablished open of Responder.\n");
312
else
313
{
314
printf ("Retrying again...\n");
315
SIGNALTIMEOUT (RETRY_OPEN_TIMEOUT_VALUE);
316
}
317
break;
318
case ZSYS_VAL_SMSG_OPEN:
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 229
Translation Application Example
NonStop FTAM Programming Examples
319
OpenMsg = (zsys_ddl_smsg_open_def *) saSpiBuffer;
320
/* Only allow #ZSPI openers */
321
if ((OpenMsg->z_qualifier_len != 5) ||
322
!memcmp (OpenMsg->u_z_data.z_qualifier +
323
OpenMsg->z_opener_name.zlen,
324
325
"#ZSPI", 5))
{
326
REPLYX (, , , , 2); /* Don’t allow open! */
327
return;
328
}
329
FILE_GETRECEIVEINFO_ ((short *) &ReceiveInfo);
330
if (PROCESSHANDLE_COMPARE_ ((short *) &ReceiveInfo.z_sender,
331
332
(short *) &ResponderPhandle) < 1)
{
333
/* Don’t allow open other than ’my’ responder! */
334
REPLYX (, , , , 49);
335
return;
336
}
337
/* Count the opener. */
338
sOpenerCount++;
339
break;
340
341
342
case ZSYS_VAL_SMSG_CLOSE:
if ((sSpiFnum < 0) || (sOpenerCount < 1))
343
break;
344
/* Count the closes */
345
sOpenerCount--;
346
if (sOpenerCount < 1)
347
{
348
/* Give responder time to do backup takeover... */
349
DELAY (500);
350
/* The first call to OpenResponderFile(), causes an attempt
*/
351
/* to send a new translate request to the responder. If the
*/
352
/*
*/
353
if (OpenResponderFile())
354
attempt fails, the responder closes.
printf ("Opener Backup Gone! Reestablished"
355
356
357
" with Primary.\n");
else
/* The second call to OpenResponderFile() tries to reopen
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 230
*/
Translation Application Example
NonStop FTAM Programming Examples
358
/* the responder. If open works, it will enable as well
359
if (OpenResponderFile()) /* Try to open once */
360
printf ("Opener Backup Gone! Reestablished Open"
361
"with Primary.\n");
362
else
363
{
364
printf ("Opener Gone! Attempting to reopen every %d"
365
" seconds.\n",
366
RETRY_OPEN_TIMEOUT_VALUE / 100);
367
SIGNALTIMEOUT (RETRY_OPEN_TIMEOUT_VALUE);
368
}
369
}
370
break;
371
default:
372
break;
373
*/
}
374 }
375 #pragma PAGE "WaitForTranslation"
376 /**********************************************************************/
377 /*
*/
378 /* Name:
WaitForTranslation
*/
379 /*
*/
380 /* Description: Read message from $RECEIVE and process it for‘
*/
381 /*
*/
translation. Returns TRUE if shutdown not wanted.
382 /**********************************************************************/
383 BOOL WaitForTranslation (void)
384 {
385
shortsLen,
386
sXltErr,
387
sCmd = 0;
388
intiNdx;
389
struct
390
{
391
shortsSize;
392
charzName [ZFTM_VAL_REQ_FILENAME_LEN];
393
}sReqFname;
394
struct
395
{
396
shortsSize;
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 231
NonStop FTAM Programming Examples
397
charzName [16];
398
}sUser;
399
shortsaOldName [12];
400
zspi_ddl_fname32_defsXltFname;
401
zosf_ddl_xlate_action_type_defeXlateAct;
402
char zFilename [ZFTM_VAL_REQ_FILENAME_LEN],
403
404
Translation Application Example
*zParam;
READUPDATEX (sRcvFnum, (char *) saSpiBuffer,
405
(short) sizeof (saSpiBuffer), &sLen);
406
FILE_GETINFO_ (sRcvFnum, (short *) &sLastError);
407
if (sLastError == 6)
408
{
409
/* System messages are handled here. */
410
HandleSysMsg (sLen);
411
REPLYX ();
412
return TRUE;
413
}
414
if (sLastError)
415
{
416
printf ("Error reading $RECEIVE: %d\n", sLastError);
417
FILE_CLOSE_ (sSpiFnum);
418
sSpiFnum = -1;
419
FILE_CLOSE_ (sRcvFnum);
420
sRcvFnum = -1;
421
return FALSE;
422
}
423
/* Get the command from the buffer*/
424
SSPUTTKN (saSpiBuffer, ZSPI_TKN_RESET_BUFFER, (char *) &sLen);
425
SSGETTKN (saSpiBuffer, ZSPI_TKN_COMMAND, (char *) &sCmd);
426
if (sCmd == ZOSF_CMD_FILENAME_TRANSLATE)
427
{
428
/* Get the tokens sent to us*/
429
SSGETTKN (saSpiBuffer, ZOSF_TKN_REQ_FILENAME,
430
(char *) &sReqFname);
431
SSPUTTKN (saSpiBuffer, ZSPI_TKN_RESET_BUFFER, (char *) &sLen);
432
SSGETTKN (saSpiBuffer, ZOSF_TKN_USERID, (char *) &sUser);
433
SSPUTTKN (saSpiBuffer, ZSPI_TKN_RESET_BUFFER, (char *) &sLen);
434
SSGETTKN (saSpiBuffer, ZOSF_TKN_XLATE_ACTION,
435
(char *) &eXlateAct);
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 232
Translation Application Example
NonStop FTAM Programming Examples
436
memcpy (zFilename, sReqFname.zName, sReqFname.sSize);
437
zFilename [sReqFname.sSize] = ’\0’;
438
439
/*For this sample program, use filename (upshifted) to look up param*/
STRING_UPSHIFT_ (zFilename, sReqFname.sSize, zFilename,
440
sReqFname.sSize);
441
zParam = getenv (zFilename);
442
if (!zParam) /* No translation...*/
443
sXltErr = 3021;
444
else
445
{
446
/* Try to convert to a fname32. */
447
sXltErr = FILENAME_TO_OLDFILENAME_ (zParam,
448
(short) strlen (zParam),
449
saOldName);
450
if (sXltErr == 0)
451
sXltErr = (FNAMETOFNAME32 ((char *) saOldName,
452
453
454
455
(char *) &sXltFname) ? 0 : 13);
}
/* For this example, replace spaces in userid with nulls and print.*/
for (iNdx = 0; iNdx < sUser.sSize; iNdx++)
456
if (sUser.zName [iNdx] == ’ ’)
457
sUser.zName [iNdx] = ’\0’;
458
printf ("Xlate of ’%s’ by %1.8s.%1.8s (",
459
zFilename, sUser.zName, sUser.zName + 8);
460
switch (eXlateAct)
461
{
462
case zosf_val_xlate_act_select:
463
printf ("F-SELECT) ");
464
break;
465
466
case zosf_val_xlate_act_create:
467
printf ("F-CREATE) ");
468
break;
469
470
default:
471
printf ("F-?? [%d]) ", eXlateAct);
472
break;
473
}
474
if (sXltErr)
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 233
NonStop FTAM Programming Examples
475
Translation Application Example
printf ("Fail, err %d\n", sXltErr);
476
else
477
printf ("Succeed: ’%s’\n", zParam);
478
/* Build the response */
479
SSINIT (saSpiBuffer, ZOSA_VAL_MIN_BUFLEN,
480
(short *) &zosf_val_ssid, ZSPI_VAL_CMDHDR,
481
ZOSF_CMD_FILENAME_TRANSLATE, ZCOM_OBJ_PROCESS);
482
if (sXltErr == 0) /* Filename if no error */
483
SSPUTTKN (saSpiBuffer, ZOSF_TKN_XLATED_FNAME,
484
(char *) &sXltFname);
485
else
486
{
487
/* Error token */
488
memcpy (&spi_error.z_ssid, &zosf_val_ssid,
499
sizeof (spi_error.z_ssid));
500
spi_error.z_error = sXltErr;
501
SSPUTTKN (saSpiBuffer, ZSPI_TKN_ERROR, (char *) &spi_error);
502
}
503
SSGETTKN (saSpiBuffer, ZSPI_TKN_BUFLEN, (char *) &sLen);
504
REPLYX ((char *) saSpiBuffer, sLen);
505
}
506
FILE_GETINFO_ (sRcvFnum, (short *) &sLastError);
507
return (sLastError == 0);
508 }
509 #pragma PAGE "MAIN"
510 /**********************************************************************/
511 /*
*/
512 /*Name:
main
*/
513 /*
*/
514 /* Description: This application Opens $RECEIVE and the Responder
*/
515 /*
process It sends the spi command to the Responder
*/
516 /*
to start translation, then reads $RECEIVE to process
*/
517 /*
translation requests.
*/
518 /**********************************************************************/
519 int main (int argc, char *argv[])
520 {
521
argc = argc; /* Not Used */
522
argv = argv; /* Not Used */
523
PROCESSHANDLE_NULLIT_ ((short *) &BackupPhandle);
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 234
NonStop FTAM Programming Examples
524
/* Open $Receive, and the Responder*/
525
if (OpenRcvFile() && OpenResponderFile())
526
527
528
Translation Application Example
/* Get and process messages forever.*/
do { ; } while (WaitForTranslation());
return 0; /* Never happens except for errors*/
529 } /* main */
530 #pragma nowarn (93) /* Ignore no refs to spi defs */
531
532
532
533
534
535
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 235
NonStop FTAM Programming Examples
Translation Application Example
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
G - 236
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.1, defines
ranges of values for the primitive elements, and defines ways of combining these
elements. See also transfer syntax. and ASN.1 (Abstract Syntax Notation-1).
Abstract Syntax Notation-1. See ASN.1 (Abstract Syntax Notation-1).
access-context parameter. A parameter used for read transfers within the data-transfer
regime to specify the file structure by which information in the file is accessed. Possible
structures for NonStop FTAM are flat all data units (for FTAM-2 files) and unstructured
all data units (for FTAM-1, FTAM-2, and FTAM-3 files). See UA (unstructured all data
units). and FA (flat all data units).
access-control attribute. A file attribute that contains the information to determine whether
file access is allowed or denied. The attribute value is set when the file is created. You
can alter the access-control attribute using the change-attribute action.
ACSE (Association Control Service Element). An application service element (ASE) in
the Application Layer of the OSI Reference Model. The ACSE exists within an
application entity and enables other ASEs to establish and release associations. It is
accessible to users of OSI/AS through the APS procedures. See also ASE (application
service element). or Application Layer.
action-result parameter. In effect, a summary of the ISO FTAM diagnostic parameter. The
action-result value success (ZFTM-VAL-ACTION-SUCCESS for the FTAM API)
indicates that the requested service was performed successfully. The action-result
value failure (ZFTM-VAL-ACTION-FAILURE for the FTAM API) indicates that the
service was not performed successfully. If any one of the diagnostic messages
returned indicates a failure, the value of action-result must be failure. See also stateresult parameter.
activity attributes. Dynamic attributes specific to an individual FTAM association. These
attributes are both created and discarded during the life of an association and might
change as the status of the association changes. See also file attributes.
AE title. See application entity title (AE title).
APDU (application protocol data unit). See PDU.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 1
Glossary
API (application programmatic interface).
API (application programmatic interface). A set of services (such as programming
language functions or procedures) that are called by an application program to
communicate with other software components. For example, an application program in
the form of a client might use an API to communicate with a server program. For
NonStop FTAM, the API consists of FTM, APS, and MFM procedures used in FTAM
programming. 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.
APLMGR (NonStop OSI/Application Manager). The NonStop subsystem that performs
management functions for NonStop FTAM. The APLMGR subsystem consists of two
entities: the APLMGR process and the management information base (MIB). There is
only one APLMGR per FTAM subsystem.
application. A user program that uses services provided by products such as NonStop
FTAM. The program accesses layers of the OSI Reference Model through the top layer
(Application Layer) to manipulate files on remote computer systems. For NonStop
FTAM, applications can be written in C or TAL.
application entity. The part of an application process that interacts with its peer entity in a
remote application process. In an OSI application, the application entity is the part that
represents the communication functionality necessary for interoperation.
application entity title (AE title). The structured identifier that identifies an application
entity to the OSI network. The AE title is passed as a parameter in the ACSE
A-ASSOCIATE request and returned in the A-ASSOCIATE response. See application
entity.
Application Layer. Layer 7 of the OSI Reference Model. This layer provides the interface
between user programs (application processes) and the OSI network. Layer 7 includes
the standards for services such as file transfer, electronic mail, and terminal access.
Application Manager. See APLMGR (NonStop OSI/Application Manager).
application name. The NonStop OSI/AS term for a reference name used to look up an OSI
address in the local OSI/AS management information base (MIB). In NonStop FTAM
terminology, this name is called the common name. See common name.
application programmatic interface. See API (application programmatic interface).
application service element. See ASE (application service element).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 2
Glossary
APS (application, presentation, and session)
procedures.
APS (application, presentation, and session) procedures. A set of procedure calls,
provided by NonStop as part of the OSI/AS subsystem, providing application programs
with access to the services of ACSE (in the Application Layer), the Presentation Layer,
and the Session Layer. The names of the APS procedures all begin with the letters
APS. The APS procedures are defined in the EXTDECS0 and CEXTDECS files. The
APS procedures, together with the definitions in the ZAPSDDL file, constitute the
OSI/AS API. A subset of the APS procedures is accessible from, and must be used
with, the FTAM API. See also API (application programmatic interface).
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). An internal data format used by NonStop FTAM. ASI
format is displayed in some of the USER and ASN1 trace records. The NonStop
initiator and responder processes transform ASI into the transfer syntax negotiated for
the association, and vice versa.
ASN.1 (Abstract Syntax Notation-1). The type and value syntax or notation language for
representing semantics of protocol that is described in ISO 8824. The Basic Encoding
Rules (ISO 8825) standard defines a set of encoding rules that can be applied to
values of types defined using the notation specified in ISO 8824. See also abstract
syntax.
association. A connection between Application Layer entities. See connection. Association
Control Service Element. See ACSE.
attach. An operation performed by a NonStop OSI subsystem, on behalf of an application,
to wait for an incoming associate or connect indication from a remote entity.
attribute. An identifiable characteristic of an object. For example, two attributes of an FTAM
file are its name and its date and time of creation. In DSM, two attributes of a process
are the location of its code file and its execution priority. See also file attributes. and
activity attributes.
attribute group. One of the four groups of file attributes defined by ISO FTAM. They are the
kernel group, which must be supported by all FTAM implementations; the security
group and the storage group, which are negotiated during association establishment;
and the private-use group, which is also negotiated but whose definition is outside the
scope of ISO FTAM.
backup CPU. The central processing unit (CPU) number of the NonStop processor on
which the backup process will run. See backup process.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 3
backup opener.
Glossary
backup opener. The backup process that has an open to an FTAM initiator or responder
process. See backup process.
backup process. In a NonStop system, a process that is identical to the primary process
and is created at the same time as the primary process. These two processes act as a
process pair. The backup process takes over if the primary process fails. See primary
process.
basic data types. 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. The initiator that calls a responder in an FTAM application. Contrast with
responding user.
CEPI (connection endpoint identifier). An internally generated identification code used to
track associations. In NonStop FTAM, an identifier of a connection endpoint for a given
FTAM association. Use of the CEPI for an association allows transfer of information to
a remote FTAM entity.
checkpoint. On a NonStop system, a snapshot of process activity that can be used in the
event of a takeover to allow a backup process to maintain fault-tolerant operation. See
backup process.
code file. A Guardian file containing the object code that you must run to create the
specified process.
command file. A text file containing a series of commands that you can run by issuing the
OBEY command in TACL or SCF, followed by the name of the text file.
common name. A reference name used to look up an OSI address in the local OSI/AS
management information base (MIB) when establishing an association. Using
common names simplifies addressing for applications and allows you to
subsequently change the addresses without changing your applications. In
OSI/AS terminology, the common name is called the application name.
conditional parameter. (1) In a PDU, a parameter that is present under certain
circumstances, for example, if another parameter has a given value. (2) In the NonStop
FTAM API, a procedure-call parameter that must be specified under certain
circumstances. Contrast with optional parameter and required parameter.
confirm primitive. A primitive issued when a service user (entity) is to be informed about its
request. This is one of four types of service primitives. See service primitive.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 4
confirm procedure.
Glossary
confirm procedure. A procedure called to retrieve the confirm data after a confirm primitive
has been received. See confirm primitive.
confirmed service. A service in which the initiating application sends a request, and the
responding application entity (for example, an FTAM responder) returns a response
that is received as a confirm primitive by the initiating application. The confirm primitive
acknowledges the success or failure of the requested action. Contrast with
unconfirmed service.
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. Dynamic conformance requirements determine what observable behavior
is permitted by the standards or profiles in instances of communication. The PICS is a
statement, made by the supplier of an OSI implementation, describing the capabilities
and options that have been implemented for a given OSI protocol. See also profile.
connection. A link between a service access point (SAP) on one protocol stack and a
corresponding point on a different protocol stack (either in the same system or in
another local or remote system). See also association.
connection endpoint identifier. See CEPI (connection endpoint identifier).
constraint set. A specification placing restrictions and refinements on the FTAM general file
model. These restrictions and refinements define a more specific model that reflects
the needs of a particular class of applications.
contents-type attribute. A file attribute that indicates either the document type of a file or
its abstract syntax name and constraint-set name. The value of this attribute is set at
file creation and cannot be changed by the change-attribute action. See also contentstype parameter.
contents-type parameter. A parameter that indicates the document type of a file and,
optionally, parameter values that further define the document type. The contentstype must either match the document type of the file being opened or be an allowed
simplification of the document type. If you are using the NonStop FTAM initiator, and
you do not specify contents-type in a call to FTM_OPEN_REQ_, it will default to
indicate that the contents type is unknown. You can then retrieve the valid file
contents-type by calling FTM_OPEN_CNF_, which returns information from the
confirm received from the responder. This parameter must also be specified in calls to
FTM_CREATE_REQ_. Document types supported by NonStop FTAM are FTAM-1,
FTAM-2, FTAM-3, and NBS-9. See document type.
contents-type-list parameter. A parameter used for negotiating the document types and
abstract syntaxes that will be available on the association. For NonStop FTAM, the
default document types requested are FTAM-1, FTAM-2, FTAM-3, and NBS-9.
Data Definition Language. See DDL (Data Definition Language).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 5
Data Link Layer.
Glossary
Data Link Layer. Layer 2 in the OSI Reference Model. This layer packages data for
transmission across the network and ensures that the data arrives at the next layer
without any errors.
data-transfer regime. The regime established after successfully gaining read or write
access to an FTAM file. In the data-transfer regime, you can send or receive data, and
you can abort the association. See also FTAM regime., file-selection regime., and fileopen regime.
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). An attribute of a NonStop virtual filestore (VFS) profile that allows
access to files in the NonStop responder’s VFS in cases where the initiator identity and
filestore password are not provided when an association is established. The default
user specifies the default Guardian user ID and password to be used.
diagnostic parameter. An optional parameter providing information that qualifies the
success or explains the failure of a requested FTM procedure call. For
applications using the FTAM API, this parameter primarily returns whatever
diagnostic messages have been received from the remote responder or the local
initiator. In addition, you can use this parameter to send diagnostic messages to a
remote responder using the FTM_CANCEL_REQ_, FTM_DATA_END_REQ_, and
FTM_U_ABORT_REQ_ procedures. See also ISO FTAM diagnostic messages.
document type. An FTAM definition, defining the structure of and method of access to a
file. NonStop FTAM supports four document types: FTAM-1, FTAM-2, FTAM-3, and
NBS-9. An FTAM-1 document is an unstructured text file that cannot be broken into
smaller segments by the protocol. An FTAM-2 document is a structured text file divided
into FADUs, which cannot be broken down. An FTAM-3 document is an unstructured
binary file. An NBS-9 document is a read-only directory as defined by the NIST FTAM
Phase 2 agreements.
EMS (Event Management Service). A Distributed Systems Management product that
provides event collection, event logging, and event distribution facilities. EMS provides
different event descriptions for interactive and programmatic interfaces, lets an
operator or an application select specific event-message data, and allows for flexible
distribution of event messages within a system or network. The FTAM and APLMGR
subsystems generate event messages that are displayed as operator messages;
however, the programmatic interface to FTAM and APLMGR event messages is not
available for customer use. See also event message.
EMS collector. A NonStop Kernel process that accumulates event messages sent from OSI
subsystem processes. See event message.
end-of-file marker. See EOF (end of file).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 6
Glossary
enhanced-file-management functional unit.
enhanced-file-management functional unit. A functional unit that adds the modification of
file attributes to the capabilities of the limited-file-management functional unit. See
limited-file-management functional unit.
Enscribe. The NonStop database file-management software provided as part of the
Guardian file system. The Enscribe software provides access to—and manipulation
of—records in a database on a NonStop system. Files on a NonStop system can be
either Enscribe files or NonStop SQL tables. See also NonStop SQL (Structured Query
Language).
entry. A DSM object type representing a routing table or directory entry in the OSI manager
MIB. ENTRY objects are used to register local and remote OSI addresses and locally
defined application names (common names) with the OSI manager process. ENTRY
objects are of four types: application (APPL), TSEL, NSAP, and SNPA.
EOF (end of file). A marker placed at the end of a file to indicate that the file contains no
additional information.
error. (1) A condition that causes a command or other operation to fail. Contrast with
warning. (2) A code that indicates the outcome of a procedure call. For the procedures
in the FTAM API, this value can be either a negative error code defined by NonStop
FTAM or a positive NonStop file-system error number.
error code. A NonStop code returned on an APS_STATUS_ procedure call that indicates
the current error condition, if any, for the CEPI specified in the APS_STATUS_ call. If a
procedure-call error is indicated, you can call APS_STATUS_ to determine what
occurred. APS_STATUS_ returns error-code and error-subcode values that
provide more detail about the nature of the problem. See error subcode.
error identifier. An ISO-defined code included in a diagnostic message that identifies a
diagnostic error.
error observer. An ISO-defined code included in a diagnostic message that identifies the
entity that detected the diagnostic error.
error source. An ISO-defined code included in a diagnostic message to identify the
presumed entity that caused the reported error.
error subcode. A NonStop subcode qualifying error-code returned on an
APS_STATUS_ procedure call. If a procedure call error is indicated, call
APS_STATUS_ to determine what occurred. APS_STATUS_ returns error-code and
error-subcode values that provide more detail about the nature of the problem. See
error code.
error type. An ISO-defined code included in a diagnostic message that indicates the
diagnostic error type: informative message, permanent error, or transient error. See
informative message., permanent error., and transient error.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 7
event.
Glossary
event. (1) In NonStop OSI terms, an indication or confirm primitive that an application using
the FTAM or OSI/AS API retrieves by calling the APS_EVENT_RECEIVE_ procedure.
See also indication primitive. or confirm primitive. (2) In DSM terms, a significant
change in some condition in the system or network. Events can be operational errors,
notifications of limits exceeded, requests for action needed, and so on. See also EMS
(Event Management Service). and event message.
Event Management Service. See EMS (Event Management Service).
event message. On NonStop systems, a message triggered when a subsystem or system
component using the Event Management Service (EMS) detects the occurrence of a
condition that might affect its operation. Event messages are collected centrally and
distributed to files, processes, and terminals that are programmed to receive them.
They are displayed in text form as operator messages.
execution priority. A numeric-valued attribute of a NonStop process that determines
whether the NonStop operating system will preempt execution of the process in favor
of other processes running in the same CPU. The operating system always executes
the highest-priority process that is ready to run. In SCF, the execution priority of an
FTAM initiator or responder process is determined using the PRIORITY attribute of the
PROCESS object.
Expand network. A network of up to 255 NonStop systems, interconnected using the
Expand network operating software. NonStop systems on an Expand network are
referred to as nodes. extend (write action). To append the data being written to the end
of a file.
external process name. See Guardian process name.
FA (flat all data units). An access context for which data is transferred as a sequence of
node-descriptor data elements and file-contents data elements. The transfer begins
with the node-descriptor data elements, which mark the beginning of data for each
node in the structure. This methodology preserves the structural semantics of the file.
In NonStop FTAM, the only document type that uses FA is FTAM-2. See accesscontext parameter.; contrast with UA (unstructured all data units).
FADU (file-access data unit). A unit of the file-access structure on which the transfer,
delete, extend, replace, and insert actions can be performed. A FADU contains zero or
more data units.
FADU-locking functional unit. A functional unit that allows concurrency control locks to be
invoked on FADUs.
fault tolerance. The ability of a computer system to continue performing its designated
functions when any part of the system fails.
file-access data unit. See FADU (file-access data unit).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 8
file-access functional unit.
Glossary
file-access functional unit. A functional unit that provides for access to an individual FADU
in the file-access structure and allows the FADU to be manipulated within the
file-access structure.
file-access service class. The service class that allows access to remote files, and
includes data manipulation and file management capabilities.
file-attribute group. See attribute group.
file attributes. Information about a file such as file name, storage account, and date and
time of (file) creation. File attributes are present from one file access to another,
although the actual values of a file attribute might change. See also activity attributes.
file-availability attribute. An attribute that indicates whether a file is available for immediate
or deferred access. For example, a file on a nondemountable device might be
classified as having immediate availability, whereas a file on a demountable device
might be classified as having deferred availability, because a significant delay could be
encountered in accessing the file on the demountable device. The attribute value is set
when a file is created.
file-management service class. A service class that permits control of the virtual filestore
through a series of independent confirmed service exchanges, but does not include
file-transfer mechanisms. The file-management service class permits the ability to read
and change file attributes, and create and delete files.
file number. A unique number generated by the NonStop operating system to be used in
file-system calls. The number is assigned to a file when an application accesses that
file, and it is discarded when the application is finished with the file. You can display a
file number by issuing the SCF LISTOPENS command to the appropriate object.
file-open regime. The regime entered when you successfully open an FTAM file. In this
regime, you can locate a part of the file to be worked on, erase the file, or request
access to read or write information in the file. You can also close the file, and you can
abort the association. See also data-transfer regime., file-selection regime., and FTAM
regime.
file protocol machine. The protocol state machine for FTAM. See protocol state machine.
file-selection regime. The regime entered after you successfully select or create an FTAM
file. In this regime you can read file attributes, change the attributes, or open the file.
You can also deselect the file or delete the file, and you can abort the association. See
also data-transfer regime., file-open regime., and FTAM regime.
filestore-password parameter. The password used by an FTAM responder to authenticate
the initiator identity. For NonStop FTAM applications, if this parameter is not supplied
by the application, no password is sent to the remote responder.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary- 9
file-system request.
Glossary
file-system request. A request to the Guardian file system by or on behalf of a process.
Several different file-system requests are monitored for a process. You can view the
number of these requests that have occurred by issuing the SCF STATS PROCESS
command.
file storage system. An organized collection of files, including attributes and names,
residing on a computer system. On NonStop systems, the file storage system used is
the Guardian file system.
File Transfer, Access and Management. See FTAM (File Transfer, Access and
Management).
file-transfer-and-management service class. A service class that combines the services
of the file-transfer and file-management service classes. See file-transfer service class.
and file-management service class.
file-transfer service class. The service class that supports the movement of files or partial
files between independent computer systems on the network. The protocol for the
file-transfer class uses grouped operations that simplify data transfer.
File Utility Program. See FUP (File Utility Program).
filter. A NonStop file containing a list of criteria against which incoming EMS event
messages can be compared so as to pass a given message (if it met all criteria) or not
pass it (if it failed one or more criteria). See event message.
first-level data types. The lowest-level DDL structures, which serve as building blocks on
which DDL parameter structures are based.
format effectors. A class of control characters mainly intended for layout and positioning of
information on character-imaging devices, such as printers and video display terminals.
FTAM (File Transfer, Access and Management). A set of Application Layer services and
protocols used for manipulating files across an OSI network, as defined by the
ISO-8571 specification.
FTAM API. See API (application programmatic interface).
FTAM initiator errors. Locally generated errors returned when the return value on a
NonStop FTAM procedure call (shown in the NonStop FTAM manuals as status or
error, depending on the procedure) indicates an error. The value of status or
error indicates what occurred and how to proceed.
FTAM regime. The regime entered when you successfully establish an FTAM association.
In the FTAM regime, you can attempt to select or create a file, and you can terminate
or abort an association. See also data-transfer regime., file-selection regime., and fileopen regime.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -10
FTAM-1 file.
Glossary
FTAM-1 file. An unstructured text file that can be accessed only as a single data unit. See
also document type.
FTAM-2 file. A sequential text file that can be accessed either as a single data unit or as
multiple data units. See also document type.
FTAM-3 file. An unstructured binary file that can be accessed only as a single data unit.
See also document type.
FTM procedures. The set of procedure calls whose names begin with “FTM”, provided with
NonStop FTAM to support the FTAM protocol. The FTM procedures are defined in the
EXTDECS0 and CEXTDECS files. The FTAM API consists of the FTM procedures plus
the MFM procedures, a subset of the APS procedures, and associated definition files.
See also API (application programmatic interface).
functional unit. In OSI terms, a collection of service primitives needed to provide one of the
major optional styles of working, such as file access or enhanced file management.
Functional units are negotiated at association establishment. Functional units
determine which sets of FTAM services are available for an association, depending on
which service class is negotiated.
FUP (File Utility Program). A NonStop utility program that can be used to perform many
functions on disk files and peripheral devices such as tape drives. For example, you
can use FUP to create and purge files, duplicate and display files, alter file
characteristics such as security attributes, and load data into files.
future-filesize attribute. A file attribute that specifies the size limit (in octets) for
modification or extension of the file. The future-filesize attribute is related to the
NonStop max-extents attribute: modifying the future-filesize attribute changes the
max-extents attribute, and vice versa.
GeneralString. The character-string type of strings containing any of the characters for all
G sets and all C sets (as defined by ISO 2022), the space character, and the delete
character. These strings contain format effectors.
GraphicString. The character-string type of strings containing any of the characters for all
G sets (as defined by ISO 2022) and the space character. These strings do not contain
format effectors.
grouped procedure. An FTM procedure that allows an application to perform several file
operations as a grouped service. The grouped procedure FTM_FILE_OPEN_REQ_
allows you to create, select, and open an FTAM file as a grouped service. The grouped
procedure FTM_FILE_CLOSE_REQ_ allows you to close and either deselect or delete
an FTAM file as a grouped service. See grouped service.
grouped service. A sequence of confirmed services that are requested in one FTAM event,
and for which the responses are received as one event. The request primitives for
these services are bracketed with the F-BEGIN-GROUP and F-END-GROUP request
primitives. See also grouping control.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -11
grouping control.
Glossary
grouping control. A mode of operation that allows your application to perform a sequence
of confirmed services in one FTAM event. The request primitives for these services are
bracketed with the F-BEGIN-GROUP and F-END-GROUP request primitives. The
grouped request primitives are concatenated and sent in a single request PDU. The
responder analyzes and retains its response to each of these requests until the group
is complete or until a state failure occurs. The responder then returns its responses as
a group.
grouping functional unit. A functional unit that provides for the combination of several
independent primitives to establish several regimes in one exchange.
Guardian process name. The external name by which the NonStop operating system.
identifies a process. This name is assigned when a process is created using the NAME
attribute. To operate on an HP Expand network, this name must be a maximum of five
ASCII characters, including the initial dollar sign ($).
hierarchical file model. A file structure with the following characteristics:
•
•
•
•
•
The file-access structure is an ordered tree.
Each node within the structure is assigned zero or one data unit.
Each node provides access to its subtree.
A node can, optionally, be named.
There are no restrictions on the number of levels, on the arc lengths, or on the
number of arcs originating from each node.
The access unit, or subtree, of a node in this model is called a file-access data unit
(FADU). FTAM-2 files have a two-level hierarchy of one root node and many
second-level nodes. FTAM-1 and FTAM-3 files have only a single root FADU. See
FADU (file-access data unit). and root FADU.
HP Tandem Advanced Command Language (TACL). The user interface to the HP
NonStop operating system. The TACL product is both a command interpreter and a
command language. Users can write TACL programs that perform complex tasks or
provide a consistent user interface across independently programmed applications.
IA5String. The character-string type of strings containing any of the 32 control characters,
94 displayable characters, the space character, and the delete character, as defined by
CCITT Recommendation T.50. These strings contain format effectors.
indication primitive. A primitive issued when a service user (entity) is to be informed about
an event. This is one of four types of service primitives. See service primitive.
indication procedure. A procedure called to retrieve the indication data after an indication
primitive has been received. See indication primitive.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -12
indirect-process-name.
Glossary
indirect-process-name. A variable that represents the name of a NonStop initiator or
responder process as it is known to APLMGR. It consists of three parts:
$appl-mgrname, #proc-type, and internal-name, which are separated by periods
(.). An SCF command that uses this form of process name is sent to the
APLMGR process, which looks up the specified process in its MIB and then
routes the command to the process. Contrast with $process-name.
informative message. An ISO-defined type of diagnostic error code that does not require
recovery and does not affect the current state of the file service. An informative
message provides information to qualify a successful action. See also error type.,
permanent error., and transient error.
initiator. The file-service user that requests the establishment of the FTAM regime. In
NonStop FTAM, the initiator is a process that allows FTAM applications on a NonStop
system to access FTAM protocol and to request services of a responder on a remote
computer system. It operates by establishing an association with the remote responder
over the OSI network. The initiator then sends and receives FTAM protocol messages
to and from the remote responder. The FTAM application programmatic interface (API)
is the application program’s interface to the initiator process. See also FTAM API.;
contrast with responder.
initiator-identity parameter. A parameter that identifies the calling user on an FTAM
association. For NonStop FTAM applications, if this parameter is not sent by the
application, no initiator identity is supplied to the remote responder. See calling user.
Inspect. The HP NonStop interactive symbolic debugger, which enables you to isolate
errors in programs running on NonStop systems. Inspect features include interactive
control of program execution with breakpoints, distributed debugging across a network,
concurrent debugging of all parts of an application, saving and examining process
states, and local system and personal customization.
interactive interface. A set of rules by which a human operator is allowed to perform
functions at a terminal in response to system prompts. Contrast with programmatic
interface.
intermediate state. See state transition.
internal process name. The name by which APLMGR recognizes a NonStop initiator or
responder process. This name is assigned when the process is created and can be a
maximum of eight ASCII characters.
International Organization for Standardization. See ISO (International Organization for
Standardization).
International Standard. See IS (International Standard).
interpretability. The ability of an FTAM implementation to work with other FTAM
implementations to deliver FTAM services.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -13
IS (International Standard).
Glossary
IS (International Standard). A final specification standard issued by ISO.
ISO (International Organization for Standardization). A worldwide federation of national
standards bodies established to promote the development of standards to facilitate the
international exchange of goods and services, and to develop mutual cooperation in
areas of intellectual, scientific, technological, and economic activity.
ISO FTAM. Generic FTAM as specified in the ISO 8571 standard.
ISO FTAM diagnostic messages. Diagnostic messages typically returned from the remote
responder, although in certain cases they might be returned locally. ISO diagnostic
messages are defined in the ISO 8571 standard for FTAM, and apply generically to
any FTAM application. Diagnostic messages can be retrieved by some indication and
confirm procedures. In addition, programs using the FTAM API can send diagnostic
messages to the remote responder using the FTM_CANCEL_REQ_,
FTM_DATA_END_REQ_, and FTM_U_ABORT_REQ_ procedures. See also
diagnostic parameter.
ISO Reference Model for Open Systems Interconnection. See OSI Reference Model.
ISO646String. See VisibleString.
kernel functional unit. A functional unit that is required of all service classes used in the
establishment and release of the FTAM and file-selection regimes.
kernel group. File attributes that must be supported by all FTAM implementations. You do
not negotiate attributes in the kernel group.
layer. There are seven layers in the OSI Reference Model. See Application Layer.,
Presentation Layer., Session Layer., Transport Layer., Network Layer., Data Link
Layer., and Physical Layer.
leaf. A node in a hierarchical file structure that has no child nodes: that is, no nodes that
terminate outbound arcs of the node in question.
limited-file-management functional unit. The functional unit that supports the creation
and deletion of files and the reading of file attributes.
local application. An FTAM application that runs on a NonStop system and uses the FTAM
API.
Management Information Base. See MIB (Management Information Base).
management interface. An interface available to the system manager for use in
configuring, monitoring, and controlling subsystems and relationships between
subsystems.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -14
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. A set of procedure calls, used with NonStop
FTAM and NonStop OSI/AS, that allow you to complete I/O operations performed in
nowait mode and to cancel a nowait operation. The names of the MFM procedures
begin with the letters MFM. The MFM procedures are defined in the EXTDECS0 and
CEXTDECS files. These procedures are part of the FTAM API. See also API
(application programmatic interface).
MIB (Management Information Base). (1) A database used by the OSI manager process
to store and retrieve configuration information and information about applications. (2) A
database used by APLMGR to store and retrieve FTAM configuration information.
module file management procedures. See MFM (module file management) procedures.
named values. DDL variables that specify values or sets of values that can be assigned to
FTAM procedure parameters or parameter fields.
National Institute of Science and Technology. See NIST (National Institute of Science
and Technology).
NBS (National Bureau of Standards). Former name of the National Institute of Science
and Technology (NIST). See NIST (National Institute of Science and Technology).
NBS-9. A file that is a read-only directory as defined by the NIST FTAM Phase 2
agreements. See also document type.
negotiation. The act of defining parameter values to be used on an FTAM association. For
example, in the initialize request (the FTM_INITIALIZE_REQ_ procedure call when
using the FTAM API), you propose a list of the attribute groups (storage and/or
security) that you want to be available for the association, using the attrib-groups
parameter. The responder inspects the attributes you propose and might reduce the list
to what it can support; it cannot add to the list you propose. When attribute groups
have been negotiated, you can use the attributes from those groups along with the
associated protocol.
Network Layer. Layer 3 in the OSI Reference Model. This layer routes data by establishing,
maintaining, and terminating communication between systems. It sets up a path, both
physical and logical, between communicating systems; routes messages through
intervening systems to their destination; and controls the flow of messages between
systems.
Network service access point. See NSAP (network service access point).
network service provider. See NSP (network service provider) process.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -15
NIST (National Institute of Science and Technology).
Glossary
NIST (National Institute of Science and Technology). A U.S. government institution,
formerly known as the National Bureau of Standards (NBS), that sets standards and
promotes their acceptance.
node. (1) The basic building block of the FTAM hierarchical file structure.
(2) A NonStop system that is part of an Expand network.
node descriptor. The part of an FTAM-2 FADU that contains information identifying the
node within the FTAM hierarchical file structure.
node name. The part of a node descriptor that names the node. See node descriptor.
nonsensitive command. An SCF command that can be issued by any user or program
allowed access to the target subsystem—that is, a command on which the subsystem
imposes no further security restrictions. For NonStop data communications
subsystems, the nonsensitive commands are all those that cannot change the state or
configuration of objects (usually information commands). Contrast with sensitive
command.
NonStop FTAM (File Transfer, Access and Management). The NonStop implementation
of the ISO FTAM standard that provides the ability to manipulate files between local
and remote file stores on a network.
NonStop OSI/AS. See OSI/AS (Application Services).
NonStop OSI/FTAM. See NonStop FTAM (File Transfer, Access and Management).
NonStop OSI/TS. See OSI/TS (Transport Services).
NonStop process pair. See process pair.
NonStop SQL (Structured Query Language). The NonStop product that provides
configuration and management of relational databases that conform to the SQL
(structured query language) standard. See SQL (structured query language).
nowait mode. In Guardian file-system operations and in some APS operations, the mode in
which the called procedure initiates an I/O operation but does not wait for it to complete
before returning control to the caller. The application calls a separate procedure
(MFM_AWAITIOX_) to wait for the completion of the operation. Contrast with wait
mode.
NSAP (network service access point). The logical point at which Network Layer services
are provided by the Network Layer entity to the Transport Layer entity.
NSP (network service provider) process. A process in the NonStop OSI implementation
that performs service and protocol functions for the Network Layer and, for LANs,
some functions of the Data Link Layer. NSP processes are provided by the underlying
X25AM and TLAM subsystems. See also TSP (transport service provider) process.
and TAPS (Tandem application, presentation, and session) process.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -16
null object type.
Glossary
null object type. A NonStop term used to represent the absence of an object type in an
SCF command. If a command supports the null object type, you can issue it without
specifying an object type. For NonStop FTAM, the NAMES and VERSION commands
support the null object type. The NAMES null command refers to a collection of object
types; for the VERSION null command, the object type is irrelevant.
object. (1) A well-defined piece of information, definition, or specification that requires a
name. Also called information object. (2) In general NonStop terms, one or more of the
devices, lines, processes, and files in a NonStop subsystem: any entity subject to
independent reference or control by one or more subsystems. An object typically has a
name and a type known to the controlling subsystem.
object identifier. A value, distinguishable from all other such values, that is associated with
an ISO information object. A standard representation of an object identifier is a set of
numbers representing a directed path through a standards-based tree hierarchy, often
shown as a sequence of two or more values enclosed in braces ({}). Examples of
objects represented by object identifiers are document type names, constraint sets,
abstract syntaxes, transfer syntaxes, and AE titles.
object state. See state.
object state transition. See state transition.
octet. A byte of data; eight bits.
OctetString. The string type consisting of a string of octets. See octet.
open. An established line of communication between two processes. You can display the
number of opens a process has by issuing the SCF STATUS PROCESS command.
open network. A communications network that can communicate between systems using
standardized procedures and functions.
Open Systems Interconnection. See OSI (Open Systems Interconnection).
operator message. A message, describing a significant event on a NonStop system, that is
intended to be seen by an operator. An operator message is the displayed-text form of
an EMS event message. See event message.
optional parameter. (1) In a PDU, a parameter that is sometimes but not always present.
(2) In the NonStop FTAM API, a procedure-call parameter that can be included in a
given procedure call or command, but is not required for use with the procedure or
command. Contrast with conditional parameter and required parameter.
original-error-info parameter. A parameter in the APS_STATUS_ procedure call that
provides a code identifying the first error detected in NonStop FTAM or an underlying
OSI layer. Using the service ID, which indicates the source of the error, and the value
returned by original-error-info, you can refer to HP manuals for further information
about the problem. See also service ID.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -17
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). The NonStop implementation of the Session Layer, the
Presentation Layer, and part (ACSE) of the Application Layer of the OSI
Reference Model. The OSI/AS subsystem manages the communication of
messages between a local NonStop system and a remote system on a network. This
subsystem manages the lower-layer services provided by NonStop OSI/TS, X25AM,
and TLAM.
OSI manager process. A process in the OSI/AS subsystem that performs subsystem
management functions. There is one OSI manager process per OSI/AS subsystem.
OSI Reference Model. A communications architecture, adopted by the ISO in 1984, that
includes seven layers that define the functions involved in communications between
two systems, the services required to perform these functions, and the protocols
associated with these services. See also layer.
OSI subsystems. The NonStop subsystems that support the various layers and application
service elements of the OSI Reference Model, including the FTAM subsystem,
APLMGR, OSI/AS, OSI/TS, and TLAM or X25AM.
OSI/TS (Transport Services). The NonStop subsystem that manages the communication
of messages from the Transport Layer on a local NonStop system to the Transport
Layer on a remote system in an OSI network.
owner ID. The identity (Guardian user ID) of the owner of a process on a NonStop system.
parallel associations. Multiple associations running concurrently within a NonStop FTAM
process.
parameter structures. DDL structures that define some of the reference parameters for the
FTM, APS, and MFM procedures.
partially supported file attribute. A virtual filestore (VFS) file attribute, in a supported
storage or security attribute group, for which any reference by the FTAM responder
yields the result that no value is available, and any attempt to change the attribute fails.
In summary, the VFS recognizes the attribute name but provides no value for it.
Contrast with supported file attribute.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -18
PDU
Glossary
PDU. The encoded message transferred across the OSI network between peer entities—for
example, between an FTAM initiator and responder. Data, such as a block of
information being transferred or a protocol primitive, is encoded into a PDU for transfer
across the network. The PDU is decoded when it arrives at its destination. Types of
PDUs include the following:
•
•
•
•
APDU (application PDU): information exchanged between Application Layer
entities—this includes ACSE and presentation PDUs created to support the FTAM
protocol (FTAM PDUs, or FPDUs)
PPDU (presentation PDU): information exchanged between Presentation Layer
entities
SPDU (session PDU): information exchanged between Session Layer entities
TPDU (transport PDU): information exchanged between Transport Layer entities
permanent error. An ISO-defined type of diagnostic error that occurs every time the
sequence of events that caused the error is repeated, and implies the failure of at least
the present operation being performed. See also error type., informative message.,
and transient error.
permitted-actions attribute. A file attribute that can be returned in an F-READ-ATTRIB
indication or confirm or set in an F-CREATE request. It specifies the actions that can
be performed on the file or the mode of access to FADUs in the file. During the
F-CREATE service, the initiator proposes a set of values. The responder can either
accept the proposed values or change them to any set of values it can handle: for
example, a default set of permitted actions that is always used for a specific document
type regardless of what is proposed. The responder implements the set of permitted
actions in some way that maps them onto the underlying real system.
Physical Layer. Layer 1 in the OSI Reference Model. This layer establishes the actual
physical connection between the network and the computer equipment. Protocols at
the Physical Layer include rules for the transmission of bits across the physical
medium and rules for connectors and wiring.
PID (process identifier). The combination of the central processing unit (CPU) number and
the process identification number (PIN) for a process running on the NonStop
operating system.
port address. For X25AM lines, the logical port number used with the X.25 network; for
TLAM, the address used to communicate with a LAN controller.
PPDU (presentation PDU). See PDU.
presentation address. An unambiguous name used to identify a set of presentation service
access points (PSAPs) that are all located at a boundary between a Presentation
Layer implementation and an Application Layer implementation in the same open
system.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -19
presentation context.
Glossary
presentation context. The combination of an abstract syntax and a transfer syntax on a
Presentation Layer connection. In NonStop FTAM, you have programmatic control over
the choice of presentation context related to document types, but not over the required
abstract syntaxes associated with the protocol control information (PCI) for FTAM,
ACSE, and the Presentation Layer.
Presentation Layer. Layer 6 in the OSI Reference Model. This layer provides a means to
resolve the differences of varying data formats between systems of different vendors. It
transfers data in a system-independent manner, performing appropriate conversions at
each system as necessary.
presentation selector. See PSEL (presentation selector).
presentation service access point. See PSAP (presentation service access point).
primary process. The currently operating process of a process pair on a NonStop system.
See backup process.
primitive. An abstract, implementation-dependent representation of an interaction between
a user of OSI services and a service provider. Examples of FTAM primitives are an
F-OPEN request, an F-P-ABORT indication, an F-CREATE response, and an
F-READ-ATTRIB confirm.
PrintableString. The character-string type of strings containing only printable characters
and the space character, as defined in ISO 8824. These strings do not contain format
effectors.
printing distributor. An EMS process that obtains formatted text for selected event
messages and distributes it to a file, a printer, or another display device.
priority. See execution priority.
private group. A free-standing group of FTAM attributes that are outside the scope of OSI
standardization.
process. A running entity, managed by the operating system, that is created by taking a
program from a file on a disk and running it in a processor.
process pair. A primary process and its backup process, created as a pair to provide fault
tolerance on a NonStop system. The backup process takes over if the primary process
fails.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -20
profile.
Glossary
profile. (1) A complete set of self-consistent parameters specifying which options in one or
more OSI standards will be supported by a group of implementations for a particular
purpose. For example, the U.S. Government Open Systems Interconnection Profile
(GOSIP) is a profile to which implementations must conform to be eligible for certain
government contracts. (2) For NonStop FTAM, a type of object defining a template that
contains configuration parameters for NonStop FTAM responder processes. When a
profile is specified for a process, the configuration parameters in the profile take
precedence over any corresponding parameters specified for the process. (3) For
NonStop OSI/AS, a type of object defining a template that contains configuration
parameters for OSI/AS dynamic subdevices. When a profile is specified for a
connection, the configuration parameters in the profile take precedence over any
corresponding parameters specified for the service as a whole.
profile type. A particular type of NonStop FTAM or OSI/AS profile. The only valid profile
type for NonStop FTAM is the virtual filestore (VFS) profile.
programmatic interface. A set of procedures and accompanying definitions that enable
programs to request services or operations. Contrast with interactive interface.
protocol. The set of rules governing the format and meaning of the frames, packets, or
messages exchanged by the peer entities within an OSI layer. See also service.
protocol data unit. See PDU.
protocol state machine. The part of a data communications process, such as an FTAM
initiator or responder process, that acts upon occurrences according to the current
state of the protocol.
provider abort. An association abort initiated by the service provider (for example, FTAM).
An abort leaves the status of any interrupted operations undefined. Contrast with user
abort.
PSAP (presentation service access point). The point at which a Presentation Layer
implementation provides presentation services to an Application Layer implementation.
The PSAP is highly system-dependent and generally refers to the way interlayer
communication is accomplished. See also SAP (service access point).
PSAP address. A presentation address that is used to identify a single PSAP. See PSAP
(presentation service access point).
PSEL (presentation selector). A logical address in the Presentation Layer through which
presentation services are made available to Application Layer implementations. On a
NonStop system, the PSEL is a number that uniquely links a TAPS process with a
process that implements Application Layer services—for example, an FTAM initiator or
responder.
PTrace (print trace). A NonStop utility that you can use to select, format, and display
unstructured trace data generated when you issue the SCF TRACE command.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -21
read functional unit.
Glossary
read functional unit. A functional unit that allows the following activities on an association:
•
•
•
Establishing the file-open regime
Transferring data from the responder to the initiator
Releasing the file-open regime
receiver. The entity that receives a communication from a remote sender.
recovery functional unit. An ISO FTAM functional unit that allows the initiator process to
recreate a previously destroyed regime.
regime. A protocol state that reflects the programming status in an FTAM program
sequence. NonStop FTAM and ISO FTAM have four regimes: FTAM regime,
file-selection regime, file-open regime, and data-transfer regime.
register request. (1) For NonStop FTAM, a request made by the FTAM API to the APLMGR
process, on behalf of an application, to establish an FTAM association. Processing an
FTAM register request includes selecting an available initiator process to service the
association. (2) For NonStop OSI/AS, a request made by the API to the OSI manager
process, on behalf of an application, either to establish an association (or connection)
or to wait for an incoming association (or connection).
relaxation. The process of deriving one document from another by making the parameters
describing it less restrictive. In particular, the legal modification of values for the
maximum-string-length, string-significance, or universal-class
parameters for a specific FTAM document type. String-length relaxation allows a
document of with a given maximum-string-length value to be opened and read using a
larger maximum-string-length value or no maximum-string-length value (unbounded
string). Character-set relaxation allows a document of a given universal-class number
to be opened and read using a different universal-class number as long as the new
universal-class number permits all characters from the original universal-class number.
request primitive. A primitive issued when a service user (entity) wants the service to do
some work. This is one of four types of service primitives. See service primitive.
request procedure. A procedure called to cause the initiating process to send a request
primitive to a responding process. See request primitive.
required parameter. (1) In a PDU, a parameter that is always present. (2) In a NonStop
programmatic or interactive interface, a parameter to a procedure (for example, a
procedure in the FTAM API) or to an interactive command (such as an SCF command)
that must be specified when the procedure is called or the command is issued.
Contrast with conditional parameter and optional parameter.
reset time. In SCF, the date and time that the statistical counters for an object were last
reset. The STATS command for the object displays the reset time.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -22
responder.
Glossary
responder. The file-service user that accepts an initiator’s request to establish an FTAM
regime. In NonStop FTAM, the responder is a process that services FTAM requests
initiated from remote systems on an OSI network. The NonStop responder acts as an
FTAM file server, mapping FTAM requests into Guardian file operations and providing a
translation between Guardian file structures and FTAM file structures. The NonStop
responder has no programmatic interface. Contrast with initiator.
responding address. The OSI address of the responder that responds to an association
request from an initiator in an FTAM application. Contrast with called address and
calling address.
responding user. The responder that responds to an association request from an initiator in
an FTAM application. Contrast with called address and calling address.
response primitive. A primitive issued when a service user (entity) wants to respond to an
event (for confirmed services only). This is one of four types of service primitives. See
service primitive.
response procedure. A procedure called by your application to send response primitives to
indications from the FTAM responder. See response primitive.
restart-data-transfer functional unit. An ISO FTAM functional unit that allows the transfer
of data to be interrupted and immediately restarted in a current transfer.
reverse traversal. Traversal through the nodes of an FTAM file in reverse order (last to
first).
root FADU. The first-level FADU in an FTAM file. In the case of FTAM-1 and FTAM-3 files,
the complete file is one FADU and so can be considered the root FADU. FTAM-2 files
consist of two levels of FADUs in a hierarchical structure. The root FADU provides
access to the complete file. See FADU (file-access data unit).
root node. The first-level node in a hierarchical file. See root FADU.
Safeguard. The NonStop system-software security package that implements three security
features: user authentication, object-access authorization, and auditing. sample time.
In SCF, the date and time that the currently displayed statistics for an object were
gathered. The sample time is displayed by the STATS command along with the
statistics.
SAP (service access point). The point at which an implementation of a given OSI layer
provides its services to an implementation of the layer above it. The SAP is highly
system-dependent and generally refers to the way interlayer communication is
accomplished.
SCF (Subsystem Control Facility). A utility that provides a common, interactive
management interface for configuring, controlling, and collecting information from
NonStop data communications products.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -23
SCF kernel.
Glossary
SCF kernel. The part of the SCF software that provides subsystem-independent functions,
such as accepting user input commands.
SCP (Subsystem Control Point). The process used to provide the focal point for all
NonStop data communications subsystems. There can be several instances of this
process. Applications using SPI send all commands for data communications
subsystems to an instance of this process, which in turn sends the commands on to
the manager processes of the target subsystems. SCP also processes a few
commands itself. It provides security features, version compatibility, support for tracing,
and support for applications implemented as process pairs.
second-level data types. DDL data types made up of one or more first-level data types.
See first-level data types.
security group. File attributes that pertain to security and access control. These attributes
are negotiated at association establishment. The security group attributes are access
control and legal qualifications. sender. The entity that initiates and sends a
communication to a remote receiver. See receiver.
sensitive command. An SCF command that can be issued only by a restricted set of
Guardian users, such as process owners and super-group users. For NonStop data
communications subsystems, the sensitive commands are those that can change the
state or configuration of objects, start or stop tracing, or change the values of statistics
counters. Contrast with nonsensitive command.
sequential flat file. An unstructured file whose data must be accessed sequentially.
service. The functions and features provided by a given layer to the layer above it in the
OSI Reference Model. Also, the functions and features provided to the application
programmer by the NonStop FTAM process. See also protocol.
service class. A set of functional units negotiated at association establishment. ISO FTAM
specifies five levels of service classes.
service ID. A value identifying the NonStop OSI service that is the source of an error
condition being reported. The APS_STATUS_ procedure returns service ID values in
the service-id parameter and within the structure returned in the originalerror-info parameter. See also original-error-info parameter.
service primitive. An abstract, implementation-independent interaction between a service
user and a service provider. Service primitives describe the sequences of events
between adjacent layers that occur through the service access point (SAP). There are
four types of service primitives. See also request primitive., indication primitive.,
response primitive., and confirm primitive.
service provider. An entity that provides services for a higher-layer entity. For example, the
FTAM initiator is a service provider, providing FTAM services to an FTAM application
program. Contrast service user.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -24
service user.
Glossary
service user. An entity that uses services provided to it by a lower-layer entity. For
example, the FTAM initiator is a service user of ACSE and presentation services
provided by OSI/AS. Contrast service provider.
session address. See SSAP (session service access point).
Session Layer. Layer 5 in the OSI Reference Model. This layer allows the setup and
termination of communication sessions between systems on the network.
session selector. See SSEL (session selector).
session service access point. See SSAP (session service access point).
simplification. The process of deriving one document from another document of a different
type by discarding structural information. In particular, the act of reading a file of a
specific FTAM document type as a less structured, or simpler, FTAM document type.
SPDU (session protocol data unit). See PDU.
SPI (Subsystem Programmatic Interface). A set of procedures and associated definition
files used on NonStop systems to define common message-based interfaces for
communication between requesters and servers—for example, in a management
application. The SPI interface to NonStop FTAM is not available for customer use.
SQL (structured query language). A fourth-generation-language standard that provides a
means to access and associate data in a relational database.
SSAP (session service access point). A network-unique address in the Session Layer
through which connections are established and maintained; also called session
address.
SSEL (session selector). A logical address in the Session Layer through which session
services are made available.
state. (1) The condition at a particular point in the OSI protocol. See also protocol state
machine. (2) In DSM, the current condition of an object that indicates its readiness to
do work. States for PROCESS objects include STARTED, STOPPED, SUSPENDED,
and UNKNOWN. The only state for SU objects is STARTED; the only state for
SUBSYS objects is DEFINED. See also state transition.; also called summary state.
state machine. See protocol state machine.
state-result parameter. A parameter, returned in indications and confirms for primitives that
establish a regime, that indicates whether or not the remote responder has established
the requested regime. The valid values are success (ZFTM-VAL-STATESUCCESS in
the FTAM API) and failure (ZFTM-VAL-STATE-FAILURE in the FTAM API). Note that
this parameter is not returned for primitives that cannot fail, such as F-DELETE,
F-CLOSE, and F-DESELECT. For such primitives, only action-result is returned. See
action-result parameter.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -25
state transition.
Glossary
state transition. In DSM, a condition that exists when a process is in transition from one
state to another. State transitions for PROCESS objects include ABORTING,
STARTING, STOPPING, and SUSPENDING. Also called summary-state transition.
status. A NonStop procedure completion code that indicates the outcome of a call. This
code can assume one of nine values.
storage group. File attributes that provide information about a file and the data stored in it.
These attributes are negotiated at association establishment. The storage-group
attributes include the following:
•
•
•
•
•
•
•
•
•
•
•
•
Storage account
Date and time of creation
Date and time of last modification
Date and time of last read access
Date and time of last attribute modification
Identity of creator
Identity of last modifier
Identity of last reader
Identity of last attribute modifier
File availability
File size
Future file size
string-significance parameter. A parameter of contents-type. This parameter applies to
the semantics of the file transfer. The values of this parameter are fixed, variable, and
not significant. See also maximum-string-length parameter., relaxation., and contentstype parameter.
structured query language. See SQL (structured query language).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -26
subdevice.
Glossary
subdevice. A logical entity maintained by a NonStop subsystem to provide access to a
physical connection—that is, to a communications line. There might be one or many
subdevices associated with a given line or process. Exactly what constitutes a
subdevice differs depending on the subsystem. In OSI subsystems, a subdevice allows
communication between a process at a particular OSI layer, such as an FTAM initiator
or responder, and the local NonStop OSI server process (TAPS, TSP, or NSP) that
provides the services of the next lower layer. Each initiator subdevice handles one
association or (at layers below ACSE) one connection. Each responder subdevice
handles one attach, which is used to establish an association requested by a remote
application.
A NonStop FTAM initiator subdevice is created dynamically when an association is
established and usually lasts only as long as the association exists. A NonStop FTAM
responder subdevice is created when the responder issues an attach.
subsystem. (1) A term that generally defines the NonStop software or hardware facilities
that provide users with access to a set of services and other resources. (2) In the
context of DSM, a program or set of processes that manages a cohesive set of objects.
Each subsystem has a process through which applications can request services by
issuing commands defined by that subsystem; in some cases, this process is the entire
subsystem. Many subsystems also have interactive interfaces.
Subsystem Control Facility. See SCF (Subsystem Control Facility).
Subsystem Control Point. See SCP (Subsystem Control Point).
Subsystem Programmatic Interface. See SPI (Subsystem Programmatic Interface).
subtree. A part of a tree comprising an arbitrary node as the subtree root node and all the
other nodes that can be reached by a path from this subtree root node. See tree.
summary state. A DSM state. See state. (definition 2).
summary-state transition. See state transition.
super group. The set of NonStop operating system users whose group ID is 255. User IDs
within the super group confer implicit authorizations not available to other users,
including the ability to run sensitive SCF commands.
super ID. The NonStop user ID represented by the pair of numbers (255,255). The local
super ID is the group manager for the super group. By default, the super ID can run
any command without restriction.
supported file attribute. A virtual filestore (VFS) file attribute that can be referenced or
modified. Contrast with partially supported file attribute.
swap disk. See swap volume.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -27
swap volume.
Glossary
swap volume. An optional disk volume used as an additional memory source during the
operation of any process under the NonStop operating system.
TACL. See HP Tandem Advanced Command Language (TACL).
tag parameter. An optional procedure-call parameter you can use in nowait applications on
NonStop systems to match nowait I/O requests with completions. If there are multiple
I/O requests outstanding in your application, the tag indicates which one has
completed.
TAL (Transaction Application Language). A high-level, block-structured language used to
write systems software and routines that support transaction-oriented applications on
NonStop systems. The TAL compiler translates source programs written in TAL into
executable object programs.
TAPS (Tandem application, presentation, and session) process. A process in the
OSI/AS subsystem that performs service and protocol functions for ACSE (in the
Application Layer), the Presentation Layer, and the Session Layer. The TAPS process
also performs some management services in the DSM environment. See also NSP
(network service provider) process. and TSP (transport service provider) process.
TAPS subdevice. A subdevice, maintained by OSI/AS, that enables communication
between an FTAM initiator or responder and the TAPS process. See subdevice.
TeletexString. The character-string type of strings conforming to CCITT Recommendation
T.61. These strings do not contain format effectors.
TLAM (Tandem LAN access method). A NonStop product that implements, for LANs, the
services of the Data Link Layer and layers below.
TPDU (transport protocol data unit). See PDU.
trace file. The file in which the SCF trace facility collects trace information while a trace is in
progress.
Transaction Application Language. See TAL (Transaction Application Language).
transfer syntax. In the Presentation Layer, the definition of the exact bit patterns to be used
to convey specified kinds of information in a communication. See also abstract syntax.
transient error. An ISO-defined type of diagnostic error that might not recur if the sequence
is repeated but does indicate the failure of the operation being performed. See also
error type., informative message., and permanent error.
transition state. See state transition.
transport address. See TSAP (transport service access point).
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -28
Transport Layer.
Glossary
Transport Layer. Layer 4 in the OSI Reference Model. This layer provides reliable data
transfer.
transport selector. See TSEL (transport selector).
transport service access point. See TSAP (transport service access point).
transport service provider. See TSP (transport service provider) process.
traversal. An ordering of the nodes in a tree such that each node occurs only once, and
which is determined by an algorithm applicable to all possible trees.
tree. A connected hierarchical file structure in which each node is linked to other nodes by
directed arcs in such a way that one node has no inbound arcs, and all other nodes
have exactly one inbound arc. See also subtree.
TSAP (transport service access point). A network-unique address in the Transport Layer
through which connections are established and maintained. Also called transport
address.
TSEL (transport selector). A logical address in the Transport Layer through which
transport services are made available.
TSP (transport service provider) process. A process in the NonStop OSI end system that
performs service and protocol functions for the Transport Layer and for the internet
protocol (IP) of the Network Layer. TSP processes are provided by the underlying
OSI/TS subsystem. See also NSP (network service provider) process. and TAPS
(Tandem application, presentation, and session) process..
UA (unstructured all data units). An access context for which data is transferred as
file-contents data elements; that is, only the data contents of the file are transferred.
See access-context parameter.; contrast with FA (flat all data units).
unconfirmed service. A subsystem service in which the initiating application sends a
request to a responding application without a response being returned to the initiating
application. Contrast with confirmed service.
unconstrained class. An ISO FTAM service class consisting of the kernel functional unit
and (optionally) any other functional unit.
universal-class number. (1) The ASN.1-specified tag for the character-string type used on
a data transfer. (2) A parameter of contents-type that specifies a code for this tag. See
also relaxation. and contents-type parameter.
unstructured file. The structure of FTAM-1 and FTAM-3 files, in which the complete file is
treated as one FADU.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -29
user abort.
Glossary
user abort. An association abort initiated by the application. An abort leaves the status of
any interrupted operations undefined. FTAM provides the F-U-ABORT service to allow
applications to request a user abort. Contrast with provider abort.
VFS (virtual filestore). A virtual interface for FTAM requests to a file storage system. The
NonStop FTAM responder implements a VFS that translates requests into Guardian
file-system operations. Files accessible via the Guardian file system can also be
accessed via the VFS component of the NonStop FTAM responder. This includes all
files on the Expand network to which the responder process’ system belongs. The
NonStop FTAM responder uses the VFS to access the Guardian file system in
servicing requests from a remote FTAM initiator.
VFS profile. A NonStop FTAM profile used as a template to configure multiple responder
processes. This is the only valid profile type for NonStop FTAM.
VideotexString. The character-string type of strings conforming to CCITT Recommendation
T.100. These strings contain format effectors.
ViewPoint operations console application. An extensible interactive application for
operators of NonStop systems. The ViewPoint application allows a system or network
to be controlled from a single terminal. It includes several block-mode display screens
for event messages, a block-mode display for system or network status, a
conversational TACL screen, and a facility called Define Process to maintain sessions
with multiple subsystems at the same time.
virtual filestore. See VFS (virtual filestore).
VisibleString. The character-string type of strings containing any of the 94 graphic
characters and the space character, as defined in ISO 646. These strings do not
contain format effectors. Also called ISO646String.
wait mode. In Guardian file-system operations and some APS operations, the mode in
which the called procedure waits for the completion of an I/O operation and then
returns a condition code to the caller. Contrast with nowait mode.
warning. An information-only message returned by the system, indicating a possible
problem. A warning can be significant, but does not cause the command or operation
to fail. A warning is less serious than an error. Contrast with error.
write functional unit. A functional unit that allows the following activities on an association:
•
•
•
Establishing the file-open regime
Transferring data from the initiator to the responder
Releasing the file-open regime
X25AM (X.25 Access Method). A NonStop product that implements the services of the
Network Layer and the Physical Layer for WANs.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -30
X.25 network.
Glossary
X.25 network. Any network or subnetwork linked using X.25 standards. X.25 standards are
CCITT standards that define packet-switching carrier communication in the Network
Layer over wide area networks (WANs).
$process-name. A variable that represents the Guardian process name of a NonStop
initiator or responder process. An SCF command that uses this form of process name
is sent directly to the specified initiator or responder process, rather than to the
APLMGR process. Contrast with indirect-process-name.
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -31
$process-name.
Glossary
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Glossary -32
Index
A
API
Aborting associations
requesting 4-147/4-149
retrieving indication
information 4-121/4-122, 4-150/4-151
See also FTM_P_ABORT_xxx
procedures
See also FTM_U_ABORT_xxx
procedures
Access, file
context A-13
control A-12
determining A-13
error subcodes B-23
ISO FTAM diagnostic
messages C-6/C-7
passwords A-14
See also Selecting files
access-context parameter 4-3, 4-124
access-passwords parameter
associated procedures 4-3
description 4-38, 4-84, 4-134
examples G-124, G-131, G-181, G-188
Account charged A-15, A-18
account parameter 4-3, 4-38, 4-86, 4-97,
4-134
ACSE associations 1-5
action-result parameter 4-3, 4-16, 4-19,
4-21, 4-23, 4-29, 4-34
Addresses
See OSI address and Common name
ae-title parameter
description A-6
examples G-115, G-172
See also local-ae-title
See also remote-ae-title
See also responding-ae-title
See FTAM API
See OSI/AS API
APLMGR process, subcodes returned
by B-12
APLMGR subsystem
architecture 1-7, 1-8
aplmgr-name parameter 4-4, 4-93
Application Control Service Element
See ACSE
Application programmatic interfaces
See FTAM API
See OSI/AS API
Applications
example types 1-2
programming capabilities 1-3
Application, context name A-7
Application, presentation, and session
procedures
See APS procedures
APS error codes
descriptions B-4/B-19
table of B-4
APS procedures
definition 3-4
external declarations 4-1
overview 1-9/1-10
Programming Example 1
example structure and
protocol G-3/G-5
example, in C G-12/G-55
example, in TAL G-56/G-105
Programming Example 2
example structure and
protocol G-6/G-11
example, in C G-106/G-160
example, in TAL G-161/G-220
See also individual procedure names
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -1
B
Index
APS procedures (continued)
using F-1
APS_DISCARD_ procedure
description F-3
examples, in C G-29, G-54, G-145
examples, in TAL G-76, G-104, G-202
APS_EVENT_RECEIVE_ procedure
description F-4
examples, in C G-27, G-34, G-146
examples, in TAL G-74, G-90, G-203
APS_INITIALIZE_ procedure
description F-6
examples, in C G-20, G-113
examples, in TAL G-66, G-171
APS_STATUS_ procedure
description F-7
examples, in C G-30, G-49, G-146,
G-148
examples, in TAL G-87, G-95, G-204,
G-205
Architecture
APLMGR subsystem 1-7, 1-8
FTAM subsystem 1-7, 1-8
NonStop FTAM 1-5/1-7
NonStop initiator 3-1/3-2
ASN.1
abstract syntax name A-6
transfer syntax A-11
Association Control Service Element
See ACSE association
Associations
aborted by OSI 4-121/4-122
aborting
requesting 4-147/4-149
retrieving indication
information 4-150/4-151
definition 1-5
initiating
requesting 4-93/4-100
retrieving response 4-101/4-105
Associations (continued)
obtaining information F-7
terminating
requesting 4-139/4-140
retrieving response 4-141/4-142
terminating API context information F-3
Attributes
available during file creation A-23/A-24
changing
requesting 4-26/4-28
retrieving response 4-29/4-31
groups A-15
groups, table of 3-10
readable when requesting attribute
list A-33/A-36
reading
requesting 4-127/4-129
retrieving 4-130/4-132
returned by responder A-16
specified during file creation A-24/A-25
table of 3-10
to be changed A-17
attrib-groups parameter 4-4, 4-96, 4-103
attrib-names parameter 4-4, 4-127
AWAITIOX procedure,upgrading E-1
B
Beginning a group of procedures 4-13/4-15
Block data transfer
ending
requesting 4-44/4-46
retrieving request
information 4-47/4-48
receiving 4-53/4-57
transferring 4-49/4-52
block-size parameter F-5
buffer-addr Parameter E-3
buffer-size parameter 4-4, 4-55
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -2
C
Index
C
C declarations file
See CEXTDECS file and ZOSIFTAM
file
C declarations files
See CEXTDECS file and ZFTMC file
Cancelling a data transfer regime
requesting 4-16/4-18
responding 4-23/4-25
retrieving indication
information 4-21/4-22
retrieving response
information 4-19/4-20
Cancelling nowait operation E-4
CANCELREQ procedure E-4
cepi parameter 4-4
CEXTDECS file 4-1, E-1, F-1
change-attrib parameter 4-4, 4-26, 4-29
Changing access control values A-14
Changing file attributes
DDL structure A-17
requesting 4-26/4-28
retrieving response 4-29/4-31
character-set verification 2-4
Charges, account A-18, A-24
charging parameter 4-4, 4-60, 4-65, 4-80,
4-141
Closing files
requesting 4-32/4-33
retrieving response 4-34
Common name
examples, in C G-20, G-66, G-114
examples, in TAL G-171
See local-appl parameter
See remote-appl parameter
See responding-appl parameter
Concurrency
for file activities A-22
levels applied to file activities A-23
Configuring NonStop FTAM
See Management Interface
Confirm procedures 3-5, 3-6
Conformance to ISO standards 2-1
Connections
definition of 1-5
See also Associations
Contents-type
description 4-86, 4-91, 4-119
contents-type 4-114
contents-type parameter
associated procedures 4-4
description 4-86, 4-91, 4-114/4-115,
4-119
contents-type-list parameter
associated procedures 4-4
DDL structure A-19
description 4-96, 4-103
examples, in C G-21, G-116
examples, in TAL G-68, G-173
Context information, terminating F-3
Context name A-7
Controlling NonStop FTAM
See Management interface
count-transferred parameter E-3
create-password parameter 4-4, 4-37, 4-85
Creating files
requesting 4-36/4-40, 4-83/4-89
retrieving response 4-41/4-43,
4-90/4-92
D
Data
declaration examples, in C G-15/G-18,
G-109/G-112
declaration examples, in
TAL G-58/G-62, G-163/G-167
element description A-7
flow to and from initiator 3-3/3-4
invalid, subcodes for B-27
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -3
D
Index
Data (continued)
parameter header A-8
Data encoding 2-5
Data structures
related to error messages B-2
Data transfer
ending
requesting 4-143/4-144
retrieving response 4-145/4-146
ending a block
requesting 4-44/4-46
retrieving request
information 4-47/4-48
Data transfer block
receiving 4-53/4-56
transferring 4-49/4-52
Data types
first-level A-3
for each procedure, table of A-42/A-43
for FTAM structuring data element A-26
second-level A-4
Data-transfer regime
cancelling
confirming 4-19/4-20
requesting 4-16/4-18
responding 4-23/4-25
retrieving indication
information 4-21/4-22
initiating 4-123/4-126, 4-152/4-154
terminating 4-145/4-146
data-value parameter
description 4-49, 4-50/4-51, 4-53, 4-55
structure 4-50, A-33
Date, generalized A-25
DDL definition file 4-1, F-1
DDL definitions
basic data types A-3/A-5
locating A-2
named values A-37/A-41
DDL definitions (continued)
procedure cross-reference
table A-42/A-43
See also ZAPS-xxx
See also ZFTM-xxx
types of A-1
ZAPS parameter structures A-6/A-11
ZFTM parameter structures A-12/A-41
Declarations
examples, in C G-15/G-18,
G-109/G-112
examples, in TAL G-58/G-62,
G-163/G-167
files 4-1
delete-action parameter 4-4, 4-77
Deleting files
requesting 4-58/4-59, 4-77/4-79
retrieving response 4-80/4-82
retrieving response
information 4-60/4-62
Deselecting files
requesting 4-63/4-64, 4-83/4-89
retrieving response 4-65/4-67,
4-80/4-82
See also Selecting files
device-name parameter F-8
Diagnostic messages
buffer A-9
information A-27
ISO FTAM, returned by responder
access-related C-6/C-8
association-related C-4
file-management-related C-6/C-7
general messages C-3
overview C-1/C-2
protocol-related C-3
selection-related C-5/C-6
NonStop FTAM, returned by
initiator D-1/D-4
observer and source A-28
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -4
E
Index
Diagnostic messages (continued)
structure of elements A-28
diagnostics parameter 4-4
diagnostic-buffer parameter F-8
Discarding API context information for
associations F-3
Distributed Systems Management
See DSM
Document types
access context, table of B-26
available for negotiating presentation
context A-20
interoperability 2-3/2-4
supported by initiator 3-11
supported by NonStop FTAM 1-2
Documentation road map -xv
Documentation, other -xiv
DSM 1-4, 1-10/1-12
E
EMS 1-11
Encoding data 2-5
Ending
group of procedures 4-68/4-69
See Terminating
Erasing FADUs
requesting 4-70/4-74
retrieving response 4-75/4-76
Errors
APS A-9
current, details of A-7
first detected A-9
NonStop FTAM, returned by
API B-4/B-19
NonStop FTAM, returned by initiator
FTAM error codes B-19/B-34
overview B-1
status codes B-2/B-4
See Diagnostic messages C-1
source identity A-10
Escape sequences
interoperability 2-4
Event Management Service
See EMS
Event messages
See EMS, Errors, and Diagnostic
messages
Events
codes and related primitives, table
of A-39
receiving, procedure for F-4
Expand network, files on 1-7
EXTDECS0 file F-1
External declarations F-1
F
FADUs
defining permitted actions A-33
erasing contents of
requesting 4-70/4-74
retrieving response 4-75/4-76
identifying A-29/A-30
fadu-id parameter 4-5, 4-70, 4-106, 4-111,
4-123/4-124, 4-152
FADU-locking functional unit 3-9
fadu-operation parameter 4-5, 4-152
File attributes
supported by initiator 3-10
File names, data type for A-9
File types supported 1-2
filename parameter 4-5, 4-83, 4-91, 4-133,
4-137
filenum parameter E-2
Files
closing
requesting 4-32/4-33
retrieving response 4-34/4-35
closing and deselecting
requesting 4-77/4-79
retrieving response 4-80/4-82
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -5
F
Index
Files (continued)
creating and selecting
requesting 4-36/4-39
retrieving response 4-41/4-43
deleting
requesting 4-58/4-59
retrieving response
information 4-60/4-62
deselecting
requesting 4-63/4-64
retrieving response 4-65/4-67
determining access A-14
erasing FADUs
requesting 4-70/4-74
retrieving response 4-75/4-76
FTAM procedures, for 4-2
legal status A-32
managing, ISO FTAM messages C-6
permitted actions A-32
selecting
ISO FTAM diagnostic
messages C-5/C-6
requesting 4-133/4-135
retrieving response 4-136/4-138
transferring
reading 4-123/4-126
writing 4-152/4-155
types of access A-36
Files accessing
See Access, file
filestore-password parameter 4-6, 4-97
File-access functional unit 3-9
file-access parameter G-38, G-81
File-access service class 3-9
file-attrib parameter 4-5, 4-130
File-management functional units 3-9
File-management service class 3-9
File-open regime
initiating 4-83/4-89, 4-114/4-117
terminating 4-32/4-33, 4-77/4-79
File-selection regime
initiating 4-36/4-40, 4-83/4-89,
4-133/4-135
terminating 4-58/4-59, 4-63/4-64
file-status parameter 4-6, 4-83/4-84
File-transfer service class 3-9
File-transfer-and-management service
class 3-9
FILLER field A-8
Format effectors A-21
format effectors
interoperability 2-4
FPDUs
interoperability 2-5
request procedures, in 3-5
FTAM protocol data units
See FPDUs
FTAM subsystem
architecture 1-7, 1-8
FTAM-2 files, updating
example structure and
protocol G-2/G-5
example, in C G-12/G-55
example, in TAL G-56/G-105
FTAM-3 files, moving
example structure and
protocol G-6/G-11
example, in C G-106/G-160
example, in TAL G-161/G-220
FTM procedures
accessing local information 3-11
categories 4-2
confirm types 3-6
definition 3-5
external declarations 4-1
grouping primitives 3-6
indication types 3-5
mapping primitives to
procedures 3-6/3-8
overview 1-9
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -6
F
Index
FTM procedures (continued)
parameters and associated calls, table
of 4-3/4-7
Programming Example 1
example structure and
protocol G-3/G-5
example, in C G-12/G-55
example, in TAL G-56/G-105
Programming Example 2
example structure and
protocol G-6/G-11
example, in C G-106/G-160
example, in TAL G-161/G-235
regime requirements, table of 4-7/4-9
request types 3-5
response types 3-6
FTM_BEGIN_GROUP_REQ_ procedure
considerations 4-14
description 4-13/4-14
errors returned 4-14
examples
in C G-126, G-132, G-140
in TAL G-184, G-189, G-197
list of 4-15
FTM_CANCEL_CNF_ procedure
considerations 4-20
description 4-19/4-20
errors returned 4-20
examples
in C G-137
in TAL G-195
list of 4-20
FTM_CANCEL_IND_ procedure
considerations 4-22
description 4-21/4-22
errors returned 4-22
examples
in C G-33, G-137
in TAL G-90, G-194
list of 4-22
FTM_CANCEL_REQ_ procedure
considerations 4-17
description 4-16/4-17
errors returned 4-17
examples
in C G-137
in TAL G-195
list of 4-17
FTM_CANCEL_RSP_ procedure
considerations 4-24
description 4-23
errors returned 4-24
examples
in C G-33, G-137
in TAL G-90, G-194
list of 4-24
FTM_CHANGE_ATTRIB_CNF_ procedure
examples
in C G-141
in TAL G-198
FTM_CHANGE_ATTRIB_REQ_ procedure
considerations 4-26/4-27
description 4-26
errors returned 4-27
examples
in C G-140
in TAL G-198
FTM_CLOSE_CNF_ procedure
considerations 4-35
description 4-34
errors returned 4-35
examples
in C G-141, G-143
in TAL G-198, G-200
list of 4-35
FTM_CLOSE_REQ_ procedure
considerations 4-32
description 4-32
errors returned 4-33
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -7
F
Index
FTM_CLOSE_REQ_
procedure (continued)
examples
in C G-140, G-142
in TAL G-197, G-200
FTM_CREATE_CNF_ procedure
considerations 4-42/4-43
description 4-41/4-42
errors returned 4-43
examples
in C G-133
in TAL G-190
list of 4-43
FTM_CREATE_REQ_ procedure
considerations 4-38
description 4-36/4-38
errors returned 4-39
examples
in C G-132
in TAL G-189
list of 4-40
FTM_DATA_END_IND_ procedure
considerations 4-48
description 4-47
errors returned 4-48
examples
in C G-136
in TAL G-194
FTM_DATA_END_REQ_ procedure
considerations 4-45
description 4-44/4-45
errors returned 4-45
examples
in C G-45, G-136
in TAL G-92, G-194
list of 4-45
FTM_DATA_IND_ procedure
considerations 4-55/4-56
description 4-53/4-54
errors returned 4-56
FTM_DATA_IND_ procedure (continued)
examples
in C G-136
in TAL G-193
FTM_DATA_REQ_ procedure
considerations 4-50/4-51
description 4-49
errors returned 4-52
examples
in C G-46, G-136
in TAL G-93, G-193
list of 4-52
FTM_DELETE_CNF_ procedure
considerations 4-61
description 4-60/4-61
errors returned 4-61
examples
in C G-143
in TAL G-201
FTM_DELETE_REQ_ procedure
considerations 4-58/4-59
description 4-58
errors returned 4-59
examples
in C G-142
in TAL G-200
list of 4-59
FTM_DESELECT_CNF_ procedure
considerations 4-66
description 4-65/4-66
errors returned 4-67
examples
in C G-142
in TAL G-199
FTM_DESELECT_REQ_ procedure
considerations 4-63
description 4-63
errors returned 4-64
examples
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -8
F
Index
FTM_DESELECT_REQ_
procedure (continued)
in C G-140
in TAL G-198
list of 4-64
FTM_END_GROUP_REQ_ procedure
considerations 4-68
description 4-68
errors returned 4-69
examples
in C G-127, G-132, G-140, G-143
in TAL G-184, G-190, G-198,
G-200
list of 4-69
FTM_ERASE_CNF_ procedure
considerations 4-76
description 4-75
errors returned 4-76
FTM_ERASE_REQ_ procedure
considerations 4-71
description 4-70
errors returned 4-71/4-72
examples 4-73/4-74
FTM_FILE_CLOSE_CNF_ procedure
considerations 4-81
description 4-80
errors returned 4-82
examples
in C G-43
in TAL G-86
FTM_FILE_CLOSE_REQ_ procedure
considerations 4-78
description 4-77
errors returned 4-79
examples
in C G-42
in TAL G-85
list of 4-79
FTM_FILE_OPEN_CNF_ procedure
considerations 4-92
description 4-90/4-92
errors returned 4-92
examples
in C G-40
in TAL G-83
FTM_FILE_OPEN_REQ_ procedure
considerations 4-87
description 4-83/4-87
errors returned 4-88/4-89
examples
in C G-39
in TAL G-82
list of 4-89
FTM_INITIALIZE_CNF_ procedure
considerations 4-104
description 4-101/4-103
errors returned 4-104
examples
in C G-34, G-117, G-120
in TAL G-77, G-175, G-178
FTM_INITIALIZE_REQ_ procedure
considerations 4-97/4-98
description 4-93/4-97
errors returned 4-98/4-100
examples
in C G-22, G-117, G-120
in TAL G-68, G-174, G-177
list of 4-99
FTM_LOCATE_CNF_ procedure
considerations 4-112
description 4-111/4-112
errors returned by 4-112
FTM_LOCATE_REQ_ procedure
considerations 4-107
description 4-106/4-107
errors returned 4-107/4-108
examples 4-109/4-110
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -9
F
Index
FTM_OPEN_CNF_ procedure
considerations 4-119/4-120
description 4-118/4-119
errors returned 4-120
examples
in C G-128, G-133
in TAL G-185, G-190
FTM_OPEN_REQ_ procedure
considerations 4-115
description 4-114/4-115
errors returned 4-116
examples
in C G-127, G-132
in TAL G-184, G-190
FTM_P_ABORT_IND_ procedure
considerations 4-122
description 4-121/4-122
errors returned 4-122
examples
in C G-32, G-154
in TAL G-88, G-213
FTM_READ_ATTRIB_CNF_ procedure
considerations 4-131
description 4-130/4-131
errors returned 4-132
examples
in C G-127
in TAL G-185
FTM_READ_ATTRIB_REQ_ procedure
considerations 4-127/4-128
description 4-127
errors returned 4-128/4-129
examples
in C G-126
in TAL G-184
FTM_READ_REQ_ procedure
considerations 4-124
description 4-123/4-124
errors returned 4-125/4-126
FTM_READ_REQ_ procedure (continued)
examples
in C G-134
in TAL G-192
list of 4-126
FTM_SELECT_CNF_ procedure
considerations 4-137
description 4-136/4-137
errors returned 4-138
examples
in C G-127
in TAL G-185
FTM_SELECT_REQ_ procedure
considerations 4-134
description 4-133/4-134
errors returned 4-135
examples
in C G-126
in TAL G-184
list of 4-135
FTM_TERMINATE_CNF_ procedure
considerations 4-141/4-142
description 4-141
errors returned 4-142
examples
in C G-31, G-144
in TAL G-88, G-201
FTM_TERMINATE_REQ_ procedure
considerations 4-139
description 4-139
errors returned 4-140
examples
in C G-44, G-144
in TAL G-87, G-201
list of 4-140
FTM_TRANSFER_END_CNF_ procedure
considerations 4-146
description 4-145/4-146
errors returned 4-146
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -10
G
Index
FTM_TRANSFER_END_CNF_
procedure (continued)
examples
in C G-42, G-138
in TAL G-85, G-196
FTM_TRANSFER_END_REQ_ procedure
considerations 4-143
description 4-143
errors returned 4-144
examples
in C G-29, G-138
in TAL G-75, G-196
list of 4-144
FTM_U_ABORT_IND_ procedure
considerations 4-151
description 4-150
errors returned 4-151
examples
in C G-32
in TAL G-89
FTM_U_ABORT_REQ_ procedure
considerations 4-148
description 4-147/4-148
errors returned 4-148
examples
in C G-35, G-50, G-80, G-154,
G-159
in TAL G-79, G-214
FTM_WRITE_REQ_ procedure
considerations 4-153
description 4-152/4-153
errors returned 4-154/4-155
examples
in C G-41, G-134
in TAL G-84, G-192
Function declarations
examples, in C G-18, G-112
examples, in TAL G-62, G-167
Functional units
interoperability 2-1/2-2
required by procedures, table
of B-22/B-23
selecting, example in C G-21, G-115,
G-119, G-173
selecting, example in TAL G-67, G-177
supported by initiator 3-9
ZFTM-DDL- parameter structure A-31
Functions supported by initiator
attribute groups 3-10
attributes 3-10
document types 3-11
functional units 3-9
service classes 3-9
func-units parameter G-115, G-119, G-173,
G-177
G
General ISO FTAM diagnostic
messages C-3
GOSIP 2-1
Grouped procedures 3-6
Grouping
beginning 4-13/4-15
ending 4-68/4-69
Grouping functional unit 3-9
Guardian file system
interaction with NonStop FTAM 1-8
overview 1-6
I
Identifying user A-37
Indication procedures 3-5
Initializing the API F-6
initial-attrib parameter 4-6, 4-36, 4-42,
4-85, 4-91
Initiating associations
requesting 4-93/4-100
retrieving response 4-101/4-105
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index- 11
K
Index
Initiating regimes
data-transfer 4-123/4-126, 4-152/4-155
file-open 4-114/4-117
file-selection 4-133/4-135
file-selection and file-open 4-83/4-89
FTAM regime 4-93/4-100
Initiating system, definition of 1-5
Initiator Data Flow 3-3
Initiator Structure 3-1
Initiator, NonStop FTAM
architectural overview 1-5/1-7
data flow to and from 3-3/3-4
error codes returned by
descriptions B-21/B-34
table of B-19/B-20
error messages returned by
overview B-3/B-4
status codes B-2/B-4
FTAM API, support for 3-4
FTM procedures 3-5/3-8
functional overview 1-1
functions supported by 3-9/3-11
interface to OSI/AS 3-1
interoperability 2-1
process, defined 1-5
programmatic interface, overview 1-3
protocol state machine 3-1
structure 3-1/3-2
initiator-id parameter 4-6, 4-97
Interfaces
management 1-4
programmatic 1-3/1-4, 1-9/1-10
user 1-5
Interface, programmatic
See FTAM API and OSI/AS API
International Organization for
Standardization
See ISO
Interoperability
definition 2-1
description 2-1/2-5
Interworking
See Interoperability
ISO FTAM
definition 1-1
diagnostic messages
access-related C-6/C-7
association-related C-4
file-management-related C-6
general messages C-3
overview C-1/C-2
protocol-related C-3
recovery-related C-8
selection-related C-5/C-6
functional overview 1-1
ISO standards -xiii
K
Kernel attribute group 3-10
Kernel functional unit 3-9
L
local-ae-title parameter 4-6
local-appl parameter 4-6, 4-94, 4-102
Location pointers, moving
requesting 4-106/4-110
retrieving response 4-111
Lower OSI layers, NonStop products
for 1-12
Lower OSI layers, other HP NonStop
products for 1-5
M
Management information base
See MIB
Management interface 1-4
Managing files, ISO FTAM messages C-6
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -12
N
Index
Manuals, related -xiv
maximum-string-length parameter 2-3
MFM procedures
definition 3-4
overview 1-9
using E-1
MFM_AWAITIOX_ procedure
considerations E-4
description E-2/E-4
examples
in C G-23
in TAL G-69
MFM_CANCELREQ_ procedure
considerations E-5
description E-4
MIB, OSI manager 1-13, 1-14
Module file management
See MFM procedures E-1
more-data parameter 4-6, 4-54
Moving files, programming example
example structure and
protocol G-6/G-11
example, in C G-106/G-160
example, in TAL G-161/G-235
Moving location pointers
requesting 4-106/4-110
retrieving response 4-106/4-107, 4-111
N
Named values
See ZAPS-VAL- named values
See ZFTM-VAL- named values
NBS-9 files, data-value
parameter A-33/A-37
next-position parameter 4-6, 4-54
NIST 2-1
NonStop FTAM
architectural overview 1-5/1-7
conformance to ISO standards 2-1
definition 1-1
NonStop FTAM (continued)
example types of applications 1-2
FTAM and APLMGR subsystems,
architecture 1-7/1-8
Guardian file system 1-8
interoperability 2-1/2-5
management interface 1-4
programming capabilities 1-3
Programming Example 1
example structure and
protocol G-2/G-5
example, in C G-12/G-55
example, in TAL G-56/G-105
Programming Example 2
example structure and
protocol G-6/G-8
example, in C G-106/G-160
example, in TAL G-161/G-220
programming interface 1-3/1-4
relationship of procedures to service
primitives 3-6/3-8
services provided 1-2
underlying subsystems 1-4/1-5
NonStop FTAM, returned by initiator
FTAM error codes B-16/B-34
overview B-1
Status codes B-2/B-4
NonStop operating system 1-2
Nowait mode
cancelling nowait operations E-4
obtaining information E-2/E-4
NSP process 1-13
O
Opening files
requesting 4-83/4-89, 4-114/4-117
retrieving response 4-90/4-92,
4-118/4-120
Operator messages
See EMS
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -13
P
Index
original-error-info parameter F-8
OSI address
examples, in C G-20, G-114
examples, in TAL G-66, G-171
specifying A-6
OSI Reference Model, HP NonStop
products for 1-5, 1-12/1-14
OSI/AS subsystem
API 3-4
interaction with 1-4, 1-12/1-14
interoperability 2-1
OSI/FTAM Programming Guide A-24
OSI/TS subsystem 1-4, 1-12/1-14
override parameter 4-6, 4-36, A-41
P
Parameter structures
general A-5
ZAPS A-6/A-11
ZFTM A-12/A-37
Parameters
See also individual parameter names
Passwords, file attributes A-14
PDUs and interoperability 2-5
PDV-list 2-5
Pointers, location
See Location pointers
Presentation data units
See PDUs
Presentation encoding 2-5
Primitives
functional overview 1-1
procedures for grouping 3-6
relationship to procedures, table
of 3-7/3-8
specifying threshold
See threshold parameter
types of, overview 1-4
Private attribute group, attributes in A-16
Private-use attribute group 3-10
Procedures
accessing local information 3-11
data types for each, table of A-42/A-43
Programming Example 1
example structure and
protocol G-2/G-5
example, in C G-12/G-55
example, in TAL G-56/G-105
Programming Example 2
example structure and
protocol G-6/G-11
example, in C G-106/G-160
example, in TAL G-161/G-235
types supported 3-4
Processing mode
defining actions permitted on
FADUs A-33
error subcodes B-24
process-mode parameter
associated procedures 4-6
description 4-85, 4-114
examples G-38, G-81, G-126, G-183
Programs
See Applications
Protocol state machine, initiator 3-1
Protocol-related ISO FTAM diagnostic
messages C-3
PSAP address A-10
pseudofn parameter E-5
PTrace utility 1-4, 1-11
R
Read functional unit 3-9
Reading file attributes
requesting 4-127/4-129
retrieving attributes 4-130/4-132
Reading files 4-123/4-126
Receiving blocks of data 4-53/4-57
Receiving events, procedure for F-4
Recovery, ISO FTAM messages C-8
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -14
S
Index
Regimes
requirements for each FTM procedure,
table of 4-7/4-9
transition outcome A-41
remote-ae-title parameter 4-6, 4-94
remote-appl parameter 4-6, 4-94
Request procedures 3-5
requested-access parameter
associated procedures 4-6
description 4-37, 4-84, 4-133
examples G-123, G-181
requested_access parameter G-131,
G-188
Responder, NonStop FTAM
architectural overview 1-5/1-7
functional overview 1-1
Responder, NonStop FTAM,
interoperability 2-2
Responding system, definition of 1-5
responding-ae-title parameter 4-6, 4-102
responding-appl parameter 4-6, 4-102
Response procedures 3-6
Road map, documentation -xv
S
SCF 1-4, 1-10
SCP 1-11
Security attribute group
attributes included in A-15
supported by initiator 3-10
Security, file attribute passwords A-14
segment-id parameter E-4
Selecting files
ISO FTAM diagnostic
messages C-5/C-6
requesting 4-36/4-40, 4-83/4-89,
4-133/4-135
retrieving response 4-41/4-43,
4-90/4-92, 4-136/4-138
SEQUENCE OF PDV-list 2-5
Service classes
interoperability 2-2
proposed and negotiated A-36
selecting, example in C G-21
selecting, example in TAL G-67
supported by initiator 3-9
Services provided by NonStop FTAM 1-2
service-class parameter 4-7, 4-95, 4-102
service-id parameter F-8
Source files A-1
Special characters
$SYSTEM.SYSTEM files 4-1, E-1, F-1
SPI 1-4
Standards supported by NonStop
FTAM -xiii
Starting a group of procedures 4-13/4-15
Starting associations
See Initiating associations
start-position parameter 4-7, 4-54
State transition outcome A-41
state-result parameter 4-7, 4-41, 4-90,
4-101, 4-118, 4-136
Status code values B-2/B-4
Status, obtaining information F-7
string-significance parameter Glossary-27
Subsystem Control Facility
See SCF
Subsystem Control Point
See SCP
Swap volume name A-11
swapvol parameter F-6
Syntax
transfer name A-11
T
tag parameter 4-7, 4-14, 4-17, 4-24, 4-26,
4-32, 4-38
TAPS process 1-13
Terminating API context information for
associations F-3
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -15
U
Index
Terminating associations
requesting 4-139/4-140
retrieving response 4-141/4-142
Terminating files
See Closing files
Terminating regimes
all existing 4-147/4-149
data-transfer 4-16/4-18, 4-143/4-144
file-open 4-32/4-33
file-open and file-selection 4-77/4-79
file-selection 4-63/4-64
FTAM regime 4-141/4-142
Testing for conformance 2-1
threshold parameter 4-7, 4-13
timelimit parameter E-3
Time, generalized A-25
time-limit parameter F-4
TLAM subsystem 1-5, 1-12/1-14
TRACE command, SCF 1-11
Transferring data
blocks 4-49/4-52
ending
requesting 4-143/4-144
retrieving response 4-145/4-146
ending a block
requesting 4-44/4-46
retrieving request
information 4-47/4-48
Transferring files 4-123/4-126, 4-152/4-155
transport-state parameter F-8
transport-substate parameter F-9
TSP process 1-14
U
Unconstrained service class 3-9
universal-class parameter 2-4
Updating files, programming example
example structure and
protocol G-2/G-4
example, in C G-12/G-55
Updating files, programming
example (continued)
example, in TAL G-56/G-105
User identity A-37
User interfaces 1-5
V
Values
See ZAPS-VAL- named values and
ZFTM-VAL- named values
VFS architecture 1-7
Virtual filestore
See VFS
W
wait-mode parameter 4-94
Write functional unit 3-9
Writing files 4-152/4-155
X
X25AM subsystem 1-12/1-14
X25AM subsystem, interaction with 1-4
Z
ZACCESS field A-37
ZACCESSCNTRL field A-12, A-17, A-18
ZACCESSCNTRLATTR field A-24, A-25,
A-36
ZACCESSCNTRLATTRISPRESENT
field A-24, A-25, A-36
ZACCESSCNTRLISPRESENT field A-18
ZACCOUNT field A-15
ZACTIONLIST field A-13
ZAE- fields
TITLE-FORMAT2 A-6
TITLE-TYPE A-6
ZAPPL-NAME field A-7
ZAPSC file A-1
ZAPSDDL file A-1
ZAPSTAL file A-1
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -16
Z
Index
ZAPS-DDL- data type identifiers
BOOLEAN A-3
CHAR128 A-4
CHAR16 A-4
CHAR20 A-4
CHAR256 A-5
CHAR32 A-4
ENUM1 A-3
INT1 A-3
INT2 A-3
ISPRESENT A-5
OBJ-ID A-5
ZAPS-DDL- parameter structure identifiers
ABSTRACT-AE-TITLE A-6
ABSTRACT-SYN-NAME A-6
AE-TITLE A-6
APPL-ADDR A-6
APPL-CNTXT A-7
cross-referenced by procedure
call A-42/A-43
CURRENT-ERROR A-7
DATA-ELEMENT-HDR A-7
DATA-HDR A-8
DIAG-BUF A-9
ERROR-CODE A-9
FILENAME A-9
ORIGINAL-ERROR A-9
PSAP A-10
SERVICE-ID A-10
SWAP-VOLUME A-11
TRANSFER-SYN-NAME A-11
ZAPS-ERR- error code identifiers
BAD-MGR (-124) B-12
HASHTABLE-ERROR (-128) B-13
INTERNAL (-104) B-7
INVALID-OPERATION (-108) B-8
INVALID-SERVICE (-141) B-19
MFM-ERROR (-118) B-10
MGR-ERROR (-126) B-12
ZAPS-ERR- error code
identifiers (continued)
MGR-FS-ERROR (-125) B-12
NONE-PENDING (-135) B-14
NO-CONNECTION (-131) B-14
NO-DATA (-116) B-9
NO-EVENT (-129) B-14
NO-POOL-SPACE (-102) B-6
NO-SEGMENT-SPACE (-101) B-6
OPERATOR-ABORT (-114) B-9
PARAMETER (-105) B-7
PARAM-BOUNDS (-137) B-15
PARAM-MISSING (-136) B-15
PARAM-RANGE (-138) B-19
SEGMENT-ACCESS (-117) B-9
SSGET (-122) B-11
SSINIT (-120) B-10
SSNULL (-121) B-11
SSPUT (-123) B-11
STATE-MACHINE (-107) B-8
table of codes B-4
TABLE-ERROR (-127) B-13
TAPS-FS-ERROR (-134) B-14
TOO-MANY-PENDING (-106) B-7
UNKNOWN-CEPI (-109) B-8
ZAPS-VAL- named values
ABSENT A-37
AE-TITLE-xxx A-37
FALSE A-37
PRESENT A-37
SERVICE-xxx A-37
TRUE A-38
ZASNAME field A-20
ZATTRSAREPRESENT field A-17, A-34
ZBEGINEND field A-30
ZCHARGEUNIT field A-19
ZCHARGEVALUE field A-19
ZCHARGING field A-18
ZCHARGINGISPRESENT field A-18
ZCHNGATTR field A-22, A-32, A-36
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -17
Z
Index
ZCHNGATTRPASSWD field A-14
ZCNTNTSTYPE field A-19, A-20, A-21
ZCNTNTSTYPEVALUE field A-24, A-25,
A-35
ZCNTNTSTYPEVALUEISPRESENT
field A-34
ZCNTNTS-TYPE-ISPRESENT field A-19
ZCNTNTS-TYPE-LIST A-19
ZCNTXT field A-13
ZCONCURRENCYACCESS field A-13
ZCONCURRENCYISPRESENT field A-13
ZCONSTRAINTSETASNAME field A-20,
A-22
ZCOUNT field A-19
ZCREATION field A-16, A-35
ZCREATIONISPRESENT field A-35
ZCREATORID field A-16, A-35
ZCREATORIDISPRESENT field A-35
ZDATAEXISTS field A-26
ZDATAEXISTSISPRESENT field A-26
ZDATETIME field A-25
ZDELETE field A-22, A-36
ZDELETEFILE field A-32
ZDELETEISPRESENT field A-12
ZDELETEPASSWD field A-14
ZDELETEVALUES field A-13
ZDEVICE-NAME field A-9
ZDIAGCOUNT field A-28
ZDIAGELEMS field A-28
ZDIAGELEMSISPRESENT field A-28
ZDIAGTYPE field A-27
ZDIAG-BUF field A-7
ZDOCTYPE field A-21
ZDOCTYPENAME field A-19, A-21
ZERASE field A-22, A-32, A-33, A-36
ZERASEPASSWD field A-14
ZERROR field A-9
ZERRORID field A-27
ZERROROBSERVER field A-27
ZERRORSOURCE field A-27
ZERROR-CODE field A-7
ZERROR-SUBCODE field A-7
ZEXCLUSIVE field A-23
ZEXTEND field A-32
ZEXTENDPASSWD field A-14
ZFADUID field A-29
ZFADULOCK field A-31
ZFADUNUMBER field A-30
ZFILEACCESS field A-31
ZFILEATTRSISPRESENT field A-22
ZFILEAVLBLTY field A-17, A-30
ZFILEAVLBLTYATTR field A-18, A-24,
A-25, A-35
ZFILEAVLBLTYATTRISPRESENT
field A-18, A-35
ZFILEMGMT field A-31
ZFILEMGMTENHANCED field A-31
ZFILENAME field A-16, A-17, A-23, A-34
ZFILENAMEISPRESENT field A-17, A-34
ZFILESIZE field A-17
ZFILESIZEATTR field A-35
ZFILESIZEATTRISPRESENT field A-35
ZFIRSTLAST field A-30
ZFTM A-39
ZFTMC file A-1
ZFTM-DDL- parameter structure identifiers
ACCESS-CNTRL-ATTR A-12
ACCESS-CNTRL-CHNG A-12
ACCESS-CNTRL-ELEM A-13
ACCESS-CNTXT A-13
ACCESS-PASSWDS A-14
ACCOUNT-ATTR A-15
ATTR-GROUPS A-15
ATTR-NAMES A-16
CHANGE-ATTR A-17
CHARGING A-18
CNTNTS-LIST A-19
CNTNTS-TYPE A-20
CONCURRENCY A-22
CONCURRENCY-KEY A-23
CREATE-ATTR A-23
CREATE-ATTR-GRP A-24
DATETIME A-25
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -18
Z
Index
ZFTM-DDL- parameter structure
identifiers (continued)
DE-FADU A-26
DIAGNOSTIC A-28
DIAG-ELEM A-27
ENTITY-REF A-28
FADU-ID A-29
FILEAVLBLTY-ATTR A-30
FILESIZE-ATTR A-31
FUNC-UNITS A-31
LEGALQUALIF-ATTR A-32
PERMITTED-ACTIONS A-32
PROC-MODE A-33
READ-ATTR A-33
REQUESTED-ACCESS A-36
SERVICE-CLASS A-36
USER-ID A-37
ZFTM-DDL-CHAR256 A-5
ZFTM-ERR- error code identifiers
ACCESS-CNTXT-INVALID
(-6009) B-26
ACCESS-INCNSTNT (-6003) B-23
ACCESS-NOT-AVAIL (-6004) B-24
ACSE-FAILURE (-6032) B-32
API-FS-ERROR (-6038) B-33
ATTR-GRP-NOT-NEG(-6024) B-31
BAD-APS-STATUS (-6019) B-29
CONNECTION-ABORTED
(-6022) B-30
DATA-VALUE-TOO-SMALL
(-6037) B-33
DATA-XFER-CANCELLED
(-6030) B-32
EMPTY-ASSOC-CNF (-6039) B-34
FADU-ID-INVALID (-6006) B-25
FADU-OP-INCNSTNT (-6007) B-25
FU-NOT-NEGOTIATED (-6002) B-22
INTERNAL (-6000) B-21
INVALID-DATA (-6010) B-26
ZFTM-ERR- error code
identifiers (continued)
INVALID-FIELD-VERSION
(-6018) B-29
INVALID-IF-VERSION (-6017) B-28
LOCATE-DOCTYPE (-6026) B-31
PRIVATE-USE-NOT-SUPP
(-6025) B-31
PROC-MODE-INCNSTNT
(-6005) B-24
PROC-MODE-NOT-AVAIL
(-6008) B-26
RESRC-DCB-ALLOC (-6021) B-30
SERV-NOT-NEGOTIATED
(-6012) B-28
SU-ABORTED (-6036) B-33
table of codes B-19/B-20
ZFTM-ERR- error subcode identifiers
ACCESS-xxx B-23
FU-xxx B-22
INVALID-DATA-xxx B-26
MGR-xxx B-12
OOS-xxx B-21
OUT-OF-SEQUENCE (-6001) B-21
PROC-MODE-xxx B-24
SERVICE-xxx B-28
table of B-16/B-18
ZFTM-VAL- named values
ACCESSCNTXT-xxx A-38
ACTION-xxx A-38
ATTR-xxx A-38
CLOSE-xxx A-38
CNTNTSLIST-xxx A-38
CNTNTSTYPE-xxx A-38
DE-xxx A-38
DIAG-xxx A-39
ENTITYREF-xxx A-39
EVT-xxx A-39
FADUID-xxx A-39
FADU-OP-xxx A-39
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -19
Z
Index
ZFTM-VAL- named values (continued)
FILEAVLBLTY-xxx A-39
OVR-xxx A-41
STATE-xxx A-41
STRINGSIG-xxx A-41
UC-xxx A-41
ZFURTHERDETAILS field A-27
ZFURTHERDETAILSISPRESENT
field A-27
ZFUTUREFILESIZE field A-17, A-18, A-24,
A-25, A-35
ZFUTUREFILESIZEISPRESENT
field A-18, A-24, A-25, A-35
ZGROUP field A-31
ZID field A-12, A-15, A-19, A-20, A-25,
A-29, A-30, A-31, A-32, A-37
ZIDENTITY field A-13
ZIDENTITYISPRESENT field A-13
ZINSERT field A-22, A-32, A-33, A-36
ZINSERTISPRESENT field A-12
ZINSERTPASSWD field A-14
ZINSERTVALUES field A-12
ZLASTATTRMOD field A-16, A-35
ZLASTATTRMODID field A-16, A-35
ZLASTATTRMODISPRESENT field A-35
ZLASTMOD field A-16, A-35
ZLASTMODID field A-16, A-35
ZLASTMODIDISPRESENT field A-35
ZLASTMODISPRESENT field A-35
ZLASTREAD field A-35
ZLASTREADACCESS field A-16
ZLASTREADERID field A-16
ZLASTREADID field A-35
ZLASTREADIDISPRESENT field A-35
ZLASTREADISPRESENT field A-35
ZLEGALQUALIF field A-17, A-32
ZLEGALQUALIFICATION field A-18, A-24,
A-25, A-36
ZLEGALQUALIFISPRESENT field A-18,
A-24, A-25, A-36
ZLEN field A-8
ZLEVELNUM field A-14
ZLEVELNUMISPRESENT field A-14
ZLOCATION field A-13
ZLOCATIONISPRESENT field A-13
ZMAXSTRINGLEN field A-22
ZMAXSTRINGLENISPRESENT field A-21
ZMGMT field A-37
ZNAME field A-26
ZNAMEISPRESENT field A-26
ZNOACCESS field A-23
ZNOTREQUIRED field A-23
ZNSAP field A-10
ZNUM-ELEMENTS field A-7, A-9
ZPASSWDS field A-13
ZPASSWDSISPRESENT field A-13
ZPERMITTEDACTIONS field A-16, A-23,
A-24, A-34
ZPERMITTEDACTIONSISPRESENT
field A-34
ZPRIVATE field of ZFTM-DDL-ATTRGROUPS A-16
ZPRIVATEUSE field A-17
ZPSAP field A-7
ZPSEL field A-10
ZRANDOM field A-33
ZREAD field A-22, A-31, A-32, A-33, A-36
ZREADATTR field A-22, A-32, A-36
ZREADATTRPASSWD field A-14
ZREADPASSWD field A-14
ZRECOVERY field A-31
ZRELATIVE field A-30
ZREPLACE field A-22, A-32, A-33, A-36
ZREPLACEPASSWD field A-14
ZRESOURCEID field A-18
ZRESTART field A-31
ZREVERSETRAVERSAL field A-32
ZSECURITY field A-15
ZSERVICE-ID field A-7
ZSHARED field A-23
ZSSEL field A-10
ZSTORAGE field A-15
ZSTORAGEACCOUNT field A-16, A-18,
A-24, A-25, A-35
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -20
Z
Index
ZSTORAGEACCOUNTISPRESENT
field A-17, A-24, A-25, A-35
ZSTRINGSIG field A-22
ZSTRINGSIGISPRESENT field A-22
ZSUGGESTEDDELAY field A-27
ZSUGGESTEDDELAYISPRESENT
field A-27
ZTRANSFER field A-37
ZTRAVERSAL field A-32
ZTSEL field A-10
ZTYPE field A-8, A-26
ZUNCONSTRAINED field A-36
ZUNIVERSALCLASS field A-21
ZUNIVERSALCLASSISPRESENTfield
A-21
ZUSERID field A-37
ZWRITE field A-31
ZXFERMGMT field A-37
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -21
Z
Index
HP NonStop OSI/FTAM Programming Reference Manual—528611-001
Index -22
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement