Digital PDFs

AA-QRAYB-TE

November 1996

176 pages

Original

0.8MB

Document:	DECnet-Plus OSAK SPI Programming Reference
Order Number:	AA-QRAYB-TE
Revision:	0
Pages:	176
Original Filename:	osak_spi.PDF

OCR Text

DECnet-Plus
DECnet-Plus OSAK SPI
Programming Reference
Order Number: AA–QRAYB–TE
November 1996

This manual provides specific information on using the session layer
programming interface to OSAK.

Revision/Update Information:

This is a revised manual.

Operating Systems:

OpenVMS VAX Version 7.1
OpenVMS Alpha Version 7.1
Digital UNIX Version 4.0

Software Versions:

DECnet-Plus for OpenVMS Version 7.1
DECnet/OSI for Digital UNIX
Version 4.0
OSAK Version 3.0

Digital Equipment Corporation
Maynard, Massachusetts

November 1996
Digital Equipment Corporation makes no representations that the use of its products in the
manner described in this publication will not infringe on existing or future patent rights, nor do
the descriptions contained in this publication imply the granting of licenses to make, use, or sell
equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant
to a valid written license from Digital or an authorized sublicensor.
Digital conducts its business in a manner that conserves the environment and protects the safety
and health of its employees, customers, and the community.
© Digital Equipment Corporation 1996. All rights reserved.
The following are trademarks of Digital Equipment Corporation: Bookreader, DDCMP, DEC,
DECdirect, DECnet, DECNIS, DECserver, DECsystem, DECwindows, Digital, DNA, InfoServer,
OpenVMS, PATHWORKS, ULTRIX, VAX, VAX DOCUMENT, VAXcluster, VAXstation, VMS,
VMScluster, and the DIGITAL logo.
The following are third-party trademarks:
OSI is a registered trademark of CA Management Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively
through X/Open Co. Ltd.
All other trademarks and registered trademarks are the property of their respective holders.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

1 OSAK SPI Routines
1.1
1.2
1.3
1.4
1.4.1
1.4.2

Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OSAK Parameter Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routine Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arguments Common to All Outbound Services . . . . . . . . . . . . . . . . . .
Parameters Common to All Outbound Services . . . . . . . . . . . . . . . . . .
spi_abort_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_accept_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_discard_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_discard_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_end_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_end_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_interrupt_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_interrupt_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_resume_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_act_start_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_async_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_capability_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_capability_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_close_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_collect_pb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_connect_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_control_give_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_data_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_exception_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_expedited_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_get_event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_get_handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_give_buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_major_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_major_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_minor_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_minor_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_open_initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_open_redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–1
1–1
1–4
1–9
1–9
1–9
1–13
1–15
1–19
1–21
1–23
1–25
1–27
1–29
1–31
1–34
1–36
1–38
1–40
1–42
1–44
1–45
1–49
1–51
1–53
1–55
1–57
1–61
1–63
1–64
1–66
1–68
1–70
1–72
1–74

iii

spi_open_responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_reject_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_release_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_release_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_resync_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_resync_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_send_more . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_token_give_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_token_please_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi_typed_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–76
1–79
1–84
1–86
1–88
1–90
1–93
1–95
1–98
1–100
1–102
1–104

2 OSAK Events
ABORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REDIRECT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-DISCARD confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-DISCARD indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-END confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-END indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-INTERRUPT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-INTERRUPT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-RESUME indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-START indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CAPABILITY-DATA confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CAPABILITY-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CONNECT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CONNECT-ACCEPT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CONNECT-REJECT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-CONTROL-GIVE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-EXPEDITED-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-P-EXCEPTION-REPORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-RELEASE confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-RELEASE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-RESYNCHRONIZE confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-RESYNCHRONIZE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-SYNC-MAJOR confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-SYNC-MAJOR indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-SYNC-MINOR confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-SYNC-MINOR indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-TOKEN-GIVE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-TOKEN-PLEASE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-TYPED-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-U-EXCEPTION-REPORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–2
2–3
2–6
2–7
2–8
2–9
2–10
2–11
2–12
2–13
2–14
2–15
2–16
2–18
2–20
2–22
2–23
2–24
2–25
2–26
2–27
2–28
2–29
2–30
2–31
2–32
2–33
2–34
2–35
2–36
2–37

3 Checking OSAK Status Codes
3.1
3.2
3.3

Success Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Informational Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3–2
3–2
3–3

4 Disruptive Events
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8

ABORT request (Local Peer Abort) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ABORT indication (Remote Peer Abort) . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transport Connection Loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-INTERRUPT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-ACTIVITY-DISCARD indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-RESYNCHRONIZE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S-EXCEPTION-REPORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PREPARE (RESYNC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4–1
4–1
4–2
4–2
4–2
4–2
4–2
4–2

5 How the OSAK SPI Implements the ISO Standards
5.1
5.2

The OSAK SPI and the ISO Protocol Definitions . . . . . . . . . . . . . . . . . . . .
Restrictions in the OSAK Implementation of the ISO Protocol
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5–1
5–2

6 Possible Values for OSAK Data Types
6.1
6.2
6.3
6.4
6.5
6.6
6.6.1
6.6.2
6.7
6.8
6.9
6.10

Data Type: osak_abort_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type: osak_action_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type: osak_activity_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type: osak_exception_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field: pm_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type: osak_reject_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rejection Originating from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rejection Originating from Session Provider . . . . . . . . . . . . . . . . . . . .
Field: request_returned_mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parameter: osak_resync_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fields: data, sync_mimnor, major_activity, and release . . . . . . . . . . . . . . .
Field: type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6–1
6–1
6–1
6–1
6–2
6–2
6–2
6–3
6–3
6–3
6–3
6–4

OSAK SPI Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OSAK Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Definitions of Request-Event Mask and Returned-Event Mask . . . . . .
Sequence of Calls After the Arrival of a REDIRECT Indication . . . . . .

1–1
1–59
1–97
2–5

Index
Tables
1–1
1–2
1–3
2–1

Preface
This book contains reference material that you need when using the OSI
Applications Kernel (OSAK) session programming interface (SPI) to create Open
Systems Interconnection (OSI) applications on any supported operating system.
Use this book with OSAK Programming.

Intended Audience
The audience for this manual is OSI application programmers who require a
basic understanding of the upper-layer standards implemented by Digital’s OSAK
product.

Prerequisites
Before using the OSAK SPI, you should ensure that you:
•

Have installed DECnet-Plus and the OSAK software on your system
The DECnet-Plus installation and configuration documentation tells you how
to install DECnet-Plus and the OSAK software.

•

Understand the parts of the OSI standards that apply to the protocols
your application uses. DECnet-Plus OSAK Programming lists the relevant
standards.
This book (and DECnet-Plus OSAK Programming) assumes that you
understand the terminology and concepts used in the relevant standards.

Related Documents
DECnet-Plus OSAK Programming gives a list of the relevant international
standards.
You may also need to refer to the DECnet-Plus Planning Guide.

Reader’s Comments
Digital welcomes your comments on this manual or any of the DECnet-Plus
documents. Send us your comments through any of the following channels:
Internet

openvmsdoc@zko.mts.dec.com

Fax

603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail

OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

vii

How To Order Additional Documentation
Use the following table to order additional documentation or information.
If you need help deciding which documentation best meets your needs, call
800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Location

Call

Fax

Write

U.S.A.

DECdirect
800−DIGITAL
800−344−4825

Fax: 800−234−2298

Digital Equipment Corporation
P.O. Box CS2008
Nashua, NH 03061

Puerto Rico

809−781−0505

Fax: 809−749−8300

Digital Equipment Caribbean, Inc.
3 Digital Plaza, 1st Street, Suite 200
P.O. Box 11038
Metro Office Park
San Juan, Puerto Rico 00910−2138

Canada

800−267−6215

Fax: 613−592−1946

Digital Equipment of Canada, Ltd.
Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: DECdirect Sales

International

Local Digital subsidiary or
approved distributor
DTN: 264−4446
603−884−4446

Internal Orders

Fax: 603−884−3960

U.S. Software Supply Business
Digital Equipment Corporation
8 Cotton Road
Nashua, NH 03063−1260
ZK−7654A−GE

Conventions
The following conventions are used in this book:
Italics

Used for the names of arguments, parameters and fields.

this typeface

Used for the names of commands and utilities.

[]

Square brackets are used in the tables entitled Parameters Used to
indicate optional parameters.
OpenVMS

Indicates information specific to the OpenVMS operating system.

viii

Digital
UNIX

Indicates information specific to the Digital UNIX operating system.

♦

Denotes the end of platform-specific information.

(OpenVMS)

Where text that refers exclusively to the OpenVMS operating
system is minimal, the operating system is indicated in brackets
after the text.

(Digital UNIX)

Where text that refers exclusively to the Digital UNIX operating
system is minimal, the operating system is indicated in brackets
after the text.

Abbreviations
The following abbreviations are used in this book:
APDU

application protocol data unit

BER

basic encoding rules

CLNS

Connectionless-Mode Network Service

CONS

Connection-Oriented Network Service

ISO

International Organization for Standardization

NSAP

network service access point

OSAK

OSI Applications Kernel

OSI

Open Systems Interconnection

PCI

protocol control information

PDU

protocol data unit

PDV

presentation data value

PSEL

presentation selector

SPDU

session protocol data unit

SSEL

session selector

TCP/IP

Transmission Control Protocol/Internet Protocol

TLV

tag, length, and value

TSDU

transport service data unit

TSEL

transport selector

1
OSAK SPI Routines
This chapter contains the following information about the OSAK session
programming interface (SPI):
•

The names of the include files, and where to find them

•

A description of the OSAK parameter block

•

A description of each OSAK data type

•

A description of each OSAK SPI routine

Communications software that conforms to the OSI standards follows a model
of layers. Each layer provides a service to the layer immediately above it. The
layer that provides the service is called the provider; the layer that uses the
service is called the user. Note this use of the term ‘user’ in this book, in the OSI
standards, and in other Digital books that deal with the OSAK software; a ‘user’
is not a person.

1.1 Include Files
The include files for the SPI are as follows:
•

osak_api.h

•

osak_api_codes.h

•

osak_api_messages.h

Their locations depend on the operating system as follows:
OpenVMS

SYS$COMMON:[SYSLIB]

Digital UNIX

/usr/include/osi

1.2 OSAK Parameter Block
This section describes the parameter block, osak_parameter_block data type, and
the data types it includes.
Table 1–1 lists the parameters in the parameter block, describes them briefly, and
shows their data types.
Table 1–1 OSAK SPI Parameters
Parameter

Brief Description

Data Type

abort_reason1

Reason for abort

osak_abort_reason

1 Returned by OSAK. Cannot be specified by the application.

(continued on next page)

OSAK SPI Routines 1–1

Table 1–1 (Cont.) OSAK SPI Parameters
Parameter

Brief Description

Data Type

action_result

Acceptance or rejection
of release request

Address (osak_action_result)

activity_id

Activity identifier

osak_mem_descriptor

activity_reason

Reason code

Address (osak_activity_reason)

alloc_param

User-defined parameter
for use with alloc_rtn
and dealloc_rtn

Unsigned long integer

alloc_rtn

Memory allocation
routine

osak_rtn

api_version2

OSAK SPI version to be
used

Unsigned long integer

called_aei3

Responder applicationentity invocation

Address (osak_aei)

calling_aei3

Initiator applicationentity invocation

Address (osak_aei)

completion_param
(OpenVMS systems
only)

User-defined parameter
for use with completion_
rtn

Unsigned long integer

completion_rtn
(OpenVMS systems
only)

Completion routine

osak_rtn

data_length

Total data octets

Unsigned long integer

data_separation

Data separation flag

osak_data_separation

dealloc_rtn

Memory deallocation
routine

osak_rtn

event_type

Type of event

osak_event

exception_reason

Reason for exception
report

osak_exception_reason

func

Service identifier

Unsigned long integer

functional_units

Presentation and session
functional units

Address (osak_fus)

initial_serial_number

Serial number of first
synchronization point

Address (osak_sync_point)

initial_tokens

Initial token settings

Address (osak_token_setting)

local_abort

Origin of abort

Long integer

Application-entity
invocation of the calling
process

Address (osak_aei)

local_data

Buffers holding
redirected local user
data

Address (osak_mem_descriptor)

more_flag

Data segmentation flag

Long integer

local_aei

2 Set this parameter to OSAK_C_API_VERSION_3.
3 Use only the p-address structure within this parameter. Within the p-address, use only the ssel, tsel,
and nsap fields. Set the psel field to null.

(continued on next page)

1–2 OSAK SPI Routines

Table 1–1 (Cont.) OSAK SPI Parameters
Parameter

Brief Description

Data Type

next_pb

Pointer to next
parameter block

Address (osak_parameter_block)

old_activity_id

Interrupted activity
identifier

osak_mem_descriptor

old_sconnection_id

Previous session
connection

Address (osak_sconnection_id)

pb_length

Size of parameter block

Unsigned long integer

peer_data

User data (inbound)

Address (osak_buffer)

port_id

Port identifier

osak_port

process_id

Process identifier

Address (osak_process_id)

Process name

Address (osak_mem_descriptor)

protocol_versions

Protocol version
numbers

Address (osak_protocol_versions)

rcv_data_list

Buffers holding
redirected peer data

Address (osak_buffer)

redirect_state

State of protocol
machine

osak_state

reject_reason5

Reason for rejecting
connection request

osak_reject_reason

request_tokens

Tokens requested from
peer entity

Address (osak_token_setting)

responding_aei3

Responding applicationentity invocation

Address (osak_aei)

resync_type

Type of
resynchronization

osak_resync_type

sconnect_id

Session connection
information

Address (osak_sconnect_id)

segmentation

Session segmentation
use and size of TSDU

Address (osak_segmentation)

status_block

Status code

osak_status_block

sync_confirm

Confirmation flag for a
minor synchronization
point

osak_sync_confirm

sync_point

Synchronization point
serial number

Address (osak_sync_point)

token_item

Token positions

Address (osak_token_setting)

tokens

Distribution of tokens

Address (osak_token_setting)

transport_template

Transport template
identifier list

Address (osak_transport_templates)

tsdu_ptr

Pointer to list of user
buffers

Address (osak_buffer)

process_name
4

3 Use only the p-address structure within this parameter. Within the p-address, use only the ssel, tsel,
and nsap fields. Set the psel field to null.
4 Use only the sversion field in this parameter. Set the other fields to null.
5 Use session-specific values only (see Section 6.6.1 and Section 6.6.2).

(continued on next page)

OSAK SPI Routines 1–3

Table 1–1 (Cont.) OSAK SPI Parameters
Parameter

Brief Description

Data Type

user_context

Space for applications to
store local information

Address

user_data

User data (outbound)

Address (osak_buffer)

workspace6

Parameter block
workspace

None

ws_length

Length of workspace

Unsigned long integer

6 The workspace is a section of memory at the end of the structure. It is not a field in the structure
itself.

1.3 Data Type Definitions
This section describes the data types specific to the OSAK SPI. The data types
are described in alphabetical order. Where a data type consists of fields, these are
presented in table form.
For more detailed information about parameters, see Section 1.4.
osak_abort_reason
Unsigned long integer
osak_action_result
Unsigned long integer
osak_activity_reason
Unsigned long integer
osak_aei

Field
p-address
ae-title
aeiid

Brief Description

Data Type

Presentation address

osak_paddress

Application-entity title

osak_aetitle

Application-entity invocation identifier

osak_aeiid

1 Leave blank. This field is present in the structure but is not used by the SPI.

osak_buffer
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_buffer)

