Digital PDFs

AA-PJ1DD-TE

November 1996

240 pages

Original

1.0MB

Document:	DECnet-Plus OSAK Programming Reference
Order Number:	AA-PJ1DD-TE
Revision:	0
Pages:	240
Original Filename:	osak_pref.PDF

OCR Text

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

This manual provides specific information on the calling interface to the
OSAK and ROSE application programming interfaces.

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 OSAK 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 . . . . . . . . . . . . . . . . . .
osak_abort_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_accept_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_discard_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_discard_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_end_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_end_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_interrupt_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_interrupt_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_resume_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_act_start_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_alter_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_alter_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_associate_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_async_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_capability_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_capability_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_close_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_collect_pb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_control_give_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_data_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_exception_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_expedited_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_get_event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_get_handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_give_buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_major_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_major_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_minor_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_minor_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–1
1–1
1–5
1–12
1–12
1–12
1–16
1–19
1–23
1–25
1–27
1–29
1–31
1–33
1–35
1–38
1–40
1–42
1–44
1–49
1–51
1–53
1–55
1–57
1–58
1–60
1–62
1–64
1–66
1–71
1–73
1–74
1–76
1–78
1–80

iii

osak_open_initiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_open_redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_open_responder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_reject_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_release_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_release_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_resync_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_resync_rsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_send_more . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_token_give_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_token_please_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_typed_req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–82
1–84
1–86
1–89
1–94
1–97
1–99
1–101
1–104
1–107
1–110
1–112
1–114
1–116

2 OSAK Events
ABORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-ASSOCIATE-ACCEPT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-ASSOCIATE-REJECT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-ASSOCIATE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-RELEASE confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-RELEASE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-DISCARD confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-DISCARD indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-END confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-END indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-INTERRUPT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-INTERRUPT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-RESUME indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ACTIVITY-START indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ALTER-CONTEXT confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-ALTER-CONTEXT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-CAPABILITY-DATA confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-CAPABILITY-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-CONTROL-GIVE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-EXPEDITED-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-P-EXCEPTION-REPORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-U-EXCEPTION-REPORT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-RESYNCHRONIZE confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-RESYNCHRONIZE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-SYNC-MAJOR confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-SYNC-MAJOR indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-SYNC-MINOR confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-SYNC-MINOR indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-TOKEN-GIVE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–3
2–5
2–7
2–9
2–12
2–13
2–14
2–15
2–16
2–17
2–18
2–19
2–20
2–21
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

P-TOKEN-PLEASE indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P-TYPED-DATA indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REDIRECT indication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–38
2–39
2–40

3 ROSE Routines
3.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.3
3.4

Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_mem_descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_rose_pb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_status_block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ROSE Routine Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_reject_u . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_ro_decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3–1
3–1
3–1
3–1
3–2
3–2
3–2
3–2
3–2
3–4
3–5
3–8
3–11
3–14
3–17

4 Trace Emitter Routines
osak_trace_dcs_verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_trace_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_trace_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_trace_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_trace_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4–2
4–4
4–5
4–7
4–9

5 How OSAK Calls Map to Protocol Messages
6 Checking OSAK Status Codes
6.1
6.2
6.3

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

6–2
6–2
6–3

7 Disruptive Events
7.1
7.2
7.3
7.4
7.5
7.6
7.7
7.8

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

7–1
7–1
7–2
7–2
7–2
7–2
7–2
7–2

8 Parameter Passing Mechanisms
9 How the OSAK Interface Implements the ISO Standards
9.1
9.2

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

9–1
9–2

10 Possible Values for OSAK Data Types
10.1
10.2
10.3
10.4
10.5
10.5.1
10.5.2
10.6
10.7
10.8
10.9
10.9.1
10.9.2
10.9.3
10.9.4
10.10
10.11
10.12
10.13
10.14
10.15
10.16

Data Type: osak_abort_ppdu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_abort_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_action_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_activity_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_exception_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exception Originating from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exception Originating from Presentation Provider . . . . . . . . . . . . . . .
Field: pm_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field: reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_pdefault_context_res . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_reject_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rejection Originating from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rejection Originating from ACSE Provider . . . . . . . . . . . . . . . . . . . . .
Rejection Originating from Presentation Provider . . . . . . . . . . . . . . . .
Rejection Originating from Session Provider . . . . . . . . . . . . . . . . . . . .
Data type: osak_release_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_release_resp_reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field: request_mask and returned mask . . . . . . . . . . . . . . . . . . . . . . . . . .
Field: result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data type: osak_resync_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Fields: data, sync_minor, major_activity and release . . . . . . . . . . . . . . . . .
Field: type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10–1
10–2
10–2
10–3
10–3
10–3
10–3
10–3
10–4
10–4
10–4
10–4
10–5
10–5
10–6
10–6
10–6
10–6
10–7
10–7
10–7
10–7

A Reporting Problems
B OSAKserver (OpenVMS Systems Only)
B.1
B.2
B.3
B.4
B.5
B.6
B.6.1
B.6.2

Index

Active and Passive Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What OSAKserver Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OSAK Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NCL and the OSAK Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting OSAKserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering Active and Passive Addresses . . . . . . . . . . . . . . . . . . . . . . . . .
Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B–1
B–3
B–3
B–3
B–3
B–3
B–4
B–4

Figures
B–1

OSAKserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B–2

OSAK API Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_associate_req: Default Protocol Version Numbers . . . . . . . . . . . .
OSAK Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
osak_open_responder: Default Protocol Version Numbers . . . . . . . . . .
osak_redirect: Default Protocol Version Numbers . . . . . . . . . . . . . . . .
Definitions of Request-Event Mask and Returned-Event Mask . . . . . .
A-ASSOCIATE indication: Default Protocol Version Numbers . . . . . . .
REDIRECT indication: Default Protocol Version Numbers . . . . . . . . .
Sequence of Calls After the Arrival of a REDIRECT Indication . . . . . .
Problem Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mappings Between OSAK Routines and Protocol Messages . . . . . . . . .
Parameter Passing Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapping Between NCL and OSAK . . . . . . . . . . . . . . . . . . . . . . . . . . .

1–1
1–46
1–68
1–87
1–91
1–109
2–10
2–41
2–43
3–15
5–1
8–1
B–3

Tables
1–1
1–2
1–3
1–4
1–5
1–6
2–1
2–2
2–3
3–1
5–1
8–1
B–1

vii

Preface
This book contains reference material that you need when using the OSI
Applications Kernel (OSAK) interface to create Open Systems Interconnection
(OSI) applications on any supported operating system. Use this book with
DECnet-Plus 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 interface, you should ensure that you:
•

Have installed DECnet-Plus and the OSAK interface
The DECnet-Plus for OpenVMS Applications Installation and Advanced
Configuration guide explains how to install DECnet-Plus and the OSAK
interfaces.

•

Have DECnet-Plus OSAK Programming available.

•

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) assume 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

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 DECnet-Plus for OpenVMS systems.

Digital
UNIX

♦

Indicates information that applies both to DECnet/OSI for Digital UNIX
and to ULTRIX operating systems. Note that the main text of the book
sometimes gives differing information about support in the OSAK
software for these operating systems; but this icon always denotes a
difference that applies to both Digital UNIX and ULTRIX systems.
Indicates the end of platform-specific information

Abbreviations
The following abbreviations are used in this book:
ACSE

Association Control Service Element

APDU

application protocol data unit

ASN.1

Abstract Syntax Notation One

BER

basic encoding rules

CLNS

Connectionless-Mode Network Service

CONS

Connection-Oriented Network Service

DCS

defined context set

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

ROSE

Remote Operations Service Element

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 Routines
This chapter contains the following information about the OSAK interface:
•

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 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 OSAK interface are:
•

osak_api.h

•

osak_api_codes.h

•

osak_api_messages.h

Their locations differ according to the operating system:
OpenVMS

SYS$COMMON:[SYSLIB]

ULTRIX

/usr/include

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 API Parameters
Parameter

Brief Description

Data Type

abort_ppdu

Presentation provider
abort identifier

osak_abort_ppdu

(continued on next page)

OSAK Routines 1–1

Table 1–1 (Cont.) OSAK API Parameters
Parameter
abort_reason

Brief Description
1

Data Type

Reason for abort

osak_abort_reason

acontext

Application context
name

Address (osak_mem_descriptor)

acse_pci_eoc

End of contents count
(ACSE)

Unsigned long integer

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_version

OSAK API version to be
used

Unsigned long integer

called_aei

Responder application
entity invocation

Address (osak_aei)

calling_aei

Initiator application
entity 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

local_aei

Application-entity
invocation of the calling
process

Address (osak_aei)

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

(continued on next page)

1–2 OSAK Routines

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

Brief Description

Data Type

local_data

Buffers holding
redirected local user
data

Address (osak_mem_descriptor)

more_flag

Data segmentation flag

Long integer

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

pcontext_list

Proposed DCS

Address (osak_pcontext_proposal)

pcontext_del_list

Proposed deletions from
DCS

Address (osak_pcontext_deletion)

pcontext_id_list

Presentation context
identifiers and
associated transfer
syntaxes

Address (osak_pcontext_id)

pcontext_del_res_list

Response to proposed
deletions from DCS

