HP A4500A - VMEbus Single Board Computer 744... Manual

ACSE/Presentation and ROSE Interface
Programmer’s Guide
Edition 4
32070-90032
HP9000 Networking
05/97
Printed in: United States
© Copyright 1997 Hewlett-Packard Company. All rights reserved.

2
Legal Notices
The information in this document is subject to change without notice.
Hewlett-Packard makes no warranty of any kind with regard to this
manual, including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose. Hewlett-Packard
shall not be held liable for errors contained herein or direct, indirect,
special, incidental or consequential damages in connection with the
furnishing, performance, or use of this material.
Warranty. A copy of the specific warranty terms applicable to your
Hewlett- Packard product and replacement parts can be obtained from
your local Sales and Service Office.
Restricted Rights Legend. Use, duplication or disclosure by the U.S.
Government is subject to restrictions as set forth in subparagraph (c) (1)
(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and
(c) (2) of the Commercial Computer Software Restricted Rights clause at
FAR 52.227-19 for other agencies.
HEWLETT-PACKARD COMPANY 3000 Hanover Street Palo Alto,
California 94304 U.S.A.
Use of this manual and flexible disk(s) or tape cartridge(s) supplied for
this pack is restricted to this product only. Additional copies of the
programs may be made for security and back-up purposes only. Resale of
the programs in their present form or with alterations, is expressly
prohibited.
Copyright Notices. ©copyright 1983-97 Hewlett-Packard Company, all
rights reserved.
Reproduction, adaptation, or translation of this document without prior
written permission is prohibited, except as allowed under the copyright
laws.
©copyright 1979, 1980, 1983, 1985-93 Regents of the University of
California
This software is based in part on the Fourth Berkeley Software
Distribution under license from the Regents of the University of
California.

3
©copyright 1980, 1984, 1986 Novell, Inc.
©copyright 1986-1992 Sun Microsystems, Inc.
©copyright 1985-86, 1988 Massachusetts Institute of Technology.
©copyright 1989-93 The Open Software Foundation, Inc.
©copyright 1986 Digital Equipment Corporation.
©copyright 1990 Motorola, Inc.
©copyright 1990, 1991, 1992 Cornell University
©copyright 1989-1991 The University of Maryland
©copyright 1988 Carnegie Mellon University
Trademark Notices UNIX is a registered trademark in the United
States and other countries, licensed exclusively through X/Open
Company Limited.
X Window System is a trademark of the Massachusetts Institute of
Technology.
MS-DOS and Microsoft are U.S. registered trademarks of Microsoft
Corporation.
OSF/Motif is a trademark of the Open Software Foundation, Inc. in the
U.S. and other countries.

4

Contents
5
1. APRI Overview
Systems Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
ASN.1 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
File Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
What is the HP ACSE/Presentation and ROSE Interface . . . . . . . . . . .15
ACSE/Presentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
ROSE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Support for Multi-Threaded Applications. . . . . . . . . . . . . . . . . . . . . . .15
Standards Supported. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Who Should Use This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
2. Supported ACSE/Presentation and ROSE Calls
ACSE/Presentation Calls and Primitives. . . . . . . . . . . . . . . . . . . . . . . . .22
A/P Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
ACSE/Presentation Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
ACSE/Presentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
ROSE Calls and Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
ROSE Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
ROSE Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
3. Using ACSE/Presentation
Synchronous ACSE/Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Summary of Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Step 1: Create a Communication Endpoint . . . . . . . . . . . . . . . . . . . . . . .33
Step 2: Establish an Association. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Initialize the A/P Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Establish Initiator and Responder Roles . . . . . . . . . . . . . . . . . . . . . . .35

6
Contents
Binding the Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Set up the Data Transfer Environment. . . . . . . . . . . . . . . . . . . . . . . . 36
Request the Association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Confirm the Association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Step 3. Exchanging Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Step 4: Release the Association. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Requesting the Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Confirm the Release Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Step 5: Closing the Communication Endpoint . . . . . . . . . . . . . . . . . . . . 44
4. Programming Guide
Summary of Programming Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
1. Prepare the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2. Manage the A/P Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Determine Initiator and Responder Roles. . . . . . . . . . . . . . . . . . . . . . 49
Determine Address Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Negotiating Application and Presentation Contexts . . . . . . . . . . . . . 51
Portability, Migration Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 52
3. Managing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Control Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Multiple Sends and Receives of Data. . . . . . . . . . . . . . . . . . . . . . . . . . 54
User Data Encoding/Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4. Using Synchronous vs. Asynchronous Mode. . . . . . . . . . . . . . . . . . . . 56
Synchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Changing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5. Managing Multiple Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Contents
7
Execution Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Resource Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
System Maximums. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
6. Other Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Error Checking Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Error-handling in Multi-Threaded Applications . . . . . . . . . . . . . . . . .63
7. Before Running ACSE/Presentation Applications. . . . . . . . . . . . . . . .64
Multi-threaded ACSE/Presentation Example . . . . . . . . . . . . . . . . . . .64
ACSE/Presentation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Program using ROSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
5. Troubleshooting Your Application
Using A/P API Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
A/P API Tracing Using Environmental Variables . . . . . . . . . . . . . . . .68
Tracing Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Selecting Types of Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Enable A/P API Tracing Using Global Variables . . . . . . . . . . . . . . . . .71
Trace Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Tracing in Multi-threaded Applications . . . . . . . . . . . . . . . . . . . . . . . .73
Using ROSE API Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Environment Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Tracing Using Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Selecting Types of Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Enable ROSE API Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Trace Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Tracing in Multi-threaded Applications . . . . . . . . . . . . . . . . . . . . . . . .79

8
Contents
A. ACSE/Presentation Reference Pages
ACSE/Presentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Glossary

9
Printing History
The manual printing date and part number indicate its current edition.
The printing date will change when a new edition is printed. Minor
changes may be made at reprint without changing the printing date. The
manual part number will change when extensive changes are made.
Manual updates may be issued between editions to correct errors or
document product changes. To ensure that you receive the updated or
new editions, you should subscribe to the appropriate product support
service. See your HP sales representative for details.
Edition 1 March 1992
Edition 2 January 1995
Edition 3 July 1996
Edition 4 May 1997

10

11
In This Book
This manual describes tools and procedures for using the
ACSE/Presentation and ROSE application programmatic interface for
OSI products. It is divided into three chapters, which provide the
following information:
Chapter 1 “APRI Overview” introduces the ACSE/Presentation
and ROSE Interface and the supported standards.
Chapter 2 “Supported ACSE/Presentation and ROSE Calls”
contains descriptions of the programmatic calls
supported by ACSE/Presentation and ROSE.
Chapter 3 “Using ACSE/Presentation” provides a sample session
using ACSE/Presentation between two processes in
synchronous mode.
Chapter 4 “Programming Guide” provides information to assist
you in writing and executing applications using the
ACSE/ Presentation (A/P) interface.
Chapter 5 “Troubleshooting Your Application” describes API
tracing for ACSE/Presentation followed by API tracing
for ROSE.
Appendix A “ACSE/Presentation Reference Pages” includes a list of
the supported ACSE/Presentation attributes and a
glossary of terms.

12

13
1 APRI Overview
This chapter provides an overview of what the HP ACSE/Presentation
and ROSE interface provides.

14 Chapter1
APRI Overview
Systems Supported
Systems Supported
Access to the ACSE/Presentation and ROSE programmatic interface is
provided with the HP OTS/9000 product on HP 9000 systems.
ASN.1 Support
If your application requires encoding/decoding abstract syntax notation
one (ASN.1) data structures, you may need to use an ASN.1 compiler.
Refer to your compiler's documentation for information about using
ASN.1 in your application programs.
File Naming
To use the MAN feature on systems that support a maximum file length
of 14 characters, the ACSE/Presentation and ROSE calls with longer
names have short alias names you can use. The short names are listed in
the tables in chapter 2.

Chapter 1 15
APRI Overview
What is the HP ACSE/Presentation and ROSE Interface
What is the HP ACSE/Presentation and
ROSE Interface
The ACSE/Presentation and ROSE interface (APRI) provides a
programmatic interface to the Association Control Service Element
(ACSE), Remote Operation Service Element (ROSE) and Presentation
layer protocols over an OSI network. See Figure 1-1.
ACSE/Presentation
Using the ACSE/Presentation (A/P) interface enables two or more
application processes on the same or different computers to:
• Establish an association (connection) with another application
process
• Exchange (send and receive) information and
• Shutdown the association (connection)
ROSE
Using ROSE with ACSE/Presentation provides the request/reply service
which is useful in building distributed applications. Note that ROSE
cannot be used independently of the ACSE/Presentation interface.
Support for Multi-Threaded Applications
This version of HP OTS/9000 supports multi-threaded applications to be
written using the same programmatic interface as before for APLI and
ROSE. Applications can use either DCE User Threads or Kernel threads
interfaces. The following programming guidelines need to be followed to
be able to write multi-threaded applications:
• The application should be compiled with the -D_REENTRANT compiler
flag. Also, it may use compiler flag -D_PTHREADS_DRAFT4 for linking
with DCE User Threads library or -D_KERNEL_THREADS for Kernel
threads library.
• Multi-threaded applications must define ap_errno as:
extern unsigned long _ap_errno();

16 Chapter1
APRI Overview
What is the HP ACSE/Presentation and ROSE Interface
#define ap_errno _ap_errno()
• Any multi-threaded application program, which also includes
osi_lib.h, should include it after the threads-specific include files.
• See the appropriate man page regarding thread-safe information
about the various api’s.

Chapter 1 17
APRI Overview
Standards Supported
Standards Supported
The interface provided is based on the services defined in the ISO ACSE
and Presentation Service Definitions (ISO 8649 and ISO 8822) and
ROSE (ISO 9072).
The HP OTS/9000 subset implementation of the ACSE/Presentation
library interface is based on the UNIX International OSI
ACSE/Presentation Library Interface specification draft dated October
25, 1990.
HP OTS/9000 also supports a restricted mode of operation which allows
internetworking with a system that conforms to the ITU-T
Recommendation X.410 (1984).

18 Chapter1
APRI Overview
Standards Supported
Figure 1-1 OSI MODEL - ACSE Presentation and ROSE
Limitations
A subset of the standard has been implemented with the following
limitations.
For limitations on particular parameters, please refer to the manpages
for the A/P and ROSE calls.
APPLICATION PROCESS
ACSE/Presentation
& ROSE Interface
ACSE ROSE
PRESENTATION
SESSION
TRANSPORT
NETWORK
DATA LINK
PHYSICAL
PHYSICAL COMMUNICATION MEDIUM
Layer 7
Layer 6
Layer 5
Layer 4
Layer 3
Layer 2
Layer 1

Chapter 1 19
APRI Overview
Standards Supported
ACSE/Presentation:
• The ap_restore(), ap_save() and ap_osic() calls are not supported.
• The environment file (env_file) is not supported. The user's
application environment is initialized using ap_init_env(), after
which individual attributes can be set or changed using ap_set_env().
• Setting multiple environment variables with one call to ap_set_env()
is not supported.
• Retrieving (getting) multiple environment variables with one call to
ap_get_env() is not supported.
• The ap_env() attributes AP_DPCN, AP_DPCR, AP_QLEN and
AP_QOS are not supported. The AP_STREAMS_FLAGS options
AP_HUP_ONABORT and AP_PEEK are not supported.
• For ap_rcv(): The AP_ALLOC option is not supported. The buffer
pointed to by the ubuf argument must be allocated by the user. The
AP_VECT option is not supported. In struct osi_buf, the next field is
ignored. The ubuf argument points to a single buffer.
• For ap_snd(): The AP_VECT option is not supported. In struct
osi_buf, the next field is ignored. The ubuf argument points to a single
buffer. The AP_DELAY option is not supported. Extended
concatenation is not supported.
The A_ASSOC_REQ can fail with AP_AGAIN. A_ASSOC_REQ is not
subject to flow control.
• ACSE/presentation primitives used in ACSE/Presentation calls: A
subset of the defined primitives are supported. Chapter 2 provides a
list of the supported primitives.
ROSE:
• Reliable Transfer Service (RTS) including operation class is not
supported.
• Priority is not implemented for this release.

20 Chapter1
APRI Overview
Who Should Use This Manual
Who Should Use This Manual
This manual is provided for application programmers who need to use
ACSE/Presentation and ROSE services.
It is expected that the user of this manual is an experienced applications
programmer with knowledge of the HP-UX operating system and
programming environment, the X.25 protocol, OSI transport, session,
and presentation layer functions, networking concepts and the following
list of documents:
• ISO 7498 - Information Processing Systems - Open Systems
Interconnection - Reference Model of Open System Interconnection
• ISO 8649 - Information Processing Systems - Open Systems
Interconnection - Service Definition for the Association Control
Service Element
• ISO 8650 - Information Processing Systems - Open Systems
Interconnection - Protocol Specification for the Association Control
Service Element
• ISO 8822 - Information Processing Systems - Open Systems
Interconnection - Connection Oriented Presentation Service
Definition
• ISO 8823 - Information Processing Systems - Open Systems
Interconnection - Connection Oriented Presentation Protocol
Specification
• ISO 8824 - Information Processing Systems - Open Systems
Interconnection - Specification of Abstract Syntax One (ASN.1)
• ISO 8825 - Information Processing Systems - Open Systems
Interconnection - Specification of Basic Encoding Rules for Abstract
Syntax One (ASN.1)
• NIST - Stable Implementation Agreements for Open Systems
Interconnection Protocols
• Overview of the Application Service Library Model
• ISO 9072/1 Remote Operations Service Definition
• ISO 9072/2 Remote Operations Protocol Specification