buffer_ptr

Pointer to beginning of buffer

Unsigned octet

buffer_length

Length of buffer

Unsigned long integer

data_ptr

Start of user data

Unsigned octet

data_length

Length of user data

Unsigned long integer

osak_data_separation
Unsigned long integer

1–4 OSAK SPI Routines

osak_event
Unsigned long integer
osak_exception_reason
Unsigned long integer
osak_fus
Field

Brief Description

Data Type

half_duplex

Half-duplex functional unit selector

Bit field mask

duplex

Duplex functional unit selector

Bit field mask

expedited

Expedited functional unit selector

Bit field mask

syncminor

Minor synchronization functional unit
selector

Bit field mask

syncmajor

Major synchronization functional unit
selector

Bit field mask

resynchronize

Resynchronize functional unit selector

Bit field mask

activities

Activities functional unit selector

Bit field mask

negotiated_release

Negotiated release functional unit
selector

Bit field mask

capability_data

Capability data functional unit selector

Bit field mask

exceptions

Exceptions functional unit selector

Bit field mask

data_separation

Data separation functional unit
selection

Bit field mask

typed_data

Typed data functional unit selector

Bit field mask

Field

Brief Description

Data Type

Handle identifier

Unsigned long integer

request_mask

Request event mask

Unsigned octet

returned_mask

Returned event mask

Unsigned octet

osak_handle

osak_handle_count
Unsigned long integer
osak_mem_descriptor
Field

Brief Description

Data Type

size

Length of buffer in octets

Unsigned long integer

pointer

Reference to buffer

Address (Unsigned octet)

osak_nsap
Field

Brief Description

Data Type

Next network service access point

Address (osak_nsap)

Address

osak_mem_descriptor

type

A constant defining the network protocol

Long integer

OSAK SPI Routines 1–5

osak_paddress

Field
psel

ssel

Brief Description

Data Type

Presentation selector

osak_mem_descriptor

Session selector

osak_mem_descriptor

tsel

Transport selector

osak_mem_descriptor

nsap

Network service access point

osak_nsap (see osak_nsap)

1 Leave blank. This field is present in the structure but is not used by the SPI.

osak_parameter_block
See Section 1.2.
osak_port
Address (Unsigned octet)
osak_protocol_versions

Field

Brief Description

Data Type

acse_version1

ACSE versions proposed

osak_acse_version

pversion1

Presentation versions proposed

osak_pversion

sversion

Session versions proposed

osak_sversion

1 Leave blank. This field is present in the structure of the parameter block but is not used by the SPI.

osak_process_id
Unsigned long integer
osak_reject_reason
Unsigned long integer
osak_resync_type
Unsigned long integer
osak_rtn
Unsigned long integer (*osak_rtn)( )
osak_sconnect_id
Field

Brief Description

Data Type

ss_user_ref

Session service user reference

osak_mem_descriptor

common_ref

Common reference

osak_mem_descriptor

add_ref_info

Additional reference information

osak_mem_descriptor

1–6 OSAK SPI Routines

osak_sconnection_id
Field

Brief Description

Data Type

called_ss_user_ref

Called session service user reference

osak_mem_descriptor

calling_ss_user_ref

Calling session service user reference

osak_mem_descriptor

common_ref

Common reference

osak_mem_descriptor

add_ref_info

Additional reference information

osak_mem_descriptor

Field

Brief Description

Data Type

init_resp

Segmentation in the direction from
initiator to responder

Unsigned short
integer

resp_init

Segmentation in the direction from
responder to initiator

Unsigned short
integer

Field

Brief Description

Data Type

pm_state

State of the connection

Unsigned octet

initiator

True if the peer entity requesting
redirection is the initiator, false if the
peer entity requesting redirection is the
responder

Long integer

Field

Brief Description

Data Type

osak_status_1

OSAK status code

Unsigned long integer

osak_status_2

Secondary OSAK status code

Unsigned long integer

transport_status_1

Generic transport provider status

Unsigned long integer

transport_status_2

Specific transport provider status

Unsigned long integer

Field

Brief Description

Data Type

version1

Session version 1

Bit field mask

version2

Session version 2

Bit field mask

osak_segmentation

osak_state

osak_status_block

osak_sversion

osak_sync_confirm
Long integer
osak_sync_point
Unsigned long integer
osak_time
Unsigned long integer

OSAK SPI Routines 1–7

osak_token_setting
Field

Brief Description

Data Type

data

Data token selector

Bit field mask length 2

sync_minor

Synchronize minor token selector

Bit field mask length 2

major_activity

Major activity token selector

Bit field mask length 2

release

Release token selector

Bit field mask length 2

osak_transport_templates
Field

Brief Description

Data Type

Pointer to next template in the list

Address (osak_transport_
templates)

name

Transport template name

osak_mem_descriptor

1–8 OSAK SPI Routines

1.4 Routine Descriptions
This section contains a description of each OSAK SPI routine. Each routine has
a set of arguments and parameters. Some of the arguments and parameters are
common to many routines. The common arguments and parameters are described
in Sections 1.4.1 and 1.4.2 respectively. Arguments and parameters that are not
common to many routines are described in the individual routine descriptions.

1.4.1 Arguments Common to All Outbound Services
This section describes the port and parameter_block arguments. These
descriptions apply to all OSAK outbound service routines.
port
Identifies the connection on which this service call is being made. You should
specify the port in all the outbound service calls that you make on a connection.
parameter_block
The address of a parameter block. A parameter block is a structure that contains
all possible parameters for all OSAK services. The OSAK SPI uses only the
relevant parameters in each service call, ignoring the rest. Section 1.2 describes
the structure of a parameter block.
For each routine, some parameters are mandatory and some are optional.
Optional parameters are enclosed in square brackets in the Syntax section of
each routine description. These parameters are not optional across the interface;
you must specify values for all optional and mandatory fields and explicitly set to
null any optional parameters that you do not want to use. Some parameters have
dependencies on others; the routine descriptions indicate these dependencies.

1.4.2 Parameters Common to All Outbound Services
This section contains descriptions, in alphabetic order, of the parameters that are
common to all the OSAK outbound services:
alloc_param
The address of a user-defined structure. You can use this structure with the
allocation and deallocation routines you are supplying, according to the needs of
your application.
To indicate that alloc_param is not in use, make it null.
alloc_rtn
The address of the entry address of a memory allocation routine. You should
supply a non-null value for this parameter. The OSAK SPI returns the address of
the allocated memory if the call is successful, and zero if it is not.
You should supply a routine that meets the memory allocation requirements
of your application. The OSAK SPI uses this routine only for internal memory
management, not for returning inbound parameter values to your application.
The allocation routine should have the following syntax:
unsigned char *alloc_rtn(size, alloc_param)
unsigned int size;
unsigned int alloc_param;
The size parameter is the number of octets of memory being requested.

OSAK SPI Routines 1–9

A jacket routine is a user-written routine designed to set up the parameters for
an existing routine. The user-written routine surrounds the call to the existing
routine. For example, your allocation routine surrounds lib$get_vm (OpenVMS
systems) or malloc (Digital UNIX systems).
The following code is an example of a jacket routine using the existing routine
malloc:
unsigned char *alloc_rtn(size, alloc_param)
unsigned int size;
unsigned int alloc_param;
{
return malloc(size);
}
The following code is an example of a jacket routine using the existing routine

lib$get_vm:
unsigned char *alloc_rtn(size, alloc_param)
unsigned int size;
unsigned int alloc_param;
{
integer status;
unsigned char *ptr;
status = lib$get_vm &size, &ptr, 0);
if (status & 0x01)
return ptr;
else
return 0;
}
completion_param (OpenVMS systems only)
The address of a user-defined structure. You can use any structure that you
need with the completion routine you are supplying. For example, you can use
a generic completion routine in several different service calls. You can use the
completion_param parameter to specify which service has finished.
completion_rtn (OpenVMS systems only)
The entry point of a completion routine.
data_length
You can use this parameter when you are sending segmented data, to specify the
total length of the data being sent.
If you specify this length, the OSAK SPI does not have to wait for the sender to
supply all the data that it wants to send. When the sender passes a data segment
to the OSAK SPI, the SPI can send that segment immediately. This improves the
throughput and memory utilization of your application.
This parameter does not apply to user information. When you are using the
routines spi_data_req or spi_typed_req, the OSAK SPI does not wait for the
full amount of data to arrive from the requester, because in these services, OSAK
does not encode the length of the data in the PCI.
dealloc_rtn
The address of the entry address of a memory deallocation routine. You should
supply a non-null value for this parameter.