Address (osak_pcontext_deletion_
result)

pcontext_redirect_list

DCS on redirected
association

Address (osak_pcontext)

pcontext_res_list

Response to proposed
DCS

Address (osak_pcontext_proposal_
result)

pdefault_context

Proposed default
presentation context

Address (osak_default_context)

pdefault_context_res

Response to proposed
default presentation
context

Address (osak_default_context_
result)

peer_data

User data (inbound)

Address (osak_buffer)

port_id

Port identifier

osak_port

pres_pci_eoc

End of contents count
(presentation)

Unsigned long integer

process_id

Process identifier

Address (osak_process_id)

process_name

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_reason

Reason for rejecting
connection request

osak_reject_reason

release_reason

Reason for releasing
association

osak_release_reason

(continued on next page)

OSAK Routines 1–3

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

Brief Description

Data Type

release_resp_reason

Reason for rejecting
release request

osak_release_resp_reason

request_tokens

Tokens requested from
peer entity

Address (osak_token_setting)

responding_aei

Responding application
entity 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)

user_context

Space for applications to
store local information

Address

user_data

User data (outbound)

Address (osak_buffer)

workspace2

Parameter block
workspace

None

ws_length

Length of workspace

Unsigned long integer

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

1–4 OSAK Routines

1.3 Data Type Definitions
This section describes the data types specific to the OSAK interface. 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_ppdu
Unsigned long integer
osak_abort_reason
Unsigned long integer
osak_acse_version
Field

Brief Description

Data Type

version1

ACSE version 1

Bit field mask

osak_action_result
Unsigned long integer
osak_activity_reason
Unsigned long integer
osak_aei
Field

Brief Description

Data Type

paddress

Presentation address

osak_paddress (see osak_
paddress)

aetitle

Application-entity title

osak_aetitle (see osak_
aetitle)

aeiid

Application-entity invocation identifier

osak_aeiid (see osak_aeiid)

Field

Brief Description

Data Type

apiid

Application-process invocation identifier,
a TLV encoding of an ASN.1 integer

osak_mem_descriptor

aeiid

Application-entity invocation identifier,
an ASN.1 integer TLV

osak_mem_descriptor

Field

Brief Description

Data Type

aptitle

Application-process title, an ASN.1 object
identifier TLV or an encoded RDN

osak_mem_descriptor

ae_qualifier

Application-entity qualifier, an ASN.1
integer TLV

osak_mem_descriptor

osak_aeiid

osak_aetitle

osak_api_version
Unsigned long integer

OSAK Routines 1–5

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 longword integer
osak_default_context
Field

Brief Description

Data Type

ts_name

An ASN.1 object identifier TLV
describing a transfer syntax

osak_mem_descriptor

as_name

An ASN.1 object identifier TLV

osak_mem_descriptor

osak_default_context_result
Unsigned long integer
osak_event
Unsigned long integer
osak_exception_reason
Unsigned long integer

1–6 OSAK Routines

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 1

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

context_
management

Context management functional unit
selector

Bit field mask

1 Supported on OpenVMS and Digital UNIX systems only.

osak_handle
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_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
(NSAP)

Address (osak_nsap)

Address

osak_mem_descriptor

type

A constant defining the network protocol

Long integer

OSAK Routines 1–7

osak_paddress
Field

Brief Description

Data Type

psel

Presentation selector

osak_mem_descriptor

ssel

Session selector

osak_mem_descriptor

tsel

Transport selector

osak_mem_descriptor

nsap

Network service access point

osak_nsap (see osak_nsap)

osak_parameter_block
See Section 1.2.
osak_pcontext
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext)

pcontext_id

An ASN.1 integer TLV describing a
presentation context identifier

osak_mem_descriptor

ts_name

An ASN.1 object identifier TLV
describing a transfer syntax name

osak_mem_descriptor

as_name

An ASN.1 object identifier TLV
describing an abstract syntax name

osak_mem_descriptor

osak_pcontext_deletion
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext_
deletion)

pcontext_id

An ASN.1 integer TLV describing a
presentation context identifier

osak_mem_descriptor

osak_pcontext_deletion_result
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext_deletion_result)

result

Response to proposal to delete
a presentation context from the
defined context set

Unsigned long integer

osak_pcontext_id
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext_id)

pcontext_id

An ASN.1 integer TLV
describing a presentation context
identifier

osak_mem_descriptor

ts_name

An ASN.1 object identifier TLV
describing a transfer syntax
name

osak_mem_descriptor

1–8 OSAK Routines

osak_pcontext_proposal
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext_proposal)

pcontext_id

An ASN.1 integer TLV

osak_mem_descriptor

ts_list

List of names of supported
transfer syntaxes

Address (osak_ts_list)

as_name

An ASN.1 object identifier TLV

osak_mem_descriptor

osak_pcontext_proposal_result
Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_pcontext_proposal_result)

ts_name

An ASN.1 object identifier TLV
describing a transfer syntax

osak_mem_descriptor

result

Response to proposal

Unsigned long integer

reason

Provider reason

Unsigned long integer

osak_port
Address (unsigned octet)
osak_protocol_versions
Field

Brief Description

Data Type

acse_version

ACSE versions proposed

osak_acse_version

pversion

Presentation versions proposed

osak_pversion

sversion

Session versions proposed

osak_sversion

osak_process_id
Unsigned long integer
osak_pversion
Field

Brief Description

Data Type

version1

Presentation version 1

Bit field mask

osak_reject_reason
Unsigned long integer
osak_release_reason
Unsigned long integer
osak_release_resp_reason
Unsigned long integer
osak_resync_type
Unsigned long integer
osak_rtn
Unsigned long integer (*osak_rtn)( )

OSAK Routines 1–9

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

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 association

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

1–10 OSAK Routines

osak_sync_point
Unsigned long integer
osak_transport_templates
Field

Brief Description

Data Type

Pointer to next template in list

Address (osak_template)

name

Name of transport template

osak_mem_descriptor

osak_time
Unsigned long integer
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

Field

Brief Description

Data Type

Pointer to next element in list

Address (osak_ts_list)

ts_name

A TLV for an ASN.1 object identifier
describing a transfer syntax

osak_mem_descriptor

osak_ts_list

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

OSAK Routines 1–11

1.4 Routine Descriptions
This section contains a description of each OSAK routine. Sections 1.4.1 and 1.4.2
describe the arguments and parameters common to all OSAK outbound services.

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 association on which this service call is being made. You should
specify the port in all the outbound service calls that you make on an association.
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 interface 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 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 interface 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 interface 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.
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 and ULTRIX systems).

1–12 OSAK Routines

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;
}
If the memory allocation routine fails to allocate memory, it should return a null
pointer.
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 interface 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 interface, the interface 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 osak_data_req or osak_typed_req, the OSAK interface 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.
You should supply a routine that meets the memory deallocation requirements of
your application. The OSAK interface uses this routine only for internal memory
management, not for returning inbound parameter values to your application.

OSAK Routines 1–13

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 interface always deallocates the same amount of memory as it allocated
using your allocation routine. Your deallocation routine can ignore the size
parameter if it does not need the number of octets of memory.
The ptr parameter is a pointer to the memory to be deallocated.
The possible return values of dealloc_rtn are:
•

Zero, indicating success

•

Any other number, indicating failure

If the call to the deallocation routine fails, the OSAK interface 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);
}
func
In this parameter, the OSAK interface returns a code identifying the service you
are calling.

1–14 OSAK Routines

more_flag
If you are sending segmented user data, use this parameter to indicate whether
there is more user data to follow. Send any further user data on a call or calls to
osak_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 interface 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
interface. 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 interface returns a status code in
this parameter. If the result is OSAK_S_TRANSERR, the OSAK interface also
returns a transport provider status code. Chapter 6 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 an association.
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 interface as OSAK_C_MINIMUM_WS.

OSAK Routines 1–15

osak_abort_req

osak_abort_req
Aborts an association.

Syntax
status = osak_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

abort_reason

osak_abort_reason

read only

[abort_ppdu]

Unsigned long integer

read only

[pcontext_id_list]

osak_pcontext_id

read only

[user_data]

osak_buffer

read only

[user_context]

Address

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
osak_abort_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameters Used
abort_reason
Specifies the reason the association is being aborted. If the reason you specify
is OSAK_C_PP_ABORT_INVALID_VALUE, indicating that an incoming event
contains an invalid presentation protocol data unit (PDU) parameter value, you
should also specify the abort_ppdu parameter.
If you specify provider abort in the abort_reason parameter, the OSAK interface
ignores all the parameters in the parameter block except for the abort_ppdu
parameter. Section 10.2 gives the possible values this parameter can have.

1–16 OSAK Routines

osak_abort_req

abort_ppdu
Specifies the identifier of an incoming event that is the cause of a provider abort
because it contains an invalid presentation PDU parameter value. Section 10.1
gives the possible values this parameter can have.
You need to specify this parameter only if the value in the abort_reason parameter
is OSAK_C_PP_ABORT_INVALID_VALUE.
pcontext_id_list
The address of the head of a linked list of structures, each one specifying a
presentation context identifier and the identifier of its associated transfer syntax.
The list should include the presentation context for ACSE and any presentation
contexts for which there is user data encoded in the user_data parameter.
This parameter must only be used (and is mandatory) if both the following
conditions are true:
•

The abort is an ACSE user abort

•

Session version 2 is being used

user_data
You should use this parameter only if the following two conditions are true:
•

The abort is an ACSE user abort

•

Session version 2 is being used

Description
The abort_reason parameter indicates whether the abort originates from the
provider or the user of the service. If the abort is a user abort and you want to
send user data on the call, you can segment the user data between the call to
osak_abort_req and calls to osak_send_more.

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_INVPCTXT
OSAK_S_INVPORT
OSAK_S_INVREASON
OSAK_S_OVERFLOW
OSAK_S_TRANSERR

OSAK Routines 1–17

osak_abort_req

See Also
osak_close_port
osak_release_req

1–18 OSAK Routines

osak_accept_rsp

osak_accept_rsp
Accepts an association attempt.

Syntax
status = osak_accept_rsp (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

[acontext]

osak_mem_descriptor

read only

[responding_aei]

osak_aei

read only

[sconnect_id]

osak_sconnect_id

read only

[segmentation]

osak_segmentation

read only

[initial_serial_number]

osak_sync_point

read only

[initial_tokens]

osak_token_setting

read only

[request_tokens]

osak_token_setting

read only

[functional_units]

osak_fus

read only

pcontext_res_list

osak_pcontext_proposal_result

read only

[user_data]

osak_buffer

read only

[user_context]

Address

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
osak_accept_rsp (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameters Used
acontext
The address of a structure you can use to specify the address of an ASN.1 object
identifier TLV for the application context name. If you do not assign a value to

OSAK Routines 1–19

osak_accept_rsp

this parameter, the OSAK interface supplies the value that was received in the
A-ASSOCIATE indication to which this call is a response.
responding_aei
The address of a structure you can use to specify the title of the responding
application entity. See Section 1.3 for a description of the data type.
You can set any of the fields of any of the substructures to null, though you
should not change the transport selector. The nsap field is ignored in this routine.
The session selector should be no longer than 16 octets.
sconnect_id
The address of a structure containing three substructures, each one specifying a
session connection reference parameter:
•

ss_user_ref—maximum size 64 octets

•

common_ref—maximum size 64 octets

•

add_ref_info—maximum size 4 octets

If you omit this parameter or make any of the fields null, the OSAK interface
does not send the associated session reference parameters.
segmentation
The address of a structure you can use to specify in which direction data should
be segmented. The structure contains two fields:
•

init_resp

•

resp_init

A value other than zero in the init_resp field indicates that segmentation is to be
used on data passing from the initiator to the responder. The value specifies the
maximum TSDU size.
A value other than zero in the resp_init field indicates that segmentation is to be
used on data passing from the responder to the initiator. The value specifies the
maximum TSDU size.
The maximum value allowed in either field is 65,535. The value may not be
greater than that proposed by the initiator.
You can use segmentation in both directions, in only one direction, or in neither
direction. If this parameter is not specified, OSAK accepts whatever the initiator
proposes.
initial_serial_number
The address of the serial number of the initial synchronization point on the
association.
You can assign a value to this parameter if both the following conditions are true:
•

The major synchronize, the minor synchronize, or the resynchronize
functional unit is selected.

•

The activity management functional unit is not selected.

If you do not assign a value to this parameter, the OSAK interface supplies the
value that was received in the A-ASSOCIATE indication to which this call is a
response.

1–20 OSAK Routines

osak_accept_rsp

initial_tokens
The address of a structure you can use to specify the initial token settings for the
association.
If the A-ASSOCIATE indication does not specify that the responder should choose
the token setting, the values in the structure should be the same as those in the
A-ASSOCIATE indication. If you specify different values, the OSAK interface
aborts the association.
If you make this parameter null when the A-ASSOCIATE indication specifies that
the responder should choose the token setting, the OSAK interface gives all the
available tokens to the initiator. The available tokens are those tokens of which
the corresponding functional units are selected in the A-ASSOCIATE indication.
Section 10.15 gives the possible values this parameter can have.
request_tokens
The address of a structure you can use to specify the tokens that the responder
requires from the initiator. The OSAK interface ignores this parameter if no
tokens are in use.
functional_units
The address of a structure you can use to specify the functional units required
at the ACSE, presentation, and session levels. If you use this parameter, you
should specify functional units for all levels. If you omit this parameter, the
OSAK interface uses the functional units selected in the event A-ASSOCIATE
indication.
To specify data separation, select the data separation and minor synchronize
functional units, and do not select the activity management functional unit.
The OSAK interface returns OSAK_S_INVFUS if you do not specify the correct
combination of functional units.
pcontext_res_list
The address of the head of a linked list of structures, each one of which gives the
response to one proposed presentation context.
This parameter is mandatory because a presentation context for the ACSE
abstract syntax should always be proposed on an A-ASSOCIATE request, and
should always be accepted on the corresponding A-ASSOCIATE-accept response.
Section 10.13 gives the possible values the parameter can have.
In the linked list, the following rules apply:
•

The next field can contain the value zero, indicating the end of the list

•

The ts_name should contain one of the transfer syntax names proposed for
this abstract syntax. This field is only necessary if you accept the abstract
syntax.

•

The result field specifies whether you accept or reject the transfer syntax.
Section 10.13 gives the possible values the parameter can have.

•

The field specifying the reason for rejecting an abstract syntax is ignored if
the result field is not a provider reject. Section 10.7 gives the possible values
the parameter can have.

OSAK Routines 1–21

osak_accept_rsp

Description
Call this routine after receiving an A-ASSOCIATE indication to accept the
association request.

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_INVFUS
OSAK_S_INVPCTXT
OSAK_S_INVPORT
OSAK_S_INVSYNCPNT
OSAK_S_INVTOKEN
OSAK_S_NOSYNCPNT
OSAK_S_OVERFLOW
OSAK_S_TRANSERR

See Also
osak_associate_req
osak_open_responder
osak_reject_rsp

1–22 OSAK Routines

The OSAK interface has queued the request and
there are free parameter blocks.
The routine has finished without error.
The OSAK interface has queued the request.
There is an invalid parameter.
A disruptive event has occurred.
There is not enough dynamic memory.
The call is invalid.
The functional units are invalid.
The presentation context list is invalid.
The port identifier is invalid.
The synchronization point serial number is
invalid.
The token setting is invalid.
The synchronization point serial number is
missing.
Too much user data has been sent for session
version 1.
There is an error in the transport provider.

osak_act_discard_req

osak_act_discard_req
Terminates an activity and cancels its effects.

Syntax
status = osak_act_discard_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

[activity_reason]

osak_activity_reason

read only

[user_data]

osak_buffer

read only

[user_context]

Address

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
osak_act_discard_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameter Used
activity_reason
The address of a value specifying the reason for discarding the activity. If you
make the address null, no reason is specified. Section 10.4 gives the possible
values this parameter can have.

Description
You can use this service only if the activity management functional unit is
selected.
If you are using session version 1, there is no user data on this service and
therefore no segmentation is allowed and the more_flag parameter must be set to
false.

OSAK Routines 1–23

osak_act_discard_req

See Also
osak_act_end_req
osak_act_discard_rsp

1–24 OSAK Routines

osak_act_discard_rsp

osak_act_discard_rsp
Responds to a request to discard an activity.

Syntax
status = osak_act_discard_rsp (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

[user_context]

Address

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
osak_act_discard_rsp (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameter Used
token_item
The address of a structure you can use to specify the tokens that the accepter
wants from the requester. 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.

OSAK Routines 1–25

osak_act_discard_rsp

Description
You can use this service only if the activity management functional unit is
selected.
Call the routine after receiving a P-ACTIVITY-DISCARD indication.
If you are using session version 1, there is no user data on this service and
therefore no segmentation is allowed and the more_flag parameter must be set to
false.

See Also
osak_resync_req

1–106 OSAK Routines

The call is invalid.
The presentation context list is invalid.
The port identifier is invalid.
The synchronization point serial number is
invalid.
The token setting is invalid.
Too much user data has been sent for session
version 1.
There is an error in the transport provider.

osak_select

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

Syntax
status = osak_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
osak_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 interface to notify you. The array has three fields:
•

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

•

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

•

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

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

An OSI association. The osak_open_initiator, osak_open_redirect and
osak_open_responder calls return the identifier of the association in the port
parameter.

•

An identifier specific to the operating system. The identifier refers to the
source on which the OSAK interface makes selections. On OpenVMS systems,
the source is a port or an event flag number (EFN). On Digital UNIX and
ULTRIX 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 interface 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 argument is 1 day (86,400 seconds). If you

OSAK Routines 1–107

osak_select

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

Set this argument to null.

•

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

Description
The routine examines the ports listed in the port_list argument 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 argument or when the time_out argument expires.
Digital
UNIX

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

OpenVMS

You can pass an event flag number (EFN) to osak_select as a port
identifier. If you do this, you should use an EFN from cluster 1.
The OSAK interface 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 interface 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 parameter. When an inbound event arrives, the OSAK interface returns
OSAK_S_NORMAL.
If you want the OSAK interface to notify you when an outbound event completes,
set the write bit in the returned_event_mask field of the port_list parameter.
When an outbound event completes, the OSAK interface returns OSAK_S_
NORMAL.

1–108 OSAK Routines

osak_select

Table 1–6 shows the meanings of values in the 2-bit masks.
Table 1–6 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 interface to wait for an event
to arrive. If no event arrives within that time, the OSAK interface returns the
status OSAK_S_NOEVENT and clears the returned-event bit mask. If an event
arrives, the OSAK interface 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 is specified in the
port_list argument.
The port identifier is invalid.
There is an error in the transport provider.

See Also
osak_get_event
osak_give_buffers

OSAK Routines 1–109

osak_send_more

osak_send_more
Sends a further segment of user data.

Syntax
status = osak_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

[user_context]

Address

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
osak_send_more (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Description
The OSAK interface allows you to segment the user data you are sending on any
service. Call osak_send_more as many times as necessary to send user data to
complete a service. The completion of each call to osak_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 the original service call. If you set the
more_flag parameter to true on the original service call, you can send all the user
data on calls to osak_send_more.

1–110 OSAK Routines

osak_send_more

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

The OSAK interface has queued the request and
there are free parameter blocks.
The OSAK interface 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 for session
version 1.
There is an error in the transport provider.

OSAK Routines 1–111

osak_token_give_req

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

Syntax
status = osak_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

[user_context]

Address

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
osak_token_give_req (port, parameter_block,)
osak_port port;
struct osak_parameter_block *parameter_block;

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.

1–112 OSAK Routines

osak_token_give_req

Description
If you are using session version 1, there is no user data on this service and
therefore no segmentation is allowed and the more_flag parameter must be set to
false.

See Also
osak_control_give_req
osak_token_please_req

OSAK Routines 1–113

osak_token_please_req

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

Syntax
status = osak_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

[user_context]

Address

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
osak_token_please_req (port, parameter_block)
osak_port port;
struct osak_parameter_block *parameter_block;

Parameter 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.

1–114 OSAK Routines

osak_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
osak_control_give_req
osak_token_give_req

OSAK Routines 1–115

osak_typed_req

osak_typed_req
Transfers typed data over an association.

Syntax
status = osak_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

[user_context]

Address

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
osak_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. At least one byte of data must be sent if
the more_flag parameter is set to false.

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

1–116 OSAK Routines

The OSAK interface has queued the request and
there are free parameter blocks.
The routine has finished without error.
The OSAK interface has queued the request.

osak_typed_req

OSAK_S_BADPARAM
OSAK_S_DISRUPTED
OSAK_S_INSFMEM
OSAK_S_INVFUNC
OSAK_S_INVPORT
OSAK_S_TRANSERR

There is an invalid parameter.
A disruptive event has occurred.
There is not enough dynamic memory.
The call is invalid.
The port identifier is invalid.
There is an error in the transport provider.

OSAK Routines 1–117

2
OSAK Events
This chapter lists the OSAK events in alphabetical order. Refer to the description
of the osak_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:
acse_pci_eoc
Indicates how many end-of-contents octets there should be in the data arriving
from the remote peer entity to meet the requirements of the ACSE PCI encoding.
To arrive at the value, the OSAK interface counts the number of indefinite length
encodings in the ACSE PCI for which it cannot find end-of-contents octets. You
should look for this number of end-of-contents octets in the ACSE PCI. If you do
not find this number, you should issue a presentation provider abort.
An end-of-contents octet consists of two zero octets.
event_type
The type of the event that osak_get_event receives. Table 1–3 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.
For a user abort, the peer_data parameter points to the start of the user
information in the incoming protocol data unit (PDU). This parameter is not
used for a redirect indication.
pres_pci_eoc
Indicates how many end-of-contents octets there should be in the data arriving
from the remote peer entity to meet the requirements of the presentation PCI
encoding.
To arrive at the value, the OSAK interface counts the number of indefinite length
encodings in the presentation PCI for which it cannot find end-of-contents octets.
You should look for this number of end-of-contents octets in the presentation PCI.
If you do not find this number, you should issue a provider abort.
An end-of-contents octet consists of two zero octets.

OSAK Events 2–1

The acse_pci_eoc and pres_pci_eoc parameters are cumulative. You must check for
a number of end-of-context octets equal to the sum of acse_pci_eoc and pres_pci_
eoc.
status_block
When osak_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 osak_give_buffers.
To free the buffers when they are returned by osak_get_event, you should follow
the tsdu_ptr pointer, not the peer_data pointer.

2–2 OSAK Events

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

[abort_ppdu]

osak_abort_ppdu

[pcontext_id_list]

osak_pcontext_id

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

local_abort

Long integer

Parameters Returned
abort_reason
This parameter explains why the association in being aborted. Section 10.2 lists
the possible values.
abort_ppdu
If the value in the abort_reason parameter is OSAK_C_PP_ABORT_INVALID_
VALUE, OSAK_C_PP_ABORT_UNREC_PARAM, or OSAK_C_PP_ABORT_
UNEXP_PARAM, indicating a presentation provider abort, the OSAK interface
uses this parameter to return the identifier of the event that contained an invalid
value.
pcontext_id_list
The address of the head of a linked list of structures, each one specifying one
presentation context (a presentation context identifier and its associated transfer
syntax) for which there is user data encoded in the user data parameter.
This parameter is null if the event is a presentation provider abort.
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:

OSAK Events 2–3

ABORT indication

•

The remote peer entity issues a call to osak_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 association. You should delete all
the data structures for the association.
If this is an ACSE user abort, your application should make multiple calls to

osak_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.

2–4 OSAK Events

A-ASSOCIATE-ACCEPT confirm

A-ASSOCIATE-ACCEPT confirm
An application entity receives this event when the remote peer entity calls
osak_accept_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

acontext

osak_mem_descriptor

[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

pcontext_res_list

osak_pcontext_proposal_result

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
acontext
The address of an encoded object identifier representing the application context
name.
responding_aei
The address of information about the application entity that is responding to a
request to set up an association. 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 versions in use on the association.
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

OSAK Events 2–5

A-ASSOCIATE-ACCEPT confirm

•

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 association.
If the incoming data units do not contain a value for the initial synchronization
point serial number, the OSAK interface returns a null address.
initial_tokens
The address of a structure indicating the initial token settings for the association.
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 token identifiers 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
association. 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 an association.
It means that the association has been established and you can start transferring
data.

2–6 OSAK Events

A-ASSOCIATE-REJECT confirm

A-ASSOCIATE-REJECT confirm
An application entity receives this event when the remote peer entity calls
osak_reject_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

reject_reason

osak_reject_reason

acontext

osak_mem_descriptor

[responding_aei]

osak_aei

[sconnect_id]

osak_sconnect_id

[functional_units]

osak_fus

[pcontext_res_list]

osak_pcontext_proposal_result

[pdefault_context_res]

osak_default_context_result

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
reject_reason
This parameter explains why the association request is being rejected.
Section 10.9 lists the values this parameter may have.
If the value returned indicates that the rejection is due to temporary congestion,
the initiator can try again to establish an association.
acontext
The address of an encoded object identifier representing the application context
name.
responding_aei
The address of information about the application entity that is responding to a
request to set up an association. The information may include the selectors, the
application-entity title, and the application-entity identifier.
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 presentation and session functional units. If the incoming
data units do not include these values, the OSAK interface returns the default
values:

OSAK Events 2–7

A-ASSOCIATE-REJECT confirm

•

Half-duplex functional unit

•

Minor synchronize functional unit

•

Activity functional unit

•

Capability functional unit

•

Exceptions functional unit

pcontext_res_list
The address of the head of a linked list of structures, each of which gives the
response to the corresponding context proposed in the A-ASSOCIATE request. If
the response is acceptance, the OSAK interface returns, in the ts_name field of
this parameter, the ASN.1 encoding for the identifier of the transfer syntax being
used. Section 10.13 lists the values that the fields of this parameter may have.
pdefault_context_res
The address of the response to the proposed default context for this association.
If incoming data units do not include the response, the OSAK interface returns a
null address.

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

2–8 OSAK Events

A-ASSOCIATE indication

A-ASSOCIATE indication
An application entity receives this event when the remote peer entity calls
osak_associate_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

acontext

osak_mem_descriptor

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

pcontext_list

osak_pcontext_proposal

[pdefault_context]

osak_default_context

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
acontext
The address of an encoded object identifier representing the application context
name.
called_aei
The address of information about the called application entity. The information
may include the selectors, the application-entity title, and the application-entity
identifier. If the incoming data units do not include this information, the OSAK
interface returns a null address.
calling_aei
The address of information about the calling application entity. The information
may include the selectors, the application-entity title, and the application-entity
identifier. 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
association. If the incoming data units do not specify any proposed protocol

OSAK Events 2–9

A-ASSOCIATE indication

version identifiers, the OSAK interface returns default values. Table 2–1 shows
the default versions.
Table 2–1 A-ASSOCIATE indication: Default Protocol Version Numbers
Protocol

Possible Version Numbers

ACSE
Presentation
Session

1
1
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

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 association.
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 association. 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 presentation and session functional units accepted for this
association. 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

pcontext_list
The address of the head of a linked list of structures, each of which contains the
following information about one of the presentation contexts that the initiator is
proposing:

2–10 OSAK Events

A-ASSOCIATE indication

•

The presentation context identifier

•

A reference to the head of a linked list of transfer syntax names

•

The abstract syntax name

pdefault_context
The address of the names of the transfer syntax and the abstract syntax that
make up the default context proposed for this association. If the incoming data
units do not specify any default context, the OSAK interface returns a null
address.

Description
This event indicates a request to establish an association. Accept the
association request by calling osak_accept_rsp; reject the association by calling
osak_reject_rsp.

OSAK Events 2–11

A-RELEASE confirm

A-RELEASE confirm
An application entity receives this event when the remote peer entity calls
osak_release_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

action_result

osak_action_result

[release_resp_reason]

osak_release_resp_reason

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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.
release_resp_reason
The reason for rejection of the release request. Section 10.11 lists the values this
parameter may have.

Description
This event responds to a request to terminate an association. By the time the
event arrives, the association has been terminated. To reclaim parameter blocks
and user buffers that were used on the association, you can call osak_close_port,
or use a completion routine (OpenVMS systems only).

2–12 OSAK Events

A-RELEASE indication

A-RELEASE indication
An application entity receives this event when the remote peer entity calls
osak_release_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

release_reason

osak_release_reason

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
release_reason
A value indicating the reason for releasing the association. If the incoming data
units do not include a value for this parameter, the OSAK interface returns the
value zero, which indicates a normal release. Section 10.10 lists the values this
parameter may have.

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

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

osak_release_rsp to accept the release request.
•

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

osak_release_rsp to accept or reject the release request.

OSAK Events 2–13

P-ACTIVITY-DISCARD confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

2–14 OSAK Events

P-ACTIVITY-DISCARD indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

reason

osak_activity_reason

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 10.4 lists the values this parameter may have.

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

osak_act_discard_rsp.

OSAK Events 2–15

P-ACTIVITY-END confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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–16 OSAK Events

P-ACTIVITY-END indication

P-ACTIVITY-END indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 osak_act_end_rsp.

OSAK Events 2–17

P-ACTIVITY-INTERRUPT confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

2–18 OSAK Events

P-ACTIVITY-INTERRUPT indication

P-ACTIVITY-INTERRUPT indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 10.4 lists the values this parameter may have.

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

OSAK Events 2–19

P-ACTIVITY-RESUME indication

P-ACTIVITY-RESUME indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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–20 OSAK Events

P-ACTIVITY-START indication

P-ACTIVITY-START indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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–21

P-ALTER-CONTEXT confirm

P-ALTER-CONTEXT confirm
An application entity receives this event when the remote peer entity calls
osak_alter_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[pcontext_res_list]

osak_pcontext_proposal_result

[pcontext_del_res_list]

osak_pcontext_deletion_result

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
pcontext_res_list
The address of the head of a linked list of structures, each of which gives the
response to the corresponding context proposed in the P-ALTER-CONTEXT
request. If the response is acceptance, the OSAK interface returns, in the ts_
name field of this parameter, the ASN.1 encoding for the identifier of the transfer
syntax being used. Section 10.13 lists the range of values that the fields of this
parameter may have.
pcontext_del_res_list
The address of the head of a linked list of structures, each of which gives the
response to the proposed deletion of a context from the DCS.

Description
This event gives the response to a proposed alteration in the DCS existing on an
association.

2–22 OSAK Events

P-ALTER-CONTEXT indication

P-ALTER-CONTEXT indication
An application entity receives this event when the remote peer entity calls
osak_alter_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[pcontext_list]

osak_pcontext_proposal

[pcontext_del_list]

osak_pcontext_deletion

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
pcontext_list
The address of the head of a linked list of structures, in each of which you can
find the following information about one of the presentation contexts proposed for
addition to the DCS:
•

The presentation context identifier

•

The address of the head of a linked list of transfer syntax names

•

The abstract syntax name

pcontext_del_list
The address of the head of a linked list of structures, in each of which you can
find the presentation context identifier of one presentation context proposed for
deletion from the DCS.

Description
This event indicates a proposed alteration in the DCS existing on an association.
Respond by calling osak_alter_rsp.

OSAK Events 2–23

P-CAPABILITY-DATA confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

2–24 OSAK Events

P-CAPABILITY-DATA indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

osak_capability_rsp.

OSAK Events 2–25

P-CONTROL-GIVE indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

2–26 OSAK Events

P-DATA indication

P-DATA indication
An application entity receives this event when the remote peer entity calls
osak_data_req.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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–27

P-EXPEDITED-DATA indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

2–28 OSAK Events

P-P-EXCEPTION-REPORT indication

P-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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
exception_reason
A value indicating the reason for the exception report. Section 10.5 lists the
values this parameter may have.

Description
This event indicates a user error has occurred that is not severe enough to cause
an association 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–29

P-U-EXCEPTION-REPORT indication

P-U-EXCEPTION-REPORT indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
exception_reason
A value indicating the reason for the exception report. Section 10.5 lists the
values this parameter may have.

Description
This event indicates an error has occurred that is not severe enough to cause
an association 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.

2–30 OSAK Events

P-RESYNCHRONIZE confirm

P-RESYNCHRONIZE confirm
An application entity receives this event when the remote peer entity calls
osak_resync_rsp.

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

[tokens]

osak_token_setting

[token_item]

osak_token_setting

[pcontext_id_list]

osak_pcontext_id

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the synchronization point serial number specified in the
resynchronization request.
tokens
The address of 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.
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.
pcontext_id_list
The address of the head of a linked list of structures, each one confirming one
presentation context in the DCS resulting from the resynchronization.

Description
This event confirms resynchronization from a specified synchronization point.

OSAK Events 2–31

P-RESYNCHRONIZE indication

P-RESYNCHRONIZE indication
An application entity receives this event when the remote peer entity calls
osak_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

[token_item]

osak_token_setting

[pcontext_id_list]

osak_pcontext_id

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
resync_type
A value indicating the type of resynchronization. Section 10.14 lists the values
this parameter may have.
sync_point
The address of the synchronization point serial number from which
resynchronization should start.
token_item
The address of a structure indicating the tokens that the remote application
entity is requesting. 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 10.15 lists the values this parameter may have.
pcontext_id_list
The address of the head of a linked list of structures, each one indicating one
presentation context in the DCS resulting from the resynchronization. If this
parameter is null and the context management functional unit is selected, the
DCS is empty after resynchronization. If the context management functional unit
is not selected, ignore this parameter.

Description
This event indicates that a request to resynchronize an association from a
specified synchronization point. Respond by calling osak_resync_rsp.

2–32 OSAK Events

P-SYNC-MAJOR confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

OSAK Events 2–33

P-SYNC-MAJOR indication

P-SYNC-MAJOR indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 osak_major_rsp.

2–34 OSAK Events

P-SYNC-MINOR confirm

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

sync_point

osak_sync_point

data_separation

osak_data_separation

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
sync_point
The address of the minor synchronization point serial number.
data_separation
Indicates whether data separation is required. The value is true if the remote
peer entity requires data separation.

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

OSAK Events 2–35

P-SYNC-MINOR indication

P-SYNC-MINOR indication
An application entity receives this event when the remote peer entity calls
osak_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

[data_separation]

osak_data_separation

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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.
data_separation
Indicates whether data separation is required. The value is true if the remote
peer entity requires data separation.

Description
This event indicates a request to set a minor synchronization point. You can
respond by calling osak_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.

2–36 OSAK Events

P-TOKEN-GIVE indication

P-TOKEN-GIVE indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 an association. The token_item parameter specifies which
tokens are being relinquished. No response is necessary because relinquishing
tokens is not a confirmed service.

OSAK Events 2–37

P-TOKEN-PLEASE indication

P-TOKEN-PLEASE indication
An application entity receives this event when the remote peer entity calls
osak_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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[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 association. The
token_item parameter specifies which tokens are being requested. No response to
the request is necessary because this is not a confirmed service.

2–38 OSAK Events

P-TYPED-DATA indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

[peer_data]

osak_buffer

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

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

OSAK Events 2–39

REDIRECT indication

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

Parameters Returned

Data Type

event_type

osak_event

status_block

osak_status_block

tsdu_ptr

osak_buffer

redirect_state

osak_state

[pcontext_list]

osak_pcontext

[pcontext_redirect_list]

osak_pcontext_proposal

[pdefault_context]

osak_default_context

[calling_aei]

osak_aei

[called_aei]

osak_aei

[acontext]

osak_mem_descriptor

[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

[acse_pci_eoc]

Unsigned long integer

[pres_pci_eoc]

Unsigned long integer

[more_flag]

Long integer

Parameters Returned
redirect_state
A structure defining the state of the association. The values in the structure
indicate whether the local entity is acting as an initiator of or a responder to the
redirection request.
pcontext_list
The address of a list of structures, each one of which is a member of the DCS
that existed when the association was originally set up. The OSAK interface
returns this parameter only if the process that redirects the association has not
established the association when it makes the request to redirect.
pcontext_redirect_list
The address of a list of structures, each one of which is a member of the DCS that
existed when the association was originally set up. The OSAK interface returns

2–40 OSAK Events

REDIRECT indication

this parameter only if the process that redirects the association has established
the association when it makes the request to redirect.
pdefault_context
The address of the presentation context identifier and the transfer syntax
identifier of the proposed or negotiated default context.
calling_aei
The address of a structure containing information about the calling application
entity. The information may include the selectors, the application-entity title, and
the application-entity identifier. 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 information about the called application
entity. The information may include the selectors, the application-entity title, and
the application-entity identifier. If the incoming data units do not include this
information, the OSAK interface returns a null address.
acontext
The address of an encoded object identifier representing the application context
name.
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 default values. Table 2–2
shows the default versions.
Table 2–2 REDIRECT indication: Default Protocol Version Numbers
Protocol

Possible Version Numbers

ACSE
Presentation
Session

1
1
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 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.

OSAK Events 2–41

REDIRECT indication

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 for the Session
and Presentation layers. 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 an association 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:
•

The state of the association when the requester called osak_redirect

•

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

The description of the routine osak_redirect in Chapter 1 describes the possible
states of an association. Table 2–3 shows the sequence of calls you should make
for each state. In this table, each state is represented by its constant value.
Section 10.6 lists the meanings of these constants.

2–42 OSAK Events

REDIRECT indication

Table 2–3 Sequence of Calls After the Arrival of a REDIRECT Indication
State

Sequence of Calls

OSAK_C_ASSOC_IND

Call osak_get_event to receive the
REDIRECT indication.
Call osak_accept_rsp or osak_reject_rsp
to accept or reject the REDIRECT
indication.
Make multiple calls to osak_get_event
to receive all the user data from the
REDIRECT indication.
Call osak_accept_rsp to accept or
osak_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–43

3
ROSE Routines
This chapter contains the following details about the ROSE interface:
•

A list of the include files for different operating systems (Section 3.1)

•

A description of each constructed data type used in the ROSE interface
(Section 3.2)

•

A description of the arguments common to all ROSE calls (Section 3.3)

•

A description of each ROSE routine (Section 3.4)

3.1 Include Files
The include files for the ROSE interface have the same name for each operating
system: osak_rose_codes.h. Their locations for the different operating systems
are:
OpenVMS

SYS$COMMON:[SYSLIB]

Digital UNIX

/usr/include/osi

ULTRIX

/usr/include

3.2 Data Type Definitions
This section describes the data types used in the ROSE interface.

3.2.1 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

3.2.2 osak_mem_descriptor
Field

Brief Description

Data Type

size

Length of buffer in octets

Unsigned long integer

pointer

Reference to buffer

Address (unsigned octet)

ROSE Routines 3–1

3.2.3 osak_ro_problem
Address (unsigned octet)

3.2.4 osak_ro_reason
Address (unsigned octet)

3.2.5 osak_rose_pb
Parameter

Description

Data Type

pb_length

Length of ROSE parameter block
including working space

Unsigned long integer

ws_length

Length of working space

Unsigned long integer

arg_length

Length of ROSE PDU that contains
error, result, or argument parameter
(user data)

Unsigned long integer

invoke_id

Address of ROSE invocation
identifier

osak_mem_descriptor

linked_id

Address of linked ROSE invocation
identifier

osak_mem_descriptor

local_value

Address locally defined operation or
error value

osak_mem_descriptor

global_value

Address of globally defined
operation or error value

osak_mem_descriptor

reason

Address of reject reason code

osak_ro_reason

problem

Address of problem code

osak_ro_problem

buffer

Address of buffer containing
outcome of a ROSE request

osak_buffer

pdu_type

Type of PDU being encoded or
decoded

Unsigned long integer

osak_rose_status

ROSE status code

osak_status_block

Field

Brief Description

Data Type

osak_status1

OSAK status code

Unsigned long integer

osak_status2

Secondary OSAK status code

Unsigned long integer

transport_status1

Generic transport provider status

Unsigned long integer

transport_status2

Specific transport provider status

Unsigned long integer

3.2.6 osak_status_block

3.3 Common Arguments
The port and rose_pb arguments are common to all the ROSE routines.
port
The identifier of the association over which you are making the ROSE call. You
need to supply this identifier so the ROSE interface can use your OSAK memory
allocation and deallocation routines if necessary. Refer to the description of the
buffer parameter for further information.

3–2 ROSE Routines

rose_pb
The address of a ROSE parameter block. A ROSE parameter block is a structure
that contains all possible parameters for all ROSE services. The ROSE interface
uses only the relevant parameters in each service call, ignoring the rest.
Section 3.2.5 describes the structure of a ROSE parameter block.

ROSE Routines 3–3

3.4 ROSE Routine Descriptions
This section contains a description of each ROSE routine.
Optional parameters are shown in square brackets ([ ]) in the Syntax section of
each description.

3–4 ROSE Routines

osak_ro_invoke

osak_ro_invoke
Encodes ROSE PCI that requests a remote peer entity to perform an operation.

Syntax
status = osak_ro_invoke (port, rose_pb)
Argument

Data Type

Access

port

osak_port

read only

rose_pb

osak_rose_pb

read only

Parameters

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

[arg_length]

Unsigned long integer

read only

pdu_type

Unsigned longword

read only

invoke_id

osak_mem_descriptor

read only

[linked_id]

osak_mem_descriptor

read only

local_value

osak_mem_descriptor

read only

global_value

osak_mem_descriptor

read only

[buffer]

osak_buffer

read only

[osak_rose_status]

osak_status_block

write only

C Binding
osak_ro_invoke(port, rose_pb)
osak_port port;
struct osak_rose_pb *rose_pb;

Parameters Used
pb_length
The length of the ROSE parameter block, including the length of the working
space.
ws_length
The length of the working space contained in the ROSE parameter block. The
length of the working space should be 8 octets.
arg_length
The length of a ROSE PDU containing an error, result, or argument parameter.
You pass the error, result, or argument as user data in the buffer parameter.
Set this parameter to zero if you are not sending an argument, result, or error
parameter.
The ROSE interface encodes the value of the arg_length parameter as part of the
ROSE PCI.

ROSE Routines 3–5

osak_ro_invoke

pdu_type
Specifies the type of APDU you are sending. Set this parameter to ROSE_C_
INVOKE.
The ROSE interface uses the value in this parameter to check that you have
included all the mandatory parameters for the routine you are calling.
invoke_id
The address of the identifier of this call to the Invoke function. You should assign
an Invoke identifier that distinguishes this instance of the Invoke function from
any other instance of the function.
When you call the Invoke function, you can reuse an Invoke identifier only if
you have received a response to the Invoke request that previously used that
identifier. If you have not received a response, you should not reuse the Invoke
identifier.
You should set the pointer field of this parameter to the address of an ASN.1
encoded integer (TLV), and the size field to the length of the encoding.
linked_id
The address of the identifier of some other instance of the Invoke function to
which you want this instance to be linked.
You should set the pointer field of this parameter to the address of an ASN.1
encoded integer (TLV), and the size field to the length of the encoding.
local_value
The address of a locally defined operation code.
Set the pointer field to the address of an ASN.1 encoded integer representing an
operation code and the size field to the length of the encoding.
Note
The local_value and global_value parameters are mutually exclusive.
If you use the local_value parameter, you should set the pointer field of
the global_value parameter to null and the size field to zero.

global_value
The address of a globally defined operation code.
Set the pointer field to the address of an ASN.1 encoded object identifier
representing an operation code and the size field to the length of the encoding.
Note
The parameters global_value and local_value are mutually exclusive.
If you use the global_value parameter, you should set the pointer field of
the local_value parameter to null and the size field to zero.

buffer
The address of a buffer structure you can use to pass user information required
by your application. This parameter is optional. You should set the parameter to
null if you are not passing a user buffer to the ROSE interface.

3–6 ROSE Routines

osak_ro_invoke

If you supply a user buffer, but the buffer is not big enough for the encoded ROSE
PCI, the ROSE interface uses your OSAK memory allocation routine to create a
new user buffer. The interface places the ROSE PCI in the new buffer and chains
it to the front of the buffer you supplied.
If you do not supply a user buffer, the ROSE interface uses your OSAK memory
allocation routine to create a new user buffer. The interface places the ROSE PCI
in the new buffer. The buffer_ptr and data_ptr parameters both point to the same
location.
The ROSE interface modifies your user buffer to accommodate the ROSE PCI.
Therefore, you should save a copy of any buffer you pass in this routine call,
unless you are certain you do not need to reference the unchanged buffer again.
osak_rose_status
Returns a status code specific to ROSE in the osak_status2 field.

Description
This routine encodes ROSE PCI that requests a remote peer entity to perform an
operation.
An instance of this routine is distinguished from all other instances by its Invoke
identifier.
You do not need to wait for the server to perform one operation before you request
another operation. You can request the server to perform an unlimited number of
operations at a given time, within the limits of the system resources available to
the server.

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

Routine has finished without error.
At least one mandatory parameter is missing.
There is not enough dynamic memory.
At least one parameter is incorrectly specified.

ROSE Routines 3–7

osak_ro_result

osak_ro_result
Encodes ROSE PCI that reports the success of a requested operation.

Syntax
status = osak_ro_result (port, rose_pb)
Argument

Data Type

Access

port

osak_port

read only

rose_pb

osak_rose_pb

read only

Parameters

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

[arg_length]

Unsigned long integer

read only

pdu_type

Unsigned longword

write only

invoke_id

osak_mem_descriptor

read only

local_value

osak_mem_descriptor

read only

global_value

osak_mem_descriptor

read only

[buffer]

osak_buffer

read only

[osak_rose_status]

osak_status_block

write only

C Binding
osak_ro_result(port, rose_pb)
osak_port port;
struct osak_rose_pb *rose_pb;

Parameters Used
pb_length
The length of the ROSE parameter block, including the length of the working
space.
ws_length
The length of the working space contained in the ROSE parameter block. The
length of the working space should be 8 octets.
arg_length
The length of a ROSE PDU containing an error, result, or argument parameter.
You pass the error, result, or argument as user data in the buffer parameter. The
ROSE interface encodes the value of the arg_length parameter as part of the
ROSE PCI. Set this parameter to zero if you are not sending an argument, result,
or error parameter.
pdu_type
Specifies the type of APDU that you are sending. Set this parameter to ROSE_C_
RESULT.

3–8 ROSE Routines

osak_ro_result

The ROSE interface uses the value in this parameter to check that you have
included all the mandatory parameters for the routine you are calling.
invoke_id
The Invoke identifier of the instance of the Invoke function to which you are
responding.
local_value
The address of a locally defined operation code.
Set the pointer field to the address of an ASN.1 encoded integer representing an
operation code and the size field to the length of the encoded integer.
Note
The local_value and global_value parameters are mutually exclusive.
If you use the local_value parameter, you should set the pointer field of
the global_value parameter to null and the size field to zero.

global_value
The address of a globally defined operation code.
Set the pointer field to the address of an ASN.1 encoded object identifier
representing an operation code and the size field to the length of the encoded
object identifier.
Note
The global_value and local_value parameters are mutually exclusive.
If you use the global_value parameter, you should set the pointer field of
the local_value parameter to null and the size field to zero.

buffer
The address of a buffer structure that you can use to pass user information
required by your application, for example, the results of the successful operation.
This parameter is optional. You should set the parameter to null if you are not
passing a user buffer to the ROSE interface.
If you supply a user buffer, but the buffer is not big enough for the encoded ROSE
PCI, the ROSE interface uses your OSAK memory allocation routine to create a
new user buffer. The interface places the ROSE PCI in the new buffer and chains
it to the front of the buffer you supplied.
If you do not supply a user buffer, the ROSE interface uses your OSAK memory
allocation routine to create a new user buffer. The interface places the ROSE PCI
in the new buffer. The buffer_ptr and data_ptr parameters both point to the same
location.
The ROSE interface modifies your user buffer to accommodate the ROSE PCI.
Therefore, you should save a copy of any buffer you pass in this routine call,
unless you are certain that you do not need to reference the unchanged buffer
again.
osak_rose_status
Returns a status code specific to ROSE in the osak_status2 field.
ROSE Routines 3–9

osak_ro_result

Description
This routine encodes ROSE PCI that reports the success of an operation to the
client that requested the operation.

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

3–10 ROSE Routines

Routine has finished without error.
At least one mandatory parameter is missing.
There is not enough dynamic memory.
At least one parameter is incorrectly specified.

osak_ro_error

osak_ro_error
Encodes ROSE PCI that reports the failure of a requested operation.

Syntax
status = osak_ro_error (port, rose_pb)
Argument

Data Type

Access

port

osak_port

read only

rose_pb

osak_rose_pb

read only

Parameters

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

[arg_length]

Unsigned long integer

read only

pdu_type

Unsigned longword

read only

invoke_id

osak_mem_descriptor

read only

local_value

osak_mem_descriptor

read only

global_value

osak_mem_descriptor

read only

[buffer]

osak_buffer

read only

[osak_rose_status]

osak_status_block

write only

C Binding
osak_ro_error(port, rose_pb)
osak_port port;
struct osak_rose_pb *rose_pb;

Parameters Used
pb_length
The length of the ROSE parameter block, including the length of the working
space.
ws_length
The length of the working space contained in the ROSE parameter block. The
length of the working space should be 8 octets.
arg_length
The length of a ROSE PDU containing an error, result, or argument parameter.
You pass the error, result, or argument as user data in the buffer parameter. The
ROSE interface encodes the value of the arg_length parameter as part of the
ROSE PCI. Set this parameter to zero if you are not sending an argument, result,
or error parameter.
pdu_type
Specifies the type of APDU that you are sending. Set this parameter to ROSE_C_
ERROR.

ROSE Routines 3–11

osak_ro_error

global_value
The address of a globally defined operation code.
Set the pointer field to the address of an ASN.1 encoded object identifier
representing an operation code and the size field to the length of the encoded
object identifier.
Note
The global_value and local_value parameters are mutually exclusive.
If you use the global_value parameter, you should set the pointer field of
the local_value parameter to null and the size field to zero.

buffer
The address of a buffer structure that you can use to pass user information
required by your application. For example, you can pass information explaining
why the requested operation was not successful. This parameter is optional. You
should set the parameter to null if you are not passing a user buffer to the ROSE
interface.
If you supply a user buffer, but the buffer is not big enough for the encoded ROSE
PCI, the ROSE interface uses your OSAK memory allocation routine to create a
new user buffer. The interface places the ROSE PCI in the new buffer and chains
it to the front of the buffer you supplied.
If you do not supply a user buffer, the ROSE interface uses your OSAK memory
allocation routine to create a new user buffer. The interface places the ROSE PCI
in the new buffer. The buffer_ptr and data_ptr parameters both point to the same
location.
The ROSE interface modifies your user buffer to accommodate the ROSE PCI.
Therefore, you should save a copy of any buffer you pass in this routine call,
unless you are certain that you do not need to reference the unchanged buffer
again.

3–12 ROSE Routines

osak_ro_error

osak_rose_status
Returns a status code specific to ROSE in the osak_status2 field.

Description
This routine encodes ROSE PCI that reports the failure of an operation to the
client that requested the operation.

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

Routine has finished without error.
At least one mandatory parameter is missing.
There is not enough dynamic memory.
At least one parameter is incorrectly specified.

ROSE Routines 3–13

osak_ro_reject_u

osak_ro_reject_u
Encodes ROSE PCI that rejects an operation request from a peer entity.

Syntax
status = osak_ro_reject (port, rose_pb)
Argument

Data Type

Access

port

osak_port

read only

rose_pb

osak_rose_pb

read only

Parameters

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

pdu_type

Unsigned longword

write only

invoke_id

osak_mem_descriptor

read only

reason

osak_ro_reason

read only

problem

osak_ro_problem

read only

[buffer]

osak_buffer

read only

[osak_rose_status]

osak_status_block

write only

C Binding
osak_ro_reject(port, rose_pb)
osak_port port;
struct osak_rose_pb *rose_pb;

Parameters Used
pb_length
The length of the ROSE parameter block, including the length of the working
space.
ws_length
The length of the working space contained in the ROSE parameter block. The
length of the working space should be 8 octets.
pdu_type
Specifies the type of APDU that you are sending. Set this parameter to ROSE_C_
REJECT.
The ROSE interface uses the value in this parameter to check that you have
included all the mandatory parameters for the routine you are calling.
invoke_id
The Invoke identifier of the instance of the Invoke function to which you are
responding.

3–14 ROSE Routines

osak_ro_reject_u

reason
The address of a reason code. Use this parameter to tell the client why you are
rejecting an APDU.
Use one of the following constants as the reason code. You can assign whatever
meaning you choose to these constants.
RORJ_C_INVOKE_PROB
RORJ_C_RET_RES_PROB
RORJ_C_RET_ERR_PROB
problem
The address of a problem code that tells the client more about why you are
rejecting the APDU.
For each reason code, there is a set of problem codes, shown in Table 3–1 . You
can assign whatever meaning you choose to these problem codes.
Table 3–1 Problem Codes
Reason Code

Corresponding Problem Codes

RORJ_C_INVOKE_PROB

RORJ_C_DUPLIC_INV
RORJ_C_UNREC_OPER
RORJ_C_MISTYPE_ARG
RORJ_C_RES_LIMIT
RORJ_C_INIT_REJ
RORJ_C_UNREC_LINK
RORJ_C_RESP_UNEXP
RORJ_C_UNEXP_CHILD_OPER
RORJ_C_UNREC_INV
RORJ_C_RES_RESP_UNEXP
RORJ_C_MISTYPE_RES
RORJ_C_UNREC_INV
RORJ_C_ERR_RESP_UNEXP
RORJ_C_UNREC_ERR
RORJ_C_UNEXP_ERR
RORJ_C_MISTYPE_PAR

RORJ_C_RET_RES_PROB

RORJ_C_RET_ERR_PROB

buffer
The address of a buffer structure you can use to pass user information required
by your application. You should set this parameter to null if you are not passing
a user buffer to the ROSE interface.
If you supply a user buffer, but the buffer is not big enough for the encoded ROSE
PCI, the ROSE interface uses your OSAK memory allocation routine to create a
new user buffer. The interface places the ROSE PCI in the new buffer and chains
it to the front of the buffer you supplied.
If you do not supply a user buffer, the ROSE interface uses your OSAK memory
allocation routine to create a new user buffer. The interface places the ROSE PCI
in the new buffer. The buffer_ptr and data_ptr parameters both point to the same
location.

ROSE Routines 3–15

osak_ro_reject_u

The ROSE interface modifies your user buffer to accommodate the ROSE PCI.
Therefore, you should save a copy of any buffer you pass in this routine call,
unless you are certain you do not need to reference the unchanged buffer again.
osak_rose_status
A status code specific to ROSE, returned in the osak_status2 field.

Description
This routine reports the rejection of a request to perform an operation. You
should use this routine if an incoming APDU carrying an Invoke indication is in
some way incorrect or badly structured, so that it does not make sense to your
application.
The Reject function disrupts all other ROSE functions.

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

3–16 ROSE Routines

Routine has finished without error.
At least one mandatory parameter is missing.
There is not enough dynamic memory.
At least one parameter is incorrectly specified.

osak_ro_decode

osak_ro_decode
Decodes ROSE PCI.

Syntax
status = osak_ro_decode (port, rose_pb)
Argument

Data Type

Access

port

osak_port

read only

rose_pb

osak_rose_pb

read only

Parameters

Data Type

Access

pb_length

Unsigned long integer

read only

ws_length

Unsigned long integer

read only

pdu_type

Unsigned longword

write only

invoke_id

osak_mem_descriptor

read only

linked_id

osak_mem_descriptor

read only

local_value

osak_mem_descriptor

read only

global_value

osak_mem_descriptor

read only

reason

osak_ro_reason

read only

problem

osak_ro_problem

read only

buffer

osak_buffer

read only

osak_rose_status

osak_status_block

write only

C Binding
osak_ro_decode(port, rose_pb)
osak_port port;
struct osak_rose_pb *rose_pb;

ROSE_C_INVOKE

•

ROSE_C_RESULT

•

ROSE_C_ERROR

ROSE Routines 3–17

osak_ro_decode

•

ROSE_C_REJECT_U
This value indicates a rejection detected by the user.

•

ROSE_C_REJECT_P
This value indicates a rejection detected by the provider.

invoke_id
The address of an Invoke identifier. You should set the pointer field of this
descriptor to null, and the size field to zero.
If the ROSE interface finds an Invoke identifier in the incoming APDU, it returns
the address of that identifier, and a value specifying its size.
linked_id
The address of a Linked identifier. You should set the pointer field of this
descriptor to null, and the size field to zero.
If the ROSE interface finds a Linked identifier in the incoming APDU, it returns
the address of that identifier, and a value specifying its size.
local_value
The address of an ASN.1 encoded integer representing an operation code.
You should set the pointer field of this descriptor to null, and the size field to zero.
If the ROSE interface finds a local value in the incoming APDU, it returns the
address of that local value, and a value specifying its size.
global_value
The address of an ASN.1 encoded object identifier representing an operation code.
You should set the pointer field of this descriptor to null, and the size field to zero.
If the ROSE interface finds a global value in the incoming APDU, it returns the
address of that global value, and a value specifying its size.
reason
The address of a reason code. You should set this parameter to null.
If the ROSE interface finds a reason code in the incoming APDU, it returns the
address of that code. The code has one of the following values:
Value

Meaning

RORJ_C_RETURN_PARAMETER
RORJ_C_GEN_PROB
RORJ_C_INVOKE_PROB
RORJ_C_RET_RES_PROB
RORJ_C_RET_ERR_PROB

Problem detected by the provider
Problem detected by the provider
Meaning assigned by your application
Meaning assigned by your application
Meaning assigned by your application

problem
The address of a problem code. You should set this parameter to null.
If the ROSE interface finds a problem code in the incoming APDU, it returns the
address of that problem code. The problem code has one of the following values:

3–18 ROSE Routines

osak_ro_decode

Reason

Corresponding Problem Codes

Returned parameter
General problem

No problem code
RORJ_C_UNREC_APDU
RORJ_C_MISTYPE_APDU
RORJ_C_BAD_STRCT_APDU
RORJ_RO_DUPLIC_INV
RORJ_C_UNREC_OPER
RORJ_C_MISTYPE_ARG
RORJ_C_RES_LIMIT
RORJ_C_INIT_REJ
RORJ_C_UNREC_LINK
RORJ_C_RESP_UNEXP
RORJ_C_UNEXP_CHILD_OPER
RORJ_C_UNREC_INV
RORJ_C_RES_RESP_UNEXP
RORJ_C_MISTYPE_RES
RORJ_C_UNREC_INV
RORJ_C_ERR_RESP_UNEXP
RORJ_C_UNREC_ERR
RORJ_C_UNEXP_ERR
RORJ_C_MISTYPE_PAR

Invoke problem

Return result problem

Return error problem

Each of these values has the meaning assigned to it by your application.
buffer
The address of a buffer structure that holds the ROSE PCI and any user data
that the ROSE interface finds in the incoming APDU.
If the ROSE interface successfully decodes the ROSE PCI, the data_length and
data_ptr parameters are both set to point to the start of the undecoded ROSE
user data.
When a provider reject occurs, the reason code is RORJ_C_RETURN_PARAM.
This means that the ROSE provider has detected an error, and has set the buffer
pointer to the address of the ROSE primitive that is in error.
osak_rose_status
A status code specific to ROSE in the osak_status2 field.

Description
This routine decodes incoming ROSE PCI. The routine does not examine and
remove the PDU part of the APDU. Your application should do this.
The routine does not check that the invoke_id parameter in the APDU is unique.
Your application should check this.

ROSE Routines 3–19

osak_ro_decode

Return Value
A value indicating the status of the routine. Possible status values are:
OSAK_S_NORMAL
OSAK_S_BADPARAM
OSAK_S_INSFMEM
OSAK_S_INVPARAM
OSAK_S_NOBUFFER

3–20 ROSE Routines

Routine has finished without error.
At least one mandatory parameter is missing.
There is not enough dynamic memory.
At least one parameter is incorrectly specified.
No user buffer supplied.

4
Trace Emitter Routines
This chapter describes the OSAK trace emitter routines you can use to enable the
OSAK trace emitter. Use these routines to output a trace record to a trace binary
file.

Trace Emitter Routines 4–1

osak_trace_dcs_verify

osak_trace_dcs_verify
Checks the DCS and default context maintained by the OSAK trace utility.

Format
status = osak_trace_dcs_verify

(port, dcs, dflt_ctxt)

Argument

Data Type

Access

port

osak_port

read only

dcs

osak_dcs_pcontext

read only

dflt_ctxt

osak_default_context

read only

C Binding
osak_trace_dcs_verify (port, dcs, dflt_ctxt )
osak_port port;
struct osak_dcs_pcontext *dcs;
struct osak_default_context *dflt_ctxt;

Arguments
port
Port on which the connection you are tracing is established.
dcs
Address of a linked list of presentation contexts. The OSAK trace utility uses this
list of presentation contexts to verify the DCS.
Set this parameter to null if you call the osak_trace_dcs_verify routine after a
session connection has been established.
dflt_ctxt
Address of the default context.
Set this parameter to null if you call the osak_trace_dcs_verify routine after a
session connection has been established.

Description
This function writes a DCS verification record to the trace binary file for the
specified connection. When decoding the trace binary file, the OSAK trace utility
checks that it is using correct values for the DCS and the default context on a
connection. The utility checks the values it holds for the DCS and the default
context against the values you supply in this routine call. This checking is done
off-line when you activate the OSAK trace utility.
The OSAK trace utility compares the DCS verification record with the DCS
contents and with the default presentation context. If the verification record
matches the DCS and the default presentation context, the OSAK trace utility
outputs the DCS contents and the default context.
If the verification record does not match the DCS and the default presentation
context, the OSAK trace utility outputs both sets of values.

4–2 Trace Emitter Routines

osak_trace_dcs_verify

Return Value
OSAK_S_NORMAL
OSAK_S_BADPARAM

OSAK_S_FILEERR
OSAK_S_INSFMEM
OSAK_S_INVFUNC
OSAK_S_INVPORT
OSAK_S_UNSPECERR

Normal execution of routine completed.
DCS is empty and the OSAK state machine is
active
or
DCS is not empty and the OSAK state machine
is idle.
Error occurred in writing to the trace binary file.
Memory allocation error.
You have not opened a trace file, or you have not
enabled tracing, for the connection.
You have specified an invalid port.
Error in some unspecified part of the system, for
example an error in the gettimeofday( ) function.

Trace Emitter Routines 4–3

osak_trace_close

osak_trace_close
Closes a trace binary file.

Format
status = osak_trace_close

(port)

Argument

Data Type

Access

port

osak_port

read only

C Binding
osak_trace_close (port)
osak_port port;

Arguments
port
Port on which the connection you are tracing is established.

Description
This routine closes the trace binary file for the connection on the port you specify.
If you do not call the osak_trace_stop routine, this routine (osak_trace_close)
calls osak_trace_stop to write a trace stop record to the binary file, and then
closes the binary file.
A call to this routine should be paired with a call to osak_trace_open.
The routine is valid only in the context of an established connection. In your
application program, it should come after a call to osak_open_initiator,
osak_open_responder, or osak_open_redirect, so that the port parameter is
valid.

Return Value
OSAK_S_NORMAL
OSAK_S_FILEERR
OSAK_S_INVFUNC
OSAK_S_INVPORT