1–10 OSAK SPI Routines

You should supply a routine that meets the memory deallocation requirements
of your application. The OSAK SPI uses this routine only for internal memory
management, not for returning inbound parameter values to your application.
The deallocation routine should have the following syntax:
unsigned long int dealloc_rtn(size, ptr, alloc_param)
unsigned long int size;
unsigned char *ptr;
unsigned long int alloc_param;
The size parameter is the number of octets of memory to be deallocated. The
OSAK SPI always deallocates the same amount of memory as it allocated using
your allocation routine. Your deallocation routine can ignore the size parameter.
The ptr parameter is a pointer to the memory to be deallocated. The possible
return values of the routine are:
•

Zero, indicating success

•

Any other number, indicating failure

If the call to the deallocation routine fails, the OSAK SPI writes the following
values to the status_block parameter:
•

OSAK_S_DEALLOCERR in the osak_status_1 field

•

The value returned by the deallocation routine in the osak_status_2 field

A jacket routine is a user-written routine designed to set up the parameters
for an existing routine. The user-written routine surrounds the call to the
existing routine. For example, your deallocation routine surrounds lib$free_vm
(OpenVMS systems) or free (Digital UNIX systems).
The following code is an example of a jacket routine using the existing routine
free:
unsigned long int dealloc_rtn (size, ptr, alloc_param)
unsigned long int size;
unsigned char *ptr;
unsigned long int alloc_param;
{
extern void free();
free (ptr);
return 0;
}
The following code is an example of a jacket routine using the existing routine

lib$free_vm:
unsigned long int dealloc_rtn (size, ptr, zone)
unsigned long int size;
unsigned char *ptr;
unsigned long int *zone;
{
unsigned long int status;
status = lib$free_vm (&size, ptr, zone);
return ((status & 1) & 0:status);
}

OSAK SPI Routines 1–11

func
In this parameter, the OSAK SPI returns a code identifying the service you are
calling. The codes are described in the include file, OSAK_API_CODES.H, which
is included with the SPI.
more_flag
Use this parameter if you are sending segmented user data to indicate whether
there is more user data to follow. You send this further user data on a call or
calls to spi_send_more.
Set the parameter to true if there are more segments of data to follow and to false
if you are sending the final segment of data.
pb_length
This parameter specifies the size of your parameter block structure. It should not
include the size of the workspace.
port_id
In this parameter, the OSAK SPI returns the port with which the parameter
block passed on a call is associated.
This parameter is relevant if you are using completion routines. When a
completion routine starts to run, indicating that a service has been completed,
you can collect that service’s parameter block and user buffers from the OSAK
SPI. The only way to find out which port the parameter block is associated with
is to examine the port_id parameter.
status_block
When a requested service finishes, the OSAK SPI returns a status code in this
parameter. If the result is OSAK_S_TRANSERR, the OSAK SPI also returns a
transport provider status code. Chapter 3 lists all the OSAK status codes.
user_context
The address of an area in which you can store local information that is relevant
to your application, for example, parameter block context information.
user_data
The address of the head of a linked list of user buffers. The list consists of zero,
one, or more buffers containing segments of encoded user data that you want to
send across a connection.
ws_length
This parameter specifies the size of the workspace you allocate as an extension to
the parameter block. The workspace should be at least the minimum size defined
by the OSAK SPI as OSAK_C_MINIMUM_WS.

1–12 OSAK SPI Routines

spi_abort_req

spi_abort_req
Aborts a connection.

Syntax
status = spi_abort_req (port, parameter_block)
Argument

Data Type

Access

port

osak_port

read only

parameter_block

osak_parameter_block

read only

Parameters Used

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

func

Unsigned long integer

write only

status_block

osak_status_block

write only

[user_data]

osak_buffer

read only

more_flag

Long integer

read only

[data_length]

Unsigned longword

read only

port_id

osak_port

write only

[completion_rtn]

osak_rtn

read only

[completion_param]

Longword

read only

C Binding
spi_abort_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameters Used
user_data
For session version 1, the user_data field can contain a maximum of 9 octets of
data.
Other parameters
All other parameters used in this routine are described in Section 1.4.1 and
Section 1.4.2.

Description
If you want to send user data on the call, you can segment the user data between
the call to spi_abort_req and calls to spi_send_more.

OSAK SPI Routines 1–13

spi_abort_req

Return Value
A value indicating the status of the routine. Possible values are:
OSAK_S_FREE
OSAK_S_NORMAL
OSAK_S_QUEUED
OSAK_S_BADPARAM
OSAK_S_DISRUPTED
OSAK_S_INSFMEM
OSAK_S_INVFUNC
OSAK_S_INVPORT
OSAK_S_OVERFLOW
OSAK_S_TRANSERR

See Also
spi_resync_req

1–94 OSAK SPI Routines

spi_select

spi_select
Inspects ports for events waiting to be received or arriving within a specified
time.

Syntax
status = spi_select (port_count, port_list, time_out)
Argument

Data Type

Access

port_count

osak_handle_count

read only

port_list

osak_handle

modify

time_out

osak_time

read only

C Binding
api_select (port_count, port_list, time_out)
osak_handle_count port_count;
osak_handle *port_list;
osak_time *time_out;

Arguments
port_count
The number of ports in the port list.
port_list
The address of an array in which you specify the identifiers of the ports you want
to inspect for events. You can also specify the types of events about which you
want the OSAK SPI to notify you. The array has three fields:
•

id specifies one or more ports that the OSAK SPI should inspect

•

request_event_mask specifies the type of event for which the OSAK SPI should
inspect the ports

•

returned_event_mask lists the events that occur on the specified ports before
the OSAK SPI returns control to your application

A port is defined to be one of the following:
•

An OSI connection. The spi_open_initiator, spi_open_redirect and
spi_open_responder calls return the identifier of the connection in the port
parameter.

•

An identifier specific to the operating system. The identifier refers to the
source on which the OSAK SPI makes selections. On OpenVMS systems, the
source is a port or an event flag number (EFN). On Digital UNIX systems,
the source is a file descriptor.

time_out
The address of a value specifying the maximum time, in seconds, that you want
the OSAK SPI to wait for an event if one is not present on a specified port. A
value of zero indicates no waiting. A null pointer indicates an indefinite wait.
The maximum permitted size for this parameter is 1 day (86,400 seconds). If you

OSAK SPI Routines 1–95

spi_select

want your application to wait longer than 1 day for an event to arrive, you can do
either of two things:
•

Set this parameter to null.

•

Make several calls to spi_select with timers lasting less than a day. When
the timer expires, re-issue the spi_select call.

Description
The routine examines the ports listed in the port_list parameter for the following:
•

Events waiting to be received

•

Events occurring within a specified time

The call finishes either when an event arrives on one of the ports listed in the
port_list parameter or when the time_out parameter expires.
Digital
UNIX

Although the spi_select call maps directly on to the Digital UNIX
select(2) system call, the semantics of the write bit are different.
The OSAK SPI uses the write bit to indicate that a write event has
finished. The Digital UNIX operating system uses the write bit to
indicate that writing is possible.
If the OSAK SPI finds an OSI port identifier, it applies OSAK
semantics. If the OSAK SPI finds a Digital UNIX file descriptor, it
maps that file descriptor to the Digital UNIX select(2) system call,
which applies Digital UNIX semantics.
To use the Digital UNIX select(2) system call, first call
spi_get_handle. This returns a file descriptor you can pass to
select(2).
To use the spi_select routine, pass either a file descriptor or a port
identifier.
♦

OpenVMS

You can pass an event flag number (EFN) to spi_select as a port
identifier. If you do this, you should use an EFN from cluster
1. The OSAK SPI passes the EFN to the OpenVMS system call
SYS$WFLOR( ).
♦

Each port has two associated event masks:
•

The request-event mask

•

The returned-event mask

If you want the OSAK SPI to notify you when an inbound event from the
transport provider arrives, set the read bit in the request_event_mask field of
the port_list argument. When an inbound event arrives, the OSAK SPI returns
OSAK_S_NORMAL.
If you want the OSAK SPI to notify you when an outbound event completes, set
the write bit in the returned_event_mask field of the port_list argument. When an
outbound event completes, the OSAK SPI returns OSAK_S_NORMAL.

1–96 OSAK SPI Routines

spi_select

Table 1–3 shows the meanings of values in the 2-bit masks.
Table 1–3 Definitions of Request-Event Mask and Returned-Event Mask
Request-Event
Bit Number

Returned-Event
Bit Number

Meaning

0
1

OSAK_C_READEVENT
OSAK_C_WRITEEVENT

You can specify a maximum time for the OSAK SPI to wait for an event to
arrive. If no event arrives within that time, the OSAK SPI returns the status
OSAK_S_NOEVENT and clears the returned-event bit mask. If an event arrives,
the OSAK SPI returns the status OSAK_S_NORMAL. You should inspect the
returned-event bit mask to find the port on which the event arrived.

Return Value
A value indicating the status of the routine. Possible values are:
OSAK_S_NORMAL
OSAK_S_NOEVENT
OSAK_S_DISRUPTED
OSAK_S_INVPARAM

OSAK_S_INVPORT
OSAK_S_TRANSERR

The routine has finished without error.
No event has occurred.
A disruptive event has occurred.
There is an invalid parameter, or no request_
event_mask field is specified in the port_list
argument.
The port identifier is invalid.
There is an error in the transport provider.

See Also
spi_get_event
spi_get_handle
spi_give_buffers
spi_open_initiator
spi_open_redirect
spi_open_responder
spi_select

OSAK SPI Routines 1–97

spi_send_more

spi_send_more
Sends a further segment of user data.

Syntax
status = spi_send_more (port, parameter_block)
Argument

Data Type

Access

port

osak_port

read only

parameter_block

osak_parameter_block

read only

Parameters Used

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

func

Unsigned long integer

write only

status_block

osak_status_block

write only

user_data

osak_buffer

read only

more_flag

Long integer

read only

data_length

Unsigned longword

read only

[completion_rtn]

osak_rtn

read only

[completion_param]

Longword

read only

C Binding
spi_send_more (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Description
The OSAK SPI allows you to segment the user data you are sending on any
service. Call spi_send_more as many times as necessary to send user data to
complete a service. The completion of each call to spi_send_more indicates that
the transport provider has processed a segment of data. This does not guarantee
that the segment has been transferred to the peer entity.
You do not have to send any user data on a service call that has the more_flag set
to true. If you set more_flag to true on the original service call, you can send all
the user data on calls to spi_send_more.

Return Value
A value indicating the status of the routine. Possible values are:
OSAK_S_FREE

1–98 OSAK SPI Routines

The OSAK SPI has queued the request and there
are free parameter blocks.

spi_send_more

OSAK_S_QUEUED
OSAK_S_DISRUPTED
OSAK_S_INVFUNC
OSAK_S_INVPORT
OSAK_S_OVERFLOW
OSAK_S_TRANSERR

The OSAK SPI has queued the request.
A disruptive event has occurred.
The call is invalid.
The port identifier is invalid.
Too much user data has been sent.
There is an error in the transport provider.

OSAK SPI Routines 1–99

spi_token_give_req

spi_token_give_req
Relinquishes ownership of some or all of the available tokens.

Syntax
status = spi_token_give_req (port, parameter_block)
Argument

Data Type

Access

port

osak_port

read only

parameter_block

osak_parameter_block

read only

Parameters Used

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

func

Unsigned long integer

write only

status_block

osak_status_block

write only

[token_item]

osak_token_setting

read only

[user_data]

osak_buffer

read only

more_flag

Long integer

read only

[data_length]

Unsigned longword

read only

[completion_rtn]

osak_rtn

read only

[completion_param]

Longword

read only

C Binding
spi_token_give_req (port, parameter_block,)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameters Used
token_item
The address of a structure specifies the tokens the requester is passing to the
accepter. The structure consists of four fields corresponding to the four tokens. In
each field, the only values allowed are zero and one:
•

Zero means that the requester is not passing this token to the accepter.

•

One means that the requester is passing this token to the accepter.

Other parameters
All other parameters used in this routine are described in Section 1.4.1 and
Section 1.4.2.

1–100 OSAK SPI Routines

spi_token_give_req

Description
You must own a token before you can give it away.
If you are using session version 1, there is no user data on this service and
therefore, no segmentation is allowed.

See Also
spi_control_give_req
spi_token_please_req

OSAK SPI Routines 1–101

spi_token_please_req

spi_token_please_req
Requests the peer entity to relinquish ownership of some or all of the available
tokens.

Syntax
status = spi_token_please_req (port, parameter_block)
Argument

Data Type

Access

port

osak_port

read only

parameter_block

osak_parameter_block

read only

Parameters Used

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

func

Unsigned long integer

write only

status_block

osak_status_block

write only

[token_item]

osak_token_setting

read only

[user_data]

osak_buffer

read only

more_flag

Long integer

read only

[data_length]

Unsigned longword

read only

[completion_rtn]

osak_rtn

read only

[completion_param]

Longword

read only

C Binding
spi_token_please_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameters Used
token_item
The address of a structure you can use to specify the tokens that the requester
wants from the accepter. The structure consists of four fields corresponding to the
four tokens. In each field, the only values allowed are zero and one:
•

Zero means that the requester does not want this token from the accepter.

•

One means that the requester wants this token from the accepter.

Other parameters
All other parameters used in this routine are described in Section 1.4.1 and
Section 1.4.2.

1–102 OSAK SPI Routines

spi_token_please_req

Description
The token you want must be available and owned by the other user before you
request ownership of the token.

See Also
spi_control_give_req
spi_token_give_req

OSAK SPI Routines 1–103

spi_typed_req

spi_typed_req
Transfers typed data over a connection.

Syntax
status = spi_typed_req (port, parameter_block)
Argument

Data Type

Access

port

osak_port

read only

parameter_block

osak_parameter_block

read only

Parameters Used

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

func

Unsigned long integer

write only

status_block

osak_status_block

write only

[user_data]

osak_buffer

read only

more_flag

Long integer

read only

[data_length]

Unsigned longword

read only

[completion_rtn]

osak_rtn

read only

[completion_param]

Longword

read only

C Binding
spi_typed_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Description
The typed data service is useful when you select the half-duplex functional unit.
You can use the service to send user information when a peer entity needs to send
data and does not hold the data token.

Return Value
A value indicating the status of the routine. Possible values are:
OSAK_S_FREE
OSAK_S_NORMAL
OSAK_S_QUEUED
OSAK_S_BADPARAM
OSAK_S_DISRUPTED
OSAK_S_INSFMEM

1–104 OSAK SPI Routines

spi_typed_req

OSAK_S_INVFUNC
OSAK_S_INVPORT
OSAK_S_TRANSERR

The call is invalid.
The port identifier is invalid.
There is an error in the transport provider.

OSAK SPI Routines 1–105

2
OSAK Events
This chapter lists the OSAK events in alphabetical order. Refer to the description
of the spi_get_event call in Chapter 1 for how to use this routine to receive
events. Chapter 1 also describes all the OSAK parameters and their data types.
You should ignore parameters that are not included in the event specification.
The following parameters are common to all events:
event_type
The type of the event that spi_get_event receives. Table 1–2 shows the event
indicated by each possible value of this parameter.
more_flag
Indicates whether there is more user data to follow. The value of this parameter
is true if there are more data units to follow and false if there are no more data
units to follow.
peer_data
The address of a linked list of user buffers containing user data transferred from
the remote peer entity. The user data does not necessarily start at the beginning
of the first buffer in the list. The tsdu_ptr parameter points to the head of the
list.
This parameter is not used for a redirect indication.
status_block
When spi_get_event finishes, the OSAK interface writes a status code to this
parameter. If the status code is OSAK_S_TRANSERR, the OSAK interface also
returns a transport provider status.
tsdu_ptr
The address of the head of a list of buffers of the type osak_buffer. The buffers
are those that you passed to the OSAK interface in calls to spi_give_buffers.
To free the buffers when they are returned by spi_get_event, you should follow
the tsdu_ptr pointer, not the peer_data pointer.

OSAK Events 2–1

ABORT indication

ABORT indication
Indicates a user or a provider abort.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

abort_reason

osak_abort_reason

[peer_data]

osak_buffer

[more_flag]

Long integer

local_abort

Long integer

Parameters Returned
abort_reason
This parameter explains why the connection is being aborted. Section 6.1 lists
the possible values.
local_abort
This parameter is true if the OSAK interface generated the ABORT indication
locally and false if the ABORT indication originated from the remote peer entity.

Description
An application entity receives this event when one of the following circumstances
occurs:
•

The remote peer entity issues a call to spi_abort_req.

•

The remote protocol machine issues a provider abort.

•

The local protocol machine issues a provider abort.

This event indicates that the remote peer entity, the local protocol machine, or
the remote protocol machine is terminating the connection. You should delete all
the data structures for the connection.
If this is a user abort, your application should make multiple calls to

spi_get_event to receive all the user data arriving on the ABORT indication, if
any. When all the user data has been received, close the OSAK port, using the
spi_close_port routine.

2–2 OSAK Events

REDIRECT indication

REDIRECT indication
An application entity receives this event when the remote peer entity calls
spi_redirect.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

redirect_state

osak_state

[calling_aei]

osak_aei

[called_aei]

osak_aei

[protocol_versions]

osak_protocol_versions

[sconnect_id]

osak_sconnect_id

[segmentation]

osak_segmentation

[sync_point]

osak_sync_point

[tokens]

osak_token_setting

[activity_id]

osak_mem_descriptor

[functional_units]

osak_fus

[rcv_data_list]

osak_buffer

[local_data]

osak_mem_descriptor

[more_flag]

Long integer

Parameters Returned
redirect_state
A structure defining the state of the connection. The values in the structure
indicate whether the local entity is acting as initiator of or responder to the
redirection request.
calling_aei
The address of a structure containing selector information about the calling
application entity. If the incoming data units do not include this information, the
OSAK interface returns a null address.
called_aei
The address of a structure containing selector information about the called
application entity. If the incoming data units do not include this information, the
OSAK interface returns a null address.
protocol_versions
The address of a structure indicating the protocol versions proposed for use on
the redirected connection. If the incoming data units do not include any proposed
protocol version identifiers, the OSAK interface returns a default value of either
1 or 2.

OSAK Events 2–3

REDIRECT indication

sconnect_id
The address of encoded session connection information. If the incoming data
units do not include any session connection information, the OSAK interface
returns a null address.
segmentation
The address of a structure containing session segmentation data that specifies
the following:
•

Whether session segmentation is in use

•

If session segmentation is in use, the maximum size permitted for a TSDU

If the incoming data units do not include session segmentation information, the
OSAK interface returns a null address.
sync_point
The address of the current synchronization point serial number.
tokens
The address of a structure indicating the existing token assignments. To interpret
the assignment, examine the redirect_state parameter to determine whether the
local entity is acting as initiator or responder.
activity_id
The identifier of the current activity.
functional_units
The address of a structure indicating the functional units in use. If the incoming
data units do not include these values, the OSAK interface returns default values:
•

Half-duplex functional unit

•

Minor synchronize functional unit

•

Activity functional unit

•

Capability functional unit

•

Exceptions functional unit

rcv_data_list
The OSAK interface returns the address of a list of the buffers holding user data
for the service in progress. If there are insufficient buffers to receive all the user
data, the OSAK interface returns true in the more_flag parameter. On a redirect,
the rcv_data_list parameter is used instead of the peer_data parameter.
local_data
The address of a structure that holds the address of a buffer containing data sent
by the redirecting application entity.

Description
This event indicates that a connection has been redirected from another local
process.
The sequence of calls that you should make after the arrival of a REDIRECT
indication depends on two things:
•

2–4 OSAK Events

The state of the connection when the requester called spi_redirect

REDIRECT indication

•

Whether all the user data fits into the buffer supplied in the most recent call
to spi_give_buffers

The description of the routine spi_redirect in Chapter 1 describes the possible
states of a connection. Table 2–1 shows the sequence of calls you should make
for each state. In this table, each state is represented by its constant value.
Section 6.5 lists the meanings of these constants.
Table 2–1 Sequence of Calls After the Arrival of a REDIRECT Indication
State

Sequence of Calls

OSAK_C_ASSOC_IND

Call spi_get_event to receive the
REDIRECT indication.
Call spi_accept_rsp to accept or
spi_reject_rsp to reject the REDIRECT
indication.
Make multiple calls to spi_get_event
to receive all the user data from the
REDIRECT indication.
Call spi_accept_rsp to accept or
spi_reject_rsp to reject the REDIRECT
indication.
Continue exchange of data between peer
entities.

OSAK_C_PARTIAL_ASSOC_IND

OSAK_C_DATA_TRANSFER

OSAK Events 2–5

S-ACTIVITY-DISCARD confirm

S-ACTIVITY-DISCARD confirm
An application entity receives this event when the remote peer entity calls
spi_act_discard_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event responds to a request to discard an activity and confirms that the
activity has been discarded.

2–6 OSAK Events

S-ACTIVITY-DISCARD indication

S-ACTIVITY-DISCARD indication
An application entity receives this event when the remote peer entity calls
spi_act_discard_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

activity_reason

osak_activity_reason

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
activity_reason
The address of the reason for discarding an activity. If the incoming event does
not include a value for this parameter, the OSAK interface returns a null address.
Section 6.3 lists the values of this parameter.

Description
This event indicates a request to discard the current activity. Respond by calling

spi_act_discard_rsp.

OSAK Events 2–7

S-ACTIVITY-END confirm

S-ACTIVITY-END confirm
An application entity receives this event when the remote peer entity calls
spi_act_end_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event responds to a request to terminate the current activity and confirms
that the activity has been terminated.

2–8 OSAK Events

S-ACTIVITY-END indication

S-ACTIVITY-END indication
An application entity receives this event when the remote peer entity calls
spi_act_end_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[sync_point]

osak_sync_point

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the major synchronization point serial number current when the
end of the activity was requested.

Description
This event indicates a request to terminate the current activity. Respond by
calling spi_act_end_rsp.

OSAK Events 2–9

S-ACTIVITY-INTERRUPT confirm

S-ACTIVITY-INTERRUPT confirm
An application entity receives this event when the remote peer entity calls
spi_act_interrupt_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event responds to a request to interrupt the current activity.

2–10 OSAK Events

S-ACTIVITY-INTERRUPT indication

S-ACTIVITY-INTERRUPT indication
An application entity receives this event when the remote peer entity calls
spi_act_interrupt_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[activity_reason]

osak_activity_reason

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
activity_reason
The address of the reason for the interruption of the activity. If the incoming
event does not include a value for this parameter, the OSAK interface returns a
null address. Section 6.3 lists the values of this parameter.

Description
This event indicates a request to interrupt the current activity. Respond by
calling spi_act_interrupt_rsp.

OSAK Events 2–11

S-ACTIVITY-RESUME indication

S-ACTIVITY-RESUME indication
An application entity receives this event when the remote peer entity calls
spi_act_resume_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

activity_id

osak_mem_descriptor

old_activity_id

osak_mem_descriptor

sync_point

osak_sync_point

[old_sconnection_id]

osak_sconnection_id

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
activity_id
The identifier of the resumed activity.
old_activity_id
The identifier of the interrupted activity.
sync_point
The address of the synchronization point serial number at which to resume the
activity.
old_sconnection_id
The address of the session connection identification information from the session
connection over which the interrupted activity occurred.

Description
This event indicates a request to resume a previously interrupted activity. No
response to the request is necessary because resumption of an activity is not a
confirmed service.

2–12 OSAK Events

S-ACTIVITY-START indication

S-ACTIVITY-START indication
An application entity receives this event when the remote peer entity calls
spi_act_start_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

activity_id

osak_mem_descriptor

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
activity_id
The identifier of the new activity.

Description
This event indicates a request to start a new activity. No response to the request
is necessary because starting an activity is not a confirmed service.

OSAK Events 2–13

S-CAPABILITY-DATA confirm

S-CAPABILITY-DATA confirm
An application entity receives this event when the remote peer entity calls
spi_capability_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event confirms that capability data sent by the remote peer entity has been
received.

2–14 OSAK Events

S-CAPABILITY-DATA indication

S-CAPABILITY-DATA indication
An application entity receives this event when the remote peer entity calls
spi_capability_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates that capability data is being sent. Respond by calling

spi_capability_rsp.

OSAK Events 2–15

S-CONNECT indication

S-CONNECT indication
An application entity receives this event when the remote peer entity calls
spi_connect_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

called_aei

osak_aei

[calling_aei]

osak_aei

protocol_versions

osak_protocol_versions

[sconnect_id]

osak_sconnect_id

[segmentation]

osak_segmentation

[initial_serial_number]

osak_sync_point

[initial_tokens]

osak_token_setting

functional_units

osak_fus

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
called_aei
The address of selector information about the called application entity. If the
incoming data units do not include this information, the OSAK interface returns
a null address.
calling_aei
The address of selector information about the calling application-entity. If the
incoming data units do not contain this information, the OSAK interface returns
a null address.
protocol_versions
The address of the identifiers of the protocol versions proposed for use on the
connection. If the incoming data units do not specify any proposed protocol
version identifiers, the OSAK interface returns a default value of 1 or 2.
sconnect_id
The address of encoded session connection information. If the incoming data
units do not include any session connection information, the OSAK interface
returns a null address.
segmentation
The address of session segmentation information that specifies:
•

Whether session segmentation is in use

•

If session segmentation is in use, the maximum size permitted for a TSDU

2–16 OSAK Events

S-CONNECT indication

If the incoming data units do not include session segmentation information, the
OSAK interface returns a null address.
initial_serial_number
The address of the initial synchronization point serial number of the connection.
If the incoming data units do not specify a value for the initial synchronization
point serial number, the OSAK interface returns a null address.
initial_tokens
The address of the initial token settings for the connection. If the incoming data
units do not specify values for the initial token settings, the OSAK interface
returns a null address.
functional_units
The address of the functional units accepted for this connection. If the incoming
data units do not include these values, the OSAK interface returns the default
values:
•

Half-duplex functional unit

•

Minor synchronize functional unit

•

Activity functional unit

•

Capability functional unit

•

Exceptions functional unit

Description
This event indicates a request to establish a connection. Accept the
connection request by calling spi_accept_rsp; reject the connection by calling
spi_reject_rsp.

OSAK Events 2–17

S-CONNECT-ACCEPT confirm

S-CONNECT-ACCEPT confirm
An application entity receives this event when the remote peer entity calls
spi_accept_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[responding_aei]

osak_aei

[protocol_versions]

osak_protocol_versions

[sconnect_id]

osak_sconnect_id

[segmentation]

osak_segmentation

[initial_serial_number]

osak_sync_point

[initial_tokens]

osak_token_setting

[request_tokens]

osak_token_setting

[functional_units]

osak_fus

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
responding_aei
The address of information about the application entity that is responding to a
request to set up a connection. The information can include the selectors, the
application-entity title, and the application-entity identifier.
protocol_versions
The address of the identifiers of the protocol version in use on the connection.
sconnect_id
The address of encoded session connection information. If the incoming data
units do not contain session connection information, the OSAK interface returns
a null address.
segmentation
The address of session segmentation data that specifies:
•

Whether session segmentation is in use

•

If session segmentation is in use, the maximum size permitted for a TSDU

If the incoming data units do not contain session segmentation information, the
OSAK interface returns a null address.
initial_serial_number
The address of the initial synchronization point serial number on this connection.
If the incoming data units do not contain a value for the initial synchronization
point serial number, the OSAK interface returns a null address.

2–18 OSAK Events

S-CONNECT-ACCEPT confirm

initial_tokens
The address of a structure indicating the initial token settings for the connection.
If the incoming data units do not contain values for the initial token settings, the
OSAK interface returns a null address.
request_tokens
The address of the identifiers of the tokens that the calling application entity
is requesting from its peer. If the incoming data units do not contain values for
requested tokens, the OSAK interface returns a null address.
functional_units
The address of the presentation and session functional units proposed for this
connection. If the incoming data units contain no functional units, the OSAK
interface returns the default values:
•

Half-duplex functional unit

•

Minor synchronization functional unit

•

Activity functional unit

•

Capability functional unit

•

Exceptions functional unit

Description
This event indicates a positive response to a request to establish a connection. It
means that the connection has been established and you can start transferring
data.

OSAK Events 2–19

S-CONNECT-REJECT confirm

S-CONNECT-REJECT confirm
An application entity receives this event when the remote peer entity calls
spi_reject_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

reject_reason

osak_reject_reason

[responding_aei]

osak_aei

[sconnect_id]

osak_sconnect_id

[functional_units]

osak_fus

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
reject_reason
This parameter explains why the connection request is being rejected. The
parameter also specifies whether this is a rejection by the service user or by the
service provider. Section 6.6 lists the values of this parameter.
If the value returned indicates that the rejection is due to temporary congestion,
the initiator can try again to establish a connection.
responding_aei
The address of selector information about the application entity that is responding
to a request to set up a connection.
sconnect_id
The address of encoded session connection information. If the incoming data
units do not include any session connection information, the OSAK interface
returns a null address.
functional_units
The address of the functional units. If the incoming data units do not include
these values, the OSAK interface returns the default values:
•

Half-duplex functional unit

•

Minor synchronize functional unit

•

Activity functional unit

•

Capability functional unit

•

Exceptions functional unit

2–20 OSAK Events

S-CONNECT-REJECT confirm

Description
This event indicates a negative response to a request to establish a connection.
Check the reason for the refusal given in the reject_reason parameter. If the
reason is a temporary problem, for example, congestion or lack of resources, you
can try to establish the connection again.

OSAK Events 2–21

S-CONTROL-GIVE indication

S-CONTROL-GIVE indication
An application entity receives this event when the remote peer entity calls
spi_control_give_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates that the remote peer entity relinquishes ownership of all the
tokens available on a connection. No response is necessary because relinquishing
tokens is not a confirmed service.

2–22 OSAK Events

S-DATA indication

S-DATA indication
An application entity receives this event when the remote peer entity calls
spi_data_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates that normal data is being transferred. No response to the
request is necessary because sending normal data is not a confirmed service.

OSAK Events 2–23

S-EXPEDITED-DATA indication

S-EXPEDITED-DATA indication
An application entity receives this event when the remote peer entity calls
spi_expedited_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates the sending of expedited data over a connection. No response
is necessary because sending expedited data is not a confirmed service.

2–24 OSAK Events

S-P-EXCEPTION-REPORT indication

S-P-EXCEPTION-REPORT indication
An application entity receives this event when the service provider signals an
exception.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

exception_reason

osak_exception_reason

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
exception_reason
A value indicating the reason for the exception report. Section 6.4 lists the values
of this parameter.

Description
This event indicates a user error has occurred that is not severe enough to cause
a connection to be aborted. The exception_reason parameter contains a value
indicating the reason for the error. You should examine the parameter and take
corrective action as appropriate.

OSAK Events 2–25

S-RELEASE confirm

S-RELEASE confirm
An application entity receives this event when the remote peer entity calls
spi_release_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

action_result

osak_action_result

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
action_result
The address of a value indicating acceptance or rejection of the release request. If
the incoming data units do not specify a value for this parameter, the OSAK
interface returns a null address, which means that the release request is
accepted.

Description
This event responds to a request to terminate a connection. To reclaim
parameter blocks and user buffers that were used on the connection, you can
call spi_close_port, or use a completion routine (OpenVMS systems only).

2–26 OSAK Events

S-RELEASE indication

S-RELEASE indication
An application entity receives this event when the remote peer entity calls
spi_release_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates a request to release a connection. Respond to the event in
one of the following ways:
•

If the negotiated release functional unit is not in use on the connection, call

spi_release_rsp to accept the release request.
•

If the negotiated release functional unit is in use on the connection, call

spi_release_rsp to accept or reject the release request.

OSAK Events 2–27

S-RESYNCHRONIZE confirm

S-RESYNCHRONIZE confirm
An application entity receives this event when the remote peer entity calls
spi_resync_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

[token_item]

osak_token_setting

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the synchronization point serial number specified in the
resynchronization request.
token_item
The address of information about the assignment of tokens on completion of the
resynchronization service. If the incoming data units do not include values for
the assignment of tokens, the OSAK interface returns a null address.

Description
This event confirms resynchronization from a specified synchronization point.

2–28 OSAK Events

S-RESYNCHRONIZE indication

S-RESYNCHRONIZE indication
An application entity receives this event when the remote peer entity calls
spi_resync_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

resync_type

osak_resync_type

sync_point

osak_sync_point

[tokens]

osak_token_setting

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
resync_type
A value indicating the type of resynchronization. Section 6.8 lists the values of
this parameter.
sync_point
The address of the synchronization point serial number from which
resynchronization should start.
tokens
The address of a structure indicating the assignment of tokens after
resynchronization. If the incoming data units do not include this value, the
OSAK interface returns zero. Zero indicates that all the tokens are available to
the application entity that is requesting resynchronization.
Section 6.9 lists the values of this parameter.

Description
This event indicates that a request to resynchronize a connection from a specified
synchronization point. Respond by calling spi_resync_rsp.
When you receive an S-RESYNCHRONIZE indication, keep data segments that
arrived before the synchronization point specified in the indication. Ignore data
segments received after that synchronization point.

OSAK Events 2–29

S-SYNC-MAJOR confirm

S-SYNC-MAJOR confirm
An application entity receives this event when the remote peer entity calls
spi_major_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

sync_point

osak_sync_point

Description
This event confirms the setting of a major synchronization point.

2–30 OSAK Events

S-SYNC-MAJOR indication

S-SYNC-MAJOR indication
An application entity receives this event when the remote peer entity calls
spi_major_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the major synchronization point serial number.

Description
This event indicates a request to set a major synchronization point. Respond by
calling spi_major_rsp.

OSAK Events 2–31

S-SYNC-MINOR confirm

S-SYNC-MINOR confirm
An application entity receives this event when the remote peer entity calls
spi_minor_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the minor synchronization point serial number.

Description
This event confirms the setting of a minor synchronization point.

2–32 OSAK Events

S-SYNC-MINOR indication

S-SYNC-MINOR indication
An application entity receives this event when the remote peer entity calls
spi_minor_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

sync_confirm

osak_sync_confirm

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the minor synchronization point serial number.
sync_confirm
The value of this parameter is true if the remote peer entity requested
confirmation of the synchronization point and false if the remote application
entity did not request a confirmation of the synchronization point.

Description
This event indicates a request to set a minor synchronization point. You can
respond by calling spi_minor_rsp, but you do not have to do so. If you do not do
so, you imply agreement with the parameters set by the remote peer entity.

OSAK Events 2–33

S-TOKEN-GIVE indication

S-TOKEN-GIVE indication
An application entity receives this event when the remote peer entity calls
spi_token_give_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

token_item

osak_token_setting

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
token_item
The address of a structure that indicates the tokens that the remote application
entity is passing to its peer.

Description
This event indicates that its sender relinquishes ownership of all or some of
the tokens available on a connection. The token_item parameter specifies which
tokens are being relinquished. No response is necessary because relinquishing
tokens is not a confirmed service.

2–34 OSAK Events

S-TOKEN-PLEASE indication

S-TOKEN-PLEASE indication
An application entity receives this event when the remote peer entity calls
spi_token_please_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

token_item

osak_token_setting

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
token_item
The address of a structure indicating the tokens that the remote application
entity is requesting from its peer.

Description
This event indicates that the remote peer entity is requesting the recipient of the
event to relinquish some or all of the tokens available on the connection. The
token_item parameter specifies which tokens are being requested. No response to
the request is necessary because this is not a confirmed service.
See Section 6.9 for the possible values.

OSAK Events 2–35

S-TYPED-DATA indication

S-TYPED-DATA indication
An application entity receives this event when the remote peer entity calls
spi_typed_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[more_flag]

Long integer

Description
This event indicates that typed data is being sent over a connection. No response
is necessary because sending typed data is not a confirmed service.

2–36 OSAK Events

S-U-EXCEPTION-REPORT indication

S-U-EXCEPTION-REPORT indication
An application entity receives this event when the remote peer entity calls
spi_exception_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

exception_reason

osak_exception_reason

[peer_data]

osak_buffer

[more_flag]

Long integer

Parameters Returned
exception_reason
A value indicating the reason for the exception report. Section 6.4 lists the values
of this parameter.

Description
This event indicates that an error has occurred that is not severe enough to
cause a connection to be aborted. The error originates from the service user. The
exception_reason parameter contains a value indicating the reason for the error.
You should examine the parameter and take corrective action as appropriate.

OSAK Events 2–37

3
Checking OSAK Status Codes
This chapter lists the status codes returned by the OSAK routines. The status
codes are divided into the following categories:
•

Success (Section 3.1)

•

Informational (Section 3.2)

•

Error (Section 3.3)

Subsidiary status codes occur only in the osak_status2 field of the status_block
parameter.
All the status codes except OSAK_S_INVPORT can be returned either as return
values or in the status_block parameter. The status code OSAK_S_INVPORT can
only be returned as a return value.
To find the status of a call, follow these guidelines:
•

In the following circumstances, you need to check only the return value of the
call:
You are sending unsegmented user data, or you are sending a final
segment of user data in a call to spi_send_more with the more_flag
parameter set to false.
You are not using completion routines (OpenVMS systems only).
The return value of the call is not OSAK_S_QUEUED or
OSAK_S_FREE.

•

In the following circumstances, you need to check the return value of the call
and the value in the status_block parameter:
You are sending segmented data.
You are using completion routines (OpenVMS systems only).
The return value of the call is OSAK_S_QUEUED or OSAK_S_FREE.
Note
You cannot check the value in the status_block parameter until the OSAK
interface returns the ownership of the parameter block to the application.

Checking OSAK Status Codes 3–1

3.1 Success Status Codes
OSAK_S_NORMAL, the routine has finished without error
This status code usually indicates that the OSAK interface has delivered the call
to the local transport provider and has returned ownership of the parameter block
and user data buffers to your application. However, the status code has specific
meanings in certain cases:
•

A call to spi_close_port returns this status code when the OSAK interface
has closed the port specified in the call.

•

A call to spi_get_event returns this status code when an event has arrived
on the connection specified in the call.

•

A call to spi_get_handle returns this status code when the OSAK interface
has identified the channel or channels specified in the call.

•

A call to spi_give_buffers returns this status code when user data buffers
have been passed to OSAK.

•

A call to spi_open_initiator, spi_open_responder or spi_redirect returns
this status code when the OSAK interface has opened a port.

•

A call to spi_collect_pb returns this status code when a parameter block
used on an outbound service has been returned.

•

A call to spi_select returns this status code when an event is present on the
channel or channels specified in the call.

3.2 Informational Status Codes
OSAK_S_FREE, OSAK has queued the request and there are free parameter
blocks
A previous request has been completed and there are one or more parameter
blocks or user data buffers awaiting collection. If you want to reuse these
parameter blocks and user data buffers, call spi_collect_pb.
The code means the same as OSAK_S_QUEUED, with the added indication that
a call to spi_collect_pb will generate an OSAK_S_NORMAL return rather than
an OSAK_S_NO_EVENT.
OSAK_S_NO_EVENT, no event has occurred
A call to spi_get_event returns this status code when there is no event waiting
to be received on the specified connection. The event_type parameter contains the
value OSAK_C_NO_EVENT.
OpenVMS

This status code is also returned when you call spi_get_event with
a completion routine and then release or abort the connection on
which the call is made. The completion routine starts running when
the connection closes.
♦

A call to spi_collect_pb returns this status code when there are no completed
outbound services on the specified connection, and hence no parameter blocks
waiting to be collected.
A call to spi_select returns this status code when there are no events waiting
on any of the channels specified in the call and the timeout period has expired.

3–2 Checking OSAK Status Codes

OSAK_S_QUEUED, OSAK has queued the request
The OSAK interface has put the call on the queue for the transport provider.
The OSAK interface retains ownership of the parameter block and the user
data buffers passed in the call. This status code can be returned by the routine
spi_connect_request, or when you are sending segmented user data using the
routine spi_send_more.
OpenVMS

This status code can also be returned when you are using a
completion routine, and on all outbound services.
♦

The code OSAK_S_QUEUED does not indicate that the OSAK interface has sent
the data unit. Errors can occur after the interface has put the call on the queue
for the transport provider. You should check the status_block parameter for such
errors, but you cannot do this until the OSAK interface returns the ownership of
the parameter block and user data buffers.
Note that, in general, service requests on the queue for the transport provider are
completed in the order in which they are issued, but there are exceptions. For
example, a call to the expedited data service may overtake a call to the normal
data service.
OpenVMS

OSAK_S_QUEUED is returned by the following routines only when
they include a completion routine:
•

spi_get_event

•

spi_open_initiator

•

spi_open_redirect

•

spi_open_responder

If no completion routine is included on a call to one of these routines,
the routine can return only OSAK_S_NORMAL or an error status.
♦

3.3 Error Status Codes
OSAK_S_BADPARAM, there is an invalid parameter
One or more of the parameters you have used in a call was invalid. This code is
rarely returned. It indicates that there is a problem in your application.
OSAK_S_DEALLOCERR, an error occurred when deallocating memory
A user-supplied deallocation routine has returned an error status. You can find
the returned error status in the status_block parameter. This error indicates a
problem with your application.
OSAK_S_DISRUPTED, a disruptive event has occurred
The request was canceled by a disruptive event. Chapter 4 explains what to do
when a disruptive event occurs.
OSAK_S_FILERR, an error occurred in opening the trace file
Returned when a call to spi_trace_open fails. Check the validity of the
parameters that you passed in the call.

Checking OSAK Status Codes 3–3

OSAK_S_INCPCI, incomplete PCI
Returned by spi_get_event when a partial event arrives with the protocol control
information (PCI) incomplete. You should make another call to spi_get_event to
collect the remaining PCI.
OSAK_S_INSFMEM, there is not enough dynamic memory
There is not enough dynamic memory to complete the service request. This
error is usually fatal to the connection on which it occurs. You should abort the
connection. Check your memory allocation and deallocation routines (see DECnetPlus OSAK Programming). You may find that you have allocated more memory
than you need.
If you cannot make additional memory available, you should shut down your
application. Aborting a connection will also release some memory.
OSAK_S_INSFWS, there is not enough workspace in the parameter block
The parameter block workspace is not large enough. You should make the
workspace at least double its existing size. The chapter on planning in DECnetPlus OSAK Programming helps you decide how large the workspace should
be.
OSAK_S_INVACTION, the action_result parameter is invalid
Returned by spi_release_rsp.
Check which functional units are in use on this connection. You should not pass
the action_result parameter in a call to spi_release_rsp unless you are using the
negotiated release functional unit on the connection.
OSAK_S_INVAEI, the application entity invocation is invalid
There is an error in at least one address component. For example, the tsel value
you are using may be unknown at the remote end of the connection.
The osak_status2 field of the status_block parameter may contain a subsidiary
status code that tells you which address component is invalid. The following
subsidiary codes may occur with OSAK_S_INVAEI:
•

OSAK_S_INVSSEL, invalid session selector
The session selector is too long. A session selector should not be longer than
16 octets.

•

OSAK_S_INVTSEL, Invalid Transport Selector
Indicates that the TSEL is not known at the remote node.

•

OSAK_S_MULTADDR, multiple upper layer addresses for t-selector
Indicates that you have opened more than one process (initiator or responder)
using the same TSEL, but a different SSEL. This is not allowed. If you want
to specify a different SSEL, you should also specify a different TSEL.

•

OSAK_S_NOSUCHENTRY, No such entry in OSAKserver address database
A call to spi_open_redirect returns this status if the address specified for
the call has not been created on the server.

•

OSAK_S_NOTAVAILABLE, OSAK is not available
A call to spi_open_initiator, spi_open_responder or spi_redirect returns
this status code when OSAK has been restricted, disabled or deleted by OSAK
network management (by means of NCL).

3–4 Checking OSAK Status Codes

•

OSAK_S_TSELINUSE, T-Selector is already in use
Indicates that a TSEL in the local_aei or calling_aei parameter is already
being used on another port or by another application.

OSAK_S_INVAPIVERSION, unsupported API version
Check that you specified the correct constant in the api_version parameter.
Chapter 1 discusses the correct constant for this version.
OSAK_S_INVFUNC, the call is invalid
This code is returned for one of the following reasons:
•

You have made an incorrect sequence of calls. For example:
Sending data before establishing a connection
Calling spi_send_more when the more_flag parameter of the previous call
is false
Calling an activity management service when the activity management
functional unit is not selected
Calling spi_get_event on a connection that has been terminated

•

You are trying to enable tracing using spi_trace_open or spi_trace_start
when you have already enabled tracing either by defining osak_trace
or by making a previous spi_trace_open call (with no intervening
spi_trace_close call).
Call spi_trace_close and spi_trace_stop, to close the existing trace files
and to stop tracing. After this, call spi_trace_open and spi_trace_start
again.

The following subsidiary code may occur with OSAK_S_INVFUNC:
OSAK_S_READPOSTED, Buffers have been given to OSAK
This code can be returned only by spi_redirect. It indicates that the OSAK
interface holds unused buffers passed from your application before the call to
spi_redirect. You cannot redirect a connection in this situation. You should
reclaim the buffers and make the call to spi_redirect again.
OSAK_S_INVFUS, the functional units are invalid
You have proposed an invalid combination of functional units. Examine the
functional_units parameter. DECnet-Plus OSAK Programming explains which
functional units are interdependent.
OSAK_S_INVID, the activity identifier is too long
Examine the activity_id and old_activity_id parameters. Neither of these
parameters should be more than six characters long.
OSAK_S_INVPARAM, there is an invalid parameter
Returned by spi_give_buffers or spi_select.
OSAK_S_INVPARAM is returned by spi_give_buffers if at least one of the
buffers you have passed to the OSAK interface is less than the minimum
permitted size for buffers, 512 octets. This minimum size applies only to buffers
that you pass to OSAK for receiving inbound events.
You should increase the size of any buffer that is smaller than 512 octets.

spi_select returns OSAK_S_INVPARAM if:
•

The time_out parameter is greater than 86,400 seconds (one day)

Checking OSAK Status Codes 3–5

•

The specified event flag is not in event flag cluster 1

OSAK_S_INVPORT, the port identifier is invalid
You have specified a port that does not exist. Examine the port argument.
OSAK_S_INVPV, the protocol versions are invalid
The protocol_versions parameter contains illegal values.
OSAK_S_INVREASON, the reason code is invalid
You have specified a reason code that is not valid for the service you are using it
on. Examine the reason parameter. Chapter 6 lists the possible reason codes and
their constant values.
OSAK_S_INVRESYNCTYPE, the resynchronization type is invalid
Returned by osak_resync_req.
Examine the resync_type parameter. There are only three valid resynchronization
types: abandon, restart, and set.
OSAK_S_INVSCONNID, invalid session connection identifier
One of the fields in the sconnect_id or the old_sconnection_id contains an invalid
value. The size restrictions on the fields in these parameters are as follows:
Field

Maximum Size

ss_user_ref

64 octets

common_ref

64 octets

add_ref_info

4 octets

called_ss_user_ref

64 octets

calling_ss_user_ref

64 octets

OSAK_S_INVSSEL, Invalid session selector
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_INVAEI. See OSAK_S_INVAEI.
OSAK_S_INVSYNCPNT, the synchronization point serial number is invalid
Returned by spi_resync_req.
Examine the sync_point and resync_type parameters. You should not specify a
value for a synchronization point serial number if the resynchronization type is
abandon.
OSAK_S_INVTEMPLATE, invalid transport template
This status is returned if the transport template parameter specified does not
contain a valid transport template name.
OSAK_S_INVTOKEN, the token setting is invalid
Examine the token_item and request_tokens parameters. The token setting is
illegal. For example:
•

A peer entity is requesting a token it already has.

•

A peer entity is requesting a token whose supporting functional unit is not
selected on this connection.

OSAK_S_INVTSEL, Invalid transport selector
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_INVAEI. See OSAK_S_INVAEI.

3–6 Checking OSAK Status Codes

OSAK_S_MULTADDR, multiple upper layer addresses for t-selector
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_INVAEI. See OSAK_S_INVAEI.
OSAK_S_NOBUFFERS, there are not enough user data buffers
This status is returned by spi_get_event. The code indicates that the OSAK
interface needs more buffer space in which to return an incoming event to your
application. Increase the number or the size of user buffers you are supplying.
Note that the incoming event is not lost. The OSAK interface returns the event
to your application when sufficient buffers are available.
If the OSAK interface receives a partial event and runs out of buffers before
receiving enough data units to decode the event, the interface retains the buffers
it is holding. The interface retains these buffers until you post the necessary
extra buffers, or until you abort the connection.
If the OSAK interface receives a partial event and has both decoded it and passed
it to the application, but has no buffers to receive the rest of the event, the
application owns the buffers it has received from the OSAK interface.
DECnet-Plus OSAK Programming explains how to plan the buffer capacity you
require.
OSAK_S_NODATA, there is no data specified
Returned by spi_data_req, spi_typed_req, spi_expedited_req, and
spi_capability_req. This status is returned if no data is specified and the
more_flag is set to false.
OSAK_S_NOPARAM, a mandatory parameter has been omitted in the call
Make the call again, including the missing parameter.
OSAK_S_NOPROCINFO, there is no process identifier and no process name
Returned by spi_redirect.
Examine the process-id and process_name parameters. In a request for
redirection of a connection, at least one of these parameters should contain a
value other than null.
OSAK_S_NORESOURCE, OSAK has run out of system resources
Examine the transport_status1 field of the status_block parameter for more
specific information on the system error. The remedial action depends on your
local situation.
OSAK_S_NOSYNCPNT, the synchronization point serial number is missing
This status code is returned by spi_connect_req and spi_accept_rsp.
Check that you assigned a value to the initial_serial_number parameter. This
parameter is mandatory if you have selected the major synchronize functional
unit, the minor synchronize functional unit, or the resynchronize functional unit,
but you have not selected the activity management functional unit.
OSAK_S_NOTAVAILABLE, OSAK is not available
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_INVAEI. See OSAK_S_INVAEI.
OSAK_S_NOTRANSPORT, there is no transport connection set up
You made an inappropriate call before a transport connection is established. For
example, you may have called spi_get_handle before calling spi_connect_req.

Checking OSAK Status Codes 3–7

OSAK_S_OVERFLOW, too much user data has been sent for session
version 1
Send the data again, dividing it into smaller units. Alternatively, you can
negotiate the session version again, proposing session version 2.
However, if you are using session version 1, you cannot send any user data on the
following calls:

spi_act_interrupt_req
spi_act_interrupt_rsp
spi_act_discard_req
spi_act_discard_rsp
spi_token_give_req
spi_control_give_req
These calls return the status code OSAK_S_OVERFLOW if you try to send any
user data.
This status code is also returned when user data is included in the
spi_reject_rsp call and the reason given for the rejection is anything other
than user specified.
OSAK_S_READPOSTED, buffers have been given to OSAK
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_INVFUNC. See OSAK_S_INVFUNC.
OSAK_S_REDIRECTERR, error occurred while redirecting
This code can be returned only by spi_redirect. For further information on the
nature of the error, check the osak_status2 field of the status_block parameter.
This field may contain either of the following secondary statuses:
•

OSAK_S_TIMEOUT, Redirect processing timed out

•

OSAK_S_TOOMANYREDIRECTS, tried to exceed maximum number of
simultaneous redirects

OSAK_S_TIMEOUT, Redirect processing timed out
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_REDIRECTERR. See OSAK_S_REDIRECTERR.
OSAK_S_TOOMANYREDIRECTS, Tried to exceed maximum number of
simultaneous redirects
This code may be returned as a secondary status in the osak_status2 field when
the primary status is OSAK_S_REDIRECTERR. See OSAK_S_REDIRECTERR.
OSAK_S_TRANSERR, there is an error in the transport provider
An error has occurred in the Transport layer or at the interface to the Transport
layer. The OSAK interface has returned ownership of the parameter block and
user data buffers to your application.
The transport_status field in the status_block parameter records a transport
provider status code that gives more information about the error. Note that
transport errors are simply passed through by the OSAK software, so their
meanings may vary between systems. For example, given a common cause of
error, a message from the Transport layer on an OpenVMS system may not be the
same as the message from the Transport layer on a Digital UNIX system.
Examples of errors that can occur are:
•

The remote system disconnects the transport connection.

3–8 Checking OSAK Status Codes

•

Someone shuts down the local transport provider.

•

Network connectivity is lost.

•

The transport provider receives an invalid PDU.

Some errors in the Transport layer are fatal only to the connection on which the
error is returned. Others are fatal to all connections. No Transport layer error
can be fatal to the OSI component using OSAK, or to the OSAK software itself.
But if you receive many TRANSERR messages, there might be a problem with
the Transport entity that needs attention.
For example, if someone shuts down the local transport provider, all connections
are affected, and you should shut down your application until the transport
provider is running again.
OSAK_S_TSELINUSE, T-Selector is already in use
This code may be returned as a secondary status in the field osak_status2 when
the primary status is OSAK_S_INVAEI. See OSAK_S_INVAEI.
OSAK_S_UNSPECERR, an unspecified error has occurred
Indicates the occurrence of either an internal error that does not correspond to an
OSAK interface error, or a system error. The osak_status2 field of the
status_block parameter contains the code for the internal error or system error.

Checking OSAK Status Codes 3–9

4
Disruptive Events
This chapter explains what the OSI Applications Kernel (OSAK) interface does
when a disruptive event occurs and what action, if any, you should take.
The following disruptive events may occur:
•

ABORT request (from the local peer entity)

•

ABORT indication (from the remote peer entity)

•

PREPARE (RESYNC)

•

S-ACTIVITY-DISCARD indication

•

S-ACTIVITY-INTERRUPT indication

•

S-EXCEPTION-REPORT indication

•

S-RESYNCHRONIZE indication

•

Transport connection loss

4.1 ABORT request (Local Peer Abort)
This event is fatal to a connection.
If you are using segmentation and you issue an ABORT request when you
have a queue of data segments waiting to be sent, the OSAK interface does
not send any of these segments. The OSAK interface returns the status code
OSAK_S_DISRUPTED.
To reclaim the user data buffers, call spi_close_port or spi_collect_pb. Then
set up the connection and send the data again.

4.2 ABORT indication (Remote Peer Abort)
This event is fatal to a connection.
Data segments sent from the remote peer entity after it issues the ABORT
request do not reach the local peer entity.
If the local peer entity is sending data when it receives the ABORT indication,
the OSAK interface does not send any of the data segments that are on the queue
for the transport provider.
The OSAK interface returns the status code OSAK_S_DISRUPTED.

Disruptive Events 4–1

4.3 Transport Connection Loss
This event is fatal to a connection. The event appears as an ABORT indication.
If the local peer entity is sending data when it receives the ABORT indication,
the OSAK interface does not send any of the data segments on the queue for the
transport provider.
The OSAK interface returns status OSAK_S_DISRUPTED.

4.4 S-ACTIVITY-INTERRUPT indication
This event is not fatal to a connection.
If you are sending data segments when an S-ACTIVITY-INTERRUPT indication
arrives, stop sending the data. Data segments you have already sent are lost, so
you should send all the data again.
If you are receiving data segments when an S-ACTIVITY-INTERRUPT
indication arrives, keep the data segments you have already received until
an S-ACTIVITY-RESUME indication arrives.

4.5 S-ACTIVITY-DISCARD indication
This event is not fatal to a connection.
When you receive an S-ACTIVITY-DISCARD indication, ignore the data that has
already arrived on the activity being discarded and reclaim the buffers you posted
to receive it.

4.6 S-RESYNCHRONIZE indication
This event is not fatal to a connection.
When you receive an S-RESYNCHRONIZE indication, keep data segments that
arrived before the synchronization point specified in the indication. Ignore data
segments received after that synchronization point.

4.7 S-EXCEPTION-REPORT indication
This event is not fatal to a connection.
When you receive a S-EXCEPTION-REPORT indication, follow the procedures
you have defined for dealing with exception reports.

4.8 PREPARE (RESYNC)
This event is not fatal to a connection.
If you receive a PREPARE (RESYNC) indication from the remote peer entity
when you are sending data, check the queue of data units waiting to be sent:
•

If the head of the queue is the first segment of a data unit, stop sending.

•

If the head of the queue is not the first segment of a data unit, continue
sending until you have sent the complete data unit, then stop sending.

If you send a PREPARE (RESYNC) indication, do not send any data after it.

4–2 Disruptive Events

5
How the OSAK SPI Implements the ISO
Standards
This chapter explains how the OSAK SPI implements the ISO Standards for
Open Systems Interconnection, and the National Institute of Standards and
Technology (NIST) modifications to these standards.
DECnet-Plus OSAK Programming gives a full list of the standards on which
the OSAK SPI is based. It is important that you have access to copies of all the
standards documents.
You can obtain the standards documents from the national standards body in
your own country. If you do not know the name and address of your national
standards body, write to the following address:
U.N. Bookstall
United Nations Assembly Building
New York, New York 11017
U.S.A.

5.1 The OSAK SPI and the ISO Protocol Definitions
The OSAK SPI conforms to the following ISO protocol definition:
•

ISO 8327 Information Processing Systems — Open Systems Interconnection —
Basic Connection Oriented Session Protocol Specification

ISO service definitions are given in the following document:
•

ISO 8326 Information Processing Systems — Open Systems Interconnection —
Basic Connection Oriented Session Service Definition

With the exception of the items listed in Section 5.2, the OSAK SPI implements
these standards with the NIST modifications given in NIST Special Publication
500-177, Stable Implementation Agreements for Open Systems Interconnection
Protocols Version 3 Edition 1 December 1989, Chapter 5, as follows:
•

The OSAK implementation of the sending side of a connection conforms to
the NIST agreement. For example, you may send no more than 10,240 octets
of data in the user_data parameter (except on calls to spi_data_req and
spi_typed_req).

•

The OSAK implementation of the receiving side of a connection conforms to
the NIST agreement.

How the OSAK SPI Implements the ISO Standards 5–1

5.2 Restrictions in the OSAK Implementation of the ISO Protocol
Definitions
The OSAK SPI has the following restrictions:
•

The OSAK SPI does not support the symmetric synchronize functional unit
defined in Addendum 1 to ISO 8327

•

The data overflow parameter in the S-CONNECT request is not supported.

5–2 How the OSAK SPI Implements the ISO Standards

6
Possible Values for OSAK Data Types
This chapter lists the possible values of all the OSI Applications Kernel (OSAK)
parameters that have constant values. The parameter names are in alphabetical
order.

6.1 Data Type: osak_abort_reason
These values can only be received.
Constant

Meaning

OSAK_C_SP_ABORT_BADPROT

A session protocol violation was detected.

OSAK_C_SP_ABORT_UNKNOWNERR

An unknown error has occurred.

OSAK_C_ABORT_ACSE_USER

The ACSE user is aborting the connection.

OSAK_C_ABORT_DISCONNECT

The transport connection has been lost.

6.2 Data Type: osak_action_result
Constant

Meaning

OSAK_C_ACCEPT

Acceptance of request to release a connection.

OSAK_C_REJECT

Rejection of request to release a connection.

6.3 Data Type: osak_activity_reason
Constant

Meaning

OSAK_C_ACTIVITY_NOTSPECIFIED

No reason is specified.

OSAK_C_ACTIVITY_CANTCONTINUE

The requester is temporarily unable to
continue the activity.

OSAK_C_ACTIVITY_SEQUENCE

There is an error in the call sequence.

OSAK_C_ACTIVITY_USER

A local session service user error has occurred.

OSAK_C_ACTIVITY_PROCEDURAL

A procedural error has occurred.

OSAK_C_ACTIVITY_DEMAND

The data token is required.

6.4 Data Type: osak_exception_reason
The exception originates from the user.

Possible Values for OSAK Data Types 6–1

Constant

Meaning

OSAK_C_EXCEPTION_NOTSPECIFIED

No reason is specified.

OSAK_C_EXCEPTION_
CANTCONTINUE

The OSAK interface is temporarily unable to
continue.

OSAK_C_EXCEPTION_SEQUENCE

There is an error in the call sequence.

OSAK_C_EXCEPTION_USER

A local session service user error has occurred.

OSAK_C_EXCEPTION_PROCEDURAL

A procedural error has occurred.

OSAK_C_EXCEPTION_DEMAND

The data token is required.

6.5 Field: pm_state
This is a field of the osak_state data type.
Constant

Meaning

OSAK_C_ASSOCIATE_IND

The process has received a connection
indication, but has not responded to it.

OSAK_C_PARTIAL_ASSOC_IND

The process has received a connection
indication with incomplete user data or no
user data.

OSAK_C_DATA_TRANSFER

The process has established a connection and
is transferring data.

6.6 Data Type: osak_reject_reason
Possible values vary according to the source of the rejection of a connection
request. The rejection may originate from either of the following sources:
•

The service user

•

The service provider

6.6.1 Rejection Originating from User

Constant

Meaning
1

OSAK_C_REJ_NOREASON

No reason is given.

OSAK_C_REJ_SP_NO_REASON

No reason is given.

OSAK_C_REJ_SP_USER_CONGESTED

Temporary congestion

OSAK_C_REJ_SP_USER_REASON

User specified reason

1 User can specify this in the call, but this value is never received because it is converted to
OSAK_C_REJ_SP_NO_REASON.

You can give any of these values in a call to spi_reject_rsp.

6–2 Possible Values for OSAK Data Types

6.6.2 Rejection Originating from Session Provider
Constant

Meaning

OSAK_C_REJ_SP_NO_SUCH_SSAP

There is no such session service access point
(SAP).

OSAK_C_REJ_SP_NO_USER

The session service user is not attached to the
session SAP.

OSAK_C_REJ_SP_CONGESTED

The session protocol machine is temporarily
congested.

OSAK_C_REJ_SP_UNSUPPORTED

The proposed session protocol version is not
supported.

OSAK_C_REJ_SP_REFUSED

The session protocol machine has rejected the
connection attempt.

OSAK_C_REJ_SP_RESTRICTION

The connection is rejected by the session
protocol machine due to an implementation
restriction stated in the OSAK PICS.

6.7 Field: request_returned_mask
These are fields of the osak_handle data type.
Constant

Meaning

OSAK_C_READEVENT

The routine spi_select writes this value when
an inbound event has occurred.

OSAK_C_WRITEEVENT

The routine spi_select writes this value when
an outbound event has been completed.

6.8 Parameter: osak_resync_type
Constant

Meaning

OSAK_C_RESYNC_ABANDON

The OSAK interface resynchronizes to a
synchronization point the serial number of which is
higher than the serial numbers of synchronization
points in use on the existing connection.

OSAK_C_RESYNC_RESTART

The OSAK interface resynchronizes to a
synchronization point set since the last
acknowledged major synchronization point.

OSAK_C_RESYNC_SET

The OSAK interface resynchronizes to any valid
synchronization point serial number.

6.9 Fields: data, sync_mimnor, major_activity, and release
These are fields of the osak_token_setting data type.

Constant

Meaning

OSAK_C_TOKEN_INIT

The token is assigned to the initiator.

Possible Values for OSAK Data Types 6–3

Constant

Meaning

OSAK_C_TOKEN_RESP

The token is assigned to the responder.

OSAK_C_TOKEN_CHOOSE

The token is assigned according to the responder’s
choice.

6.10 Field: type
This is a field of the osak_nsap data type.
Constant

Meaning

OSAK_C_CONS

Connection-oriented network service

OSAK_C_CLNS

Connectionless network service

OSAK_C_RFC1006

RFC 1006 network

6–4 Possible Values for OSAK Data Types

Index
A

ABORT indication
description, 2–2
abort_reason parameter
constant values, 6–1
action_result parameter
constant values, 6–1
activity_reason parameter
constant values, 6–1

S-ACTIVITY-DISCARD confirm
description, 2–6
S-ACTIVITY-DISCARD indication
description, 2–7
S-ACTIVITY-END confirm
description, 2–8
S-ACTIVITY-END indication
description, 2–9
S-ACTIVITY-INTERRUPT confirm
description, 2–10
S-ACTIVITY-INTERRUPT indication
description, 2–11
S-ACTIVITY-RESUME indication
description, 2–12
S-ACTIVITY-START indication
description, 2–13
S-CAPABILITY-DATA confirm
description, 2–14
S-CAPABILITY-DATA indication
description, 2–15
S-CONNECT indication
description, 2–16
S-CONNECT-ACCEPT confirm
description, 2–18
S-CONNECT-REJECT confirm
description, 2–20
S-CONTROL-GIVE indication
description, 2–22
S-DATA indication
description, 2–23
S-EXPEDITED-DATA indication
description, 2–24
S-P-EXCEPTION-REPORT indication
description, 2–25
S-RELEASE confirm
description, 2–26
S-RELEASE indication
description, 2–27
S-RESYNCHRONIZE confirm
description, 2–28
S-RESYNCHRONIZE indication
description, 2–29

E
Event flag number, 1–95
exception_reason parameter
constant values, 6–1

H
handle_list parameter
handle_request_mask field
constant values, 6–3

O
osak_nsap
type field
constant values, 6–4

R
REDIRECT indication
description, 2–3
redirect_state parameter
constant values, 6–2
reject_reason parameter
constant values, 6–2
resync_type parameter
constant values, 6–3
Routine call
status of, 3–1

Index–1

S-SYNC-MAJOR confirm
description, 2–30
S-SYNC-MAJOR indication
description, 2–31
S-SYNC-MINOR confirm
description, 2–32
S-SYNC-MINOR indication
description, 2–33
S-TOKEN-GIVE indication
description, 2–34
S-TOKEN-PLEASE indication
description, 2–35
S-TYPED-DATA indication
description, 2–36
S-U-EXCEPTION-REPORT indication
description, 2–37
spi_abort_req, 1–13
spi_accept_rsp, 1–15
spi_act_discard_req, 1–19
spi_act_discard_rsp, 1–21
spi_act_end_req, 1–23
spi_act_end_rsp, 1–25
spi_act_interrupt_req, 1–27
spi_act_interrupt_rsp, 1–29
spi_act_resume_req, 1–31
spi_act_start_req, 1–34
spi_aync_close, 1–36
spi_capability_req, 1–38
spi_capability_rsp, 1–40
spi_close_port, 1–42
spi_collect_pb, 1–44
spi_connect_req, 1–45
spi_control_give_req, 1–49
spi_data_req, 1–51
spi_exception_req, 1–53
spi_expedited_req, 1–55
spi_get_event, 1–57
spi_get_handle, 1–61
spi_give_buffers, 1–63
spi_major_req, 1–64
spi_major_rsp, 1–66
spi_minor_req, 1–68
spi_minor_rsp, 1–70
spi_open_initiator, 1–72
spi_open_redirect, 1–74
spi_open_responder, 1–76
spi_redirect, 1–79
spi_reject_rsp, 1–84
spi_release_req, 1–86
spi_release_rsp, 1–88
spi_resync_req, 1–90
spi_resync_rsp, 1–93
spi_select, 1–95
spi_send_more, 1–98
spi_token_give_req, 1–100
spi_token_please_req, 1–102

Index–2

spi_typed_req, 1–104
Status codes
error, 3–3
in status_block parameter, 3–1
informational, 3–2
OSAK_S_BADPARAM, 3–3
OSAK_S_DEALLOCERR, 3–3
OSAK_S_DISRUPTED, 3–3
OSAK_S_FILERR, 3–3
OSAK_S_FREE, 3–2
OSAK_S_INCPCI, 3–4
OSAK_S_INSFMEM, 3–4
OSAK_S_INSFWS, 3–4
OSAK_S_INVACTION, 3–4
OSAK_S_INVAEI, 3–4
OSAK_S_INVAPIVERSION, 3–5
OSAK_S_INVFUNC, 3–5
OSAK_S_INVFUS, 3–5
OSAK_S_INVID, 3–5
OSAK_S_INVPARAM, 3–5
OSAK_S_INVPORT, 3–6
OSAK_S_INVPV, 3–6
OSAK_S_INVREASON, 3–6
OSAK_S_INVRESYNCTYPE, 3–6
OSAK_S_INVSCONNID, 3–6
OSAK_S_INVSSEL, 3–4
OSAK_S_INVSYNCPNT, 3–6
OSAK_S_INVTEMPLATE, 3–6
OSAK_S_INVTOKEN, 3–6
OSAK_S_INVTSEL, 3–4
OSAK_S_MULTADDR, 3–4
OSAK_S_NOBUFFERS, 3–7
OSAK_S_NODATA, 3–7
OSAK_S_NOPROCINFO, 3–7
OSAK_S_NORESOURCE, 3–7
OSAK_S_NORMAL, 3–2
OSAK_S_NOSUCHENTRY, 3–4
OSAK_S_NOSYNCPNT, 3–7
OSAK_S_NOTAVAILABLE, 3–4, 3–7
OSAK_S_NOTRANSPORT, 3–7
OSAK_S_NO_EVENT, 3–2
OSAK_S_OVERFLOW, 3–8
OSAK_S_QUEUED, 3–3
OSAK_S_READPOSTED, 3–8
OSAK_S_REDIRECTERR, 3–8
OSAK_S_TIMEOUT, 3–8
OSAK_S_TOOMANYREDIRECTS, 3–8
OSAK_S_TRANSERR, 3–8
OSAK_S_TSELINUSE, 3–5
OSAK_S_UNSPECERR, 3–9
return values, 3–1
success, 3–2

T
token_item parameter
constant values, 6–3
Transport Service Data Unit
see TSDU
Transport template, 1–3
TSDU, 1–3, 1–16, 1–46, 1–63, 1–81

Index–3