Digital PDFs

AA-CK81A-TB

May 1985

192 pages

Original

6.5MB

Document:	TOPS-10 PSI Users Guide Feb85
Order Number:	AA-CK81A-TB
Revision:	0
Pages:	192
Original Filename:	AA-CK81A-TB_TOPS-10_PSI_Users_Guide_Feb85.pdf

OCR Text

TOPS-10
PSI User's Guide
AA-CKB1 A-TB

February 1985
This manual describes how to write programs that transfer data
over a Public Packet Switching Network (PPSN). The manual
also describes how to gain access to a TOPS-10 host through
a PPSN.
OPERATING SYSTEM:
SOFTWARE:

TOPS-10 V7.02

DECnet-10 V3.0
GALAXY V4.1
TOPS-10 PSI Gateway V1.0
TOPS-10 PSI Gateway Access Libraries V1.0

Software and manuals should be ordered by title and order number, In the United States. send orders
to the nearest distribution center, Outside the United States. orders should be directed to the nearest
DIGITAL Field Sales Office or representative,

Northeast/Mid-Atlantic Region

Central Region

Western Region

Digital Equipment Corporation
PO Box CS2008
Nashua, New Hampshire 03061
Telephone :(603)884-6660

Digital Equipment Corporation
Digital Equipment Corporation
Accessories and Supplies Center Accessories and Supplies Center
1050 East Remington Road
632 Caribbean Drive
Sunnyvale. California 94086
Schaumburg, Illinois 60195
Telephone:(312)64o-5612
Telephone:(408)734-4915

digital equipment corporation. marlboro. massachusetts

First Printing, February 1985
© Digital Equipment Corporation 1985. All Rights Reserved.

The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may
appear in this document.
The software described in this document is furnished under a license and may
only be used or copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by DIGITAL or its affiliated companies.
The following are trademarks of Digital Equipment Corporation:

~DmDDmDTM
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

MASSBUS
PDP

P/OS
Professional
Q-BUS
Rainbow
RSTS

RSX
RT
UNIBUS
VAX
VMS
VT
Work Processor

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future
documentation.

CONTENTS

PREFACE
PART I

INTRODUCTION

CHAPTER 1

INTRODUCTION TO PACKET SWITCHING

1.1
VIRTUAL CIRCUITS • • • • •
• • • 1-1
1.2
USER INTERFACES TO A PPSN
• • • • 1-3
1.2.1
The X.25 Recommendation
••••
• • 1-4
1.2.1.1
LEVEL 1 - Physical and Electrical
Characteristics
• • • • • • • . • • • • 1-5
1.2.1.2
LEVEL 2 - Link Access Procedures • •
1-5
1.2.1.3
LEVEL 3 - Packet Procedures
•
• 1-6
1.2.2
The X.3, X.28, and X.29 Recommendations
• • 1-8
1.3
A TYPICAL CALL • • • • • • • • • • • •
• 1-9
1.3.1
Setting up a Virtual Circuit •
• • • • 1-9
1.3.2
Transferring Data • • • • •
• • • • 1-9
1.3.3
Clearing a Virtual Circuit • • • • • •
• • 1-9
1.4
FLOW CONTROL •
••••••
1-10
1.4.1
Flow Control for Control Packets •
1-10
1.4.2
Flow Control for Data Packets
1-11
1.5
ADDITIONAL PPSN FACILITIES • • • • • • •
1-12
1.5.1
Interrupts • • • • •
1-12
1.5.2
Resets • • • • • • •
1-12
1.5.3
Restarts • • • • • •
1-12
Optional Facilities
1.5.4
1-12
."

. ..

PART II X.25 REFERENCE GUIDE
CHAPTER 2
2.1
2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
CHAPTER 3
3.1
3.2
3.2.1
3.2.2
3.2.3
3.3
3.4
CHAPTER 4
4.1

THE TOPS-10 X.25 SOFTWARE
TOPS-10 PSI SOFTWARE FUNCTIONS •
PORT STATES • • • • • • • •
THE PROGRAMMING ENVIRONMENT • • • • • • •
TYPES OF USER PROGRAMS • • • • • • • • • •
Initiating an SVC Call and Using the SVC
Receiving an SVC Call and Using the SVC
Using a PVC • • • • • • • • • • • • • •

• • 2-3
• • • • 2-6
•
2-13
•
2-13
•
2-14
2-15
•
2-16

FORTRAN-10 SUBROUTINE CALLS
FORTRAN-10 AND THE TOPS-10 PSI GATEWAY ACCESS
SOFTWARE • • • • • • • • •
• • • •
SENDING AND RECEIVING DATA
•••••
Conversion of 36-Bit Binary Data in
TOPS-10/TOPS-10 Transfers
•••••
••••
Other Types of Binary Data Conversion • • • • •
ASCII Data Conversion
• • ••
•
LINKING A FORTRAN-10 PROGRAM •
•• • • • • • •
THE SUBROUTINE CALLS • • • • •
• • • • •

3-1
3-2
3-3
3-3
3-3
3-4
3-4

MACRO-10 SUBROUTINE CALLS
MACRO-10 AND THE TOPS-10 PSI GATEWAY SOFTWARE
iii

• • 4-1

4.2
4.3

LINKING A MACRO-I0 PROGRAM
THE SUBROUTINE CALLS • • • •

4-3
• • • 4-3

PART III X.29 REFERENCE GUIDE
CHAPTER 5
5.1
5.2
5.3
5.4
5.5
5.5.1
5.5.2
5.5.3
5.5.4
5.5.5
5.5.6
5.6
5.7

THE TOPS-I0 X.29 SOFTWARE
SAMPLE DIALOGUE
X.3, X.28 AND X.29 •
COMMAND LEVELS • • •
COMMUNICATING WITH THE PAD •
COMMUNICATING WITH X29SRV
Error Conditions
• • • ••
CLEAR Command
• • • •
CONNECT Command
• • • • • •
DEFINE Command •
• • • •
•
DISCONNECT Command
INFORMATION Command
• • • •
ENTERING COMMAND MODE
TERMINATING A CONNECTION
• • • • •

•

• • • • • 5-4
• 5-5
• • • • • 5-6
• 5-8
• • 5-8
• • • • 5- 9
• •
5-10
• • ••
5-11
• •
5-13
• • ••
5-14
• • ••
5-15
• • ••
5-16
• • • • 5-17

PROGRAM FEATURES • • •
Receiving Program
••••.
Transmitting Program
• • • •
LISTING OF SAMPLE PROGRAM SVCRCV.FOR
LISTING OF SAMPLE PROGRAM SVCXMI.FOR •

A-I
• A-I
• A-6
A-13
A-18

•
•
•
•

APPENDIXES
APPENDIX A
A.l
A.l.l
A.l.2
A.2
A.3
APPENDIX B
B.l
B.l.l
B.l.2
B.l.3
B.2
B.3

SAMPLE FORTRAN-I0 PROGRAMS

SAMPLE MACRO-I0 PROGRAMS
PROGRAM FEATURES • • •
••••
Standard Set-up
• • • •
Receiving Program
• • • • • •
Transmitting Program.
LISTING OF SAMPLE PROGRAM SVCRCV.MAC
LISTING OF SAMPLE PROGRAM SVCXMI.MAC

APPENDIX C

BIBLIOGRAPHY

APPENDIX D

ERROR MESSAGES DISPLAYED BY X29SRV

APPENDIX E

GLOSSARY

• • B-1
•
• • • B-1
•
• • • • B-2
• • • • • • • B-7
•
B-12
• • • • • • B-14

INDEX
FIGURES
1-1
1-2
1-3
1-4

A Public Packet Switching Network (PPSN) • • • • •
Relationship Between X.25 and the PPSN •
Protocol Levels
• • • • • • • • •
• • •
User Data/Packet/Frame Nesting • • • • • • • • • •
iv

1- 2
1-4
1-5
1-7

1-5
1-6
2-1
4-1
5-1
5-2
5-3
5-4

Relationship Between X.3, X.28, X.29 and the PPSN 1-8
A Typical Call Sequence
• • • • • •
1-10
TOPS-10 PSI Gateway Software Components
• • 2-2
Return Code Bit Mask • • • • • • • • •
• • 4-2
X.29 Terminal Access to a TOPS-10 Host.
• •• 5-2
X.29 Terminal Access to a TOPS-10 Host that Is Not
Running the X.29 Software
• • • • • • • • • • 5-3
X.3, X.25, and X.29 Supporting an X.29 Terminal
Connection • • • • • • • • • • • •
• • 5-6
TOPS-10 PSI Gateway X.29 Interface • • • • • • • • 5-7

TABLES
1-1
2-1
2-2
2-3
2-4
2-5
2-6
3-1
3-2
4-1
4-2
4-3
4-4
4-5

Control Packet Pairs • • • • • • • • • • • • • • 1-11
TOPS-10 PSI Gateway Access Routine Functions • • • 2-4
Types of Virtual Circuits and the Functions that
Can Be Used with Each
• • • • • • • • • • ••
2-6
TOPS-10 PSI Gateway Port States
• 2-7
State Changes for PVC Ports
• • • 2-9
State Changes for SVC Ports
2-10
TOPS-10 Gateway Access Routine Functions and
Their Port States
• • • • • •
2-12
Specifications for the Dtype and Datlen Variables 3-21
Fatal Error Conditions • • • • • • • . • •
3-28
Return Code Values • • • • • • • • • • •
• • • 4-2
More-bit and Data-qualifier Bit Meanings
4-20
Fatal Error Conditions • • • • • • • • • • • • •
4-25
Port States
• • • • • • •
4-26
Interrupt/Data Bit Mask Meanings • • • • •
4-26

PREFACE

This manual contains information on:
that uses the
{Public Packet

•

Writing a FORTRAN-10 or MACRO-10
TOPS-10 X.25 software to access
Switching Network)

program
a PPSN

•

Using
the
TOPS-10
X.29
software
to
terminal - through a PPSN - to a TOPS-10 host

connect

The manual is divided into three parts:
•

Part I,
the Introduction, which
discussion of packet switching

contains

Chapter

•

Part II, the X.25 Reference Guide, which contains Chapter 2,
a discussion of the TOPS-10 PSI (Packetnet System Interface)
Software; Chapter 3, a guide to using the FORTRAN-10-ca11ab1e
X.25 Gateway Access Routines; and Chapter 4, a guide to using
the MACRO-10-ca11ab1e X.25 Gateway Access Routines

•

Part III, the X.29 Reference Guide, which contains Chapter 5,
a guide to using the X.29 Software to connect a terminal
through a PPSN to a remote TOPS-10 host

•

Appendixes, which include sample programs,
X.29 error messages, and a glossary

bibliography,

The reader of this manual should:
•

Be an experienced FORTRAN-10 or MACRO-10 programmer

•

Have read all user documentation published by his PPSN

•

Have access to CCITT publications that describe
X.25, and X.29 recommendations (see Appendix C)

the

X.3,

Other DIGITAL documents useful to the reader of this manual are:
TOPS-10/20 FORTRAN Language Manual.

Order No.

This manual describes the language
and FORTRAN-20.

vii

AA-N383A-TK

elements

FORTRAN-10

DECsystem-lO
AA-C780C-TB

MACRO

Assembler

Order

Manual.

Reference

No.

This manual describes the language elements of the MACRO-IO
Assembler
for
the
DECsystem-lO.
It is helpful for
understanding methods of programming in assembly language on
TOPS-IO.
TOPS-IO LINK Reference Manual.
This manual
TOPS-IO.

describes

Order No.
LINK-IO,

TOPS-IO Monitor Calls Manual,
AA-0974E-TB & AA-K039B-TB

Volumes

AA-0988D-TB

the

linking

loader

for

and

Order

Nos.

These manuals describe the functions
that the monitor
performs to service monitor calls for assembly language
programs. Volume 1 covers facilities and functions of the
monitor.
Volume 2 covers monitor calls, calling sequences,
symbols, and GETTAB tables.
DECnet-lO User's Guide.

Order No.

AA-L414A-TB

This manual contains procedures and examples for:

The MACRO programmer who will write network
programs

The nonpriviledged terminal user who will use TOPS-IO
commands and the Network File Transfer (NFT) utility
program in network-related tasks.
This manual also
describes the SET HOST command which provides login
capabilities.

The following graphic conventions are used in commands and
call formats in this manual:

application

subroutine

Meaning

Convention/Symbol
UPPERCASE

Uppercase letters in a subroutine call or
command string indicate user input required.

lowercase

Lowercase letters in a subroutine call or
command string indicate an input variable for
which you must supply a value.

Spaces

Spaces separate elements of a command.,
Tabs
or multiple spaces can also be used.
Spaces
must be input where shown.

Red

Red characters indicate information that
specify in typing the command.

Black

Black characters
information.

indicate

you

system-supplied

This symbol indicates that you press the
labeled RETURN.

key

This symbol indicates that you press the
labeled ESC, ALT, or SEL.

key

viii

Convention/Symbol

Meaning
This symbol indicates that you press the
labeled BREAK or ATTN.

key

This symbol indicates that you press the key
marked CTRL while you press another key, for
example, (CTRLlU)
or (CTRLlV)
Unless otherwise noted, all numbers in this manual are decimal.

PART I
Introduction

CHAPTER 1
INTRODUCTION TO PACKET SWITCHING

Packet switching is the transmission of data in units called packets.
One type of network that performs packet switching is a Public Packet
Switching Network (PPSN).
A PPSN supplies each packet it transmits
with
a
header.
This header contains control information and
destination fields that enable a PPSN to deliver packets in the
correct order to the correct destinations.
The PPSN interleaves
packets from many users over shared transmission lines and routes the
packets to their destinations.
The PPSN determines the route each
packet takes; neither the sender nor the receiver of the packets can
influence that determination.
Packet switching significantly improves
the
efficiency
of
a
transmission line by sharing the line between many users, therefore,
reducing the amount of time the line is idle.
A PPSN can also
accommodate different speeds and formats of data transfer and, through
its error control mechanisms, reduce the undetected error rate to an
acceptably low figure.

1.1

VIRTUAL CIRCUITS

PPSNs evolved to fill the need for a data communications service that
was distinct from traditional communication circuits. Any computer or
terminal can communicate with one or more computers or terminals
connected to the PPSN as if they were directly connected.
These
computers or terminals can be of any type and manufacture and can
operate at different speeds. As long as they are connected to a PPSN,
they can communicate with each other.
The connection between the
computer and the PPSN is over a leased circuit provided by a common
carrier. Terminals are connected to the PPSN over leased circuits or
dial-up lines (see Figure 1-1).

1-1

INTRODUCTION TO PACKET SWITCHING

- - __

_--

Network----·---·-...,.~

,.,..

Interface

"...,.,.. ....... -.......

",/

... "

PPSN

- -; /!.- ....

--\-

-~~~I

,.,..,.,..""',,'" I

,," ..............

"1
/
/

Network
Interface

-- _

MR-S-2731-83

Figure 1-1:

A Public Packet Switching Network (PPSN)

The techniques used within the network are transparent to both the
sender and the receiver.
Neither the sending computer or terminal nor
the receiving computer or terminal is concerned with the control of
packets in the network or with the route that packets take through the
network <.
The connection between the sender and receiver
is called a virtual
circuit and
is set up by an initial exchange of packets between the
sender and the receiver.
Each packet contains a reference number
identifying the link between the user and the network.
Consequently,
each virtual circuit is identified by two reference numbers:
one
identifying the link between the sender and the PPSN and one
identifying the link between the receiver and the PPSN.
These
reference numbers are allocated when the sender and receiver set up a
virtual circuit.
In a PPSN, such reference numbers are called Logical Channel Numbers
(LCNs) •
The physical connection between the sender and a PPSN (and
also the receiver and a PPSN) consists of logical channels.
A virtual
circuit associates one of the sender's logical channels with one of
the receiver's logical channels, and the sender and receiver each
recognize the virtual circuit only by the LCN at its own end.
In
general, the LCNs are different at each end of a virtual circuit.
The association between the sender and receiver can be either
permanent or temporary.
A permanent association is analogous to a
leased circuit directly connecting the sender and the receiver.
Packets bearing the appropriate LCN as transmitted by the sender are
routed by the network directly to the receiver, where they are
delivered bearing the LCN appropriate to that end. This association
is called a Permanent virtual Circuit (PVC).

1-2

INTRODUCTION TO PACKET SWITCHING
A temporary
A temporary association is analogous to a dial-up line.
virtual circuit is set up only when there is data to transmit and is
cleared when the transfer of this data is complete. The sender sets
up such a virtual circuit by sending a Call Request packet, and the
receiver accepts the circuit by sending a Call Accepted packet.
Data
can then be transferred between the sender and receiver.
Either the
sender or receiver can clear a virtual circuit by sending a Clear
Request packet,
at which time the other returns a Clear Confirmation
packet.
This type of association is called a Switched Virtual Circuit
(SVC) •

1.2

USER INTERFACES TO A PPSN

All user devices connected
to
the
network
fall
into
two
classes - those that work
in packet mode and
those that do not.
Packet-mode devices are either computers or
intelligent terminals
capable of conversing with the network and using packets as units of
transmission.
Non-packet mode devices, which
include asynchronous
terminals and other start-stop devices, cannot connect directly to the
network but instead communicate through a packet assembly/disassembly
(PAD) facility provided by the network.
To ensure that the growth of PPSNs
is orderly and controlled, a
special
group
of
the CCITT
(Comite Consultatif International
Telegraphique et Telephonique)
has established recommendations for
standard
network
interfaces for packet-mode and non-packet-mode
devices.
There are four applicable recommendations:
X.2S defines the packet-mode device interface and is entitled:
X.2S

Interface between Data Terminal Equipment
(DTE)
and
Data Circuit-terminating Equipment (DCE) for terminals
operating in the packet mode on public data networks.

X.3, X.28, and X.29 define the non-packet-mode
are entitled:

device

interface
in a

and

X.3

Packet assembly/disassembly facility (PAD)
data network.

public

X.28

DTE/DCE interface for a start-stop mode Data Terminal
Equipment accessing the packet assembly/disassembly
facility (PAD) in a public data network situated in the
same country.

X.29

Procedures for the exchange of control information and
user data between a packet-mode DTE and a packet
assembly/disassembly facility (PAD).

Data Terminal Equipment (DTE) is the term the CCITT uses to refer to
your computer or terminal device.
Data Circuit-terminating Equipment
(DCE) is the term the CCITT uses to refer to the equipment of the
PPSN.

1-3

INTRODUCTION TO PACKET SWITCHING
1.2.1

The X.2S Recommendation

Recommendation X.25 defines only the interface between the packet-mode
DTE and the DCE (see Figure 1-2) and does not state how the network
functions.
The sequence of events at the interface does not provide
any information about what is happening at the corresponding interface
between the network and the remote DTE.
The principal feature of X.25
is that
it provides a
full-duplex
synchronous pathway that
is transparent to both the sender and the
receiver.
The interface removes the sender's need to have precise
knowledge of the characteristics of the remote DTEs. Consequently, it
allows many devices to communicate over a single physical link.
The
interface administers all transmission by providing virtual circuits,
control of packets, and error control over the network.
Packet-mode DTE
(Computer)

X.25
defines t h i s - interface

~
/

DCE
_ - /' \ ' .......
.......

_--::~DCE~

./ .,,/

\ ....... .............. '....... ......./. /

/'
./ ....... \
/' /' ././
\

PPSN

/'
/

::.. -::-:. ____ -t - -/-Y'- __

.,,/./' / / /
/
/

.,,/

X.25
defines this
interface

\.(....---

Packet-mode DTE
(Computer)

Figure 1-2:

MR-S-2732-83

Relationship Between X.2S and the PPSN

The X.25 standard defines three levels of control procedures
(or
protocols)
which apply to the single physical link that joins the
device (the DTE) to the network interface (the DeE).
See Figure 1-3.

1-4

INTRODUCTION TO PACKET SWITCHING

Packet
Level
(level 3)

Multiple Virtual Circuits

Link
Level
(level 2)

Single Data Link

Physical
Level
(level 1)

Physical Link

--"

PPSN

MR-S-2733-83

Figure 1-3:

Protocol Levels

1.2.1.1 LEVEL 1 - Physical and Electrical Characteristics - Level 1
defines the physical and electrical characteristics across the DTE/DCE
interface.
Level 1 ensures that bits are exchanged across the
interface at a
fixed rate with appropriate timing information.
The
interface uses the X.2l bis standard.
This standard is the same as
specified
in the EIA (Electronic Industries Association) RS232C and
CCITT V.24 standards for connecting a DTE to a modem.
Levell is responsible for:
•

Physical characteristics

•

Electrical characteristics

•

Fault indications

1.2.1.2 LEVEL 2 - Link Access Procedures - Level 2 defines the link
access procedures across the DTE/DCE interface.
The procedures are
compatible with the HDLC (High-level Data Link Control)
standard of
ISO.
The major purpose of Level 2 is to provide an error-free data
communications path over a single physical link between a DTE and a
DCE.

1-5

INTRODUCTION TO PACKET SWITCHING
The link level is responsible for:
•

Providing an efficient means of
the DTE and the DCE

exchanging

packets

•

Providing error-detection and taking steps
such errors

•

Providing frame synchronization to ensure that
and transmitter are in step

•

Reporting procedural errors to Level 3

between

recover
the

from

receiver

1.2.1.3 LEVEL 3 - Packet Procedures - Level
3 defines
the packet
level procedures.
These procedures enable DTEs to communicate with
each other across the network.
A PPSN can transmit the following types of packets:

• Call Accepted
• Call Connected
• Call Request
• Clear Confirmation

• Clear Indication
• Clear Request
• Data
• Incoming Call
• Interrupt
• Interrupt Confirmation
• Receive Not Ready
• Receive Ready
• Reset Confirmation
• Reset Indication
• Reset Request
• Restart Request
• Restart Confirmation

• Restart Indication

1-6

INTRODUCTION TO PACKET SWITCHING
Prior to the transfer of data, a permanent or switched virtual circuit
must be active between the two DTEs that are to communicate. Several
virtual circuits can be established simultaneously with one or more
users, and both PVCs and SVCs can be active at the same time.
The
packet level is responsible for:
•

Placing the control and user data into packets

•

Sequencing control of those packets

•

Establishing, maintaining, and clearing virtual circuits

Figure 1-4 shows how the interface forms user data into a packet
forms the packet into a larger transmission unit called a frame.

and

User Level

Packet (level 3)

Frame
(level 2)

Da~

' - - -______

Info

Field

MR-S-2734-83

Figure 1-4:

User Data/Packet/Frame Nesting

In essence, users communicate directly with
Level
3
(packet
procedures) •
The user data is divided
into packet lengths and a
header is added to form a packet. The coding of the data field is of
no significance to the PPSN but the field itself is always restricted
in length by the network (a typical length is 128 bytes). The packet
header is a 24-bit field that contains the routing address, the LCN,
packet identification, and optional codes (dependent on the type of
packet), for example, reverse charging or priority of traffic.
The packet passes to Level 2 (link access procedures)
where further
control and error-detecting information and delimiting flags are added
to form a frame.
The control information consists of a frame
identification and fields
indicating the type and direction of
information flow between the DTE and the DCE.
The error information
consists of a 16-bit Frame Checking Sequence (FCS).
Level 1
(physical and electrical characteristics)
controls
the
physical transmission of the frame between the DTE and the DCE.
The
DCE checks that each frame is in the correct sequence and error free.
It then passes the packet frame to the network.
Levels 1 and 2 are purely local to the DTE/DCE interface; they have no
interaction with Levels 1 and 2 of the remote.DTE.
However, the
actions taken at Level 3 do interact with the remote DTE.

1-7

INTRODUCTION TO PACKET SWITCHING
1.2.2

The X.3, X.28, and X.29 Recommendations

Recommendations X.3, X.28, and X.29 specify how the assembly and
disassembly of packets for start-stop devices should be provided in
PPSNs.
A start-stop device needs special software to:
•

Form the user data into packets

•

Control the transmission and reception of those packets

•

Set up virtual circuits

•

Provide an internal interface to application programs

The packet assembly/disassembly
(PAD)
facility
provides
these
functions.
The PAD facility allows a PPSN to communicate with both
packet-mode and start-stop devices.
Typically, when at a start-stop device , you first command the PAD to
establish a virtual circuit to the desired remote computer. After
connecting to the network,
you can send commands or text as
if
directly connected to the remote computer.
The PAD assembles the individual characters forming the commands or
text into packets and dispatches them through the network to the
remote 'computer.
Packets,
arriving at the PAD from the remote
computer,
are disassembled and sent character-by-character to the
start-stop device.
Figure 1-5 shows the relationship between
PPSN.

X.3,

X.28,

X.29

and

X.25 defines
this interface

X.29 defines
procedures for
exchange of
information
across here

---

OCE

___ . . . \-"
\

PPSN

_ - I\ OTE

:--;;::;,
///

-"-"

- / - ~ - ___-.......-:::/
-- ---

/.-

(Start-stop Terminal)

-- . . ./.:.

___
Non-packet-mode

_ -

'~CSI /PAO (defined by X.3)
"/

Non-packet-mode
OTE

(Start-stop Terminal)

MR -8·2735·83

Figure 1-5:

Relationship Between X.3, X.28, X.29 and the PPSN

1-8

the

INTRODUCTION TO PACKET SWITCHING
Access from a start-stop terminal to a PAD is either by leased circuit
or by dial-up line.
In the latter case, a user incurs both a local
telephone call charge for accessing the PAD and charges according to
the tariff of the PPSN.
These charges should be considerably less
than those
incurred by
dialing
and
holding
the
equivalent
long-distance telephone call.

1.3

A TYPICAL CALL

A typical call includes making a virtual circuit active,
data over that circuit, and clearing the circuit.

1.3.1

transferring

Setting up a Virtual Circuit

The connection between the DTE and DCE consists of a number of logical
channels.
The user at the local DTE sends a Call Request packet over
an available logical channel to the local DCE.
This Call Request
packet contains the Logical Channel Numbe:r (LCN) , which is selected by
the DTE, and the address of the remote DTE with which the user wishes
to communicate.
The local DCE notes the LCN and then sends the Call
Request packet to the remote DCE.
The remote DCE chooses a
free
logical channel from those available at the remote DTE/DCE interface
and sends an Incoming Call packet to the remote DTE.
This
Incoming
Call packet contains the LCN for this remote DTE/DCE interface as well
as the address of the local (calling) DTE.
If the user at the remote DTE can accept the call, he sends a Call
Accepted packet to his DCE.
The Call Accepted packet contains the LCN
of the DTE/DCE interface at his end.
His DCE sends this packet to the
local DCE,
which forwards it as a Call Connected packet to the local
DTE.
A virtual circuit now exists between the local DTE and the remote DTE.
Each DTE only knows of the circuit by the LCN at its own end.

1.3.2

Transferring Data

The two users can now transfer data between the two DTEs.
Each sends
data that his local interface forms into Data packets that contain the
local LCN, but which arrive containing the remote LCN.
The Data
packets also contain packet-send and packet-receive sequence numbers.
These numbers are used for flow control (see Section 1.4.2).

1.3.3

Clearing a Virtual Circuit

Either the local or the remote DTE can clear a virtual circuit by
sending a Clear Request packet to the DCE.
The Clear Request packet
contains the LCN of the DTE/DCE interface from which it originated.
The DCE forwards the Clear Request packet as a Clear Indication packet
to the other DCE, which is then forwarded to the DTE.
The DTE replies
with a Clear Confirmation packet that is sent through the DCEs to the
other DTE.
The network erases the entries
in the internal call
control tables.

1-9

INTRODUCTION TO PACKET SWITCHING
The Clear Request packet is also sent (in reply to the Call Request
packet)
if either of the DTEs or the network is unable to set up a
virtual circuit.
In these cases, the packet contains information on
why the call request was refused.
A typical call sequence is shown in Figure 1-6.
Network

Local DTE/DCE Interface
DTE

DCE

Call -------I.....
Request

•

Clear
Request

DTE

Incoming ----Call
,.
Call
Accepted

. . - - Call
Connected
Data
..

Data

Remote DTE/DCE Interface

..
,.

..
..

•

..
Clear
Indication

Data

..
Clear
Confirmation

~-Clear

Confirmation

Figure 1-6:
1.4

MR-S-2736-83

A Typical Call Sequence

FLOW CONTROL

The network provides two methods for controlling the flow of packets:
one for Data packets and one for all other packets (control packets).

1.4.1

Flow Control for Control Packets

Control packets are in pairs;
for example, Call Request and Call
Connected packets.
After a DTE sends a Call Request packet, it can do
nothing until it has received a Call Connected packet.
This simple
method controls the flow of packets by not allowing any further
packets to be sent on a particular virtual circuit until the previous
action is complete. Table 1-1 lists all control packet pairs.

1-10

INTRODUCTION TO PACKET SWITCHING
Table 1-1:

Control Packet Pairs

Call Request

Call Connected

Clear Request

Clear Confirmation

Interrupt Request

Interrupt Confirmation

Reset Request

Reset Confirmation

Restart Request

Restart Confirmation

1.4.2

Flow Control for Data Packets

The method for controlling the flow of Data packets in Section 1.4.1
is too restrictive. Thus, a second method allows the DTE and the DCE
to anticipate receipt of Data packets from the other and also allows
each to send several Data packets before an acknowledgement is
received.
To achieve this, each Data packet contains a packet send
sequence number - P(S).
This number starts at zero and is increased
by one for each successive packet sent on one logical channel in one
direction.
The interface keeps a separate count for each logical
channel. You can send up to a pre-set number of packets on a logical
channel in one direction before an acknowledgement must be received.
The pre-set number is called the window size and flow control is based
on the concept of a window.
A window is the ordered set of
consecutive Data packets authorized to be transmitted across the
DTE/DCE interface. The interface progressively closes the window for
a logical channel as it transmits packets on that channel. The window
is completely shut when the interface has transmitted a number of
packets equal to the window size. At that time,
the interface can
send no more packets on that channel until the other end of the
virtual circuit sends an acknowledgement.
That acknowledgement is the Receive Ready packet.
This packet
contains the LCN and a packet receive sequence number - P(R).
The
P(R) number indicates that all packets up to the number P(R)-l have
been received and that the next packet expected should have the number
P(R).
The Receive Ready packet reopens the shut window.
This enables
more packets, up to the window size, to be sent, starting at the one
numbered P(R).
If the Receive Ready packet is sent before the window is completely
shut,
the window is kept partially open and Data packets can be sent
continuously.
If Data packets are being sent in both directions at the same time, it
is possible to cut down the number of Receive Ready packets by
including the P(R) number in the Data packets being sent in the
opposite direction.

1-11

INTRODUCTION TO PACKET SWITCHING
1.5

ADDITIONAL PPSN FACILITIES

This section describes additional facilities that may be provided by a
PPSN for controlling the exchange of packets between DTEs.

1.5.1

Interrupts

The interrupt procedure lets a DTE transmit one byte of data to a
remote DTE by using the method of flow control for control packets
(see Section 1.4.1).
Interrupt packets are paired: an interrupt can
be sent in one direction on a particular virtual circuit only if any
previous interrupt has been acknowledged.
The interrupt procedure has
no effect on the flow of Data packets.
The one byte of interrupt data
is a user-defined field and is of no significance to the PPSN.

1.5.2

Resets

The reset procedure allows a DTE to reinitialize a virtual circuit by
resetting the lower window edge and P(R) and P(S) numbers to zero.
All Data and Interrupt packets in the network are discarded.
The
reset procedure uses the method of flow control for control packets
(see Section 1.4.1).

1.5.3

Restarts

The restart procedure allows a DTE or DCE to clear and reinitialize
all circuits.
Usually,
restarts are used only for non-recoverable
error conditions or link initialization. During a restart,
the DTE
discards all outstanding Data and Interrupt packets on all channels.
The DTE or DCE executes this procedure as needed;
the user has no
control over the procedure. For flow control, the restart procedure
uses the method for control packets (see Section 1.4.1).

1.5.4

Optional Facilities

Three types of optional facilities are offered by PPSNs:
•

Those that require no prior arrangement at subscription time
but can be requested on a per call basis; that is, they can
be requested by specifying fields in the Call Request packet.

•

Those that require prior arrangement at subscription time and
always apply from then on.

•

Those that require prior arrangement at subscription time and
then may be optionally requested on a per call basis.

1-12

INTRODUCTION TO PACKET SWITCHING
The optional facilities are:
•

Bilateral Closed User Group (BCUG) The BCUG restricts a
DTE to communicating with another single DTE.
If used, this
must be subscribed to with the PPSN and, when used, specified
on a per call basis.
The facility is applicable to SVCs
only.
There is an addition to this basic facility:
BCUG with
outgoing access.
This allows a DTE to initiate calls to DTEs
outside their BCUG.

•

Closed User Group
(CUG) The CUG restricts a DTE to
communicating with two or more DTEs in the same group.
If
used, this facility must be subscribed to with the PPSN and,
when used,
specified on a per call basis. The facility is
applicable to SVCs only.
Additions to this basic facility, which may be subscribed
separately or together are:

CUG with outgoing access - allows a DTE to initiate calls
to DTEs outside their CUG.
CUG with incoming access - allows a DTE to receive
from DTEs outside their CUG.

calls

•

Throughput Class Negotiation Throughput class is the
maximum rate of data transmission for a particular SVC.
Throughput class negotiation allows a DTE to request a higher
or lower data rate depending on the throughput of data
packets.
If used, this facility must be subscribed to with
the PPSN and specified on a per call basis.

•

Default Throughput Class Assignment - This permits a DTE to
specify a default Throughput Class different from the PPSN's
default.
If used, this facility must be subscribed to with
the PPSN.

•

Fast Select This allows a DTE to include a user data field
in any Call Request, Call Accepted, or Clear Request packet
that is longer than 16 bytes.
If used, this facility must be
subscribed to with the PPSN and, when used, specified on a
per call basis.
The facility is applicable to SVCs only.
There are qualifiers to this basic facility, as follows:
No restriction on response - allows the remote DTE to
accept or reject the request to set up a virtual circuit
and also reply with user data.
Restriction on response - prevents the remote DTE from
accepting the request to set up a virtual circuit but
allows user data to be sent with the rejection.

•

Fast Select Acceptance This allows a DTE to accept
Incoming Call packets that contain a user data field.
If
used, this facility must be subscribed to with the PPSN.

1-13

INTRODUCTION TO PACKET SWITCHING
•

Flow Control Parameter Negotiation - This permits selection
of maximum packet sizes and window sizes in each direction of
a particular virtual circuit.
If used, this facility must be
subscribed to with the PPSN and, when used, must be specified
on a per call basis.
The values specified must be acceptable
to the PPSN to which the DTE is connected.

Nonstandard Default
• specify
a default
default.
the PPSN.

Packet size - This permits a DTE to
packet size different from the PPSN's
If used, this facility must be subscribed to with

Nonstandard Default
• specify
a default
default.
the PPSN.

Window size - This permits a DTE to
window size different from the PPSN's
If used, this facility must be subscribed to with

•

One-way Logical Channel Incoming - This prevents a particular
logical channel from handling outgoing calls.
If used, this
facility must be subscribed to with the PPSN.

•

One-way Logical Channel Outgoing - This prevents a particular
logical channel from handling incoming calls.
If used, this
facility must be subscribed to with the PPSN.

•

Incoming Calls Barred - This prevents a DTE from receiving
any calls.
If used, this facility must be subscribed to with
the PPSN.

•

Outgoing Calls Barred - This prevents a DTE from initiating
any calls.
If used, this facility must be subscribed to with
the PPSN.

•

Incoming Calls Barred within a CUG This prevents a DTE
from receiving any calls from within a CUG.
If used, this
facility must be subscribed to with the PPSN.

•

Outgoing Calls Barred within a CUG - This prevents a DTE from
initiating any calls within a CUG.
If used, this facility
must be subscribed to with the PPSN.

•

Reverse Charging - This allows a DTE to request that the
remote DTE pays for the call.
If used, this facility must be
subscribed to with the PPSN and, when used,
specified on a
per call basis.

•

Reverse Charging Acceptance - This allows a DTE to accept a
request for reverse charging.
If used, this facility must be
subscribed to with the PPSN.

•

Extended Packet Sequence Numbering - This allows a DTE to
change the packet sequence peS)
numbering to modulo 128
instead of modulo 8.
If used,
this facility must be
subscribed to with the PPSN.

•

Packet Retransmission - This allows a
DTE
to
request
retransmission of one or more Data packets by specifying a
peR) in a Reject packet.
If used,
this facility must be
subscribed to with the PPSN.

•

RPOA Selection - This allows a DTE to specify a Remote Port
of Access to another PPSN if access to more than one PPSN is
permitted.
If used, this facility must be subscribed to with
the PPSN and, when used, must be specified on a per call
basis.
1-14

PART II
X.25 Reference Guide

CHAPTER 2
THE TOPS-IO X.2S SOFTWARE

The TOPS-IO PSI software contains the following three modules:
•

TOPS-IO PSI Gateway Access Routines

•

TOPS-IO PSI Gateway Software

•

X29SRV, the TOPS-IO X.29 Software

Figure 2-1 illustrates the placement of the TOPS-IO PSI Gateway Access
Routines and the TOPS-IO Gateway Software in the central (TOPS-lO)
processor and the communications processor (DTE).
(For information on
the
TOPS-IO X.29 Software, see Part III of this manual.)
To
communicate ~rough a PPSN, you place TOPS-IO PSI subroutine calls
within your FORTRAN-IO or MACRO-IO program.
These subroutine calls
are described in Chapters 3 and 4.
The FORTRAN-IO or MACRO-IO program
collects the data to be sent and passes it to the TOPS-IO PSI Gateway
Access Routines. These routines assemble an access protocol message,
set up a DECnet logical link, and pass the data to the TOPS-IO PSI
Gateway Software.
This software reconstitutes the message
for
transmission on a virtual circuit and reformulates the message into
X.2S packets.

2-1

THE TOPS-10 X.2S SOFTWARE

Local
OECsystem-10
TOPS-10
Node , . - - - - - - - - - - - .
User Program
TOPS-10 PSI
Gateway
Access Routines

X.25

Gateway
Access
Protocol

Remote
OTE

Remote
Node
Remote
User
Program

MR-S-3710-84

Figure 2-1:

TOPS-10 PSI Gateway Software Components

2-2

THE TOPS-10 X.2S SOFTWARE
The TOPS-IO PSI Gateway Software controls data transmission,
ensures
error-free data, and manages the X.25 port through which communication
to the PPSN occurs.
This software provides the functions required to
implement TOPS-IO PSI protocol levels 1, 2, and 3 (see Section 1.2.1).
Once the TOPS-IO PSI Gateway Software sends the packets across the
virtual circuit into the X.25 PPSN, the PPSN controls the transmission
of the packets until they reach their destination.
If the message
must travel across more than one PPSN, each PPSN provides the facility
for connecting to the adjoining PPSN.
An incoming message is handled
in the reverse order from an outgoing message.

2.1

TOPS-10 PSI SOFTWARE FUNCTIONS

Where there is communication between user processes at peer
levels
(equivalent network layers)
in widely separated processors,
the
processes use a protocol. Where adjacent network layers communicate,
they use an
interface.
The TOPS-IO
PSI Software provides the
protocols and any other services needed for you to communicate with
the PPSN.
The TOPS-IO PSI Gateway Access Routines provide the interface between
the X.25 user program and the local DTE, which is connected to the
PPSN.
This interface uses UUO calls to
interact with
the TOPS-IO
operating system at the user level.
The TOPS-IO PSI Gateway Access Routines establish a communications
path to the local DTE through a DECnet logical link to the DN20 (PSI
Gateway) over which access protocol messages pass.
The user program
controls the logical link with subroutines that format and interpret
protocol messages.
The local DTE, which is connected to the PPSN,
communicates with the PPSN through a virtual circuit.
Table 2-1 summarizes the subroutines available to communicate through
a
PPSN.
Chapters 3 and 4 describe them in greater detail.
Table 2-1
lists the subroutines in the order
in which they should be used;
subroutines that open virtual circuits are listed first; subroutines
used with open virtual circuits are listed next;
subroutines that
close virtual circuits are listed last.

2-3

THE TOPS-IO X.2S SOFTWARE
Table 2-1:

TOPS-IO PSI Gateway Access Routine Functions

Function

Action

Type of Packet This
Function Sends or
Reads

OPEN PERMANENT
CIRCUIT

Opens access to
a PVC.

None.

Reserves the PVC for
the exclusive use of
the caller.
Assigns a port in
the X.2S Access
module.
WAIT INCOMING
CALL

Designates a port as
willing to accept
incoming calls.

None.

INITIATE SWITCHED
CIRCUIT

Issues a call to a
remote DTE to
establish an SVC.

Sends a Call Request
packet.

Assigns a port in
the X.2S Access
module.
READ ACCEPT
DATA

Obtains data sent by
the remote DTE when
the remote DTE
accepted a call.

Reads
a
Call
connected packet.

READ INCOMING
CALL

Obtains all data
accompanying an
incoming call.

Reads
an
Incoming
call packet.

ACCEPT INCOMING
CALL

Accepts an incoming
call.

Sends a Call Accepted
packet.

RESET VIRTUAL
CIRCUIT

Resets (or
acknowledges the
reset of) a virtual
circuit.

Sends a Reset Request
or Reset Confirmation
packet.

READ RESET
DATA

Obtains data sent by
the remote DTE when
the remote DTE reset
the virtual circuit.

Reads
a
Reset
Indication packet.

SEND DATA
MESSAGE

Transmits one packet
of data over a
virtual circuit.

Sends a Data packet.

READ DATA
MESSAGE

Obtains a packet of
data transmitted by
a remote node over
a virtual circuit.

Reads a Data packet.

SEND INTERRUPT
MESSAGE

Transmits an
interrupt byte over
a virtual circuit.

Sends
an
packet.

2-4

Interrupt

THE TOPS-IO X.2S SOFTWARE
Table 2-1:

TOPS-10 PSI Gateway Access Routine Functions (Cont.)

Function

Action

Type of Packet This
Function Sends or
Reads

READ INTERRUPT
MESSAGE

Obtains an interrupt
byte transmitted by
a remote node over a
virtual circuit.

Reads
an
packet.

CONFIRM INTERRUPT
MESSAGE

Confirms receipt of
an interrupt byte.

Sends an Interrupt
Confirmation packet~

READ PORT
STATUS

Obtains the state of
the X.25 access
port.

None.

NO COMMUNICATION
SEEN

Acknowledges failure
of a PVC due to loss
of communication
with the PPSN.

None.

CLEAR SWITCHED
CIRCUIT

Clears an SVC.

Sends a Clear
Request packet.

READ CLEAR
DATA

Obtains data sent by
the remote DTE when
that DTE cleared the
SVC.

Reads a Clear
Request packet.

TERMINATE PORT
ACCESS

Releases all
resources
associated with a
specific access
port.

None.

You can use many
your connection
functions can be
2-2 correlates
can be used with

Interrupt

TOPS-10 PSI Gateway Access Routine functions whether
is over an SVC or a PVC.
However, some of the
used only with one type of virtual circuit.
Table
the types of virtual circuits with the functions that
them.

2-5

THE TOPS-lO X.2S SOFTWARE
Table 2-2:

Types of Virtual Circuits and the Functions
Used wi th Each

that

Can

Functions that Can
Be Used Only with
SVCs

Functions that Can Be
Used Only with PVCs

Functions that Can Be
Used with SVCs and
PVCs

ACCEPT INCOMING
CALL

NO COMMUNICATION
SEEN

CONFIRM INTERRUPT
MESSAGE

CLEAR SWITCHED
CIRCUIT

OPEN PERMANENT
CIRCUIT

READ DATA MESSAGE

INITIATE SWITCHED
CIRCUIT

READ INTERRUPT
MESSAGE

READ ACCEPT DATA

READ PORT STATUS

READ CLEAR DATA

READ REpET DATA

READ INCOMING CALL

RESET VIRTUAL CIRCUIT

WAIT INCOMING CALL

SEND DATA MESSAGE

SEND INTERRUPT
MESSAGE
TERMINATE PORT ACCESS
The TOPS-lO PSI Gateway Access Routines assign a port to a
user
program - providing the port resources exist - when the user program
issues one of the following subroutine calls:
•

OPEN PERMANENT CIRCUIT

•

INITIATE SWITCHED CIRCUIT

•

WAIT INCOMING CALL

The user program can then use the port number supplied by the TOPS-lO
PSI Gateway Access Routines to refer to the virtual circuit created by
these events.

2.2

PORT STATES

A port state, which is represented by a decimal value,
is associated
with each port.
The state of a port changes because of user action or
because of events perceived by the TOPS-IO PSI Gateway Access
Software.
Issuing certain commands can cause a port state change that
is necessary for subsequent actions.
For example, when you invoke the
INITIATE SWITCHED CIRCUIT function to create a connection to a remote
DTE, you must wait until
the port state changes from CALLING to
RUNNING before you can transmit data.
You poll the port state with
the READ PORT STATUS function to determine when the port has entered
the RUNNING state.
Table 2-3 lists port states.

2-6

THE TOPS-lO X.2S SOFTWARE
Table 2-3:

TOPS-lO PSI Gateway Port States

State

Decimal
Value

Meaning

UNDEFINED

Occurs when the port is not assigned.

OPEN

Occurs when you issue an OPEN PERMANENT
CIRCUIT function for a PVC but have not
yet received a response from the local
DTE.
Success of the OPEN
PERMANENT
CIRCUIT changes the port
state
to
RUNNING or UNSYNC.

CALLING

Occurs when the port user
issues an
INITIATE SWITCHED CIRCUIT. Remains until
one of the following occurs:

•

The
destination
rejects the call.

DTE

accepts

• You issue a CLEAR SWITCHED CIRCUIT.
call fails due to lack of
• The
resources in the X.2S gateway node.
If the destination DTE accepts the call,
the port enters the RUNNING state and
data transmission can proceed.
LISTENING

Occurs when you issue a WAIT INCOMING
CALL function to make the port available
to receive an incoming call for a DECnet
connection from the TOPS-lO PSI Gateway
Software.

CALLED

Occurs when
an
incoming
call
is
associated with the port and remains
until you accept or reject the call (see
READ INCOMING CALL in
TOPS-IO
PSI
Gateway Access Routine Functions, Table
2-1) •

RUNNING

Occurs
when
the associated virtual
circuit is available for data transfer.

SYNC

Occurs when you issue a RESET VIRTUAL
CIRCUIT call, but the reset has not yet
been confirmed.
In a SYNC state, the
port is not available for data transfer.
You must poll the port state and wait
until it changes to RUNNING.

UNSYNC

Occurs when the PPSN or remote user
initiates the reset of the
virtual
circuit, but you do not
issue a RESET
VIRTUAL CIRCUIT to acknowledge. The port
is not available for data transfer.
Before transferring more data, you must
issue a RESET VIRTUAL CIRCUIT, which
changes the port state from UNSYNC to
RUNNING.

2-7

THE TOPS-IO X.25 SOFTWARE
Table 2-3:

TOPS-IO PSI Gateway Port States (Cont.)

r--.---------------r-----------.----------------------------------------.------~

State

Decimal
Value

Meaning

CLEARING

Occurs when you
invoke
the
CLEAR
SWITCHED CIRCUIT call to clear
the
switched virtual circuit, but the public
network has not yet sent confirmation.

CLEARED

Occurs when the switched virtual circuit
has been cleared by the public network
or the remote DTE.
To exit from this
state, you must close the port (see
TERMINATE PORT ACCESS in TOPS-IO PSI
Gateway Access Routine Functions, Table
2-1) •

ERROR

Occurs when the TOPS-IO PSI Gateway
Software
detects
a
fatal
error
condition.
Use the READ PORT STATUS
function to determine the nature of the
error. When the port state is ERROR, you
cannot communicate over the PPSN.
To
clear this state, use the TERMINATE PORT
ACCESS function.

NO
COMMUNICATION

Occurs when
happened:

one

the following has
a
Restart
for
the

•

The PPSN has
sent
Indication
packet
associated DTE.

•

The
frame level underlying
virtual circuit has failed.

•

An operator has set the associated
DTE to the OFF State. You have not
executed the NO COMMUNICATION SEEN
function.

the

The sequence of port state changes is governed by whether the virtual
circuit connection to the PPSN is permanent or switched. Certain port
states such as LISTENING pertain only to switched virtual circuits.
Tables 2-4 and 2-5 describe the port state changes.

2-8

THE TOPS-IO X.2S SOFTWARE
Table 2-4:

State Changes for PVC Ports

Old State

New State

Cause of Change

any

UNDEFINED

You issue
ACCESS.

TERMINATE

PORT

any state
but OPEN

NO
COMMUNICATION

Communication with the
node or PPSN is lost.

X.2S

NO
COMMUNICATION

RUNNING

You
execute
the
NO
COMMUNICATION SEEN function.

OPEN

ERROR

One of the fOllowing:

•

Insufficient resources to
maintain another port.

•

The requested
already in use.

PVC

The requested PVC is not
• defined.

•

Communication
X.2S node or
been lost.

with
PPSN

the
has

OPEN

RUNNING

The requested PVC is assigned
to you, and the remote user
has not sent any unconfirmed
resets.

OPEN

UNSYNC

The requested PVC is assigned
to you,
and there
is
an
unconfirmed reset from
the
remote
user.
You
should
confirm the reset with a RESET
VIRTUAL CIRCUIT.

RUNNING

SYNC

You
issue a RESET VIRTUAL
CIRCUIT
but
it
is
not
confirmed by the PPSN.

RUNNING

UNSYNC

The PPSN requests a reset and
waits for the local user to
issue a RESET VIRTUAL CIRCUIT.

SYNC

RUNNING

The public
network
confirms an
earlier
VIRTUAL CIRCUIT by you.

UNDEFINED

OPEN

You issue an OPEN PERMANENT
CIRCUIT to communicate with a
remote DTE.

UNSYNC

RUNNING

previous
You acknowledge a
reset request from the public
network with a RESET VIRTUAL
CIRCUIT.

2-9

(PPSN)
RESET

THE TOPS-IO X.25 SOFTWARE
Table 2-5:

State Changes for SVC Ports

~.------------~------------~----------------------------------------------~

Old State

New State

Cause of Change

any

ERROR

Communication with the X.25
public network has been lost.

any

UNDEFINED

You issue a TERMINATE PORT ACCESS.

CALLED

CLEARED

An
incoming call request is cleared by
the remote user before you act.

CALLED

CLEARING

You reject an incoming call with a CLEAR
SWITCHED CIRCUIT, but the remote user
has not yet confirmed this rejection.

CALLED

RUNNING

You accept an
incoming call with the
ACCEPT INCOMING CALL function.

CALLING

CLEARED

The remote DTE rejects a call request
originating when you request an INITIATE
SWITCHED CIRCUIT.

CALLING

CLEARING

You
issue a CLEAR SWITCHED
CIRCUIT
request
after
an
INITIATE SWITCHED
CIRCUIT before the remote DTE could
respond
to
the
INITIATE
SWITCHED
CIRCUIT.

CALLING

RUNNING

The remote DTE accepts a call request
originating from an
INITIATE SWITCHED
CIRCUIT that you issued.

CLEARING

CLEARED

The public network confirms
have cleared the circuit.

LISTENING

CALLED

An
incoming call
listening port.

RUNNING

CLEARED

The public network has cleared
the
circuit, and the local DTE has confirmed
the clearing.

RUNNING

CLEARING

You have used the CLEAR SWITCHED CIRCUIT
function
to request clearing of the
circuit.

RUNNING

SYNC

You
issue a
RESET VIRTUAL CIRCUIT not
yet confirmed by the public network.

RUNNING

UNSYNC

The public network
request and awaits
CIRCUIT from you.

SYNC

CLEARED

The public network has cleared
the
circuit, and the local DTE has confirmed
the clearing.

SYNC

CLEARING

You have issued a CLEAR SWITCHED CIRCUIT
to clear the circuit.

2-10

has

node

that

arrived

you
on

has issued a reset
a
RESET
VIRTUAL

THE TOPS-IO X.25 SOFTWARE
Table 2-5:

State Changes for SVC Ports (Cant.)

Old State

New State

Cause of Change

SYNC

RUNNING

A previous request for a RESET VIRTUAL
CIRCUIT from you
is confirmed by the
public network.

UNDEFINED

CALLING

You issue an INITIATE SWITCHED CIRCUIT
to communicate with a remote DTE.

UNDEFINED

LISTENING

You issue a WAIT INCOMING CALL
for an incoming call.

UNSYNC

CLEARED

The public network clears the circuit
and the X.25 software confirms
the
clear.

UNSYNC

CLEARING

You
issue a CLEAR SWITCHED
request to clear the circuit.

UNSYNC

RUNNING

You acknowledge a previous reset request
from the public network with a RESET
VIRTUAL CIRCUIT.

wait

CIRCUIT

Table 2-6 shows TOPS-IO Gateway Access Routine functions
with
corresponding port states.
The port must be in the given state before
the X.25 function can be issued.
Table 2-6 lists the X.25 functions
in the order in which they are used.

2-11

THE TOPS-lO X.2S SOFTWARE
Table 2-6:

TOPS-lO Gateway Access Routine Functions
States

and

Their

Port States

~
~()"
~~
~<"~

~
~ "< C <~ ~
~ ~~ <~ ~ C'-cf

~
~~ ~~

~ o~ <~ ~<~ '90 ~~ \S'~ \S'~ ~~ -cf~~ ~~ ~o
~

Functions

OPEN PERMANENT CIRCUIT

INITIATE SWITCHED CIRCUIT

WAIT INCOMING CALL

READ ACCEPT DATA
--

READ INCOMING CALL

ACCEPT INCOMING CALL

CLEAR SWITCHED CIRCUIT

X
X

READ CLEAR DATA

RESET VIRTUAL CIRCUIT

X
X

READ RESET DATA
SEND DATA r,nESSAGE
READ DATA MESSAGE

X
X

._-

SEND INTERRUPT MESSAGE

READ INTERRUPT MESSAGE

CONFIRM INTERRUPT MESSAGE

READ PORT STATUS
TERMINATE PORT ACCESS

._-

X
X

NO COMMUNICATION SEEN

MR-S-3713-84

2-12

Port

THE TOPS-I0 X.2S SOFTWARE
2.3

THE PROGRAMMING ENVIRONMENT

The packet switching technique used in the PPSNs is transparent to the
user.
After the user program collects data to be transmitted, the
program passes that data to the TOPS-I0 PSI Software, which forms the
data into packets.
The PPSN adds routing information to each packet
and uses that information to carry the packet to its destination.
At
the destination,
the PPSN discards routing information and converts
the packets into their original form.
The TOPS-IO X.25 software uses the virtual circuit concept, which is
described
in Section 1.1,
to establish a logical link between two
stations in the network.
The virtual circuits have the following
characteristics:

2.4

•

They allow simultaneous
(full-duplex) •

data

exchange

two

directions

•

They provide flow control, so that two stations operating
different speeds can work together.

•

They permit multichannel access so that one
processor
connected
to a PPSN with a single physical line can
communicate with several destinations over several virtual
circuits.

•

They can be either permanent or switched.

TYPES OF USER PROGRAMS

When you write a program that calls TOPS-IO X.25 subroutines,
program can perform one or more of the following functions:
•

Initiating an SVC Call and using the SVC

•

Receiving an SVC Call and using the SVC

•

Using a PVC

Furthermore, a program that performs one or more
should contain three sections, which are:

these

that

functions

•

Initialization - initiating communication between
and remote nodes

the

local

•

Sending and receiving - sending and receiving data
and
interrupts as well as handling resets between the local and
remote nodes

•

Conclusion - terminating communication between the local
remote nodes

and

The following sections describe the contents of each of the parts of a
user program that calls TOPS-I0 X.25 subroutines.

2-13

THE TOPS-IO X.2S SOFTWARE
2.4.1

Initiating an SVC Call and Using the SVC

When you write a program that
following steps:
1.

initiates

SVC

call,

perform

the

Initialization
•

Execute the INITIATE SWITCHED CIRCUIT function,
which
initiates an SVC call to a remote DTE and changes the
port state to CALLING.

•

Execute the READ PORT STATUS function to determine if the
port state has changed to CLEARED or RUNNING.

•

If the port state has become CLEARED, the remote DTE or
remote node has rejected your calli execute the TERMINATE
PORT ACCESS function before using the port again.
If the
port state has become RUNNING,
the remote node has
accepted your call, and your program can continue.

Sending and Receiving
The TOPS-10 X.2S software includes
that:

•

Send and receive data

•

Send and read interrupts

•

Send and respond to reset requests

group

subroutines

Regardless of whether your program conducts communication
over an SVC or a PVC,
the same group of TOPS-10 X.2S
subroutines is used to perform those functions.
Table 2-2
lists this group of subroutines as the functions that you can
use with SVCs and PVCs.
When sending or receiving data:
•

Execute the SEND DATA MESSAGE function to send data

•

Execute the READ DATA MESSAGE function to receive data
NOTE
The TOPS-10 PSI Gateway maintains flow control of
Data packets.
This relieves you of the need to
maintain the packet send
(P(S))
and
packet
receive
(P(R))
sequence numbers, which are
discussed in Section 1.4.2.

When sending or reading interrupt data:
•

Execute the SEND INTERRUPT MESSAGE function to send
interrupt data.
The X.2S software allows no more than
one outstanding unacknowledged interrupt.

•

Execute the READ PORT STATUS function to determine if
interrupt has been acknowledged,

•

Execute the READ INTERRUPT MESSAGE function to
interrupt data transmitted by the remote node.

2-14

obtain

THE TOPS-IO X.25 SOFTWARE
function
to
Execute the CONFIRM INTERRUPT MESSAGE
• acknowledge
receipt of an interrupt transmitted by a
remote node.
Note that because flow control
of
interrupts
occurs
independent of data flow control, interrupts can overtake
other transmitted data.
When handling resets:

•

Execute the RESET VIRTUAL
that a virtual circuit
reset.

•

Use the READ PORT STATUS function
virtual circuit has been reset.

•

Execute the READ RESET DATA function to obtain the cause
and diagnostic codes from the Reset Indication Packet.

CIRCUIT function to request
be reset or to acknowledge a
to

determine

When a reset request has been made, data and interrupts
are in transit on the virtual circuit can be discarded.
3.

2.4.2

that

Conclusion
•

Execute the READ PORT STATUS function.

•

If the port state is CLEARED, the remote node has cleared
the SVC you have been using; execute the READ CLEAR DATA
function to obtain any information the remote node sent
when it cleared the SVC.
If the port state is not
CLEARED, execute the CLEAR SWITCHED CIRCUIT function to
terminate the SVC you have been using.

•

Execute the TERMINATE PORT ACCESS
releases the port you have been using.

which

function,

Receiving an SVC Call and Using the SVC

When you write a program that is to receive an SVC call,
following steps:
1.

perform

the

Initialization
•

Execute the WAIT INCOMING CALL
your job to receive a call.

function,

•

Execute the READ PORT
state becomes CALLED.

function

•

Execute the READ INCOMING CALL function, which obtains
any data sent from the remote node when the call was
made. Use that data to deter.mine whether to accept or
clear the call.

•

Execute the ACCEPT
CIRCUIT function.

STATUS

INCOMING

2-15

CALL

which
until

CLEAR

enables
the

port

SWITCHED

THE TOPS-IO X.2S SOFTWARE
2.

Sending and Receiving
•

Send and receive data and interrupts.
Send and
respond
to reset requests.
For information on performing these
functions, see item 2 in Section 2.4.1.

Conclusion
•

Execute the READ CLEAR DATA or CLEAR SWITCHED CIRCUIT
function,
then
execute
the TERMINATE PORT ACCESS
function.
For information on pe~forming these functions,
see item 3 in Section 2.4.1.

Using a PVC

2.4.3

When you write a program
following steps:
1.

uses

PVC,

you

must

include

the

Initialization
•

Execute the OPEN PERMANENT CIRCUIT function,
which
acquires the specified PVC for your exclusive use at your
node.

•

Execute the READ PORT STATUS function to determine if the
port state has changed to UNSYNC, RUNNING, or ERROR.
If
the port state has changed to UNSYNC, the PPSN or
remote
node has
initiated a
reset; execute the RESET VIRTUAL
CIRCUIT function, and continue.
If the port state is
ERROR, the TOPS-IO PSI Gateway Software has rejected your
open request; to recover,
execute the TERMINATE PORT
ACCESS function,
then again execute the OPEN PERMANENT
CIRCUIT function.

Sending and Receiving
•

that

Send and receive data and interrupts.
Send and
respond
to reset requests.
For information on performing these
functions, see item 2 in Section 2.4.1.

Conclusion
•

Execute the TERMINATE PORT ACCESS,
which
the PVC and the port you have been using.

2-16

releases

both

CHAPTER 3
FORTRAN-IO SUBROUTINE CALLS

3.1

FORTRAN-IO AND THE TOPS-IO PSI GATEWAY ACCESS SOFTWARE

When issuing TOPS-IO PSI Gateway Access subroutine calls in FORTRAN-IO
programs, you normally specify variable names for the subroutine
arguments.
You must also place values in some of the variables you
have named before your FORTRAN-IO program is executed.
In other
cases, the subroutine returns values in variables you have named as
the program is executed.
Discussions of the FORTRAN-IO TOPS-IO PSI Gateway Access subroutine
calls in section 3.2 explain which values you must supply and which
values are returned by the software.
This section lists the types of variables you can
FORTRAN-IO TOPS-IO PSI Gateway Access subroutine calls.

specify

These data types are not necessarily the standard FORTRAN-IO data
types.
For
information on standard FORTRAN-IO data types, see the
TOPS-IO/20 FORTRAN Language Manual.
The data types are:
8-BIT BYTE

the rightmost 8 bits in a word,
otherwise specified in Section 3.2.

8-BIT BYTE ARRAY

a I-dimensional array composed of four 8-bit
bytes per word.
These 8-bit bytes are left
justified in each word; the rightmost 4 bits
in each word are unused.

INTEGER

a whole decimal number that occupies one word
and is in the range (-2**35)-1 to (+2**35)-1.

INTEGER ARRAY

a I-dimensional array composed of integers.

ASCII STRING

a
string
of
contiguous
7-bit
ASCII
characters.
These
characters
are left
justified on the word boundary of the first
word and terminated by a null character in
the word following the last word of the
string.

LOGICAL

a variable that can have a
.TRUE. or .FALSE.

3-1

value

unless

either

FORTRAN-IO SUBROUTINE CALLS
The names of the subroutine arguments in Section 3.2 do not follow the
FORTRAN-IO convention specifying that variable names beginning with
the letters I, J, K, L, M, or N are integer variables.
To determine
whether a variable
is an
integer,
read
the description of that
variable.
NOTE
Since FORTRAN-IO does not allow null parameters in an
argument list, specify a null string with the value O.

3.2

SENDING AND RECEIVING DATA

This section discusses how to send and receive data
in a FORTRAN-I0
program and how the FORTRAN-callable TOPS-I0 PSI Gateway Access
Routines convert data before and after transmission through a PPSN.
The subroutine that queues data for transmission to a
PPSN is SEND
DATA MESSAGE,
and the subroutine that receives data transmitted
through a PPSN is READ DATA MESSAGE.
The FORTRAN-callable SEND DATA
MESSAGE subroutine is X25SDMi the FORTRAN-callable READ DATA MESSAGE
subroutine is X25RDM.
The names of arguments used in calling X25SDM
and X25RDM are noted throughout this section.
See the discussions of
X25SDM and X25RDM in Section 3.4 for more information about those
arguments.
When calling X25SDM:
•

Specify an array of data to
argument.

•

Specify a value that indicates how the TOPS-I0
PSI Gateway
Access Routines should interpret the data to be transmitted
in the dtype argument (See Table 3-1 for a list of values you
can specify for dtype).
The value you should specify for
dtype depends on the destination for the data and the type of
data being transmitted.
To transmit 36-bit binary data to
another TOPS-I0 system, specify 0 for dtype
(see Section
3.2.1) •
To transmit any type of data to another operating
system (for example, one that has a word size other than 36
bits),
specify a value other than 0 for dtype (see Sections
3 • 2 • 2 and 3. 2 • 3) •

transmitted

the

datbuf

When calling X25RDM:
•

Specify an array to
argument.

contain

•

Specify a value that indicates how received data
is to be
placed in datbuf in the dtype argument. When calling X25RDM,
the value you should specify for dtype depends on the source
of the data and the type of data being transmitted.
For
example, if 36-bit binary data was transmitted by a
TOPS-I0
system and dtype 0 was specified in the X25SDM call at that
system, specify a value of 0 in the X25RDM call (see Section
3.2.1) •

3-2

received

data

the

datbuf

FORTRAN-10 SUBROUTINE CALLS
3.2.1

Conversion of 36-Bit Binary Data in TOPS-10/TOPS-10 Transfers

When you write programs to transmit 36-bit binary data between two
TOPS-10 systems, specify a value of 0 for dtype in all X25SDM and
X25RDM subroutine calls. Doing so ensures the integrity of data
transmitted between the two TOPS-IO systems.
Calling X25SDM with dtype 0 causes the TOPS-IO PSI Gateway Access
Routines to treat the entire array specified in datbuf as a stream of
bits. Before transmitting this data to a PPSN,
the Access Routines
convert the data into eight-bit units called octets. This conversion
is performed from left to right through the array specified in datbuf.
The first bit in datbuf becomes the most significant (left-most) bit
in the first octet. The eighth bit in datbuf becomes the least
significant
(right-most)
bit in the first octet.
The ninth bit
becomes the most significant bit in the second octet, and so on.
If
the last octet formed contains fewer than eight bits, the Access
Routines fill the remaining positions in that octet with binary zeros.
Calling X25RDM with dtype 0 causes the TOPS-IO PSI Gateway Access
Routines to copy the data from received octets into successive bit
positions in elements of the receiving datbuf array.

3.2.2

Other Types of Binary Data Conversion

When you write programs that send and/or receive non-36-bit binary
data,
specify dtype value 1,
2,
3, or 4.
(See Table 3-1 for
information about these dtype values.)
When you specify dtype value 1, 2, 3, or 4 in an X25SDM call,
the
TOPS-10 PSI Gateway Access Routines treat each element of the array
specified in datbuf as a series of 8-bit bytes.
The Access Routines
format each 8-bit byte into an octet. This formatting occurs left to
right through the datbuf array.
When you specify dtype value 1, 2, 3, or 4
in an X25RDM call, the
Access Routines format the received octets into 8-bit bytes and place
these 8-bit bytes in the datbuf array.
This conversion occurs
according
to the value you give dtype.
If the two programs
transmitting and receiving data are both running on TOPS-10 systems,
specify the same value for dtype in the X25RDM call as was used in the
X25SDM call.

3.2.3

ASCII Data Conversion

When you write programs that send and/or receive 7-bit ASCII data,
specify dtype value 5, 6, 7, 8, or 9.
(See Table 3-1 for information
about these dtype values.)
When you specify dtype value 5, 6, 7, 8, or 9 in an X25SDM call, the
TOPS-10 PSI Gateway Access Routines format each 7-bit ASCII character
from the datbuf array into one octet. The Access Routines set the
most significant
(left-most) bit in the octet to O.
This formatting
occurs left to right through the datbuf array.
When you specify dtype value 5, 6, 7, 8, or 9 in an X25RDM call, the
Access Routines format the received octets into 7-bit bytes in the
datbuf array.
The number of 7-bit bytes per array element depends
upon the value you specify for dtype. The Access Routines ignore the
most significa\t (left-most) bit of each received octet.
3-3

FORTRAN-IO SUBROUTINE CALLS
3.3

LINKING A FORTRAN-IO PROGRAM

The FORTRAN-IO TOPS-IO PSI Gateway Access Routines are in the library
file X25GAF.REL. After you have written a program and compiled it to
produce relocatable object modules, you must link the modules with
X25GAF.REL to produce an executable image file.
To link your program,
type:
• R LINK C~
*REL:X25GAF.REL, object-l[, ••• , object-nJ
*/SAVE /GO ~

where:
object-l through object-n are the names of your relocatable
object modules.

3.4

THE SUBROUTINE CALLS

The TOPS-IO PSI Gateway Access Routine functions summarized in Chapter
2 are described here as a set of FORTRAN-IO subroutine calls.
The
calls are in alphabetical order in the following format:
•

A title that contains the name of the FORTRAN-IO call and the
TOPS-IO PSI Gateway Access Routine function

•

Information on how to use the function

•

The call format

•

Descriptions of the subroutine arguments

3-4

FORTRAN-IO SUBROUTINE CALLS

X25AIC

ACCEPT INCOMING CALL

Use the X25AIC subroutine to accept an incoming call request.
You can
use data returned by the X25RIC (READ INCOMING CALL) subroutine to
determine whether to accept an incoming call.
Before you issue an
X25AIC subroutine call, the port state must be CALLED.
The format of the X25AIC subroutine call is:
CALL X25AIC (nport, usrgrp, facbuf, faclen, datbuf, datlen,
rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you
call X25WIC (WAIT INCOMING CALL)
to set up the
virtual circuit.

usrgrp

is a user-supplied ASCII string that contains the
name of a bilateral closed user group or closed
user group.
This name can be a maximum of 16
ASCII characters in length.
If you choose not to
supply the user group, specify 0 as the usrgrp
argument.

facbuf

is an 8-bit-byte array in which you place any
facilities
data needed to support your PPSN
service. Specify the length of facbuf in faclen.
(For information on facilities data,
see the
documentation for your PPSN. )

faclen

is a user-supplied integer that specifies the
length of facbuf
in 8-bit bytes. The maximum
value for faclen depends upon the value you
specify in usrgrp for this subroutine call:
•

If you specify a bilateral closed user group
in usrgrp, the maximum value for faclen is 60.

•

If you specify a closed user group in
the maximum value for faclen is 61.

usrgrp,

•

If you do not specify a value for user
the maximum value for faclen is 63.

group,

Your PPSN may further restrict this field.
datbuf

is an 8-bit-byte array in which
you
place
user-specified accept data. Specify the length of
datbuf in datlen.

datlen

is a user-supplied integer that specifies the
length of datbuf in 8-bit bytes. The maximum
value for datlen normally is 16 (or 128 for fast
select calls), although your PPSN may further
restrict this field.

3-5

FORTRAN-lO SUBROUTINE CALLS

X25AIC (Cont.)
rcode

is an integer variable in which X25AIC stores a
return code.
If rcode is nonzero, the incoming
call is not accepted.
Rcode values and their
meanings are:

The
X25AIC
subroutine
is
executed
successfully:
the incoming call is accepted,
and the port state changes from CALLED to
RUNNING.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25WIC before executing X25CIM.

•

You have attempted to
execute
this
subroutine when the port state is not
CALLED.

•

The logical link between the user job and
the Gateway node has been disconnected.

The facilities
because it is
the PPSN.

The user-specified accept data field
is
truncated because it is longer than the limit
set by the PPSN.

3-6

data field
is
truncated
longer than the limit set by

FORTRAN-IO SUBROUTINE CALLS

X25CIM

CONFIRM INTERRUPT MESSAGE

Use the X25CIM subroutine to confirm the receipt of interrupt data.
When you issue an X25CIM subroutine call, the port state must be
RUNNING.
Only one interrupt can be outstanding at a time.
The format of the X25CIM subroutine call is:
CALL X25CIM (nport, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED
CIRCUIT) ,
X250PC
(OPEN
PERMANENT
CIRCUIT), or X25WIC (WAIT INCOMING CALL) •

rcode

is an integer variable in which X25CIM stores a
return code.
If rcode is nonzero, the interrupt
is not confirmed.
Rcode values and their meanings
are:

The
X25CIM
subroutine
is
executed
successfully:
the received
interrupt is
confirmed.
The port state remains RUNNING.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:

•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25CIM.

•

execute
this
You have attempted to
subroutine when the port state is not
RUNNING.

•

The logical link between the user job and
the Gateway node has been disconnected.

No interrupt confirmation is requested.
The
PPSN does not send you an interrupt message
that requires confirmation.

3-7

FORTRAN-10 SUBROUTINE CALLS

X25CSC

CLEAR SWITCHED CIRCUIT

Use the X25CSC subroutine to terminate an SVC connection.
Once you
have executed the X25CSC subroutine, any data in transit can be lost,
and you can no longer communicate over the specified circuit.
However,
the port remains assigned; to release the port, execute the
X25TPA (TERMINATE PORT ACCESS) subroutine. When you issue an X25CSC
subroutine call,
the port state must be CALLED, CALLING, RUNNING,
SYNC, or UNSYNC.
The format of the X25CSC subroutine call is:
CALL X25CSC (nport, usrclr, usrgrp, facbuf, faclen, datbuf,
datlen, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you
call X25ISC (INITIATE SWITCHED CIRCUIT) or X25WIC
(WAIT
INCOMING CALL)
to set up the virtual
circuit.

usrclr

is a user-supplied 8-bit byte in which you place
the clear diagnostic for
transmission to the
remote DTE.
Users of the SVC choose values for
the clear diagnostic, which is the reason for
clearing the SVC.

usrgrp

is a user-supplied ASCII string that contains the
name of a bilateral closed user group or closed
user group.
This name can be a maximum of 16
ASCII characters in length.

facbuf

is an 8-bit-byte array in which you place any
facilities data required to support your PPSN
service.
Specify the length of facbuf in faclen.
(For
information on facilities data,
see the
documentation for your PPSN.)

faclen

is a user-supplied
integer that specifies the
length of facbuf
in 8-bit bytes.
The maximum
value for faclen depends upon the value you have
specified in usrgrp for this subroutine call:
•

If you have specified a bilateral closed user
group in usrgrp, the maximum value for faclen
is 60.

•

If you have specified a closed user group in
usrgrp, the maximum value for faclen is 61~

•

If you have not specified a value for
user
group, the maximum value for faclen is 63.

Your PPSN may further restrict this field.
datbuf

is an 8-bit-byte array in which
you
place
user-specified clear data.
Specify the length of
datbuf in datlen.

3-8

FORTRAN-IO SUBROUTINE CALLS

X25CSC (Cont.)
datlen

is a user-supplied integer that specifies the
length of datbuf in 8-bit bytes.
The maximum
value for datlen normally is 16 (or 128 for
fast
select calls), although your PPSN may further
restrict this field.

rcode

is an integer variable in which X25CSC stores a
return code.
If rcode is nonzero, the SVC is not
cleared.
Rcode values and their meanings are:

The
X25CSC
subroutine
is
executed
successfully:
a clear request is sent to the
PPSN, and the port state changes from RUNNING
to CLEARING.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC or X25WIC before executing
X25CSC.

•

You have attempted to
execute
this
subroutine when the port state is not
CALLING, CALLED,
RUNNING,
SYNC,
or
UNSYNC.

•

The logical link between the user job and
the Gateway node has been disconnected.

The facilities
because it is
the PPSN.

The user-specified clear data
field
is
truncated because it is longer than the limit
set by the PPSN.

3-9

data field
is
truncated
longer than the limit set by

FORTRAN-IO SUBROUTINE CALLS

X251SC

INITIATE SWITCHED CIRCUIT

Use the X25ISC subroutine to issue a virtual call request over a
switched virtual circuit to a remote DTE.
A successful return does
not indicate that the remote DTE has responded to the call. When the
remote DTE responds to the call, the port state changes from CALLING
to RUNNING (if the remote user accepted the call) or CLEARED
(if the
remote user rejected the call). When you issue an X25ISC subroutine
call, the port state must be UNDEFINED.
The format of the X25ISC subroutine call is:
CALL X25ISC (netwrk, passwd, dest, subadr, usrgrp, facbuf,
faclen, datbuf, datlen, buffer, nport, rcode)
where:
netwrk

is a user-supplied ASCII string that contains the
name
of
the
PPSN over which you want to
communicate. This name can be a maximum of 16
ASCII characters.

passwd

is a user-supplied ASCII string that contains the
password required for gaining access to the X.25
Gateway.
This password can be a maximum of 16
ASCII characters.
Your system manager determines
the X.25 Gateway Access password.
If you do not
need to use a password, specify 0 for the passwd
argument.

dest

is a user-supplied ASCII string that contains a
numeric string representing the address of the
called DTE.
This address can be a maximum of 15
ASCII characters.

subadr

is a user-supplied ASCII string that contains a
numeric string representing the address of the
calling DTE.
This address can be a maximum of 15
ASCII characters.
If you choose not to supply the
source-DTE address, specify 0 for
the subadr
argument.

usrgrp

is a user-supplied ASCII string that contains the
name of a bilateral closed user group or closed
user group.
This name can be a maximum of 16
ASCII characters.
If you choose not to supply the
user group, specify 0 as the usrgrp argument.

facbuf

faclen

is a user-supplied
integer that specifies the
length of facbuf
in 8-bit bytes.
The maximum
value for faclen depends upon the value you have
specified in usrgrp for this subroutine call:
•

If you have specified a bilateral closed user
group in usrgrp, the maximum value for faclen
is 60.
3-10

FORTRAN-10 SUBROUTINE CALLS

X251SC (Cont.)

•

If you have specified a closed user group in
usrgrp, the maximum value for faclen is 61.

•

If you have not specified a value for user
group, the maximum value for faclen is 63.

Your PPSN may further restrict this field.
datbuf

is an 8-bit-byte array in which
you
place
user-specified call data.
Specify the length of
datbuf in datlen.

datlen

is a user-supplied
integer that specifies the
length of datbuf in 8-bit bytes.
The maximum
value for datlen normally is 16 (or 128 for
fast
select calls).

buffer

is an integer array that is used as workspace by
the X.25 Gateway Access Routines.
This buffer can
be 144 to 396 words, depending on your selected
packet size.
To compute the length of the buffer,
use the following formula:
length = 140 + (packet size/4)
For example, if your packet size is 16, specify
buffer length of 144.

nport

is an integer variable in which X25ISC returns the
assigned port identifier.
You must use this value
as an argument for many of the other subroutine
calls.

rcode

is an integer variable in which X25ISC stores a
return code.
If rcode is nonzero, the switched
circuit is not initiated, and no port is assigned.
Values for rcode and their meanings are:

X25ISC is executed successfully;
a
call
request is sent to the PPSN.
The port state
changes from UNDEFINED to CALLING.

have
not
THE TOPS-10 PSI Gateway does
sufficient
resources
to allocate a new
switched circuit.

The TOPS-10 PSI Gateway Access Routines do
not have sufficient resources to allocate a
new circuit.

3-11

FORTRAN-IO SUBROUTINE CALLS

X251SC (Cont.)
3

The TOPS-lO PSI Gateway software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:
•

You have specified a
already been allocated.

port

that

has

•

A logical link could not be established
to the Gateway node for reasons other
than those specified here.

You have specified a network name that has
not been defined in the DECnet-IO Network
Management data base.

The facilities
because it is
the PPSN.

The user-specified call
data
field
is
truncated because it is longer than the limit
set by the PPSN.

You did not specify a password, or you
specified an incorrect password for gainlng
access to the PPSN through the Gateway node.

You did not specify the destination DTE
address
to which the circuit is to be
established.

The specified destination DTE address is
long.

The specified source DTE address is too long.

The version numbers of the TOPS-lO
Gateway
Access Routines and TOPS-IO
Gateway Software are not compatible.

3-12

data field
is
truncated
longer than the limit set by

too

PSI
PSI

FORTRAN-IO SUBROUTINE CALLS

X25NCS

NO COMMUNICATION SEEN

Use the X25NCS subroutine to acknowledge one or more failures of a
permanent virtual circuit due to loss of communication with the PPSN.
After such a failure, you retain possession of the permanent virtual
circuit.
When you issue an X25NCS call, the port state must be NO
COMMUNICATION.
The format of the X25NCS subroutine call is:
CALL X25NCS (nport, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you
call the subroutine
X250PC
(OPEN
PERMANENT
CIRCUIT) to set up the virtual circuit.

rcode

is an integer variable in which X25NCS stores a
return code.
If rcode is nonzero, the subroutine
fails to acknowledge the loss of communication
with the PPSN.
Reode values and their meanings
are:

The
X25NCS
subroutine
is
executed
successfully:
you have acknowledged a loss
of communication with the PPSN and are ready
to
resume
using
the permanent virtual
circuit, and the port state changes from NO
COMMUNICATION to RUNNING.

The TOPS-IO PSI Gateway Access
Software
encounters a procedure error as it tries to
execute this subroutine.
The procedure error
occurs for one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X250PC before executing X25NCS.

•

You have attempted to
execute
this
subroutine when the port state is not NO
COMMUNICATION.

execute
this
You have attempted to
• subroutine
switched virtual
with
a
circuit.
•

The logical link between the user job and
the Gateway node has been disconnected.

3-13

FORTRAN-IO SUBROUTINE CALLS

X250PC

OPEN PERMANENT CIRCUIT

Use the X250PC subroutine to acquire the exclusive use of a specified
PVC.
The function does not try to contact the remote DTE.
A
successful response changes the port state to RUNNING or UNSYNC.
You
can transfer data over the PVC as soon as the port state is RUNNING.
A port state of UNSYNC indicates that the remote DTE has issued a
reset; you must issue an X25RVC (RESET VIRTUAL CIRCUIT) subroutine
call before you can proceed. When you issue an X250PC subroutine
call, the port state must be UNDEFINED.
The format of the X250PC subroutine call is:
CALL X250PC (netwrk, passwd, pvcnam, buffer, nport, rcode)
where:
netwrk

is a user-supplied ASCII string that contains the
name
of
the
PPSN over which you wish to
communicate.
This name can be a maximum of 16
ASCII characters.

passwd

is a user-supplied ASCII string that contains the
required password for gaining access to the X.25
Gateway.
This password can be a maximum of 16
ASCII characters.
Your system manager determines
the X.25 Gateway Access password.
If you do not
need to use a password, specify a passwd of O.

pvcnam

is a user-supplied ASCII string that contains the
name of the PVC you are using.
This name can be a
Your system
maximum of 16 ASCII characters.
manager can supply you with the PVC name.

buffer

is an integer array that is used as workspace by
the X.25 Gateway Access Routines.
This array can
range in size from 144 to 396 words, depending on
your packet size.
To compute the length of the
buffer, use the following formula:
length

= 140 + (packet size/4)

For example,if your packet size is 16,
buffer length of 144.
nport

specify

is an integer variable in which X250PC returns the
assigned port identifier.
You must use this value
as an argument for many of the other subroutine
calls.

3-14

FORTRAN-10 SUBROUTINE CALLS

X250PC (Cont.)
rcode

is an integer variable in which X250PC stores a
return code.
If rcode is nonzero, you have not
obtained access to the specified pvc.
Rcode
values and their meanings are:

X250PC is executed successfully: a permanent
virtual circuit was allocated exclusively for
your job, and the port state changes from
UNDEFINED to OPEN.

have
The TOPS-10 PSI Gateway does
not
sufficient
resources
to allocate a new
permanent circuit.

The TOPS-IO PSI Gateway Access Routines do
not have sufficient resources to allocate a
new circuit.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a
already been allocated.

port

that

has

•

A logical link could not be established
to the Gateway node for reasons other
than those specified here.

You have specified a network name that has
not been defined
in the DECnet-lO Network
Management data base.

You have not specified a password, or
have specified an incorrect password
gaining access to the PPSN through
Gateway node.

You have specified a permanent circuit that
has not been defined in the DECnet-lO Network
Management data base.

The version numbers of the TOPS-10
Gateway
Access Routines and TOPS-10
Gateway Software are not compatible.

3-15

you
for
the

PSI
PSI

FORTRAN-I0 SUBROUTINE CALLS

X25RAD

READ ACCEPT DATA

Use the X25RAD subroutine to read information obtained from the remote
DTE after
it accepted your request to establish a switched virtual
circuit connection.
Some PPSNs do not supply data
in all the
described fields.
Where no data is supplied, the fields are filled
with nulls (binary Os) or the corresponding length field
is zero.
When you issue an X25RAD subroutine call, the port state must be
RUNNING.
The format of the X25RAD subroutine call is:
CALL X25RAD (nport, usrgrp, facbuf, faclen, datbuf, datlen,
rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for
nport is returned when you
call X25ISC (INITIATE SWITCHED CIRCUIT) to set up
the virtual circuit.

usrgrp

is an ASCII string in which X25RAD returns the
binary closed user group or closed user group
supplied by the remote DTE.
This field may be a
maximum of 16 ASCII characters and is delimited by
a binary O.

facbuf

is an 8-bit-byte array in which X25RAD returns
facilities data supplied by the remote DTE.
The
length of facbuf is specified
in faclen ..
(For
information
on
facilities
data,
see
the
documentation for your PPSN. )

faclen

is an integer variable that you set to the maximum
number of 8-bit bytes facbuf can receive.
This
data can be as many as 63 8-bit bytes~
Upon
return,
X25RAD sets faclen equal to the actual
number of 8-bit bytes returned in facbuf.

datbuf

is an 8-bit-byte array in which X25RAD returns
accept data supplied by the remote DTE.
The
length of datbuf is specified in datlen.

datlen

is an integer variable that you set to the maximum
number of 8-bit bytes datbuf can accept.
This
data can be as many as 16 8-bit bytes (or 128 for
fast select calls).
Upon return,
X25RAD sets
faclen to the actual number of 8-bit
bytes
returned in datbuf.

rcode

is an integer variable in which X25RAD stores a
return code.
If rcode is nonzero, the subroutine
has failed to retrieve all data supplied by the
remote DTE.
Rcode values and their meanings are:

The
X25RAD
subroutine
is
executed
successfully:
the user accept data and/or
user accept facilities were returned.
The
port state remains RUNNING.

3-16

FORTRAN-10 SUBROUTINE CALLS

X25RAD (Cont.)
3

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X2SISC before executing X2SRAD.

You have attempted to
execute
this
• subroutine
when the port state is not
RUNNING.

•

You have attempted to
execute
this
subroutine
with
a permanent virtual
circuit.

•

The logical link between the user job and
the Gateway node has been disconnected.

There is no user-specified accept data.

The facilities data field was
truncated
because you did not supply a buffer large
enough to accept that data.

The user-specified accept data field was
truncated because you did not supply a buffer
large enOugh to accept that data.

3-17

FORTRAN-10 SUBROUTINE CALLS

X25RCD

READ CLEAR DATA

Use the X25RCD subroutine to read data obtained when an SVC is
cleared.
The content of the data is PPSN specific, but not all PPSNs
provide this information when an SVC is cleared.
Use the X25RPS (READ
PORT STATUS)
subroutine to determine that the PPSN has cleared the
virtual circuit. When you issue an X25RCD subroutine call,
the port
state must be CLEARED.
The format of the X25RCD subroutine call is:
CALL X25RCD (nport, cause, diag, usrgrp, facbuf, faclen, datbuf,
datlen, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you
call X25ISC (INITIATE SWITCHED CIRCUIT) or X25WIC
(WAIT
INCOMING CALL)
to set up the virtual
circuit.

cause

is an integer variable in which X25RCD returns the
network clear cause supplied by the PPSN.
If
cause is nonzero,
the network has cleared the
call, cause contains the network clear cause, and
diag contains the network clear diagnostic.
If
cause is 0, the remote user has cleared the SVC,
and the user clear diagnostic is contained in
diag.
(For information on the network clear cause
and diagnostic, see the documentation for your
PPSN. )

diag

is an integer variable in which X25RCD returns the
network or user clear diagnostic.

usrgrp

is an ASCII string into which X25RCD returns the
binary closed user group or closed user group
supplied by the remote DTE.
This field may be a
maximum of 16 ASCII characters and is delimited by
a binary O.

facbuf

is an 8-bit-byte array in which X25RCD returns
facilities data supplied by the remote DTE.
The
length of facbuf is specified in faclen.
(For
information
on
facilities
data,
see
the
documentation for your PPSN.)

faclen

is an integer variable that you set to the maximum
number of a-bit bytes facbuf can receive. This
data can be as many as 63 8-bit bytes.
Upon
return, X25RAD sets faclen equal to the actual
number of 8-bit bytes returned in facbuf.

datbuf

is an 8-bit-byte array in which X25RCD returns
clear data supplied by the remote DTE.
The length
of datbuf is specified in datlen.

3-18

FORTRAN-IO SUBROUTINE CALLS

X25RCD (Cant.)
datlen

is an integer variable that you set to the maximum
number of 8-bit bytes datbuf can accept.
This
data can be as many as 16 8-bit bytes (or 128 for
fast select calls).
Upon return X25RCD sets
faclen
to the actual
number of 8-bit
bytes
returned in datbuf.

rcode

is an integer variable in which X25RCD stores a
return code.
If rcode is nonzero, the subroutine
has failed to retrieve data supplied by the remote
DTE.
Rcode values and their meanings are:

The
X25RCD
subroutine
is
executed
successfully:
the
clear
cause,
clear
diagnostic, and/or user clear data and/or
facilities data were returned.
The port
state remains CLEARED.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs
for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC or X25WIC before executing
X25RCD.

You have attempted to
execute
this
• subroutine
when the port state is not
CLEARED.
You have attempted to
execute
this
• subroutine
with
a permanent virtual
circuit.
•

The logical link between the user job and
the Gateway node has been disconnected.

The facilities data field was
truncated
because you did not supply a buffer large
enough to contain this data.

The clear data field was truncated because
you did not supply a buffer large enough to
contain this data.

3-19

FORTRAN-IO SUBROUTINE CALLS

X25RDM

READ DATA MESSAGE

Use the X25RDM subroutine to receive data from a virtual circuit.
The
data can be either normal or qualified. When you issue an X25RDM
subroutine call, the port state must be RUNNING.
The format of the X25RDM subroutine call is:
CALL X25RDM (nport, dtype, datbuf, datlen, qbit, mbit, rcode)
where:
nport

dtype

is an integer that you set to a value indicating
how received data should be placed in datbuf.
See
Table 3-1 for a list of values you can specify for
dtype.

datbuf

is an array of any data type in which X25RDM
returns received data.
X25RDM places data in the
array according to the value of dtype.

datlen

is an integer that you set to the maximum length
of datbuf.
To avoid a truncation error (rcode
error 8), use the minimum value for datlen that
corresponds to the value you have specified for
dtype (see Table 3-1).
You can obtain your packet
size
(ps)
by executing the X25RPS
(READ PORT
STATUS)
subroutine.
Upon return, X25RDM sets
datlen to the actual length of datbuf in the units
specified in dtype.
If the returned actual length
in dat1en is 0 and the return code in rcode is 0
(successful), you have received an empty Data
packet.

qbit

is an integer in which X25RDM returns a
indicating data qualification.
If qbit
datbuf contains qualified data.

mbit

is a logical variable in which X25RDM returns a
value indicating whether the next packet to be
received is logically related to the current one.
If mbit is
.TRUE., the next packet is logically
related to the current one
(the nature of this
relationship
is
user defined).
If mbit is
.FALSE., the next packet is not logically related
to the current one.
(See the discussion of X25SDM
for information on the relationship between mbit
and the more bit of the received Data packet.)

3-20

value
is 1,

FORTRAN-10 SUBROUTINE CALLS

X25RDM (Cont.)
Table 3-1:

Specifications for the Dtype and Datlen Variables

Dtype
Values

Dat1en Minimum
Values

Unit
Size

Location of data in
Each Array Element

(ps*2/9) +1 t

All 36 bits

ps/4

Leftmost 32 bits

ps/4

Rightmost 32 bits

ps/2

Rightmost 16 bits

Rightmost 8 bits

Leftmost 7 bits, which
is equivalent to the Al
FORMAT field descriptor
unit per array
1
element

ps/2

Leftmost 14 bits, which
is equivalent to the A2
FORMAT field descriptor
2 units per array
element

{ps/3)+1

Leftmost 21 bits, which
is equivalent to the A3
FORMAT field descriptor
3 units per array
element

ps/4

Leftmost 28 bits, which
is equivalent to the A4
FORMAT field descriptor
4 units per array
element

{ps/5)+1

Leftmost 35 bits, which
is equivalent to the AS
FORMAT field descriptor
5 units per array
element

t ps is your packet size
rcode

is an integer variable in which X25RDM stores a
return code.
If rcode is nonzero, the subroutine
has failed
to receive data from the virtual
circuit.
Rcode values and their meanings are:

The
X25RDM
subroutine
is
executed
successfully:
a normal or qualified user
data packet was returned.
The port state
remains RUNNING.

3-21

FORTRAN-IO SUBROUTINE CALLS

X25RDM (Cont.)
3

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25RDM.

You have attempted to
execute
this
• subroutine
when the port state is not
RUNNING.
•

The logical link between the user job and
the Gateway node has been disconnected.

There is no user data to be returned.

The received data was truncated because you
have supplied a buffer too small to contain
an entire data packet.

You have received a partially filled data
packet with the more bit set.
The more bit
is set upon return from
the
function.
However,
it is entirely up to you how you
handle such a data packet. For example, you
may choose to ignore the data packet and
reset the circuit.

There is no data from the PPSN to be returned
because the circuit has been reset.

You have
dtype.

specified

3-22

invalid

value

for

FORTRAN-10 SUBROUTINE CALLS

X25RIC

READ INCOMING CALL

Use the X25RIC subroutine to obtain information about an incoming call
when the port state changes from LISTENING to CALLED. When you issue
an X25RIC subroutine call, the port state must be CALLED.
The format of the X25RIC subroutine call is:
CALL X25RIC (nport, netwrk, addr, subadr, usrgrp, facbuf,
faclen, datbuf, datlen, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you
call X25WIC (WAIT INCOMING CALL)
to set up the
virtual circuit.

netwrk

is an ASCII string in which the X25RIC subroutine
places the name of the network from which the call
originated. This name can be a maximum of 16
ASCII characters and is delimited by a binary o.

addr

is an ASCII string in which the X25RIC subroutine
places the address of the calling (remote) DTE.
This address can be a maximum of 16
ASCII
characters and is delimited by a binary O.

subadr

is an ASCII string in which this subroutine places
the address of the called
(local)
DTE.
This
address can be a maximum of 16 ASCII characters
and is delimited by a binary O.

usrgrp

is an ASCII string in which this subroutine places
the binary closed user group or closed user group
supplied by the remote DTE.
This field may be a
maximum of 16 ASCII characters and is delimited by
a binary O.

facbuf

is an 8-bit-byte array in which X25RIC returns
facilities data supplied by the remote DTE.
The
(For
length of facbuf is specified in faclen.
information
see
the
facilities
data,
on
documentation for your PPSN. )

faclen

is an integer variable that you set to the maximum
number of 8-bit bytes facbuf can receive.
This
data can be as many as 63 8-bit bytes.
Upon
return, X25RIC sets faclen equal to the actual
number of 8-bit bytes returned in facbuf.

datbuf

is an 8-bit-byte array in which this subroutine
returns user-specified call data supplied by the
remote DTE.
The length of datbuf is specified in
datlen.

3-23

FORTRAN-IO SUBROUTINE CALLS

X25RIC (Cont.)
datlen

is an integer variable that you set to the maximum
number of 8-bit bytes datbuf can accept. This
data can be as many as 16 8-bit bytes (or 128 for
fast select calls).
Upon return, X25RIC sets
faclen to the actual number of 8-bit
bytes
returned in datbuf.

rcode

is an integer variable in which X25RIC stores a
return code.
If rcode is nonzero, the subroutine
has failed to obtain information about an incoming
call.
Rcode values and their meanings are:

The
X25RIC
subroutine
is
executed
successfully:
incoming call data and/or
facilities data were returned.
The port
state remains CALLED.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25WIC before executing X25RIC.

•

You have attempted to
execute
this
subroutine when the port state is not
CALLED.

•

The logical link between the user job and
the Gateway node has been disconnected.

There is no user-specified call data.

The facilities data field was
truncated
because you did not supply a buffer large
enough to contain that data.

The user-specified call data
field
was
truncated because you did not supply a buffer
large enough to contain that data.

3-24

FORTRAN-IO SUBROUTINE CALLS

X25RIM

READ INTERRUPT MESSAGE

Use the X25RIM subroutine to receive interrupt data. When you issue
an X25RIM subroutine call, the port state must be RUNNING.
Use the
X25RPS (READ PORT STATUS) subroutine to determine if there is an
interrupt byte to read.
The format of the X25RIM subroutine call is:
CALL X25RIM (nport, intbyt, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED
CIRCUIT),
X250PC
(OPEN
PERMANENT
CIRCUIT), or X25WIC (WAIT INCOMING CALL) •

intbyt

is an integer variable in the rightmost 8 bits
which X25RIM returns the interrupt byte.

rcode

is an integer variable in which X25RIM stores a
return code.
If rcode is nonzero, the subroutine
has failed to obtain interrupt data.
Values for
rcode and their meanings are:

The
X25RIM
subroutine
is
executed
successfully:
an interrupt data byte was
returned.
The port state remains RUNNING.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25RIM.

•

execute
this
You have attempted to
subroutine when the port state is not
RUNNING.

•

The logical link between the user job and
the Gateway node has been disconnected.

There is no interrupt.

There is no interrupt from the PPSN to be
returned because the circuit has been reset.

3-25

FORTRAN-IO SUBROUTINE CALLS

X25RPS

READ PORT STATUS

Use the X25RPS subroutine to poll the port maintained by the TOPS-IO
PSI Gateway Software.
You can
issue an X25RPS subroutine call
regardless of the current port state.
However, if the port state is
UNDEFINED,
perror,
iiostd,
oiostd, davail,
iavail, and psize have
indeterminate meaning.
The format of the X25RPS subroutine call is:
.CALL X25RPS (nport, perror, stat, iiostd, oiostd, davail,
iavail, psize, rcode)
where:
nport

is an integer that identifies
the port you are
using.
A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED
CIRCUIT) ,
X250PC
(OPEN
PERMANENT
CIRCUIT), or X25WIC (WAIT INCOMING CALL) •

perror

is an integer variable in which X25RPS returns the
last fatal error condition (see Table 3-2) that
changed the port state to the ERROR state.
Perror
has meaning only when stat is 10 (ERROR).

stat

is an integer variable in which X25RPS returns the
current port state as a decimal value.
See Table
2-3 for
a
list of the decimal
values
and
explanations of port states.

iiostd

is a logical variable in which X25RPS returns the
incoming
interrupt flag.
If
iiostd is .TRUE.,
there is a previously received interrupt that you
have
not yet confirmed;
use X25CIM
(CONFIRM
INTERRUPT MESSAGE) to confirm the interrupt.

oiostd

is a logical variable in which X25RPS returns the
outgoing
interrupt flag.
If oiostd is .TRUE., an
outgoing interrupt has been transmitted but not
confirmed by the remote DTE.

davail

is a logical variable in which X25RPS returns
the
data-available
flag.
If
davail
is
.TRUE.,
incoming user data
is available on the data
subchannel; use X25RDM (READ DATA MESSAGE) to read
the data.

3-26

FORTRAN-IO SUBROUTINE CALLS

X25RPS (Cont.)
iavail

is logical variable in which X25RPS returns the
interrupt-data-available
flag.
If iavail
is
.TRUE., incoming interrupt data is available on
the
interrupt
subchannel;
use X25RIM
(READ
INTERRUPT MESSAGE) to read the data.

psize

is an integer variable in which X25RPS returns the
current packet size.

rcode

is an integer variable in which X25RPS stores a
return code.
If rcode is nonzero, X25RPS has
failed to poll the specified port.
Rcode values
and their meanings are:

The
X25RPS
subroutine
is
executed
successfully:
the port status and flags have
been returned.
The port
state
remains
unchanged.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure
error
occurs
because the logical link between the user job
and the Gateway node has been disconnected.

3-27

FORTRAN-lO SUBROUTINE CALLS

X25RPS (Cont.)
Table 3-2:

Fatal Error Conditions

Decimal
Value

Meaning

Unknown error

Insufficient gateway resources

Circuit in use (reserved)

Undefined circuit name

Undefined network name

No communication with the Public Network

Data field truncated

Facilities field truncated

Source DTE subaddress is too long

Destination DTE address is too long

Version skew

Invalid user group

3-28

FORTRAN-IO SUBROUTINE CALLS

X25RRD

READ RESET DATA

Use the X25RRD subroutine to read information obtained when a
virtual
circuit is reset.
The content of the data is network specific, but
not all networks provide this information when a call is reset.
Use
the X25RPS (READ PORT STATUS) subroutine to determine that the virtual
circuit has been reset. When you issue an X25RRD subroutine call, the
port state must be UNSYNC.
The format of the X25RRD subroutine call is:
CALL X25RRD (nport, cause, diag, rcode)
where:
nport

cause

is an integer variable in which X25RRD returns the
network reset cause supplied by the PPSN.
If
cause is nonzero,
the network has reset the
virtual circuit, cause contains the network reset
cause,
and diag contains the
network
reset
diagnostic.
If cause
is 0, the remote user has
reset the virtual circuit, and the user reset
diagnostic is contained in diag.
(For information
on the network reset cause and diagnostic, see the
documentation for your PPSN.)

diag

is an integer in which x25RRD returns the user
reset diagnostic if the remote user has reset the
virtual circuit.

rcode

is an integer variable in which X25RRD stores a
return code.
If rcode is nonzero, the subroutine
has failed to retrieve data associated with the
resetting of a virtual circuit.
Rcode values and
their meanings are:

executed
The
X25RRD
subroutine
is
successfully:
reset
cause
and
reset
diagnostic bytes were returned.
The port
state remains UNSYNC.

3-29

FORTRAN-lO SUBROUTINE CALLS

X25RRD (Cont.)
3

The TOPS-lO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25RRD.

have attempted to
execute
this
• You
subroutine when the port state is not
UNSYNC.
•

The logical link between the user job and
the Gateway node has been disconnected.

3-30

FORTRAN-IO SUBROUTINE CALLS

X25RVC

RESET VIRTUAL CIRCUIT

Use the X25RVC subroutine to reinitialize a virtual circuit and return
it to the state it was in before data was transferred over that
circuit. At the time of resetting, the PPSN might discard data and
interrupt
packets that are in transit.
Also, use the X25RVC
subroutine to acknowledge a reset from the network.
When you issue an X25RVC subroutine call, the port state must be
either RUNNING or UNSYNC. When you initiate a reset, the port state
changes from RUNNING to SYNC. When the PPSN initiates a reset,
the
port state changes from RUNNING to UNSYNC.
Acknowledge a PPSN reset
as soon as possible because the network may time out and clear the
circuit before you acknowledge. Acknowledging a PPSN reset changes
the port state from UNSYNC to RUNNING.
The format of the X25RVC subroutine call is:
CALL X25RVC (nport, diag, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED
CIRCUIT),
X250PC
(OPEN
PERMANENT
CIRCUIT), or X25WIC (WAIT INCOMING CALL) •

diag

is an integer that you fill with one byte of
diagnostic data.
,You and the remote user should
agree upon acceptable values for diag.
The X.25
software ignores this value if you use X25RVC to
confirm a network reset.

rcode

is an integer variable in which X25RVC stores a
return code.
Rcode values and their meanings are:

X25RVC is executed successfully.
If you used
X25RVC to initiate a reset on the circuit, a
reset request was sent to the PPSN and the
port state changes from RUNNING to SYNC.
If
you used X25RVC to confirm a reset indication
from the PPSN, a reset confirmation was sent
to the PPSN, and the port state changes from
UNSYNC to RUNNING.

3-31

FORTRAN-IO SUBROUTINE CALLS

X25RVC (Cont.)
3

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25RVC.

You have attempted to
execute
this
• subroutine
when the port state is not
RUNNING or UNSYNC.
•

The logical link between the user job and
the Gateway node has been disconnected.

3-32

FORTRAN-10 SUBROUTINE CALLS

X25SDM

SEND DATA MESSAGE

Use the X25SDM subroutine to queue a buffer of data for transmission
to the PPSN. When calling X25SDM, specify in the dtype variable how
data in the array datbuf is to be interpreted.
If this subroutine is executed successfully, the X.25 Gateway Access
Routines
have
successfully
transmitted
the buffer.
However,
successful execution does not mean that the data has reached the PPSN.
With X25SDM you can send data over either a normal or a qualified data
subchannel.
When you call X25SDM, the TOPS-10 PSI Gateway Access Routines format
the datbuf array into octets, the contents of which are determined by
the value you specify for dtype (see Sections 3.2.1 through 3.2.3).
Before transmitting the octets to a PPSN, the Access Routines form the
octets into Data packets. During that conversion, if a Data packet
becomes
full,
the Access Routines set the more bit of that
packet - regardless of the value you have specified in the mbit
parameter.
The Access Routines then transmit the Data packet to the
PPSN.
This conversion continues in that way until all data in the
datbuf array has been converted into Data packets and transmitted.
However, the value you specify for mbit does affect whether the Access
Routines set the more bit of the final packet in the sequence of
packets currently being transmitted.
If you have specified a value of
.FALSE.
for mbit, the Access Routines transmit the final packet with
the more bit not set.
If you have specified a value of
.TRUE.
for
mbit, and the final packet is full, the Access Routines transmit the
final packet with the more bit set.
If you have specified a value of
.TRUE.
for mbit, but the final packet is not full, the Access
Routines do not immediately transmit the final packet. Such a packet
normally is transmitted to the PPSN only after subsequent X25SDM calls
provide additional data to be transmitted.
You can, however, cause the Access Routines to transmit a partially
filled Data packet to the PPSN.
To do so, call X25SDM, with mbit
specified as .FALSE., and datlen set to O.
Note that if you call
X25SDM in this way and there is no partially filled Data packet
waiting to be sent, nothing is transmitted, but the subroutine is
successfully executed (rcode is 0). Also, calling X25SDM with datlen
specified as 0 and mbit specified as
~TRUE.
is meaningless and
results in no packet being transmitted to the PPSN.
When you issue an X25SDM subroutine
RUNNING.

call,

the

port

state

must

The format of the X25SDM subroutine call is:
CALL X25SDM (nport, dtype, datbuf, datlen, qbit, mbit, rcode)
where:
nport

is an integer that identifies the port you are
using.
A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED CIRCUIT), X250PC (OPEN PERMANENT CIRCUIT)
or X25WIC (WAIT INCOMING CALL) •

3-33

FORTRAN-IO SUBROUTINE CALLS

X25SDM (Cont.)
dtype

is an integer that you set to a value indicating
how data
in the transmitted array should be
interpreted.
See Table 3-1 for a list of dtype
values.

datbuf

is an array of any data type in which you place
data to be transmitted.
This data is interpreted
in the format specified in dtype.

datlen

is an integer that you have set to the length of
datbuf.
If you have specified a value for dtype
in the range 5 through 9, then specify datlen as
the number of characters in datbuf.
Otherwise,
specify datlen as the length of the datbuf array.

qbit

is an integer that you have set to indicate data
qualification.
If qbit is 0, datbuf contains
normal data.
If qbit
is 1, datbuf contains
qualified data.

mbit

is a logical variable that indicates whether the
next datbuf you send is logically related to the
current one.
If mbit is .TRUE., the next datbuf
is logically related to the current one (the
nature of this relationship is user defined) •
If
mbit is .FALSE., the next datbuf is not logically
related to the current one.
(See the introductory
information on X25SDM for a discussion of the
relationship between mbit and the more bit of the
transmitted Data packet.)

rcode

is an integer variable in which X25SDM stores a
return code.
If rcode is nonzero, the subroutine
has failed to transmit data.
Rcode values and
their meanings are:

The
X25SDM
subroutine
is
executed
successfully:
the
data
in datbuf was
transmitted in one or more packets to the
PPSN.
The port state remains RUNNING.

The TOPS-lO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25SDM.

You have attempted to
execute
this
• subroutine
when the port state is not
RUNNING.
•
19

The logical link between the user job and
the Gateway node has been disconnected.

You have
dtype.

specified

3-34

invalid

value

for

FORTRAN-lO SUBROUTINE CALLS

X25SIM

SEND INTERRUPT MESSAGE

Use the X25SIM subroutine to send interrupt data.
One execution of
X25SIM sends one byte of interrupt data. When you issue an X25SIM
subroutine call, the port state must be RUNNING. Only one interrupt
can be outstanding at anyone time. To find whether an interrupt has
been acknowledged, execute the READ PORT STATUS function.
The format of the X25SIM subroutine call is:
CALL X25SIM (nport, intbyt, rcode)
where:
nport

is an integer that identifies the port you are
using. A value for nport is returned when you set
up the virtual circuit by calling X25ISC (INITIATE
SWITCHED
CIRCUIT) ,
X250PC
(OPEN
PERMANENT
CIRCUIT), or X25WIC (WAIT INCOMING CALL) •

intbyt

is the interrupt byte, an integer in the
to 255.

rcode

is an integer variable in which X25SIM stores a
return code.
If rcode is nonzero, the subroutine
has failed to transmit interrupt data.
Rcode
values and their meanings are:

range

The
X25SIM
subroutine
is
executed
successfully:
an interrupt message was sent
to the PPSN. The port state remains RUNNING.

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a port that has not
been allocated.
You may have failed to
execute X25ISC, X250PC, or X25WIC before
executing X25SIM.

have attempted to
execute
this
• You
subroutine when the port state is not
RUNNING.
•
11

The logical link between the user job and
the Gateway node has been disconnected.

Prior to the current execution of X25SIM, you
have sent the PPSN an interrupt message that
has not yet been confirmed.
There can be
only one outstanding interrupt at any time.

3-35

FORTRAN-IO SUBROUTINE CALLS

X25TPA

TERMINATE PORT ACCESS

Use the X25TPA subroutine to release all resources associated with a
port.
Executing the X25TPA subroutine causes an active SVC to be
cleared or an active PVC to be released.
In either case,
the port
state changes to UNDEFINED, and any data in transit may be lost.
You
can issue this subroutine regardless of the current port state.
The format of the X25TPA subroutine is:
CALL X25TPA (nport, rcode)
where:
nport

rcode

is an integer variable in which X25TPA stores a
return code.
Rcode values and their meanings are:

X25TPA
is
executed
successfully:
all
resources
associated with the port were
released, and
the
port
state
becomes
UNDEFINED.

'rhe TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine.
The procedure
error
occurs
because you have specified a port that has
not been allocated.
You may have failed to
execute X25ISC,
X250PC, or X25WIC before
executing X25TPA.

3-36

FORTRAN-10 SUBROUTINE CALLS

X25WIC

WAIT INCOMING CALL

Use the X25WIC subroutine to create a target object to which your X.25
Gateway node can connect when an incoming call arrives from the PPSN.
The Network Services Protocol (NSP), which identifies the user process
as a passive task, provides the X25WIC subroutine with a network
channel. The user process perceives an incoming virtual call as an
incoming DECnet logical link from the X.25 Gateway module.
You become
aware of the incoming call when the port state changes from LISTENING
to CALLED.
The format of the X25WIC subroutine call is:
CALL X25WIC (name, buffer, nport, rcode)
where:
name

is a user-supplied ASCII string that contains the
DECnet object identification (in the format of a
name or a numeric string)
that identifies your
process.
Your system manager can supply you with
the object identification, which is in the X.25
Server
Data
Base.
See the TOPS-IO System
Manager's Guide for information on how the X.25
Gateway Software compares data in the X.25 Server
Data Base with data in Incoming Call Packets to
select which incoming calls should be routed to
your process.

buffer

is an integer array that is used as workspace by
the X.25 Gateway Access Routines.
This buffer can
be 144 to 396 words, depending on your selected
packet size.
To compute the length of the value
for buffer, use the following formula:
length = 140 + (packet size/4)
For example, if your packet size is 16, specify
buffer length of 144.

nport

is an integer that identifies the port you are
using.
The X25WIC subroutine returns this value,
which you must use as an argument for many of the
other subroutine calls.

rcode

is an integer variable in which X25WIC stores a
return code.
If rcode is nonzero, you are not
ready to receive an incoming call.
Rcode values
and their meanings are:

X25WIC is executed successfully:
a circuit
was allocated for receiving incoming calls
from the PPSN, the port state changes from
UNDEFINED to LISTENING.

The TOPS-IO system does not have
resources to allocate a new port.

3-37

sufficient

FORTRAN-IO SUBROUTINE CALLS

X25WIC (Cont.)
3

The TOPS-IO PSI Gateway Software encounters a
procedure error as it tries to execute this
subroutine. The procedure error occurs for
one of the following reasons:
•

You have specified a
already been allocated.

•

A DECnet server logical link could not be
established because of system or DECnet
errors.

3-38

port

that

has

CHAPTER 4
MACRO-lO SUBROUTINE CALLS

4.1

MACRO-lO AND THE TOPS-lO PSI GATEWAY SOFTWARE

The TOPS-lO PSI Gateway
1 are described here
these subroutine calls,
single communications
program execution by:

Access Routine functions summarized in Chapter
as a set of MACRO-lO subroutine calls.
To use
you can write a program that establishes a
link on a channel (port).
You can then direct

•

Using the TOPS-lO software interrupt system (see the
Monitor Calls Manual).

•

Executing the X%RPS
(READ
PORT
STATUS)
interrogate the condition of that port.

TOPS-IO

function

Before executing a MACRO-IO call, the TOPS-IO PSI Gateway Software
stores all registers.
After the subroutine has been executed, the
Gateway Software restores all registers to their former state and
returns control to the main program.
Every MACRO-lO TOPS-lO PSI Gateway
form:

subroutine

call

has

•

The address of an argument block, ARGBLK, in ACI

•

PUSHJ SP, subroutine-address

•

A return to the +1 location

Whenever you specify an ASCIZ value for a subroutine argument,
one of the following:
pointer

that

points

standard

supply

•

A non-null ASCIZ byte
string.

non-null

•

A non-null ASCIZ byte pointer that points to a null string.

•

A binary 0; that is, a null string.

When a subroutine call requires an ASCIZ byte pointer as an argument,
you do not need to restrict it to a 7-bit byte pointer.
The ASCIZ
byte pointer can be of any byte size greater than or equal to 7 bits
and up to 36 bits.
You must, however, terminate the ASCIZ string with
a binary zero byte.

4-1

MACRO-IO SUBROUTINE CALLS
The file UNV:X25SYM.UNV contains universal symbols such as virtual
circuit port states, return codes, and other bit-mask symbols.
For
example, universal symbols for virtual circuit port states are XS%UND
and XS%RUN and for
return codes are XC%SUC and XC%PER.
The user
source program must reference this universal file using the SEARCH
macro.
Since the TOPS-IO PSI Gateway Access routines use the push down stack
for manipulation of data and other tasks, you should initialize the
stack pointer to point to a push down list of at least 1000
(octal)
wor.ds.
On an unsuccessful return from a MACRO-IO call,
the following
flags
are returned
in the right half of the return-code word (see Figure
4-1). All bits set to zero indicates success.
18

ITIIIIIIIIIIIIIIIII
MR-S-27S4-83

Figure 4-1:

Return Code Bit Mask

In all the MACRO-IO function descriptions, each bit in the return code
bit mask has a specific meaning.
The TOPS-IO system numbers bits from
left to right in ascending order. See Table 4-1 for
the meaning of
each set bit when one or more specific bits of the return code are
nonzero.
Table 4-1:

Return Code Values

Bit

Symbol

Meaning

18
19
20

XC%RSS
XC%VSK
XC%BTS

Reset seen
Version skew
Buffer is too short

21
22
23

XC%BTL
XC%SDL
XC%DDL

Buffer is too long
Source DTE subaddress is too long
Destination DTE address is too long

24
25
26

XC%NIC
XC%AIC
XC%NDN

No interrupt confirmation is requested
Awaiting interrupt confirmation
No destination

27
28
29

XC%INA
XC%DFT
XC%FFT

Illegal network access code
Data field truncated
Facilities field truncated

30
31
32

XC%UNN
XC%NIN
XC%NDA

Undefined network name
No interrupt to read
No data to read

33
34
35

XC%PER
XC%IAR
XC%IGR

Procedure error
Insufficient access resources
Insufficient gateway resources

None

XC%SUC

Successful

4-2

MACRO-IO SUBROUTINE CALLS
4.2

LINKING A MACRO-IO PROGRAM

The MACRO-IO TOPS-IO PSI Gateway Access Routines are in the library
file X25GAM.REL.
After you have written and assembled a program to
produce relocatable object modules, you must link the modules with
X25GAM.REL to produce an executable image file.
To link your program,
type:
.R LINK ~
*REL:X25GAM.REL, object-l[, ••• , object-nJ ~
*/SAVE /GO ~
where:
object-l through object-n
object modules.

4~3

are

the

names

your

relocatable

THE SUBROUTINE CALLS

The MACRO-IO calls are in alphabetical order in the following format:
•

A title containing the name of the MACRO-IO call and the name
of the TOPS-IO PSI Gateway Access Routine function

•

The purpose of the function

•

A description of the function

•

The calling sequence

•

The parameter descriptions

In this chapter, all word offsets - such as the number 10 in the
All other numbers in this
expression ARGBLK+IO - are octal numbers.
manual are decimal, unless otherwise noted.

4-3

MACRO-lO SUBROUTINE CALLS

X%AIC

ACCEPT INCOMING CALL

Use the X%AIC subroutine to accept an incoming call request.
You can
use data returned by the X%RIC (READ INCOMING CALL) subroutine to
determine whether to accept an incoming call. When you issue an X%AIC
subroutine call, the port state must be CALLED.
The calling sequence for the X%AIC subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%AIC
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you called X%WIC (WAIT INCOMING CALL) to set
up the virtual circuit.

ARGBLK+I

contains the return code.
Following are the X%AIC
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%AIC is executed
successfully:
the
incoming call
is accepted, and the port
state changes from CALLED to RUNNING.

XC%DFT

The user-specified accept data field
is
truncated because it is longer than' the
limit set by the PPSN.

XC%FFT

The facilities data field
is truncated
because it is longer than the limit set by
the PPSN.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%WIC before
executing
X%AIC.

•

You have attempted to execute this
subroutine when the port state is not
CALLED.

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.

4-4

MACRO-IO SUBROUTINE CALLS

XO/oAIC (Cont.)
ARGBLK+2

contains an ASCIZ string pointer to the name of
the bilateral closed user group or closed user
group.
This name is user supplied and can be a
maximum of 16 ASCII characters.

ARGBLK+3

contains the length and address of the buffer into
which you have placed any facilities data required
to support your PPSN service.
In the left half of
ARGBLK+3, specify the length of that buffer in
8-bit bytes.
The maximum value you can specify in
the left half of ARGBLK+3 depends upon the value
you have specified in ARGBLK+2 for this subroutine
call:
•

If you specify a bilateral closed user group
in ARGBLK+2, the maximum value you can specify
in the left half of ARGBLK+3 is 60.

•

If you specify a closed user
group
in
ARGBLK+2, the maximum value you can specify in
the left half of ARGBLK+3 is 61.

•

If you do not specify a value in ARGBLK+2, the
maximum value you can specify in the left half
of ARGBLK+3 is 63.

Your PPSN may further restrict this value.
In the
right half of ARGBLK+3, specify the address of the
buffer.
(For information on facilities data, see
the documentation for your PPSN.)
ARGBLK+4

contains the length and address of the buffer into
which you have placed any user-specified accept
data.
In the left half of ARGBLK+4,
specify the
length of that buffer in 8-bit bytes.
The maximum
length normally is 16 8-bit bytes (or 128 for fast
select calls), although your PPSN may further
restrict this value.
In the right half
of
ARGBLK+4, specify the address of the buffer.

4-5

MACRO-IO SUBROUTINE CALLS

X%CIM

CONFIRM INTERRUPT MESSAGE

Use the X%CIM subroutine to confirm the receipt of interrupt data.
When you
issue an X%CIM subroutine call,
the port state must be
RUNNING.
Only one interrupt can be outstanding at a time.
The calling sequence for the X%CIM subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%CIM
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT)
X%OPC
(OPEN
PERMANENT CIRCUIT) or X%WIC (WAIT INCOMING CALL) •

ARGBLK+I

contains the return code.
Following are the X%CIM
return codes and their meanings.
Upon return from
this subroutine, one or more of these may be set:
XC%SUC

X%CIM is executed
successfully:
the
interrupt is confirmed.
The port state
remains RUNNING.

XC%NIC

No interrupt confirmation is requested.
The user has not received an interrupt
message from the PPSN that requires a
confirmation.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC,
X%OPC,
or X%WIC
before executing X%CIM.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

•

The logical link between the user
job
and
the
Gateway
node
has been
disconnected.

4-6

MACRO-IO SUBROUTINE CALLS

X%CSC

CLEAR SWITCHED CIRCUIT

Use the X%CSC subroutine to terminate an SVC connection.
Once you
have executed the X%CSC subroutine, any data in transit may be lost,
and you can no longer communicate over the specified circuit.
However,
the port remains assigned; to release the port, execute the
X%TPA (TERMINATE PORT ACCESS) subroutine. When you issue an X%CSC
subroutine call, the port state must be CALLED, CALLING, RUNNING,
SYNC, or UNSYNC.
The calling sequence for the X%CSC subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%CSC
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you called X%ISC (INITIATE SWITCHED CIRCUIT)
or X%WIC
(WAIT INCOMING CALL)
to set up the
virtual circuit.

ARGBLK+I

contains the return code. Following are the X%CSC
return codes and their meanings.
Upon return from
this subroutine, one or more of these may be set:
XC%SUC

X%CSC is executed successfully:
a clear
request is sent to the PPSN, and the port
state changes from RUNNING to CLEARING.

XC%DFT

The user-specified clear data field
is
truncated because it is longer than the
limit set by the PPSN.

XC%FFT

The facilities data field
is truncated
because it is longer than the limit set by
the PPSN.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC or X%WIC
before
executing X%CSC.

•

You have attempted to execute this
subroutine when the port state is not
CALLING, CALLED, RUNNING,
SYNC, or
UNSYNC.

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains the DTE clear cause. The X.2S software
passes the rightmost 8-bit byte to the remote DTE.

4-7

MACRO-10 SUBROUTINE CALLS

X%CSC (Cont.)
ARGBLK+3

contains an ASCIZ byte pointer to the name of the
bilateral closed user group or closed user group.
This name is user supplied and can be a maximum of
16 ASCII characters.
Some PPSNs may not allow
this field.

ARGBLK+4

contains the length and address of the buffer into
which you have placed any facilities data required
to support your PPSN service.
In the left half of
ARGBLK+4,
specify the length of that buffer in
8-bit bytes. The maximum value you can specify in
the left half of ARGBLK+4 depends upon the value
you have specified in ARGBLK+3 for this subroutine
call:
•

If you specify a bilateral closed user group
in ARGBLK+3, the maximum value you can specify
in the left half of ARGBLK+4 is 60.

•

If you specify a closed user
group
in
ARGBLK+3, the maximum value you can specify in
the left half of ARGBLK+4 is 61.

•

If you do not specify a value in ARGBLK+3, the
maximum value you can specify in the left half
of ARGBLK+4 is 63.

Your PPSN may further restrict this value.
In the
right half of ARGBLK+4, specify the address of the
buffer.
(For information on facilities data, see
the documentation for your PPSN.)
ARGBLK+5

contains the length and address of the buffer into
which you have placed any user-specified clear
data.
In the left half of ARGBLK+5,
specify the
length of that buffer in 8-bit bytes.
The maximum
length normally is 16 8 bit bytes (or 128 for fast
select calls), although your PPSN may further
restrict this value.
In the right half
of
ARGBLK+5, specify the address of the buffer.

4-8

MACRO-10 SUBROUTINE CALLS

X%ISC

INITIATE SWITCHED CIRCUIT

Use the X%ISC subroutine to issue a virtual call request over a
switched virtual circuit to a remote DTE.
A successful return does
not indicate that the remote DTE has responded to the call. When the
remote DTE responds to the call, the port state changes from CALLING
to RUNNING or CLEARED. When you issue an X%ISC subroutine call, the
port state must be UNDEFINED.
(Note that the remote DTE is also
called the destination DTE, and the local DTE can be called the source
DTE. )
The calling sequence for the X%ISC subroutine call is:
MOVEI AC1,ARGBLK
PUSHJ P,X%ISC
where:
ARGBLK+O

contains the software interrupt channel and the
PRTBLK.
In the left half of ARGBLK+O, specify a
positive number to
indicate software interrupt
serVlce to be enabled for the logical link to the
X.25 node.
In the right half of ARGBLK+O, specify
the address of a block of storage called PRTBLK,
which the X.25 Gateway Access Routines use as a
workspace.
To compute the length of PRTBLK in
words, use the following formula:
length = 140 + (packet size/4)
For example, if your packet size is 16, specify
PRTBLK length of 144.

The X.25 software returns the port number
in
ARGBLK+O.
You must use this value when calling
many of the other subroutines. The port number is
also the interrupt channel when you specify a
positive number in the left half for
input.
You
can use it to determine which channel the software
interrupt has been granted by the system.
ARGBLK+1

contains the return code.
Following are the X%ISC
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%ISC is executed successfully:
a call
request is sent to the PPSN, and the port
state changes from UNDEFINED to CALLING.

XC%VSK

The version numbers of the TOPS-IO PSI
Gateway Access Software and the TOPS-lO
PSI Gateway Software are not compatible.

XC%SDL

The specified source DTE subaddress is too
long.

XC%DDL

The specified destination DTE
too long.

XC%NDN

You have not specified the destination DTE
address to which the circuit is to be
established.
4-9

address

MACRO-10 SUBROUTINE CALLS

XO/oISC (Cont.)
XC%INA

You have not specified a password or you
have specified an incorrect password for
gaining access to the PPSN through the
Gateway node.

XC%DFT

The user-specified call data field
is
truncated because it is longer than the
limit set by the PPSN.

XC%FFT

The facilities data field
is truncated
because it is longer than the limit set by
the PPSN.

XC%UNN

You have specified a network name that has
not been defined in the DECnet-l0 Network
Management data base.

XC%PER

The
TOPS-lO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port
already been allocated.

which

has

A
logical
• established
reasons
here.

link
could
not
be
to the Gateway node for
other than those specified

XC%IAR

The TOPS-10 PSI Gateway Access Routines do
not have sufficient resources to allocate
a new circuit.

XC%IGR

The TOPS-I0 PSI Gateway
sufficient resources to
switched circuit.

does not have
allocate a new

ARGBLK+2

contains an ASCIZ byte pointer to the name of the
PPSN over which you want to communicate. This
name is user supplied and can be a maximum of 16
ASCII characters.

ARGBLK+3

contains an ASCIZ byte pointer to the password
required for gaining access to the X.25 Gateway.
This password is user supplied and can be a
maximum of 16 ASCII characters.
Your system
manager determines this password.

ARGBLK+4

contains an ASCIZ byte pointer to the address of
the
destination
DTE.
This address
is user
supplied and can be a maximum of 15
ASCII
characters.

ARGBLK+5

contains an ASCIZ byte pointer to the subaddress
of the source DTE.
This subaddress
is user
supplied and can be a maximum of 15
ASCII
characters.

4-10

MACRO-10 SUBROUTINE CALLS

X%lSC (Cont.)
ARGBLK+6

contains an ASCIZ byte pointer to the name of the
bilateral closed user group or closed user group.
This name is user supplied and can be a maximum of
16 ASCII characters.

ARGBLK+7

contains the length and address of the buffer into
which you have placed any facilities data required
to support your PPSN service.
In the left half of
ARGBLK+7,
specify the length of that buffer in
8-bit bytes.
The maximum value you can specify in
the left half of ARGBLK+7 depends upon the value
you have specified in ARGBLK+6 for this subroutine
call:
•

If you specify a bilateral closed user group
in ARGBLK+6, the maximum value you can specify
in the left half of ARGBLK+7 is 60.

•

If you specify a closed user
group
in
ARGBLK+6, the maximum value you can specify in
the left half of ARGBLK+7 is 61.

•

If you do not specify a value in ARGBLK+6, the
maximum value you can specify in the left half
of ARGBLK+7 is 63.

Your PPSN may further restrict this value.
In the
right half of ARGBLK+7, specify the address of the
buffer.
(For information on facilities data,
see
the documentation for your PPSN.)
ARGBLK+10

contains the length and address of the buffer into
which you have placed any user-specified call
data.
In the left half of ARGBLK+8,
specify the
length of that buffer in 8-bit bytes.
The maximum
length normally is 16 8-bit bytes (or 128 for fast
select calls),
although your PPSN may further
restrict this value.
In the right half
of
ARGBLK+8, specify the address of the buffer.

4-11

MACRO-IO SUBROUTINE CALLS

X%NCS

NO COMMUNICATION SEEN

Use the X%NCS subroutine to acknowledge one or more failures of the
permanent virtual circuit due to loss of communication with the PPSN.
After such a failure, you retain possession of the permanent virtual
circuit.
When you issue an X%NCS call, the port state must be NO
COMMUNICATION.
The calling sequence for the X%NCS subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%NCS
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you called the subroutine
X%OPC
(OPEN
PERMANENT CIRCUIT) to set up the virtual circuit.

ARGBLK+I

is the return code.
Following
return codes and their meanings:

are

the

X%NCS

XC%SUC

The
X%NCS
subroutine
is
executed
successfully:
you have acknowledged the
loss of communication with the PPSN and
are using the permanent virtual circuit,
and the port state changes
from
NO
COMMUNICATION to RUNNING.

XC%PER

The TOPS-IO PSI Gateway Access Software
encounters a procedure error as it tried
to execute this subroutine.
The procedure
error occurred for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%OPC before
executing
X%NCS.

•

You have attempted to execute this
subroutine when the port state is not
NO COMMUNICATION.

•

You have attempted
subroutine with a
circuit.

to execute this
switched virtual

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.

4-12

MACRO-IO SUBROUTINE CALLS

X%OPC

OPEN PERMANENT CIRCUIT

Use the X%OPC subroutine to acquire exclusive use of a specified pvc.
The function does not try to contact the remote DTE. A successful
response changes the port state to RUNNING or UNSYNC.
You can
transfer data over the pvc as soon as the port state is RUNNING.
A port state of UNSYNC indicates that the remote DTE has issued a
reset; you must issue an X%RVC (RESET VIRTUAL CIRCUIT) subroutine call
before you can proceed. When you issue an X%OPC subroutine call, the
port state must be UNDEFINED.
The calling sequence for the X%OPC subroutine call is:
MOVEI ACl,ARGBLK
PUSHJ P,X%OPC
where:
ARGBLK+O

contains the software interrupt channel and the
PRTBLK.
In the left half of ARGBLK+O, specify a
positive number to indicate software interrupt
service to be enabled for the the logical link to
the X.25 node.
In the right half of ARGBLK+O,
specify the address of a block of storage called
PRTBLK, which the X.25 Gateway Access Routines use
as a workspace.
To compute the length of PRTBLK
in words, use the following formula:
length

= 140 + (packet size/4)

Therefore, if your packet size is 16, for example,
specify a PRTBLK length of 144.
The X.25 software returns the port number in
ARGBLK+O.
You must use this value when calling
many of the other subroutines. The port number is
also the interrupt channel when you specify a
positive number in the left half for
input.
You
can use it to determine which channel the software
interrupt has been granted by the system.
ARGBLK+l

contains the return code. Following are the X%OPC
return codes.
Upon return from this subroutine,
one or more of these can be set:
XC%SUC

X%OPC
is
executed
succe~sfully:
a
permanent virtual circuit 1S allocated
exclusively for the user job, and the port
state changes from UNDEFINED to OPEN.

XC%VSK

The version numbers of the TOPS-IO PSI
Gateway Access Routines and the TOPS-IO
PSI Gateway Software are not compatible.

XC%NDN

You have specified a permanent circuit
that has not been defined in the DECnet-lO
Network Management data base.

XC%INA

You have not specified a password, or you
have specified an incorrect password for
gaining access to the PPSN through the
Gateway node.
4-13

MACRO-10 SUBROUTINE CALLS

X%OPC (Cont.)
XC%UNN

You have specified a network name that has
not been defined in the DECnet-10 Network
Management data base.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port
already been allocated.

that

has

A
logical
• established
reasons
above.

could
not
be
link
to the Gateway node for
other than those specified

XC%IAR

does
not
The
TOPS-IO
system
sufficient resources to allocate
circuit.

XC%IGR

The TOPS-IO PSI Gateway
sufficient resources to
permanent circuit.

have
a new

does not have
allocate a new

ARGBLK+2

contains an ASCIZ byte pointer to the name of the
PPSN over which you want to communicate. This
name is user supplied and can be a maximum of 16
ASCII characters.

ARGBLK+3

contains an ASCIZ byte pointer to the password
required for gaining access to the X.25 Gateway.
This password 1S user supplied and can be a
Your system
maximum of 16 ASCII characters.
manager determines this password.

ARGBLK+4

contains an ASCIZ byte pointer to the name of the
PVC you are using.
This name is user supplied and
can be a maximum of 16 ASCII characters.
Your
system manager can supply you with the PVC name.

4-14

MACRO-10 SUBROUTINE CALLS

XO/oRAD

READ ACCEPT DATA

Use the X%RAD subroutine to read information obtained from the remote
DTE after it accepted your request to establish a switched virtual
ci~cuit connection.
Some PPSNs do not supply data in all the
described fields.
Where no data is supplied, the fields are filled
with nulls (binary Os) or the corresponding length field
is zero.
When you issue an X%RAD subroutine call,
the port state must be
RUNNING.
The calling sequence for the X%RAD subroutine call is:
MOVEI ACI,ARGBLK
PUSHJ P,X%RAD
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you call X%ISC (INITIATE SWITCHED CIRCUIT) to
set up the virtual circuit.

ARGBLK+I

contains the return code. Following are the X%RAD
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%RAD is executed successfully:
the user
accept data and/or facilities data is
returned.
The port state remains RUNNING.

XC%DFT

The accept data field is truncated because
you did not supply a buffer large enough
to contain that data.

XC%FFT

The facilities data field
is truncated
because you did not supply a buffer large
enough to contain that data.

XC%NDA

There is no user accept data.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC before
executing
X%RAD.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

•

You have attempted
subroutine with a
circuit.

to execute this
permanent virtual

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.

4-15

MACRO-IO SUBROUTINE CALLS

X%RAD (Cont.)
ARGBLK+2

contains an ASCIZ byte pointer to the buffer in
which X%RAD returns the binary closed user group
or closed user group supplied by the remote DTE.
The group name can be a maximum of 16 ASCII
characters.

ARGBLK+3

contains the length and address of the buffer in
which X%RAD returns facilities data supplied by
the remote DTE.
In the left half of ARGBLK+3,
specify the maximum number of 8-bit bytes that the
buffer can receive.
This data can be as many as
63 8-bit bytes.
Upon return, X%RAD sets the left
half of ARGBLK+3 equal to the actual number of
8-bit bytes returned in the buffer.
In the right
half of ARGBLK+3,
specify the address of this
buffer.
(For information on facilities data, see
the documentation for your PPSN.)

ARGBLK+4

contains the length and address of the buffer in
which X%RAD returns accept data supplied by the
remote DTE.
In the left half of ARGBLK+4, specify
the maximum number of 8-bit bytes that the buffer
can receive.
This data can be as many as 16 8-bit
bytes
(or 128 for
fast select calls).
Upon
return, X%RAD sets the left half of ARGBLK+4 equal
to the actual number of 8-bit bytes returned in
the buffer.
In the right half of ARGBLK+4,
specify the address of this buffer.

4-16

MACRO-IO SUBROUTINE CALLS

X%RCD

READ CLEAR DATA

Use the X%RCD subroutine to read data obtained when an SVC is cleared.
The content of the data is PPSN specific, but not all PPSNs provide
this information when an SVC is cleared.
Use the X%RPS
(READ PORT
STATUS)
subroutine to determine that the PPSN has cleared the virtual
circuit. When you issue an X%RCD subroutine call, the port state must
be CLEARED.
The calling sequence for the X%RCD subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%RCD
whe.re:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you call X%ISC (INITIATE SWITCHED CIRCUIT) or
X%WIC
(WAIT INCOMING CALL) to set up the virtual
circuit.

ARGBLK+l

contains the return code.
Following are the X%RCD
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%RCD is executed successfully:
the clear
cause, clear diagnostic, and/or user clear
data, and/or facilities are returned.
The
port state remains CLEARED.

XC%DFT

The user clear data field
is truncated
because you did not supply a buffer large
enough to contain that data.

XC%FFT

The facilities data field
is truncated
because you did not supply a buffer large
enough to contain that data.

XC%NDA

There is no user clear data.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC or X%WIC
before
executing X%RCD.

•

You have attempted to execute this
subroutine when the port state is not
CLEARED.

4-17

MACRO-IO SUBROUTINE CALLS

X%RCD (Cont.)
have attempted
• You
subroutine with a

to execute this
permanent virtual

circuit.
The logical link between the user job
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains the clear cause bytes returned by X%RCD.
In the left half of ARGBLK+2, X%RCD returns the
network clear cause supplied by the PPSN.
If this
value is nonzero,
the network has cleared the
call.
This value is the network clear cause and
the network clear diagnostic is in the right half
of this word.
If this value is zero,
the remote
user has cleared the SVC, and the user clear
diagnostic is contained
in the right half of
ARGBLK+2.
(For
information on the network clear
cause and diagnostic, see the documentation for
your PPSN.)

ARGBLK+3

contains an ASCIZ byte pointer to the buffer in
which X%RCD returns the binary closed user group
or closed user group supplied by the remote DTE.
The group name can be a maximum of 16 ASCII
characters.

ARGBLK+4

contains the length and address of the buffer in
which X%RCD returns facilities data supplied by
the remote DTE.
In the left half of ARGBLK+4,
specify the maximum number of 8-bit bytes that the
buffer can receive.
This data can be as many as
63 8-bit bytes.
Upon return, X%RCD sets the left
half of ARGBLK+4 equal to the actual number of
8-bit bytes returned in the buffer.
In the right
half of ARGBLK+4,
specify the address of this
buffer.
(For information on facilities data, see
the documentation for your PPSN.)

ARGBLK+5

contains the length and address of the buffer in
which X%RCD returns clear data supplied by the
remote DTE.
In the left half of ARGBLK+5, specify
the maximum number of 8-bit bytes that the buffer
can receive.
This data can be as many as 16 8-bit
bytes
(or 128 for
fast select calls).
Upon
return, X%RCD sets the left half of ARGBLK+5 to
the actual number of 8-bit bytes returned in the
buffer.
In the right half of ARGBLK+4,
specify
the address of this buffer.

4-18

MACRO-IO SUBROUTINE CALLS

X%RDM

READ DATA MESSAGE

Use the X%RDM subroutine to receive data from a virtual circuit.
The
data can be either normal or qualified. When you issue an X%RDM
subroutine call, the port state must be RUNNING.
The calling sequence for the X%RDM subroutine is:
MOVEI ACl,ARGBLK
PUSHJ P,X%RDM
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT),
X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL) •

ARGBLK+l

contains the return code.
Following are the X%RDM
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%RDM is executed successfully: a normal
or qualified user data packet is returned.
The port state remains RUNNING.

XC%RSS

There is no data
returned because
reset.

XC%BTS

The buffer is too short.
You receive a
partially filled data packet with the more
bit set.
The more bit is set upon return
from
the
function.
However,
it is
entirely up to you how you handle such a
data packet.
For example, you can choose
to ignore the data packet and reset the
circuit.

XC%DFT

The data field is truncated because you
supplied a buffer which is not large
enough to accommodate the entire data
packet.

XC%NDA

There is no user data to be returned.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:

from the PPSN to be
the circuit has been

•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC,
X%OPC,
or X%WIC
before executing X%RDM.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

4-19

MACRO-10 SUBROUTINE CALLS

XO/oRDM (Cont.)
The logical link between the user job
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains the more-data and data-qualifier bits
(see Table 4-2)
and the number of bytes of data
received.
Interpret the received more-data and
data-qualifier bits in the following way:
•

If bit 0 is 0, the more-data bit is not set.
This
means that the next packet is not
logically related to the current one.

•

If bit 0 is 1, the more-data bit is set. This
means that the packet you have just read is
full and the next packet is logically related
to
the current one
(the nature of this
relationship is user defined).

•

If bit 1 is 0, the data you have just read
normal data.

•

If bit 1 is 1, the data you have just read
qualified data.

In the right half of ARGBLK+2, specify the maximum
number of bytes that you can receive.
Upon
return, X%RDM sets ARGBLK+2 to the actual number
of bytes received.
If the actual number of bytes
received is 0 and the return code in ARGBLK+1 is
XC%SUC
(successful), you have received an empty
Data packet.
ARGBLK+3

Table 4-2:

contains the destination byte pointer to the
location in which X%RDM returns incoming data.
Upon return, X%RDM sets this byte pointer to the
first byte following the last received byte.

More-bit and Data-qualifier Bit Meanings

Bit

Symbol

Meaning

XM%MOR

More bit

XM%QUA

Qualified data bit

4-20

MACRO-IO SUBROUTINE CALLS

X%RIC

READ INCOMING CALL

Use the X%RIC subroutine to obtain information about an incoming call
when the port state changes from LISTENING to CALLED. When you issue
an X%RIC subroutine call, the port state must be CALLED.
The calling sequence for the X%RIC subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%RIC
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you call X%WIC (WAIT INCOMING CALL) to set up
the virtual circuit.

ARGBLK+I

contains the return code.
Following are the X%RIC
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%RIC is executed successfully:
incoming
call
data and/or call facilities are
returned. The port state remains CALLED.

XC%DFT

The user-specified call data field
is
truncated because you did not supply a
buffer large enough to contain that data.

XC%FFT

The facilities field is truncated because
you did not supply a buffer large enough
to contain that data.

XC%NDA

There is no user call data.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%WIC before
executing
X%RIC.

•

You have attempted to execute this
subroutine when the port state is not
CALLED.

logical link between the user job
• The
and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains an ASCIZ byte pointer to the buffer in
which X%RIC returns the name of the network from
which the call originated. This name can be a
maximum of 16 ASCII characters.

4-21

MACRO-10 SUBROUTINE CALLS

XO/oRIC (Cont.)
ARGBLK+3

contains an ASCIZ byte pointer to the buffer in
which X%RIC returns the address of the calling
(remote) DTE. This address can be a maximum of 16
ASCII characters.

ARGBLK+4

contains an ASCIZ byte pointer to the buffer in
which X%RIC returns the subaddress of the called
(local) DTE. This subaddress can be a maximum of
16 ASCII characters.

ARGBLK+5

contains an ASCIZ byte pointer to the buffer in
which X%RIC returns the binary closed user group
or closed user group supplied by the remote DTE.
The group name can be a maximum of 16 ASCII
characters.

ARGBLK+6

contains the length and address of the buffer in
which X%RIC returns facilities data supplied by
the remote DTE.
In the left half of ARGBLK+6,
specify the maximum number of 8-bit bytes that the
buffer can receive. This data can be as many as
63 8~bit bytes.
Upon return, X%RIC sets the left
half of ARGBLK+6 equal to the actual number of
8-bit bytes returned in the buffer.
In the right
half of ARGBLK+6,
specify the address of this
buffer.
(For information on facilities data, see
the documentation for your PPSN.)

ARGBLK+7

contains the length and address of the buffer in
which
X%RIC returns user-specified call data
supplied by the remote DTE.
In the left half of
ARGBLK+7,
specify the maximum number of 8-bit
bytes that the buffer can receive. This data can
be as many as 16 8-bit bytes (or 128 for fast
select calls). upon return, X%RIC sets the left
half of ARGBLK+7 equal to the actual number of
8-bit bytes returned in the buffer.
In the right
half of ARGBLK+7,
specify the address of this
buffer.

4-22

MACRO-IO SUBROUTINE CALLS

X%RIM

READ INTERRUPT MESSAGE

Use the X%RIM subroutine to receive interrupt data. When you issue an
X%RIM subroutine call, the port state must be RUNNING.
Use the X%RPS
(READ PORT STATUS)
subroutine to determine whether there
is an
interrupt byte to read.
The calling sequence for the X%RIM subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%RIM
where:
ARGBLK+O

contains the port number,
which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT, or X%WIC (WAIT INCOMING CALL).

ARGBLK+I

contains the return code.
Following are the X%RIM
return codes and their meanings.
Upon return from
this subroutine, one or more of these can be set:

ARGBLK+2

XC%SUC

X%RIM is
executed
successfully:
an
interrupt data byte is returned.
The port
state remains RUNNING.

XC%RSS

There is no interrupt from the PPSN to be
returned because the circuit has been
reset.

XC%NIN

There is no interrupt.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a
procedure error as it tries
to execute this subroutine.
The procedure
error occurs for
one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC,
X%OPC,
or X%WIC
before executing X%RIM.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

•

The logical link between the user
job
and
the
Gateway
node
has been
disconnected.

contains a word
interrupt byte.

4-23

which

X%RIM

returns

the

MACRO-IO SUBROUTINE CALLS

X%RPS

READ PORT STATUS

Use the X%RPS subroutine to poll the port maintained by the TOPS-IO
PSI Gateway Software.
You can issue an X%RPS subroutine call
regardless of the current port state.
However, if the port state is
UNDEFINED,
the left half of ARGBLK+2 and all of ARGBLK+3 have
indeterminate meaning.
The calling sequence for the X%RPS subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%RPS
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL).

ARGBLK+I

contains the return code.
Following are the X%RPS
return codes and their meanings:

ARGBLK+2

XC%SUC

X%RPS is executed successfully:
the port
status and flags are returned. The port
state remains unchanges.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs because the logical link
between the user job and the Gateway node
has been disconnected.

contains the error condition and port state.
In
the left half of ARGBLK+2, X%RPS returns the last
fatal error condition (see Table 4-3) that changes
the port state to the ERROR state.
In the right
half of ARGBLK+2, X%RPS returns the current port
state.
See Tables 2-3 and 4-4 for information
about port states.

4-24

MACRO-IO SUBROUTINE CALLS

XO/oRPS (Cont.)
ARGBLK+3

contains the interrupt/data bit mask
(see Table
4-5)
and
the packet size.
In the left half of
ARGBLK+3,
X%RPS sets bits that
indicate
the
following:
•

If bit 0 is set,
there
is an
incoming
interrupt to be confirmed.
Use X%CIM (CONFIRM
INTERRUPT MESSAGE) to confirm the interrupt.

If bit 1 is set,
an outgoing
interrupt has
• been
transmitted but not confirmed by the
remote DTE.
•

If bit 2 is set, incoming data is available on
the data subchannel.
Use X%RDM (READ DATA
MESSAGE) to read the data.

•

If bit 3 is set, incoming
interrupt data is
available on the
interrupt subchannel.
Use
X25RIM (READ INTERRUPT MESSAGE)
to read the
data.

In the right half of ARGBLK+3, X%RPS
current packet size.
Table 4-3:

returns

Fatal Error Conditions

Bit

Symbol

Meaning

XE%IUG

Invalid user group

XE%VSK

Version skew

XE%DDL

Destination DTE address is too long

XE%SDL

Source DTE subaddress is too long

XE%FFT

Facilities field truncated

XE%DFT

Data field truncated

XE%NCM

No communication with the Public Network

XE%UNN

Undefined network name

XE%UCN

Undefined circuit name

XE%INU

Circuit in use (reserved)

XE%IGR

Insufficient gateway resources

XE%UNK

Unknown error

4-25

the

MACRO-lO SUBROUTINE CALLS

XO/oRPS (Cont.)
Table 4-4:

Port States

Decimal
Value

Symbol

Meaning

XS%UND

UNDEFINED

XS%OPN

OPEN

XS%CAG

CALLING

XS%LSN

LISTENING

XS%CAD

CALLED

XS%RUN

RUNNING

XS%SYN

SYNC

XS%UNS

UNSYNC

XS%CLG

CLEARING

XS%CLD

CLEARED

XS%ERR

ERROR

XS%NCM

NO COMMUNICATION

Table 4-5:
Bit

Interrupt/Data Bit Mask Meanings
Symbol

Meaning

XM%IIC

Incoming interrupt confirmation pending

XM%OIC

Outgoing interrupt confirmation pending

XM%DAT

Incoming data is available

XM%INT

Incoming interrupt data is available

1---

'--.

4-26

MACRO-IO SUBROUTINE CALLS

X%RRD

READ RESET DATA

Use the X%RRD subroutine to read information obtained when a virtual
circuit is reset.
The content of the data is network specified, but
not all networks provide this information when a call is reset.
Use
the X%RPS (READ PORT STATUS) subroutine to determine that the virtual
circuit has been reset. When you issue an X%RRD subroutine call,
the
port state must be UNSYNC.
The calling sequence for the X%RRD subroutine is:
MOVEI ACl,ARGBLK
PUSHJ P,X%RRD
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL).

ARGBLK+l

contains the return code.
Following are the X%RRD
return codes and their meanings:
XC%SUC

X%RRD is executed successfully:
the reset
cause
and reset diagnostic bytes are
returned.
The port state remains UNSYNC.

XC%PER

The
TOPS-IO
PSI
Gateway
software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC, X%OPC,
or X%WIC
before executing X%RRD.

•

You have attempted to execute this
subroutine when the port state is not
UNSYNC.

job
The logical link between the user
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains the reset cause and diagnostic bytes.
In
the left half of ARGBLK+2,
X%RRD returns the
network reset cause byte supplied by the PPSN.
If
this value is nonzero, the network has reset the
virtual circuit, and this value is the network
reset
cause
and
the network diagnostic is
contained in the right half of this word.
If this
value is zero,
the remote user has reset the
virtual circuit, and the user reset diagnostic
byte is contained in the right half of ARGBLK+2.
(For information on the network reset cause byte,
see the documentation for your PPSN.)

4-27

MACRO-lO SUBROUTINE CALLS

X%RVC

RESET VIRTUAL CIRCUIT

Use the X%RVC subroutine to reinitialize a virtual circuit and return
it to the state it was
in before data is transferred over that
circuit. At the time of resetting, the PPSN might discard data and
interrupt packets that are in transit.
Also, use the X%RVC subroutine
to acknowledge a reset from the network.
When you initiate a reset, the port state changes from RUNNING to
SYNC.
When the PPSN initiates a reset, the port state changes from
RUNNING to UNSYNC.
Acknowledge a PPSN reset as soon as possible
because the network may time out and clear the circuit before you
acknowledge. When you issue an X%RVC subroutine call, the port state
must be either RUNNING or UNSYNC.
The calling sequence for the X%RVC subroutine call is:
MOVEI ACl,ARGBLK
PUSHJ P,X%RVC
where:
ARGBLK+O

contains the port number, which
identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL) •

ARGBLK+l

contains the return code.
and their meanings are:

The X%RVC return

codes

XC%SUC

X%RVC is executed successfully.
If you
use X%RVC to initiate a reset on the
circuit, a reset request is sent to the
PPSN and the port state changes from
RUNNING to SYNC.
If you use X%RVC to
confirm a reset indication from the PPSN,
a reset confirmation is sent to the PPSN,
and the port state changes from UNSYNC to
RUNNING.

XC%PER

The
TOPS-lO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC,
X%OPC,
or X%WIC
before executing X%RVC.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING or UNSYNC.

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.

4-28

MACRO-IO SUBROUTINE CALLS

XO/oRVC (Cont.)
ARGBLK+2

contains an 8-bit byte in which you
supply
user-defined diagnostic data to the remote user.
The X.25 software ignores this value if you use
X%RVC to confirm a network reset.

4-29

MACRO-IO SUBROUTINE CALLS

X%SDM

SEND DATA MESSAGE

Use the X%SDM subroutine to queue a buffer of data for transmission to
the PPSN.
If this subroutine is executed successfully, the X.25
Gateway Access Routines have successfully transmitted the buffer.
However, successful execution does not mean that the data has reached
the PPSN.
Normally, the X%SDM subroutine is blocked until the entire data
message is transmitted successfully to the TOPS-IO PSI Gateway.
If
your program needs to perform non-blocking I/O functions,
you must
check the status of the channel
(and, therefore, the link to the
TOPS-IO PSI Gateway) prior to calling the X%SDM subroutine as follows:

ARGBLK: BLOCK
RSBLK: XWD
XWD
MOVE
HRRM
MOVEI
NSP.
JRST
MOVEI
TDNN
JRST
MOVEI
CALL

-DIO

iX.25 argument block
iWait bit, function, block length
iCode supplies channel number

«NS.WAI»+.NSFRS,2
0,0

iGet port number (also channel number)
iStore channel number in argument block

Sl,ARGBLK
Sl,RSBLK+.NSACH
Sl,RSBLK
Sl,
ERROR
Sl,NS.NDR
Sl,RSBLK+.NASCH
LSWARE
Sl,ARGBLK
X%SDM##

iRead status
iError
iSet up bit mask
iIs channel free for output?
iNo, go elsewhere
iSend the string to the network

With X%SDM, you can send data over either a normal or a qualified data
subchannel.
When you issue an X%SDM
RUNNING.

subroutine

call,

the

port

state

must

The calling sequence for the X%SDM subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%SDM
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL).

ARGBLK+I

contains the return code. Following are the X%SDM
return codes and their meanings. Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%SDM is executed successfully:
packet is sent to the PPSN.
state remains RUNNING.

4-30

a data
The port

MACRO-IO SUBROUTINE CALLS

XO/oSDM (Cont.)
XC%BTS

You attempt to send a buffer of data with
the more bit set, but the buffer is
smaller than the packet size that has been
agreed upon by the user job and the PPSN
during circuit initialization time.

XC%BTL

You attempt
is larger
been agreed
PPSN during

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs for one of the following
reasons:

to send a buffer of data which
than the packet size that has
upon by the user job and the
circuit initialization time.

•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC,
X%OPC, or X%WIC
before executing X%SDM.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains the more-data and data-qualifier bits
(see Table 4-2)
and the length of data to be
transmitted.
Set the following bits for the
following purposes:
To set the more-data bit, set bit 0 to 1. You
• can
set the more-data bit only if you are
sending a full packet. Setting the more data
bit also implies that the next packet is
logically related to the current one
(the
nature of this relationship is user defined) •
•

If you are transmitting normal data, set bit 1
to O.
If you are transmitting qualified data,
set bit 1 to 1.

In the right half of ARGBLK+2, specify the
in bytes of the data to be transmitted.
ARGBLK+3

length

contains the source byte pointer of the location
of the data to be transmitted.
The data must be
in bytes of 8 bits or less.
Upon return, X%SDM
sets ARGBLK+3 to the first byte following the last
transmitted byte.

4-31

MACRO-IO SUBROUTINE CALLS

X%SIM

SEND INTERRUPT MESSAGE

Use the X%SIM subroutine to send interrupt data.
One execution of
X%SIM sends one byte of interrupt data. When you issue an X%SIM
subroutine call, the port state must be RUNNING.
Only one interrupt
can be outstanding at anyone time.
To determine if an interrupt has
been acknowledged, execute the READ PORT STATUS function.
The calling sequence for the X%SIM subroutine is:
MOVEI ACI,ARGBLK
PUSHJ P,X%SIM
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL) •

ARGBLK+I

is the return code.
Following are the X%SIM
return codes and their meanings. Upon return from
this subroutine, one or more of these can be set:
XC%SUC

X%SIM is
executed
successfully:
an
interrupt message is sent to the PPSN.
The port state remains RUNNING.

XC%AIC

Prior to this execution of X%SIM, you have
sent the PPSN an interrupt message that
has not yet been confirmed. There can be
only one outstanding interrupt at any
time.

XC%PER

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine.
The procedure
error occurs for one of the following
reasons:
•

You have specified a port that has not
been allocated.
You may have failed
to execute X%ISC, X%OPC,
or X%WIC
before executing X%SIM.

•

You have attempted to execute this
subroutine when the port state is not
RUNNING.

The logical link between the user job
• and
the
Gateway
node
has been
disconnected.
ARGBLK+2

contains one 8-bit byte of interrupt data.

4-32

MACRO-10SUBROUTINE CALLS

X%TPA TERMINATE PORT ACCESS
Use the X%TPA subroutine to release all resources associated with a
port.
Executing the X%TPA subroutine causes either an active SVC to
be cleared or an active PVC to be released.
In either case, the port
state changes to UNDEFINED, and any data in transit can be lost.
You
can issue this subroutine regardless of the current port state.
The calling sequence for the X%TPA subroutine is:
MOVEI AC1,ARGBLK
PUSHJ P,X%TPA
where:
ARGBLK+O

contains the port number, which identifies the
port you are using.
The port number is returned
when you set up the virtual circuit by calling
X%ISC
(INITIATE SWITCHED CIRCUIT), X%OPC (OPEN
PERMANENT CIRCUIT), or X%WIC (WAIT INCOMING CALL).

ARGBLK+l

contains the return code.
Following are the X%TPA
return codes and their meanings:
XC%SUC

X%TPA is executed
successfully:
all
resources associated with the port are
released and the
port
state
became
UNDEFINED.

XC%PER

The
TOPS-10
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs because you have specified a
port that has not been allocated. You may
have failed to execute X%ISC, X%OPC, or
X%WIC before executing X%TPA.

4-33

MACRO-10 SUBROUTINE CALLS

X%WIC

WAIT INCOMING CALL

Use the X%WIC subroutine to create a target object to which your X.25
Gateway node can connect when an incoming call arrives from the PPSN.
The X%WIC subroutine obtains a network channel from Network Services
Protocol
(NSP)
that identifies the user process as a passive task.
The user process perceives an incoming virtual call as an
incoming
DECnet logical link from the X.25 Gateway module.
You perceive the
incoming call when the port state changes from LISTENING to CALLED.
The calling sequence for the X%WIC subroutine is:
MOVEI AC1,ARGBLK
PUSHJ P,X%WIC
where:
ARGBLK+O

contains the software interrupt channel and the
PRTBLK.
In the left half of ARGBLK+O, specify a
positive number to indicate software interrupt
service to be enabled for the logical link to the
X.25 node.
In the right half of ARGBLK+O, specify
the address of a block of storage called PRTBLK,
which the X.25 Gateway Access Routines use as a
workspace.
To compute the length of PRTBLK in
words, use the following formula:
length = 140 + (packet size/4)
Therefore, if your packet size is 16, for example,
specify a PRTBLK length of 144.
The X.25 software returns the port number in
ARGBLK+O.
You must use this value when calling
many of the other subroutines.
The port number is
also the interrupt channel when you specify a
positive number in the left half for
input.
You
can use it to determine which channel the software
interrupt has been granted by the system.

ARGBLK+1

contains the return code.
Following are the X%WIC
return codes and their meanings:
XC%SUC

X%WIC is executed successfully:
a circuit
is allocated to receive incoming calls
from the PPSN, and the port state changes
from UNDEFINED to LISTENING.

XC%IAR

The
TOPS-IO
system
does
not
sufficient resources to allocate
port.

4-34

have
a new

MACRO-IO SUBROUTINE CALLS

X%WIC (Cont.)
XC%PER

ARGBLK+2

The
TOPS-IO
PSI
Gateway
Software
encounters a procedure error as it tries
to execute this subroutine. The procedure
error occurs for one of the following
reasons:
•

You have specified a port
already been allocated.

that

has

•

A DECnet server logical link could not
be established because of system or
DECnet errors.

contains an ASCIZ string pointer to the DECnet
object identification (in the format or name or a
numerlC string)
that identifies your process.
Your system manager can supply you with the object
identification, which is in the X.25 Server Data
Base.
See the TOPS-IO PSI System Manager's Guide
for information on how the X.25 Gateway Software
compares data in the X.25 Server Data Base with
data in Incoming Call Packets to select which
incoming calls should be routed to your process.

4-35

PART III
X.29 Reference Guide

CHAPTER 5
THE TOPS-IO X.29 SOFTWARE

The TOPS-IO X.29 Software, X29SRV, connects your terminal - through a
PPSN - to a TOPS-IO host.
To make this connection,
follow the
instructions in this chapter, which explain how to:
•

Establish a physical connection between your terminal and the
PPSN Packet Assembler/Disassembler (PAD) facility.

•

Instruct the PAD to create a virtual circuit that connects
your terminal to X29SRV on the TOPS-IO host through the X.25
Gateway node.

•

Instruct X29SRV to connect your terminal to the TOPS-lO
of your choice.

host

Figure 5-1 illustrates the major hardware and software components that
are needed for these connections.

5-1

THE TOPS-10 X.29 SOFTWARE

TOPS-10
Host

DECsystem-10

MR-S-3711-84

Figure 5-1:

X.29 Terminal Access to a TOPS-10 Host

The remote terminal in Figure 5-1 is communicating with a TOPS-10 host
that is running both X29SRV and the user job.
It is also possible to
connect a remote terminal to a TOPS-10 host other than one that is
running the X.29 Software.
Figure 5-2 illustrates the components
needed for such a connection.

5-2

THE TOPS-lO X.29 SOFTWARE

TOPS-10
Host

DECsystem-10

User Job

NRT
Protocol
DECsystem-10

X29SRV
TOPS-10 PSI
Gateway
Access Routines

MR-S-3712-84

Figure 5-2:

X.29 Terminal Access to a
Running the X.29 Software

5-3

TOPS-lO

Host

that

Not

THE TOPS-10 X.29 SOFTWARE
5.1

SAMPLE DIALOGUE

To access the TOPS-IO system from a public access PAD on
network, follow these steps:

the

TELENET

Dial into TELENET.
Your terminal displays
a
message
indicating you have established a connection successfully.

Enter Dl as your terminal type at the TERMINAL= prompt.

Enter C, which stands for the CONNECT
network address at the @ prompt.

Note that X29SRV indicates you have connected to
successfully.

~5.

Use the CONNECT command to connect to the DECnet host of your
choice, in this case, DRMESQ.

Note that your terminal displays the response from
system.

Use the BREAK key to return to X29SRV Command Mode.

Use the DISCONNECT command to disconnect from the host.

Use the CONNECT command again to connect
host, ALBIE.

10.

Use the CLEAR command to terminate your session.

5-4

command,

and
the

the

another

your
system

host

DECnet

THE TOPS-IO X.29 SOFTWARE
The following example shows the terminal session:
TELENET
617 181

<------------------------------------------------------(1)

TERMINAL=D1

@C 61772 @D

<----------------------~---------------------(2)

<------------------------------------------------(3)

617 72 CONNECTED
<---------------------------------------------(4)
Digital Equipment Corporation TOPS-10 PSI Gateway X.29 Server
Friday, April 13, 1984 11:06:31:AM
V1.0(0) #110(00)
X29SRV> CONNECT DRMESQ ~

<---------------------------------(5)

RL175D DEClO Development 11:10:47 TTY52 system 1026/1042
Connected to Node DRMESQ(26) Line # 52
Please LOGIN or ATTACH

<-----(6)

• ~AEA~
<-----------------------------------------------------(7)
BREAK
X29SRV> DISC ~
<-------------------------------------------(8)

HOST SYSTEM DISCONNECTED
X29SRV> CONNECT ALBIE @D

<-------------------------------(9)

CSSE KS 4145 7.02 11:12:29
[ Idle line disconnected by host ]
HOST SYSTEM DISCONNECTED
X29SRV> CLEAR ~
<------------------------------------------(10)
DISCONNECTING •••••
617 72 DISCONNECTED 00 00 00:00:01:17 30 25

5.2

X.3, X.28 AND X.29

The CCITT has endorsed three recommendations that define the form that
character terminal access to an X.25 packet switching network should
take.
These are Recommendations X.3,
X.28 and X.29
(described in
Section 1.2).
These three recommendations and X.25 together provide a specification
for a Packet Assembler/Disassembler (PAD), which interfaces character
terminals to an X.25
packet
switching
network.
The
CCITT
recommendations are:
•

Recommendation X.3, which defines the set of parameters that
the PAD uses to control your terminal. You can set the
parameter values or they can be pre-set in network tables
and/or set by the host.

•

Recommendation X.28, which defines control procedures used to
establish the physical connection to the PPSN, the commands
you send to the PAD, and the service signals you receive from
the PAD.

5-5

THE TOPS-lO X.29 SOFTWARE
•

Recommendation X.29, which defines the control messages sent
between the PAD and an X29SRV host.
All control or PAD
messages are special X.25 data packets, called qualified data
packets.

•

Recommendation X.25, which defines procedures used by the PAD
to establish a virtual call to the host, to transmit and
receive data packets, and to clear virtual calls.

Figure 5-3 shows how the different protocols work together to
an X.29 terminal connection •

.~ I !)
l - .

X.28

X.25

X.3

support

HOST

@>$\

...- - - - - - - X . 2 9 --------I~
MR-S-3714-84

Figure 5-3:

5D3

X.3, X.25,
Connection

and

X.29

Supporting

X.29

Terminal

COMMAND LEVELS

You can communicate with a TOPS-IO host system through a
PPSN using
various software components that belong to either the PPSN or the
TOPS-IO PSI Gateway system.
For
example,
assume
that
your
DECsystem-IO is part of the configuration in Figure 5-4:

5-6

THE TOPS-lO X.29 SOFTWARE

~-s:4\

-----

-r------t

Asynchronous
Terminal
Connection

DECsystem-10

MR-S-3715-84

Figure 5-4:

TOPS-lO PSI Gateway X.29 Interface

The PAD can be implemented either as a dedicated device with
controlling software or as software modules within an existing
computer system that has an X.25 interface.
Normally,
the two
software components that you will communicate with prior to logging
into your TOPS-lO system are:
•

The PAD operating software

•

X29SRV residing on one of the TOPS-lO systems in
network

the

DECnet

The PAD operating software is the first level software in the
connection.
It provides you with a set of commands, one of which lets
you request a connection to the TOPS-lO PSI Gateway node on the X.25
PPSN.
Each PPSN provides a different set of commands.
Refer to your
PPSN user's manual for their descriptions.
The TOPS-lO PSI X.29 software
provides you with commands to:

is
to

the
a

second

•

Request a connection
network

•

Disconnect from a connection
DECnet network

•

Perform other miscellaneous functions

5-7

level

software.

TOPS-lO

system

TOPS-lO

system

the

DECnet
on

the

THE TOPS-IO X.29 SOFTWARE
Each software component
communication:
•

provides

you

with

two

distinct

modes

Command Mode
In Command Mode, the software component processes the text
you enter at your terminal as user commands.
You control the
software component in this mode.
One of these commands lets
you enter the data mode.
Another command lets you terminate
the connection from the component itself.

•

Data Mode
In Data Mode, most of the text you enter at the terminal
is
forwarded
to the next component as data to be processed by
the next component.
Usually, a special character or sequence
of characters
(ESCAPE command)
lets you enter the command
mode.
This may not necessarily be the ESCAPE key at your
keyboard.
See
the
appropriate documentation of each
component for information about the ESCAPE command in Data
Mode.

Thus, while you are communicating with X29SRV in its Command Mode, the
PAD
software processes your terminal
input in its Data Mode.
Similarly, while you are connected to the TOPS-IO system, both X29SRV
and the PAD software process your terminal input in their respective
Data Modes.
Refer to your PPSN user's manual for the descriptions of commands
the Command Mode and the ESCAPE command in the Data Mode.

5.4

COMMUNICATING WITH THE PAD

To connect your terminal to a PAD:

5.5

Follow instructions in your PPSN user's manual
connection between your terminal and the PAD.

create

Follow instructions in your PPSN user's manual
to create a
connection between the PAD and the TOPS-IO PSI Gateway node,
which creates a virtual circuit between your terminal and
X29SRV.
To follow the instructions in the PPSN user's
manual, you will need the DTE address of the X.25 Gateway
node; your system manager can supply you with that value.

COMMUNICATING WITH X29SRV

X29SRV provides you with commands to control your terminal session and
the characteristics of the connection.
You can abbreviate all commands.
Use the number of characters needed
to make the command unique.
For example, you can use CL for the CLEAR
command or I for the INFORMATION command.

5-8

THE TOPS-10 X.29 SOFTWARE
5.5.1

Error Conditions

If you enter a command that is syntactically
responds with the following error message:

incorrect,

X29SRV

?Illegal X29SRV command <command text>
<diagnostic text>
where <command text> is the text string that X29SRV acknowledges
receiving from you and <diagnostic text> is the reason the command is
incorrect.
The following are examples of X29SRV detection
of
syntactical errors. For example, if you misspell the command CONNECT,
your terminal displays:
X29SRV> CONECT MARKET FOX ~
?Illegal X29SRV command "CONECT MARKET FOX"
Unrecognized switch or keyword: "CONECT"
X29SRV>
If you abbreviate a command so that it is not unique, you cause an
error condition. For example, there are two commands that begin with
the character C -- CLEAR and CONNECT. Therefore, you must shorten the
commands to two characters -- CL and CO.
X29SRV> C MARKET FOX ~
?Illegal X29SRV command tIC MARKET FOX"
Ambiguous switch or keyword: "c"
X29SRV>
If you enter a command that is longer than the packet size set up by
the network for your terminal connection, the command cannot be
processed correctly by X29SRV.
The following sections list the commands in alphabetical order.

5-9

THE TOPS-lO X.29 SOFTWARE
5.5.2

CLEAR Command

Description:
Command Mode command.
The CLEAR command disconnects your terminal from X29SRV.
You
return to the PAD's Command Mode when X29SRV terminates the
connection.
Format:
CLEAR
Arguments:
None.
Messages:
DISCONNECTING
The PAD software has been requested to disconnect
your terminal from X29SRV and put your terminal
communication back at the PAD's Command Mode.
Remarks:
None.
Example:
X29SRV> CLEAR

DISCONNECTING

5-10

THE TOPS-IO X.29 SOFTWARE
5.5.3

CONNECT Command

Description:
Command Mode command.
The CONNECT command requests a connection to one of the TOPS-IO
systems on the DECnet network that is serviced by X29SRV.
Format:
CONNECT

host

[padset]

Arguments:
host

is the host name of
DECnet network.

the

TOPS-IO

system

the

pad set

is the name of a set of CCITT and other national
X.3 parameters present at the DECsystem-10 running
X29SRV.
X29SRV uses
the
values
of
those
parameters to define your terminal characteristics
after the connection to the host is established
successfully.
Your system manager can supply you with the names
of the X.3 parameter sets you can use and the X.3
parameters contained in each set.
If you do not
include the name of an X.3 parameter set in the
command, a default parameter set will be used.
For more information on X.3 parameters, see the
TOPS-IO PSI System Manager's and Operator's Guide.

Messages:
CONNECTION IS NOT SUPPORTED
X29SRV cannot service the host system that you
specified due to incompatible protocols within the
DECnet network (usually because that system is not
running either the TOPS-IO or TOPS-20 operating
system) •
FAILED TO CONNECT
The host system that you specified does not exist
on the DECnet network or it is temporarily out of
service.
UNDEFINED X.3 PARAMETER SET
The name of the X~3 parameter set that you
specified in the CONNECT command has not been
defined and the default parameter set has been
used instead.
TIMED OUT
You took too long to request
host system.

5-11

connection

THE TOPS-IO X.29 SOFTWARE
DISCONNECTING
The PAD software has been requested to disconnect
your terminal from X29SRV and put your terminal
communication back at the PAD's Command Mode.
Remarks:
Depending on how your system manager defines the characteristics
of X29SRV,
it may allow you to try again after unsuccessfully
attempting to connect to a host system.
For security reasons,
the system manager may choose to have X29SRV terminate a
connection after an unsuccessful attempt and you will be back at
the PAD's Command Mode.
If you issue the CONNECT command while the connection to a host
system is still active, your job on that system will be detached
when the new connection is being established.
Example:
X29SRV> CONNECT DRMESQ FDX ~
RL175D DEClO Development 17:27:02 TTY54 system 1026/1042
Connected to Node DRMESQ(26) Line
54
Please LOGIN or ATTACH

5-12

THE TOPS-IO X.29 SOFTWARE
5.5.4

DEFINE Command

Description:
Command Mode command.
The DEFINE command lets you change the X.3 parameters that define
your terminal connection characteristics.
If you use this command prior to connecting to a TOPS-10 host,
the X.3 parameters in the set specified by the CONNECT command
(or the default set if none is specified) may supersede the
values defined by this command.
Format:
DEFINE

DEFAULT
padset

Arguments:
pad set

Messages:
UNDEFINED X.3 PARAMETER SET
The parameter set that you specified has not
defined.
None

been

The command has been executed successfully.

Remarks:
If you specify the DEFAULT keyword,
the default parameter set
will be used.
Your system manager can tell you what X.3
parameters are contained in that set.
Example:
X29SRV> DEFINE DEFAULT ~
X29SRV> DEFINE FOX ~

5-13

THE TOPS-IO X.29 SOFTWARE
5.5.5

DISCONNECT Command

Description:
Command Mode command.
'rhe DISCONNECT command lets you terminate the connection to the
TOPS-IO host.
If you have not logged out prior to entering this
command, your job at the host system will be detached. You will
be back at the X29SRV's Command Mode.
Format:
DISCONNECT
Arguments:
None.
Messages:
HOST SYSTEM DISCONNECTED
The host system disconnected youz terminal session
successfully.
None

You are not connected to any host system.

Remarks:
None
Example:
X29SRV> DISCONNECT

HOST SYSTEM DISCONNECTED

5-14

THE TOPS-10 X.29 SOFTWARE
5.5.6

INFORMATION Command

Description:
Command Mode command.
The INFORMATION command displays various information related to
the terminal connection.
Due to security reasons, the system
manager may choose to disable this command and
not
all
information will be displayed.
Format:
INFORMATION
Arguments:
None.
Messages:
None
Remarks:
None.
Example:
X29SRV> INFORMATION

9-JUN-84 02:43:29PM Line 00 At Node 110 (DRMESQ)
Connected to DRMESQ
Available X.3 profiles (6): DEFAULT, EDIT, FOX, HDX, KERMIT, UK

5-15

THE TOPS-IO X.29 SOFTWARE
5.6

ENTERING COMMAND MODE

When you communicate with the TOPS-IO host system, you are in the Data
Mode.
You can enter the X29SRV Command Mode by pressing the BREAK key
at your keyboard. This triggers the PAD software to transmit a
command sequence to X29SRV notifying it of your request.
X29SRV
responds by temporarily suspending the output from the TOPS-IO host
system and starts processing the text you type at your terminal as
X29SRV commands (see Section 5.3).
If data is passing through the
PPSN when you press the BREAK key,
it is discarded by the PAD
software. A null command (a carriage return without preceding text)
lets you resume the Data Mode.
The example below shows the interaction between you and X29SRV during
a terminal session. Assume you want to disconnect from your current
TOPS-IO host system and connect to another TOPS-IO host system,
DRMESQ, on the same DECnet network:
.ms @D
24 messages, 27 blocks.
MS)read (message sequence) subject (string) DN20
%No messages match this specification
MS)exit @D
•

(BREAK)

BREAK
X29SRV) CONNECT DRMESQ

RL175D DEClO Development 14:27:47 TTY52 system 1055/1056
Connected to Node DRMESQ(26) Line # 52
Please LOGIN or ATTACH
.TTY NO ECHO

5-16

THE TOPS-IO X.29 SOFTWARE
You can resume a connection with a TOPS-IO host system by pressing the
RETURN key without any preceding text as follows:
X29SRV> CONNECT DRMESQ

RC702A 7.02 Miso System 09:33:48 TTY44 system 3500
Connected to Node DRMESQ(l) Line # 44
Please LOGIN or ATTACH
.TTY NO ECHO
.logi 07, 1055 ~
JOB 3 RC702A 7.02 Miso System TTY44

******

09:34

• d i r /f

7-Aug-84

Tue

(BREAK)

BREAK
X29SRV> info ~
7-AUG-84 09:34:24AM Line 00 At Node 169 (DRMESQ), Connected to DRMESQ
Available X.3 profiles (6): DEFAULT, EDIT, FDX, HDX, KERMIT, UK
X29SRV> ~
CONTINUE
(CTRl/R)

PIT:
SUBSYS
MAIL
DSKO:
DECLAR

5.7

dir/f ~
[07,1055]
SFD
PSITST
TXT
X25GEN

SFD
SFD

CCL

INI

SWITCH

X29

SFD

NML

SFD

TERMINATING A CONNECTION

You can break a connection with your PPSN at any time
the phone.

5-17

hanging

APPENDIXES

APPENDIX A
SAMPLE FORTRAN-IO PROGRAMS

This appendix contains sample FORTRAN-IO programs
with each other through a PPSN. The programs are:

that

communicate

•

SVCRCV, which accepts a switched Virtual
receives data sent through the circuit.

Circuit

call

and

•

SVCXMI, which initiates a Switched Virtual Circuit
sends data through the circuit.

call

and

Section A.I explains features of the two programs, while Section A.2
contains a listing of SVCRCV, and Section A.3 contains a listing of
SVCXMI.

A.I

PROGRAM FEATURES

This section explains and gives hints related to
of each program.

A.I.I

individual

features

Receiving Program

The program SVCRCV is the passive partner (slave) of the transmitting
program, SVCXMI.
SVCRCV starts by declaring itself available to
receive an incoming call from the X.25 gateway node. The program does
this by calling the subroutine X25WIC (Wait Incoming Call):
PROGRAM SVCRCV
EXTERNAL X25WIC
INTEGER CSTATE, NSTATE, PORT, RESULT
DIMENSION WORKSP(172)
CSTATE = 0
CALL X25WIC ('EXAMPLE', WORKSP, PORT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 3
NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 4) CALL ABORT (PORT, RESULT, NSTATE)

A-I

SAMPLE FORTRAN-lO PROGRAMS
SVCRCV initializes the current port state, CSTATE, as 0
(UNDEFINED)
before calling the subroutine X2SWIC. After the subroutine returns
successfully (return code 0), the program sets the current port state
to 3
(LISTENING).
Note that there are other subroutines that change
the port state upon successful execution.
When one of
these
subroutines has been successfully executed, you do not need to execute
X2SRPS to determine the port state. For example:
•

X2SRCV (RESET VIRTUAL CIRCUIT), which changes the port
from UNSYNC to RUNNING.

state

•

X2SNCS (NO COMMUNICATION SEEN), which changes the port
from NO COMMUNICATION to RUNNING.

state

The chosen length of the data packets in this example is 128 bytes.
The length of the array WORKSP (which is to be used by the TOPS-IO PSI
Gateway Access routines as working space) is calculated as follows:
140 + (128/4) = 172
The subroutine X2SWIC declares the user task to be a DECnet target
task that is available for network dialogue with the PSI Gateway
Software and uses the object name EXAMPLE.
After the subroutine
returns successfully, NSP assigns a logical link to the user task.
Contact your system manager for the appropriate object names and/or
object numbers on your system.
The program defines ABORT as a subroutine that displays the current
port state and error, terminates port access, and stops the program:

1000

SUBROUTINE ABORT (PORT, CODE, STATE)
EXTERNAL X2STPA
INTEGER PORT, CODE, STATE
WRITE (S,lOOO) CODE, STATE
FORMAT (/,' * ERROR #' ,12,', current port state' ,12,' *' ,I)
CALL X2STPA (PORT, 0)
STOP
END

After the X.2S port is allocated to wait for an incoming call, the
program calls the integer function ISTAT to poll for the port state
until it has changes:

100

200
300

INTEGER FUNCTION ISTAT (PORT, STATE)
EXTERNAL X2SRPS, IDLE
INTEGER PORT, STATE, PSTATE, RESULT
CALL X2SRPS (PORT, 0, PSTATE, 0, 0, 0, 0, 0, RESULT)
IF (RESULT .EQ. 0) GOTO 200
ISTAT = 10
RETURN
IF (PSTATE .NE. STATE) GO TO 300
CALL IDLE (S)
GOTO 100
ISTAT = PSTATE
RETURN
END

At times, you will find it necessary to wait for the circuit to change
from one state to another
(for example, from LISTENING to CALLED)
before any processing can be done for that circuit. While waiting, it
is advisable to incorporate a MACRO-lO routine into your code that
puts your program into a dormant state before calling subroutine
X2SRPS to check the status of the circuit. Constant calling of
subroutine X2SRPS to check the status of the circuit tends to create
unnecessary CPU activity.
A-2

SAMPLE FORTRAN-lO PROGRAMS
The function ISTAT calls the subroutine IDLE to perform that task;
Tl=l
T2=2
AP=l6
SP=l7

IDLE::

UUOSYM

PUSH
PUSH
MOVE
MOVE
MOVSI
ADD
HIBER
JFCL
POP
POP
POPJ
END

SP,Tl
SP,T2
T2,0(AP)
T2,0(T2)
TI,(HB.SEC)
Tl,T2
TI,

iSave temporary registers
iGet FORTRAN parameter entry
iGet the idle interval in seconds
iSleep
;Restore temporary registers

SP,T2
SP,TI
SP,O

iReturn

After the incoming call is received, the program accepts it by calling
the subroutine X25AIC (Accept Incoming Call).
In this instance, you
want to accept the incoming call unconditionally; you can, therefore,
ignore the content of the incoming call packet and proceed to call
subroutine X25AIC.
However, you can check the contents of the
incoming call packet by calling the subroutine X25RIC (Read Incoming
Call) before establishing the circuit.
The program accepts the
incoming call without specifying the user group, accept data, and
facilities. Those null parameters are represented by 0:
EXTERNAL X25AIC
CSTATE = 4
CALL X25AIC (PORT, 0, 0, 0, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 5
After the subroutine X25AIC returns successfully, the programmer
correctly assume that the port state has changes from 4 (CALLED) to 5
(RUNNING) • The program is ready to transfer data.

A-3

SAMPLE FORTRAN-lO PROGRAMS
It has been agreed that after the circuit is established, the program
SVCXMI will send an interrupt byte of any value to indicate that it is
ready to transmit data over the circuit. The program SVCRCV attempts
to read that interrupt byte:

EXTERNAL IDLE, X25RPS
INTEGER IBYTE
LOGICAL IAVAIL
100

110
1100

CALL X25RPS (PORT, 0, 0, 0, 0, 0, IAVAIL, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
IF (IAVAIL .EQ • • TRUE.) GO TO 110
CALL IDLE (1)
GOTO 100
CALL X25RIM (PORT, IBYTE, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
WRITE (5,1100) IBYTE
FORMAT (/,' Received interrupt byte '" ,03,/)

The private protocol, which has been agreed between the two programs,
calls for the program SVCRCV not to confirm the interrupt byte that it
has just received until it receives all of the data sent by its
partner, SVCXMI.
The main segment of the program SVCRCV is the subroutine RCVCON, which
reads and
interprets the data that the program receives from the
network.
RCVCON interprets data
according
to
the
following
conventions:
•

A data record is a set of data packets of which the last data
packet has the more bit not set.

•

Each data record is preceded by a "control" data packet
containing one 8-bit byte that indicates the conversion mode.
This user-defined conversion mode is in the range 1 to 9 and
indicates to the receiving program how it should read and
interpret the following data record.

•

If the "control" data packet contains a control-Z
(octal 32), the transmission is complete.

character

The subroutine RCVCON declares the dimension of the receiving data
array to be 512 words, which is long enough to ensure that there is
enough room for all types of data.
You should supply an array buffer
large enough to accommodate at least one packet of data with any data
type conversion mode.
You can obtain the current packet size by
calling the subroutine X25RPS.
The resulting length of the receiving array can vary from one data
type conversion mode to another.
For example, assume you have full
packet of 128 data bytes with the more bit not set is pending to be
read.
If the subroutine X25RDM (READ DATA MESSAGE) is called with
data type 0
(full 36 bits),
it will return a data array of 29

A-4

SAMPLE FORTRAN-10 PROGRAMS
elements. However, if the subroutine is called with data type 5
(leftmost 7 bits) it will return an array of 128 elements.
This read
conversion of the data, which is done by the subroutine X25RDM,
is
symmetrical to the write conversion procedure, which is done by the
subroutine X25SDM:

100

150

200

210
2100
212
220
2200
222
500

510
5100
520
5200
530
5300
540
5400
550
5500

SUBROUTINE RCVCON (PORT)
EXTERNAL X25RDM
INTEGER PORT, QBIT, CNVRSN, RESULT, LENGTH, REMLEN
LOGICAL MBIT
INTEGER BUFFER(512)
INTEGER IBUF(512)
REAL XBUF(512)
EQUIVALENCE (XBUF(l), BUFFER(l», (IBUF(l), BUFFER(l»
CALL WTDATA (PORT)
LENGTH = 512
CALL X25RDM (PORT, 4, BUFFER, LENGTH, QBIT, MBIT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (LENGTH .LE. 0) GOTO 100
IF (BUFFER(l) .EQ. "32) RETURN
CNVRSN = BUFFER(l)
REMLEN = 512
CALL WTDATA (PORT)
I = 512 - REMLEN + 1
LENGTH = REMLEN
CALL X25RDM (PORT, CNVRSN, BUFFER(I), LENGTH, QBIT, MBIT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (LENGTH .LE. 0) GOTO 100
GOTO (200,200,200,200,200,500,500,500,500,500) (CNVRSN+1)
REMLEN = REMLEN - LENGTH
IF (MBIT .EQ • • TRUE.) GOTO 150
LENGTH = 512 - REMLEN
GOTO (210,220,220,220,220) (CNVRSN + 1)
DO 212 I = 1,LENGTH,2
WRITE (5,2100) XBUF(I), XBUF(I+1)
FORMAT (' ',F10.6,' ',F10.6)
CONTINUE
GOTO 100
DO 222 I = 1,LENGTH
WR I TE ( 5 , 2200 ) I BUF ( I )
FORMAT (110)
CONTINUE
GO TO 100
ITEMPI = CNVRSN - 5 + 1
ITEMP2 = MOD (LENGTH, ITEMPl)
REMLEN = REMLEN - «LENGTH / ITEMPl) + ITEMP2)
IF (MBIT .EQ • • TRUE.) GOTO 150
LENGTH = 512 - REMLEN
GOTO (510,520,530,540,550) ITEMPI
WRITE (5,5100) (IBUF(I) ,I=l,LENGTH)
FORMAT (lH ,512Al,$)
GOTO 100
WRITE (5,5200) (IBUF(I) ,I=l,LENGTH)
FORMAT (lH ,512A2,$)
GOTO 100
WRITE (5,5300) (IBUF(I) ,I=l,LENGTH)
FORMAT (lH ,512A3,$)
GOTO 100
WRITE (5,5400) (IBUF(I) ,I=l,LENGTH)
FORMAT (lH ,512A4,$)
GOTO 100
WRITE (5,5500) (IBUF(I),I=l,LENGTH)
FORMAT (lH ,512A5,$)
GOTO 100
END
A-5

SAMPLE FORTRAN-10 PROGRAMS
Before each call of the subroutine X25RDM,
the program calls the
subroutine WTDATA to poll for incoming data from the network.
This
subroutine is similar to the function ISTAT, which checks for the port
state transition:

100

SUBROUTINE WTDATA (PORT)
EXTERNAL IDLE, X25RPS
INTEGER PORT, RESULT
LOGICAL DAVAIL
CALL X25RPS (PORT, 0, 0, 0, 0, DAVAIL, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (DAVAIL .EO • • TRUE.) RETURN
CALL IDLE (1)
GO TO 100
END

After the subroutine RCVCON is executed successfully, the main program
calls the subroutine X25CIM (CONFIRM INTERRUPT MESSAGE) to confirm the
interrupt received at the beginning of the connection:
CALL X25CIM (PORT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
At this point, the program SVCRCV has performed all of its funct10ns
and is ready to terminate the circuit.
However, before doing so, this
program, the passive partner of the pair, must wait for the circuit to
be cleared by the other program:

EXTERNAL X25RCD, X25TPA
INTEGER CAUSE, DIAGNO

1110
200

A.1.2

NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 9) GOTO 200
CALL X25RCD (PORT, CAUSE, DIAGNO, 0, 0, 0, 0, RESULT)
WRITE (5,1110) CAUSE, DIAGNO
FORMAT (' Port is cleared, cause "' ,03,', diagnostic "' ,03)
CALL X25TPA (PORT, RESULT)
STOP
END

Transmitting Program

The program SVCXMI is the active partner
(master)
of the receiving
program,
SVCRCV.
The program initiates all operations; that is, it
initiates the Switched Virtual Circuit call, the data transfer,
and
the clearing of the virtual circuit after receiving the confirmation
from its partner that the data has been received.
The program communicates with the user
to acquire text data and
generates "number crunching type" data to transfer to the receiving
program.
This program covers all data types,
both text and binary
(integer and real), which can be transferred over an X.25 circuit with
the FORTRAN-10 PSI Gateway Access routines.

A-6

SAMPLE FORTRAN-lO PROGRAMS
The program begins by prompting the user for the remote DTE
which the program uses in placing the virtual circuit call:

address,

PROGRAM SVCXMI
INTEGER LENGTH, DTE(4)
100
1000
1010

WRITE (5,1000)
FORMAT (' DTE address: ',$)
READ (5,1010) LENGTH, (DTE(I) ,1=1,4)
FORMAT (Q,4A5)
IF (LENGTH .LE. 0) GOTO 100

The program SVCXMI calls the subroutine X25ISC
Circuit) to establish the virtual circuit:

(Initiate

Switched

EXTERNAL X25ISC
DIMENSION WORKSP(172)
INTEGER CSTATE, NSTATE, PORT
CSTATE = 0
CALL X25ISC (8HTELENET , 'X25-GATE " DTE,
0, 0, 0, 0, 0, 0, WORKSP, PORT, RESULT)
$
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 2

After the subroutine X25ISC returns successfully,
the programmer
assumes that the port state has changes from 0 (UNDEFINED) to 2
(CALLING) without calling the subroutine X25RPS to obtain the new port
state.
In the above call of the subroutine X25ISC, the programmer chose not
to supply the calling DTE address, user group name, user data, or
facilities.
Those are specified as null parameters
(Os).
An ASCII
string parameter may be passed to the X.25 Gateway Access subroutines
as a variable name, Hollerith constant, or character constant.
Since
FORTRAN-lO does not allow null parameters in the argument list of a
CALL statement, specify a null string with the value O.
After the call request packet is sent to the network,
the program
calls the integer function ISTAT, which is described in Section A.l.l,
and polls for the port state until it has changes:

NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 5) CALL ABORT (PORT, 0, NSTATE)

A-7

SAMPLE FORTRAN-10 PROGRAMS
The program SVCXMI now sends an interrupt byte to its
indicate that it is ready to start transferring data.
prompts you for the value of the interrupt byte:

partner to
The program

INTEGER IBYTE
200
2000
2010

CSTATE = 5
WRITE (5,2000)
FORMAT (' Interrupt byte (octal): ',$)
READ (5,2010) IBYTE
FORMAT (03)
CALL X25SIM (PORT, IBYTE, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

This program demonstrates different ways of sending ASCII data, such
as text entered by the user and read in Al format and an ASCII file
read in A5 format.
Before each record of text is transmitted over the circuit, SVCXMI
notifies its partner of the type of transmitted data.
The program
does this by sending a "control" data packet containing one byte that
specifies the data type (see Section A.l.l for a description of the
private protocol between the two programs). After you enter the text,
the program stores each ASCII character in the leftmost 7 bits of each
array element of the array BUFFER. The variable LENGTH contains the
number of characters you enter:

INTEGER BUFFER(256)

300
3000
3010

CALL X25SDM (PORT, 4, 5, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
WRITE (5,3000)
FORMAT (' Text string: ',$)
READ (5,3010,ERR=300) LENGTH, (BUFFER(I) ,1=1,256)
FORMAT (Q,256Al)
IF (LENGTH .LE. 0) GO TO 300
CALL X25SDM (PORT, 5, BUFFER, LENGTH, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

A-8

SAMPLE FORTRAN-10 PROGRAMS
The program now tries to send a portion of
circuit:

ASCII

file

over

the

INTEGER FILBUF(2)
DOUBLE PRECISION FILNAM
EQUIVALENCE (FILBUF(l), FILNAM)
400
4000
4010

4020

410
420
430
440

WRITE (5,4000)
FORMAT (I File name: 1,$)
READ (5,4010) (FILBUF(I) ,I=1,2)
FORMAT (2A5)
OPEN (UNIT=l,DEVICE='DSK ' ,FILE=FILNAM,ACCESS='SEQIN ' ,ERR=440)
CALL X25SDM (PORT, 4, 9, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) GOTO 440
DO 420 M = 1,20
READ (1,4020,END=430,ERR=430) LENGTH, (BUFFER(I) ,I=1,256)
FORMAT (Q,256A5)
IF (LENGTH .LE. 0) GOTO 410
CALL X25SDM (PORT, 9, BUFFER, LENGTH, 0, .TRUE., RESULT)
IF (RESULT .NE. 0) GOTO 440
CALL X25SDM (PORT, 3, "6412, 1, 0, .TRUE., RESULT)
IF (RESULT .NE. 0) GOTO 440
CONTINUE
CALL X25SDM (PORT, 9, BUFFER, 0, 0, .FALSE., RESULT)
CLOSE (UNIT=l)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

After each text line from the ASCII file, the program sends a pair of
carriage return and line feed characters in the rightmost 16 bits
format (statement 410). The characters are passed to the subroutine
in the following format:

o
MR-S-2755-83

The rightmost 16 bits of the above 36-bit word
(6412 octal)
are
formatted
into 2 octets of the data packet (bits 20-27 form the first
octet and bits 28-35 form the second).
When those two octets are
received and interpreted by the receiving program, they are converted
into 7-bit ASCII characters that become carriage return (15 octal) and
line feed (12 octal) characters to be displayed.

A-9

SAMPLE FORTRAN-IO PROGRAMS
The above example demonstrates how to manipulate and transmit the data
with mixed data conversion modes.
Even though the read and write
conversion procedures are symmetrical, you can read the data with a
data type that differs from the one used in sending the data for some
conversion formats.
For example, you can use any of the ASCII data
formats
(5 to 9) and some others (e.g.
rightmost 16 bits as above,
with care) interchangeably to send and read the text data.
However, take extra care with other binary data conversion modes. The
following examples demonstrate ways of sending various types of binary
data. For those types of data,
it is advisable to use the same
conversion mode to send and receive the data.
In the following example, the program generates its own data to be
sent to the receiving program. The sending program calculates the
first 25 Fibonacci numbers and sends 10 copies of that set of numbers
with data type 3 (rightmost 16 bits).
The Fibonacci sequence starts:
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, ••••
Each new term is obtained by taking the sum of the two previous terms.
If the first term of the sequence is F(O), then
F(O)

= 0,

F(l)

and in general
F(n) = F(n-l) + F(n-2),

• GE.

The largest Fibonacci number in this set is 46368
(132440 octal),
which occupies a maximum of 16 bits of the array element. The FORTRAN
data type of the numbers is integer.

INTEGER IBUF(256)
EQUIVALENCE (IBUF(I), BUFFER(l»

500

IBUF(l) = 0
IBUF(2) = I
DO 500 I = 3,25
IBUF(I) = IBUF(I-l) + IBUF(I-2)
CONTINUE

A-lO

SAMPLE FORTRAN-10 PROGRAMS
First, the sending program sends an identification text string to
receiving program so that it can notify you of the nature of
received data. Notice that the length of the text string, 30, is
number of characters in the string, not the number of 36-bit words
string comprises:

the
the
the
the

CALL X25SDM (PORT, 4, 9, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL X25SDM (PORT, 9, 'The first 25 Fibonacci numbers', 30,
$
0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

The program sends 10 copies of
record:

510

CALL X25SDM (PORT,
DO 510 I = 1,10
CALL X25SDM (PORT,
IF (RESULT .NE. 0)
CONTINUE
CALL X25SDM (PORT,
IF (RESULT .NE. 0)

the

Fibonacci

numbers

one

data

4, 3, 1, 0, .FALSE., RESULT)
3, IBUF, 25, 0, .TRUE., RESULT)
CALL ABORT (PORT, RESULT, CSTATE)
3, IBUF, 0, 0, .FALSE., RESULT)
CALL ABORT (PORT, RESULT, CSTATE)

The data type 0 (36 bits) is ideal for transferring arrays of binary
data
(REAL, DOUBLE PRECISION, etc.). The following example sends an
array of the first 128 numbers and their square roots.
The program
generates the values of the array:

REAL NUMBER, XBUF(256)
EQUIVALENCE (XBUF(l) , BUFFER(l))

600

NUMBER = 1.0
DO 600 I = 1,256,2
XBUF(I) = NUMBER
XBUF(I+1) = SQRT (NUMBER)
NUMBER = NUMBER + 1.0
CONTINUE

A-II

SAMPLE FORTRAN-I0 PROGRAMS
The program sends the entire array by calling
only once:

the

subroutine

X25SDM

CALL X25SDM (PORT, 4, 9, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL X25SDM (PORT, 9, 30HNumbers and their Square Roots, 30,
$
0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL X25SDM (PORT, 4, 0, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL X25SDM (PORT, 0, ~BUF, 256, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

The program concludes the data transfer session by sending a control-Z
character
(32 octal) to its partner, then waits for the confirmation
of the interrupt byte it sent at the beginning of the session:
CALL X25SDM (PORT, 4, "32, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL WTCFRM (PORT, 300)
The subroutine WTCFRM is defined:

100

SUBROUTINE WTCFRM (PORT, WAIT)
EXTERNAL X25RPS, IDLE
INTEGER PORT, WAIT, RESULT
LOGICAL PENDNG
DO 100 I = 1,WAIT
CALL X25RPS (PORT, 0, 0, 0, PENDNG, 0, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (PENDNG .EQ • • FALSE.) RETURN
CALL IDLE (1)
CONTINUE
RETURN
END

At this point,
the receiving program acknowledges the end
of
transmission.
The sending program clears the virtual circuit and
terminates:
CALL X25CSC (PORT, "252, 0, 0, 0, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 8
CSTATE = ISTAT (PORT, CSTATE)
CALL X25TPA (PORT, RESULT)
STOP
END
The sending program clears the virtual circuit with the
user
diagnostic octal 252.
The program then waits for the network to
confirm the clear request by calling the function ISTAT, which is
described in Section A.l.l.

A-12

SAMPLE FORTRAN-IO PROGRAMS
A.2

LISTING OF SAMPLE PROGRAM SVCRCV.FOR
PROGRAM SVCRCV

C Storage declarations
C
EXTERNAL IDLE, X25AIC, X25RCD, X25RPS, X25TPA, X25WIC
INTEGER CSTATE, NSTATE, PORT, RESULT, IBYTE, CAUSE, DIAGNO
LOGICAL IAVAIL
DIMENSION WORKSP(172)
C Declare self to be available to receive an incoming call
C
CSTATE = 0
CALL X25WIC ('EXAMPLE', WORKSP, PORT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Check port state and wait for port state to become CALLED, then
C proceed and accept the incoming call
C
CSTATE = 3
NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 4) CALL ABORT (PORT, RESULT, NSTATE)
C Accept incoming call unconditionally
C
CSTATE = 4
CALL X25AIC (PORT, 0, 0, 0, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 5
C Check only interrupt available flag, ignore other indicators
C
100
CALL X25RPS (PORT, 0, 0, 0, 0, 0, IAVAIL, 0, RESULT)
C Check if we have detected the interrupt byte
C
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
IF (IAVAIL .EQ • • TRUE.) GOTO 110
C Idle process for 1 second before checking the circuit status again
C
CALL IDLE (1)
GOTO 100
C Read interrupt message
C
110
CALL X25RIM (PORT, IBYTE, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Display the received interrupt byte in octal
C
WRITE (5,1100) IBYTE
1100 FORMAT (/,' Received interrupt byte "',03,/)
C Read data and perform conversion for display
C
CALL RCVCON (PORT)
C Confirm interrupt that we received to confirm end of data reception
C
CALL X25CIM (PORT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Wait until port is cleared. If port state becomes anything else,
A-13

SAMPLE FORTRAN-IO PROGRAMS
C go ahead and terminate port access anyway.
C

NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 9) GOTO 200

C Read clear cause and diagnostic, ignore the data and facilities
C

1110

CALL X25RCD (PORT, CAUSE, DIAGNO, 0, 0, 0, 0, RESULT)
WRITE (5,1110) CAUSE, DIAGNO
FORMAT (I Port is cleared, cause "1,03,1, diagnostic "' ,03)

C Terminate port access and program
C

200

CALL X25TPA (PORT, RESULT)
STOP
END
SUBROUTINE RCVCON (PORT)

C+
C DESCRIPTION

Read and display received data.

C PARAMETERS
C-

PORT

Port number

EXTERNAL X25RDM
INTEGER PORT, QBIT, CNVRSN, RESULT, LENGTH, REMLEN
LOGICAL MBIT
INTEGER BUFFER(5l2)
INTEGER IBUF(5l2)
REAL XBUF(5l2)
EQUIVALENCE (XBUF(l), BUFFER(l»,

(IBUF(l), BUFFER(l»

C Wait for protocol data byte
C

100

CALL WTDATA (PORT)

C Set length of the receiving buffer and read protocol byte
C

LENGTH = 512
CALL X25RDM (PORT, 4, BUFFER, LENGTH, QBIT, MBIT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
C Ignore null string
C

IF (LENGTH .LE. 0) GO TO 100
C Check if this is the end of data reception
C

IF (BUFFER(l)

.EQ. "32) RETURN

C Record the data conversion code
C
CNVRSN = BUFFER(l)
C Initialize buffer length
C
REMLEN = 512
C wait for actual data buffer

A-14

SAMPLE FORTRAN-10 PROGRAMS
C

150

CALL WTDATA (PORT)

C Calculate the starting address of the receiving buffer
C

I = 512 - REMLEN + 1
LENGTH = REMLEN

C Read data record
C

CALL X25RDM (PORT, CNVRSN, BUFFER(I), LENGTH, QBIT, MBIT, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (LENGTH .LE. 0) GOTO 100
C Dispatch processing code
C

GOTO (200,200,200,200,200,500,500,500,500,500)

(CNVRSN+1)

C Calculate the remaining length of the receiving buffer
C

200

REMLEN = REMLEN - LENGTH

C If there are more data to read, go back and continue reading using
C the same conversion format, otherwise display received data at the
C controlling terminal
C

IF (MBIT .EQ • • TRUE.) GO TO 150
LENGTH = 512 - REMLEN
GO TO (210,220,220,220,220) (CNVRSN + 1)
C Binary data: 36 bits
C

210
2100
212

DO 212 I = 1,LENGTH,2
WRITE (5,2100) XBUF(I), XBUF(I+l)
FORMAT ( I I ,F10.6, I ',FI0.6)
CONTINUE
GO TO 100

C Binary data: high 32 bits, low 32 bits, low 16 bits and low 8 bits
C

220
2200
222

DO 222 I = 1,LENGTH
WRITE (5,2200) IBUF(I)
FORMAT (110)
CONTINUE
GOTO 100

C Calculate the remaining length of the receiving buffer
C

500

ITEMPl
ITEMP2
REMLEN

CNVRSN - 5 + 1
MOD (LENGTH, ITEMP1)
REMLEN - «LENGTH / ITEMP1) + ITEMP2)

C If there are more data to read, go back and continue reading using
C the same conversion format, otherwise display received data at the
C controlling terminal
C

IF (MBIT • EQ. • TRUE.) GO TO 150
LENGTH = 512 - REMLEN
GO TO (510,520,530,540,550) ITEMPl
C ASCII data in Al format

A-15

SAMPLE FORTRAN-10 PROGRAMS
C

510
5100

WRITE (5,5100) (IBUF(I) ,I=l,LENGTH)
FORMAT (lH ,5l2Al,$)
GOTO 100

C ASCII data in A2 format
C

520
5200

WRITE (5,5200) (IBUF(I) ,I=l,LENGTH)
FORMAT (IH ,5l2A2,$)
GOTO 100

C ASCII data in A3 format
C

530
5300

WRITE (5,5300) (IBUF (I) ,1=1, LENGTH)
FORMAT (IH ,5l2A3,$)
GOTO 100

C ASCII data in A4 format
C

540
5400

WRITE (5,5400) (IBUF(I) ,I=l,LENGTH)
FORMAT (IH ,5l2A4,$)
GOTO 100

C ASCII data in A5 format
C

550
5500

WRITE (5,5500) (IBUF(I) ,I=l,LENGTH)
FORMAT (IH ,5l2A5,$)
GOTO 100
END
SUBROUTINE WTDATA (PORT)

C+

C DESCRIPTION

Read port status and wait for incoming data indication

C PARAMETERS
C-

PORT

Port number

EXTERNAL IDLE, X25RPS
INTEGER PORT, RESULT
LOGICAL DAVAIL
C Check only data available flag, ignore other indicators
C

100

CALL X25RPS (PORT, 0, 0, 0, 0, DAVAIL, 0, 0, RESULT)

C Check if we have detected the incoming data
C

IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (DAVAIL .EQ • • TRUE.) RETURN
C Idle process for 1 second before checking the circuit status again
C

CALL IDLE (1)
GOTO 100
END
SUBROUTINE ABORT (PORT, CODE, STATE)
C+

C DESCRIPTION

Terminate communication and abort the process.

A-16

SAMPLE FORTRAN-I0 PROGRAMS
C

C PARAMETERS PORT
C
C
C

Port number.
CODE
Error code.
STATE
Current port state.

CEXTERNAL X25TPA
INTEGER PORT, CODE, STATE
1000

WRITE (5,1000) CODE, STATE
FORMAT (I,' * ERROR #' ,12,', current port state' ,12,' *' ,I)
CALL X25TPA (PORT, 0)
STOP
END
INTEGER FUNCTION ISTAT (PORT, STATE)

C+
C DESCRIPTION

Read port status.

C PARAMETERS
C

PORT
STATE

Port number.
Current port state.

C RETURN
C

New port state when it is changes; or ERROR port state
if failed to read port status.

CEXTERNAL X25RPS, IDLE
INTEGER PORT, STATE, PSTATE, RESULT
C Check only port state, ignore other indicators
C

100

CALL X25RPS (PORT, 0, PSTATE, 0, 0, 0, 0, 0, RESULT)

C If failed to read port status, return port state ERROR
C

IF (RESULT .EQ. 0) GOTO 200
ISTAT = 10
RETURN
C If the port state has changes, return the new port state
C

200

IF (PSTATE .NE. STATE) GOTO 300

C Otherwise, idle the process for 5 seconds before checking
C the port state again
C

CALL IDLE (5)
GOTO 100
C Return new port state
C

300

ISTAT = PSTATE
RETURN
END

A-17

SAMPLE FORTRAN-10 PROGRAMS
A.3

LISTING OF SAMPLE PROGRAM SVCXMI.FOR
PROGRAM SVCXMI

C Storage declarations
C

EXTERNAL IDLE, X25CSC, X25ISC, X25SDM, X25SIM, X25TPA
INTEGER CSTATE, NSTATE, PORT, RESULT, IBYTE, LENGTH
INTEGER DTE(4), BUFFER(256), IBUF(256), FILBUF(2)
REAL NUMBER, XBUF(256)
DOUBLE PRECISION FILNAM
EQUIVALENCE (FILBUF(l), FILNAM)
EQUIVALENCE (IBUF(l), BUFFER(l), (XBUF(l), BUFFER(l»
DIMENSION WORKSP(172)
C Prompt for remote DTE address
C

100
1000
1010

WRITE (5,1000)
FORMAT (' DTE address: ',$)
READ (5,1010) LENGTH, (DTE(I) ,1=1,4)
FORMAT (Q, 4A5)
IF (LENGTH .LE. 0) GOTO 100

C Initiate the virtual circuit to the network
C

eSTATE = 0
eALL X25ISC (8HTELENET , 'X25-GATE " DTE,
$
0, 0, 0, 0, 0, 0, WORKSP, PORT, RESULT)
IF (RESULT .NE~ 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 2
C Check port state and wait for port state to become RUNNING
C

NSTATE = ISTAT (PORT, CSTATE)
IF (NSTATE .NE. 5) CALL ABORT (PORT, 0, NSTATE)
e Send an interrupt to indicate start of transmission. The remote end
e will confirm this interrupt after it receives all data successfully

200
2000
2010

eSTATE = 5
WRITE (5,2000)
FORMAT (' Interrupt byte (octal): ',$)
READ (5,2010) IBYTE
FORMAT (03)
CALL X25SIM (PORT, IBYTE, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

C Send protocol byte to SVCRCV to indicate data conversion mode
C

CALL X25SDM (PORT, 4, 5, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Read input data from terminal using Al format descriptor

A-18

SAMPLE FORTRAN-I0 PROGRAMS
C

300
3000
3010

WR I T E

(5 , 3000 )

FORMAT (I Text string: 1,$)
READ (5,3010,ERR=300) LENGTH,
FORMAT (Q,256Al)

(BUFFER(I) ,1=1,256)

C Do not attempt to send null string
C

IF (LENGTH .LE. 0) GOTO 300
C Send the text string in Al format to SVCRCV.
C

CALL X25SDM (PORT, 5, BUFFER, LENGTH, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Read file name
C

400
4000
4010

WR I T E

(5, 4 0 0 0 )

FORMAT (I File name: 1,$)
READ (5,4010) (FILBUF(I) ,1=1,2)
FORMAT (2A5)

C Open input file
C

OPEN (UNIT=l,DEVICE='DSK ' ,FILE=FILNAM,ACCESS='SEQIN ' ,ERR=440)
C Send protocol byte to SVCRCV to indicate data conversion mode
C

CALL X25SDM (PORT, 4, 9, 1, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) GOTO 440
C Send the first 20 lines of the file to SVCRCV.
C

4020

DO 420 M = 1,20
READ (1,4020,END=430,ERR=430) LENGTH, (BUFFER(I) ,1=1,256)
FORMAT (Q,256A5)
IF (LENGTH .LE. 0) GOTO 410
CALL X25SDM (PORT, 9, BUFFER, LENGTH, 0, .TRUE., RESULT)
IF (RESULT .NE. 0) GOTO 440

C Follow each line with a pair of <CR)<LF) in the rightmost 16 bits
C

410
420

CALL X25SDM (PORT, 3, "6412, 1, 0, .TRUE., RESULT)
IF (RESULT .NE. 0) GOTO 440
CONTINUE

C Flush the buffered data to SVCRCV by calling X25SDM with 0 length
C

430

CALL X25SDM (PORT, 9, BUFFER, 0, 0, .FALSE., RESULT)

C Close input file
C

440

CLOSE (UNIT=I)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

C Initialize first 2 Fibonacci numbers
C

IBUF(l) = 0
IBUF(2) = 1
C Calculate the next 23 Fibonacci numbers

A-19

SAMPLE FORTRAN-10 PROGRAMS
C

DO 500 I = 3,25
IBUF(I) = IBUF(I-l) + IBUF(I-2)
CONTINUE

500

C Send the sequence to the receiving program
C

CALL X25SDM (PORT, 4, 9, 1, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
$

CALL X25SDM (PORT, 9, 'The first 25 Fibonacci numbers', 30,
0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

C Send protocol byte to SVCRCV to indicate data conversion mode
C

CALL X25SDM (PORT, 4, 3, 1, 0, • FALSE., RESULT)
C Send 10 copies of the set of Fibonacci numbers
C

DO 510 I = 1,10
CALL X25SDM (PORT, 3, IBUF, 25, 0, .TRUE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CONTINUE

510

C Flush the buffered data to SVCRCV by calling X25SDM with 0 length
C

CALL X25SDM (PORT, 3, IBUF, 0, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Calculate the first 128 square roots
C

NUMBER = 1.0
DO 600 I = 1,256,2
XBUF(I) = NUMBER
XBUF(I+l) = SQRT (NUMBER)
NUMBER = NUMBER + 1.0
CONTINUE

600

C Send the identification string
C

CALL X25SDM (PORT, 4, 9, 1, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
$

CALL X25SDM (PORT, 9, 30HNumbers and their Square Roots, 30,
0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)

C Send data array
C

CALL X25SDM (PORT, 4, 0, 1, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CALL X25SDM (PORT, 0, XBUF, 256, 0, • FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C Send control-Z to indicate end of data transmission
C

CALL X25SDM (PORT, 4, "32, 1, 0, .FALSE., RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
C wait for confirmation of the interrupt we sent at the beginning

A-20

SAMPLE FORTRAN-IO PROGRAMS

C
CALL WTCFRM (PORT, 300)
C Clear virtual circuit and close port
C
CALL X25CSC (PORT, "252, 0, 0, 0, 0, 0, RESULT)
IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, CSTATE)
CSTATE = 8
C Wait until clear request is confirmed
C
CSTATE = ISTAT (PORT, CSTATE)
C Terminate port access
C
CALL X25TPA (PORT, RESULT)
STOP
END
SUBROUTINE ABORT (PORT, CODE, STATE)
C+

C DESCRIPTION
C
C PARAMETERS PORT
C
C
C
C-

Terminate communication and abort the process.
Port number.
CODE
Error code.
STATE
Current port state.

EXTERNAL X25TPA
INTEGER PORT, CODE, STATE
1000

WRITE (5,1000) CODE, STATE
FORMAT (I,' * ERROR #' ,12,', current port state ',12,' *' ,I)
CALL X25TPA (PORT, 0)
STOP
END
SUBROUTINE WTCFRM (PORT, WAIT)

C+

C DESCRIPTION
C
C
C PARAMETERS
C
C-

wait for interrupt confirmation within certain period.
After that, return, so we do not wait forever.
PORT
WAIT

Port number
Amount of time in seconds to wait.

EXTERNAL X25RPS, IDLE
INTEGER PORT, WAIT, RESULT
LOGICAL PENDNG
C Read port status
C
DO 100 I = 1,WAIT
CALL x25RPS (PORT, 0, 0, 0, PENDNG, 0, 0, 0, RESULT)
C Check if the transmitted interrupt has been confirmed -

A-21

if so, return

SAMPLE FORTRAN-10 PROGRAMS
C

IF (RESULT .NE. 0) CALL ABORT (PORT, RESULT, 5)
IF (PENDNG .EQ • . FALSE.) RETURN
C Idle process for 1 second before checking the circuit status again
C

100

CALL IDLE (1)
CONTINUE
RETURN
END
INTEGER FUNCTION ISTAT (PORT, STATE)

C+
C DESCRIPTION

Read port status.

C PARAMETERS
C

PORT
STATE

Port number.
Current port state.

C RETURN
C

New port state when it is changes; or ERROR port state
if failed to read port status.

CEXTERNAL X25RPS, IDLE
INTEGER PORT, STATE, PSTATE, RESULT
C Check only port state, ignore other indicators
C

100

CALL X25RPS (PORT, 0, PSTATE, 0, 0, 0, 0, 0, RESULT)

C If failed to read port status, return port state ERROR
C

IF (RESULT .EQ. 0) GOTO 200
ISTAT = 10
RETURN
C If the port state has changes, return the new port state
C

200

IF (PSTATE .NE. STATE) GOTO 300

C Otherwise, idle the process for 5 seconds before checking
C the port state again
C

CALL IDLE (5)
GOTO 100
C Return new port state
C

300

ISTAT = PSTATE
RETURN
END

A-22

APPENDIX B
SAMPLE MACRO-I0 PROGRAMS

This appendix contains sample MACRO-IO programs that communicate
each other through a PPSN.
The programs are:

with

•

SVCRCV, which accepts a Switched Virtual
receives data sent through the circuit.

Circuit

call

and

•

SVCXMI, which initiates a Switched Virtual Circuit
sends data through the circuit.

call

and

Section B.l explains features of the two programs, while Section B.2
contains a
listing of SVCRCV, and Section B.3 contains a listing of
SVCXMI.

B.l

PROGRAM FEATURES

This section explains the set-up section that both programs
gives hints related to individual features of each program.

B.l.l

use

and

Standard Set-up

Both programs include a standard set-up section that defines buffers
and variables.
The file UNV:X25SYM.UNV contains universal symbols
such as virtual circuit port states
(for example, XS%UND,
XS%RUN),
return codes (for example, XC%SUC, XC%PER) and other bit-mask symbols:
SEARCH

X25SYM

Because the TOPS-IO PSI Gateway Access routines use the push down
stack for manipulation of data and other tasks, a MACRO-IO programmer
should initialize the stack pointer to point to a push down list of at
least 1000 (octal) words:
SIZE=1000
STACK:

BLOCK

SIZE

The chosen length of the data packets to be used in this example is
128 bytes.
The length of the data block WSPACE, which is to be used
by the X.25 Gateway Access routines as working space, is calculated as
follows:
140 + (128/4) = 172

B-1

SAMPLE MACRO-10 PROGRAMS
The size of the argument block ARGBLK is set at 10 so that it
shared by all X.2S Gateway Access routines:
WSPSIZ=<128/4>+.PBSIZ
WSPACE:
BLOCK
WSPSIZ
ARGBLK:
BLOCK
10.

can

iWorking area for the X.2S library
iArgument block

The set-up for the software interrupt system is standard (refer to the
TOPS-IO Monitor Calls Manual for additional information).
In this
example, only interrupt channel zero is used.
A priority level zero
handler at SRVCKT is specified:
CH.X2S=0
PSIARG:
PSIVEC:

B.1.2

EXP
XWD
XWD
EXP
BLOCK
EXP
BLOCK

.PCNSP
0,0
0,0
SRVCKT
1

ilnterrupt channel number
iCondition, interrupt on NSPe events
iOffset into PSIVEC"NOFLAGS
iPriority of a
iNew PC
iOld PC
iNo Flags
iDECnet channel status word

Receiving Program

The program SVCRCV is written to act as the passive partner (slave) of
the transmitting program, SVCXMI.
SVCRCV starts by setting up the
push down stack and the software interrupt system:

B-2

SAMPLE MACRO-IO PROGRAMS
SALL
TITLE
SEARCH

SVCXMI Communication Master Program
UUOSYM,MACSYM,X25SYM

Accumulators
Sl=l
S2=2
S3=3
S4=4
Tl=5
T2=6
SP=17

;Scratch ACs

;Temporary ACs

; Push Down Stack
SIZE=lOOO
STACK: BLOCK

SIZE

Interrupt System Storage Definitions
CH.X25=0
PSIARG: EXP
XWD
XWD
PSIVEC: EXP
BLOCK
EXP
BLOCK
START:

RESET
MOVE

PSIINI: MOVEI
PIINI.
HALT
MOVE
PISYS.
HALT

°
I

;Interrupt channel number
;Condition, interrupt on NSP. events
;Offset into PSIVEC"NOFLAGS
;Priority of
;New PC
;Old PC
;No Flags
;DECnet channel status word

SP,[IOWD SIZE,STACK]

;Reset the world
;Set up push down stack

.PCNSP
0,0
0,0
SRVCKT

SI,PSIVEC
Sl,

;Initialize software interrupt system
; Fai led
TI, [PS.FOF!PS.FAC+PSIARG]
TI,
;Keep interrupt system off temporarily
; Failed

When you specify a positive number as an
interrupt channel
in the
argument block of the subroutines X%ISC, X%OPC, or X%WIC, the number
does not have any particular significance in itself.
It is simply a
flag
that tells the Gateway Access Library to enable software
interrupts for that X.25 circuit.
All DECnet and X.25 programmed
interrupts come through a single PSI vector.
You cannot assign a
different vector to each X.25 circuit as you can for
normal TOPS-IO
I/O.
When you enable the software interrupts for an X.25 circuit, the port
number, which is returned by the subroutines X%ISC, X%OPC, or X%WIC,
is also the software interrupt channel number. The port number can be
used to determine which circuit the interrupt is for when it occurs.
When the system grants an interrupt, you can determine which circuit
the interrupt is for by looking at the status word of the interrupt
control block (fourth word).
It will contain the interrupt channel
number
(port number)
in the right half and the link status (DECnet
format) in the left half.
If the status word
is zero, you should
ignore the interrupt.

B-3

SAMPLE MACRO-IO PROGRAMS
The Gateway Access subroutines are linked with your program image,
therefore, it is possible for an interrupt to occur while your program
executes a subroutine call.
Use the Software Interrupt System
carefully.
You must insure that the system will grant no interrupts
until all the necessary data structures have been initialized, control
has been returned to the user code, and no interrupts have been lost.
The Gateway Access subroutines save the context of all sixteen
registers before using them.
When an interrupt occurs, you must
verify your register's contents to make sure they are not interrupted.
An X.2S circuit must be established before interrupts can be taken on
that link.
However, if the Software Interrupt System is not enabled
before the program calls a Gateway Access subroutine to establish the
circuit,
interrupts can be lost as they are granted at the first
possible instance.
To avoid this problem, you should
initialize the
Software Interrupt System first, before initiating any X.2S circuits
to prevent interrupts being lost.
Turn the Software Interrupt System
off just before calling the subroutines X%ISC, X%OPC, or X%WIC and
turn it back on after program control is returned to the user code.
The Gateway Access subroutines X%ISC, X%OPC,
and X%WIC set up the
conditions that would trigger software interrupts on an X.2S circuit.
You should not change that setting during the "life" of that circuit.
Use the routine X%RPS (Read Port Status) to find out about events on
the virtual circuit.
Use the software interrupt system whenever
possible.
Normally,
the Software Interrupt System enables a program
to run more efficiently.
SVCRCV declares itself available to receive an incoming call from the
X.2S gateway node by calling the routine X%WIC (Wait Incoming Call):

ARGINI: SETZM
MOVE
BLT

ARGBLK
Tl, [ARGBLK"ARGBLK+l]
Tl,ARGBLK+9.

X25ISC: MOVEI
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
EXIT
MOVEI
MOVEM

Tl,XS%UND
Tl,STATE
iSet port state to UNDEFINED
Tl, [CH.X25"WSPACE]
Tl,ARGBLK
iInterrupt channel and work area
Tl, [POINT 7, [ASCIZ/TELENET/]]
Tl,ARGBLK+2
iNetwork name
Tl, [POINT 7, [ASCIZ/X25-GATE/]]
Tl,ARGBLK+3
iAccess password
Tl, [POINT 7, [ASCIZ/3ll060700l53/]]
Tl,ARGBLK+4
iDestination DTE address
Sl,ARGBLK
X%ISC##
Tl,ARGBLK+l
;Get return code
Tl,XC%SUC
iIs it successful?
1,
i No, terminate
Tl,XS%CAG
iYes,
Tl,STATE
;Change port state to CALLING

DISMIS: MOVE
PISYS.
EXIT
MOVEI
DSM.l: HIBER
EXIT
JRST

TI, [PS.FON]
Tl,

iInitialize entire argument block area

iTurn interrupt system on
; Failed

Tl,O
TI,
1,
DSM.l

;Dismiss the process
; Failed

B-4

SAMPLE MACRO-lO PROGRAMS
After establishing itself as a server, the process dismisses
itself
and waits for an incoming call from the network. While your program
is waiting for an X.25 incoming call, you should use the HIBER UUO
with a
timer of 0 seconds (hibernate indefinitely) instead of the
SLEEP UUO.
The HIBER uua requires less overhead in a program that may
wait for a long period of time.
When an event occurs on the virtual circuit,
the monitor
transfers
control to the interrupt routine SRVCKT, which is specified in the
interrupt control block PSIVEC.
The first thing the interrupt handler
routine does
is check the current status of the virtual circuit by
calling the routine X%RPS.
The routine then transfers control to the
appropriate routine, which processes the port state transitions or
events (for example, incoming data) :

SRVCKT: PUSH
PUSH
PUSH
PUSH
SETZM
MOVE
BLT
MOVEI
CALL
MOVE
CAIE
JRST
MOVE
HRRZ
CAIN
JRST

CAIN
JRST
JRST
NOTHNG: POP
POP
POP
POP
DEBRK.

SP,Sl
SP,S2
SP,TI
SP,T2

;Save registers

ARGBLK+I
TI, [ARGBLK+I"ARGBLK+2]
TI ,ARGBLK+9.
SI,ARGBLK
X%RPS##
TI,ARGBLK+I
TI,XC%SUC
X25TPA
TI, STATE
T2,ARGBLK+2
TI,XS%CAG
[CAIN
T2,XS%CAG
JRST NOTHNG
CAIN
T2,XS%RUN
JRST X25SDM
JRST
X25TPA]
TI,XS%RUN
[CAIN
T2,XS%RUN
JRST NOTHNG
JRST
X25TPA]
X25TPA

;Initialize argument block entries

SP,T2
SP,TI
SP,S2
SP,SI

;Pass access argument block
;Check port state
;Get return code
;Is it successful?
;No, terminate
;Get old port state
;Get new port state
;From CALLING state
;Remain in CALLING state
;00 nothing
~Changes to RUNNING state
iTransmit data to the network
;Otherwise, terminate
;From RUNNING state
iRemain in RUNNING state
iDo nothing
iOtherwise, terminate
iDon't want to handle other states
iRestore registers

B-5

SAMPLE MACRO-IO PROGRAMS
The current port state (which has been maintained by the program)
and
the new one
(newly obtained from the routine X%RPS) are examined to
determine the port state transition.
In the above example,
the port
state transition from XS%LSN (LISTENING) to XS%CAD (CALLED), indicates
that the program has received an incoming call from the network.
The
program proceeds to accept the incoming call:

X25AIC: SETZM
MOVE
BLT
MOVE I
CALL
MOVE
CAIE
JRST
MOVEI
MOVEM
JRST

ARGBLK+l
Tl, [ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
Sl,ARGBLK
X%AIC##
Tl,ARGBLK+l
Tl,XC%SUC
X25TPA
Tl,XS%RUN
Tl,STATE
NOTHNG

ilnitialize argument block entries
iAccept incoming call unconditionally
iGet return code
ils it successful?
i No, terminate
iYes,
iChange port state to RUNNING
iDone servicing interrupt

After accepting the incoming call, the program has updated its copy of
the current port state to XS%RUN (RUNNING).
Note that there are other
subroutines that change the port state upon successful execution.
When one of these subroutines has been successfully executed, you do
not need to execute X%RPS to determine the port state. For example:
X%RVC (RESET VIRTUAL CIRCUIT), which changes the port state
UNSYNC to RUNNING.

from

You can detect events on the virtual circuit by examining word
ARGBLK+3 of the argument block that is returned by X%RPS.
The above
example tests the bit XM%DAT to determine if there is a data packet to
be read from the virtual circuit.
The following section of the program
displays them on the control terminal:

X25RDM: SETZM
MOVE
BLT
RDM.l:

MOVEI
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
JRST
MOVE
MOVEI
IDPB
OUTSTR
JRST

ARGBLK+l
Tl, [ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
Tl,128.
Tl,ARGBLK+2
TI, [POINT 7,BUFFER]
TI,ARGBLK+3
Sl,ARGBLK
X%RDM##
Tl,ARGBLK+l
Tl,XC%SUC
[TXNE
Tl,XC%NDA
JRST NOTHNG
JRST
X25TPA]
TI,ARGBLK+3
T2,O
T2,Tl
BUFFER
RDM.I

receives

data

packets

and

ilnitialize argument block entries

iMaximum packet size
iDestination buffer
iRead one packet
iGet return code
iIs it successful?
i No, is it No Data Available error?
i
Yes, dismiss interrupt
iNo, it is fatal error
iGet pointer to last received byte
Make ASCIZ string
Display text at terminal
Read the next packet

B-6

SAMPLE MACRO-IO PROGRAMS
Note that while reading data from the network, the program ignores the
value of bit XM%MOR, which represents the more bit of the received
data packet.
(XM%MOR is returned in word ARGBLK+2 of the argument
block by routine X%RDM.) This is because the more bit of a data packet
should only be used in the context of logical streams of received
data.
The more bit is not a reliable indicator of additional data
packets being available on the virtual circuit at that moment.
The
content of word ARGBLK+l
(return code) of the argument block will
indicate when there is no more data to be read (bit XC%NDA is set).
When your program is notified by the interrupt system and the routine
X%RPS to handle the incoming data, do not call X%RPS to obtain the
value of bit XM%DAT before reading each data packet, unless you are
processing other events simultaneously.
Use the routine X%RDM to read
data continuously until X%RDM returns the return code which indicates
that there is no more data to be read (bit XC%NDA is set) or there are
other error conditions.
Finally, when error conditions are encountered, the program terminates
by clearing the virtual circuit and halting itself:

X25TPA:

B.1.3

MOVEI
CALL
EXIT
END

Sl,ARGBLK
X%TPA##
1,
START

;Terminate port access
;Stop program
;End Of Program

Transmitting Program

The program SVCXMI is the active partner
(master)
of the receiving
program, SVCRCV.
This program initiates all of the operations; that
is, it initiates the Switched Virtual Circuit call and the data
transfer.
The program interacts with the user to acquire data to be
transferred to the receiving program.

B-7

SAMPLE MACRO-IO PROGRAMS
The program first initializes the process environment and the software
interrupt system:
SALL
TITLE
SEARCH

SVCRCV Communication Slave Program
UUOSYM,MACSYM,X25SYM

Accumulators
Sl=l
S2=2
S3=3
S4=4
Tl=5
T2=6
SP=17
i

iScratch ACs

iTemporary ACs

Push Down Stack

SIZE=1000
STACK:
BLOCK

SIZE

Interrupt System Storage Definitions
CH.X25=0
PSIARG: EXP
XWD
XWD
PSIVEC: EXP
BLOCK
EXP
BLOCK
START:

RESET
MOVE

PSlINI: MOVEI
PIINI.
HALT
MOVE
PISYS.
HALT

iInterrupt channel number
iCondition, interrupt on NSP. events
iOffset into PSIVEC"NOFLAGS
iPriority of a
iNew PC
iOld PC
iNo Flags
iDECnet channel status word

SP, [lOWD SIZE,STACK]

iReset the world
iSet up push down stack

.PCNSP
0,0
0,0
SRVCKT
1

Sl,PSIVEC
Sl,

iInitialize software interrupt system
Failed
Tl, [PS.FOF!PS.FAC+PSIARG]
Tl,
iKeep interrupt system off temporarily
i Failed
i

B-8

SAMPLE MACRO-IO PROGRAMS
The program proceeds to initiate the Switched Virtual Circuit:

ARGINI: SETZM
MOVE
BLT

ARGBLK
Tl, [ARGBLK"ARGBLK+l]
Tl ,ARGBLK+9.

;Initialize entire argument block area

X25ISC: MOVEI
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
EXIT
MOVEI
MOVEM

Tl,XS%UND
Tl,STATE
;Set port state to UNDEFINED
Tl, [CH.X25"WSPACE]
Tl,ARGBLK
;Interrupt channel and work area
Tl, [POINT 7, [ASCIZ/TELENET/]]
Tl,ARGBLK+2
;Network name
Tl, [POINT 7,[ASCIZ/X25-GATE/]]
Tl,ARGBLK+3
;Access password
Tl, [POINT 7,[ASCIZ/311060700153/]]
Tl,ARGBLK+4
;Destination DTE address
Sl,ARGBLK
X%ISC##
Tl,ARGBLK+l
;Get return code
Tl,XC%SUC
;Is it successful?
1,
; No, terminate
Tl,XS%CAG
;Yes,
Tl,STATE
;Change port state to CALLING

DISMIS: MOVE
PISYS.
EXIT
MOVEI
DSM.l: HIBER
EXIT
JRST

Tl, [PS.FON]
Tl,

;Turn interrupt system on
; Failed

Tl,O
Tl,
1,
DSM.l

;Dismiss the process
; Failed

B-9

SAMPLE MACRO-IO PROGRAMS
When an event occurs on the virtual circuit,
the monitor
transfers
control
to the
interrupt routine SRVCKT, which is specified in the
interrupt control block PSIVEC.
The routine SRVCKT serves as a
port
state driven machine.
Depending on the port state of the virtual
circuit at the time of the interrupt, the program transfers control to
an associated routine.

SRVCKT: PUSH
PUSH
PUSH
PUSH
SETZM
MOVE
BLT
MOVE I
CALL
MOVE
CAIE
JRST
MOVE
HRRZ
CAIN
JRST

CAIN
JRST
JRST
NOTHNG~

POP
POP
POP
POP
DEBRK.

SP,SI
SP,S2
SP,Tl
SP,T2

;Save registers

ARGBLK+l
TI,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
SI,ARGBLK
X%RPS##
TI,ARGBLK+l
Tl,XC%SUC
X25TPA
Tl, STATE
T2,ARGBLK+2
Tl,XS%CAG
[CAIN
T2,XS%CAG
JRST NOTHNG
CAIN
T2,XS%RUN
JRST X25SDM
JRST
X25TPA]
Tl,XS%RUN
[CAIN
T2,XS%RUN
JRST NOTHNG
JRST
X25TPA]
X25TPA

iInitialize argument block entries

SP,T2
SP,Tl
SP,S2
SP,Sl

iPass access argument block
iCheck port state
iGet return code
iIs it successful?
iNo, terminate
iGet old port state
iGet new port state
iFrom CALLING state
iRemain in CALLING state
iDo nothing
iChanges to RUNNING state
iTransmit data to the network
iOtherwise, terminate
iFrom RUNNING state
iRemain in RUNNING state
iDo nothing
iOtherwise, terminate
iDon't want to handle other states

iRestore registers

B-IO

SAMPLE MACRO-I0 PROGRAMS
Upon an interrupt, the program checks the current port state by
calling routine X%RPS (Read Port Status) and transfers control to the
appropriate routine. The current port state and the new one are
examined to determine the port state transition.
In the above
example, the port state transition from XS%CAG
(CALLING)
to XS%RUN
(RUNNING),
indicates that the switched virtual circuit has been
established successfully.
The program now can proceed to transmit
data to the network:

X25SDM: MOVEI
MOVEM
OUTSTR

T1,XS%RUN
T1, STATE
HELP

SDM.1 :

OUTSTR
MOVE
SETZ

PROMPT
T1, [POINT 7,BUFFER]
T2,

:Receiving buffer
:Reset counter

SDM.2:

INCHWL
CAIN
JRST
IDPB
AOS
CAIE
JRST

Sl
Sl,32
X25TPA
S 1 ,T1
T2
Sl,12
SDM.2

:Get one character from terminal
;End of text?
: Yes, terminate circuit
:Stash character away
:Update counter
:End of text line?
; No, continue

SDM.3:

SETZM
MOVE
BLT
CAlLE
MOVEI
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
JRST

ARGBLK+1
T1, [ARGBLK+1"ARGBLK+2]
T1,ARGBLK+9.
T2,128.
T2,128.
T2,ARGBLK+2
T1, [POINT 7,BUFFER]
T1,ARGBLK+3
Sl,ARGBLK
X%SDM##
Tl,ARGBLK+l
T1,XC%SUC
[TXNN
T1,XC%PER
JRST SDM.1
JRST
X25TPA]
SDM.1

:Initialize argument block entries

JRST

:Update port state to RUNNING

:Set the maximum length of the string
: Truncate the text to 128 characters
;Get pointer to the text string
:Send the string to the network
:Get the return code
:Is it successful?
;No, then is it procedure error?
:No, it is non-fatal error
:Yes, terminate
:Get next string from terminal

The program prompts for user data from the controlling terminal and
sends the text to the receiving program.
The program terminates when
you enter a CTRL/Z:

X25TPA:

MOVEI
CALL
EXIT
END

Sl,ARGBLK
X%TPA##
1,
START

;Terminate port access
;Stop program
iEnd Of Program

B-ll

SAMPLE MACRO-IO PROGRAMS
B.2

LISTING OF SAMPLE PROGRAM SVCRCV.MAC
SALL
TITLE
SEARCH

SVCRCV Communication Slave Program
UUOSYM,MACSYM,X25SYM

Accumulators
Sl=l
S2=2
S3=3
S4=4
Tl=5
T2=6
SP=17
i

;Temporary ACs

Push Down Stack

SIZE=1000
STACK:
i

;Scratch ACs

BLOCK

SIZE

X.25 Access Argument Blocks

WSPSIZ=<128./4>+.PBSIZ
WSPACE:
BLOCK
WSPSIZ
ARGBLK:
BLOCK
10.
BUFFER:
BLOCK
32.
STATE:
BLOCK
1
i

;Working area for the X.25 library
;Argument block
;Incoming data buffer
iPort state

Interrupt System Storage Definitions

CH.X25=0
PSIARG:
PSIVEC:

START:
PSIINI:

EXP
XWD
XWD
EXP
BLOCK
EXP
BLOCK

°
1

iInterrupt channel number
;Condition, interrupt on NSP. events
;Offset into PSIVEC"NOFLAGS
;Priority of
iNew PC
;Old PC
iNo Flags
iDECnet channel status word

RESET
MOVE

SP,[IOWD SIZE,STACK]

iReset the world
;Set up push down stack

.PCNSP
0,0
0,0
SRVCKT
1

MOVEI
PIINI.
HALT
MOVE
PISYS.
HALT

Sl,PSIVEC
Sl,

ARGINI:

SETZM
MOVE
BLT

ARGBLK
T1,[ARGBLK"ARGBLK+l]
Tl,ARGBLK+9.

X25WIC:

MOVEI
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
EXIT
MOVEI
MOVEM

T1,XS%UND
T1,STATE
;Set port state to UNDEFINED
T1,[CH.X25"WSPACE]
Tl,ARGBLK
iInterrupt channel and work area
Tl,[POINT 7, [ASCIZ/EXAMPLE/])
Tl,ARGBLK+2
iDECnet object name
Sl,ARGBLK
;Pass access argument block
X%WIC"
;Wait Incoming Call
T1,ARGBLK+1
;Get return code
T1,XC%SUC
iIs it successful?
1,
i No, terminate
T1,XS%LSN
;Yes,
T1,STATE
iChange port state to LISTENING

DISMIS:

MOVE
PISYS.
EXIT
MOVEI

T 1 , [P S • FON)
Tl,
1,
T1,O

;Initialize software interrupt system
; Fa iled
Tl,[PS.FOF!PS.FAC+PSIARG]
T1,
;Keep interrupt system off temporarily
; Failed
iInitialize the argument block

;Turn interrupt system on
; Failed

B-12

SAMPLE MACRO-IO PROGRAMS
DSM.l:

HIBER
EXIT
JRST

Tl,
1,
DSM.l

;Dismiss the process
; Failed

SRVCKT:

PUSH
PUSH
PUSH
PUSH

SP,Sl
SP,S2
SP,Tl
SP,T2

;Save registers

SETZM
MOVE
BLT
MOVEI
CALL
MOVE
CAIE
JRST
MOVE
HRRZ
CAIN
JRST

;Initialize argument block entries

JRST

ARGBLK+l
Tl,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
Sl,ARGBLK
X%RPS##
Tl,ARGBLK+l
Tl,XC%SUC
X25TPA
Tl,STATE
T2,ARGBLK+2
Tl,XS%LSN
[CAIN
T2,XS%LSN
JRST NOTHNG
CAIN
T2,XS%CAD
JRST X25AIC
JRST
X25TPA]
Tl,XS%RUN
[CAIE
T2,XS%RUN
JRST X25TPA
MOVE
Tl,ARGBLK+3
TXNE
Tl,XM%DAT
JRST X25RDM
JRST
NOTHNG]
X25TPA

X25AIC:

SETZM
MOVE
BLT
MOVEI
CALL
MOVE
CAIE
JRST
MOVEI
MOVEM
JRST

ARGBLK+l
;Initialize argument block entries
Tl,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
Sl,ARGBLK
;Accept incoming call unconditionally
X%AIC##
;Get return code
Tl,ARGBLK+l
Tl,XC%SUC
;Is it successful?
, No, terminate
X25TPA
Tl,XS%RUN
;Yes,
Tl,STATE
;Change port state to RUNNING
NOTHNG
;Done servicing interrupt

X25RDM:

SETZM
MOVE
BLT

ARGBLK+l
Tl,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.

RDM.l:

MOVEI
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
JRST

Tl,128.
Tl,ARGBLK+2
Tl,[POINT 7,BUFFER]
Tl,ARGBLK+3
Sl,ARGBLK
X%RDM##
Tl,ARGBLK+l
Tl,XC%SUC
[TXNE
Tl,XC%NDA
JRST NOTHNG
JRST
X25TPA]
Tl,ARGBLK+3
T2,O
T2,Tl
BUFFER
RDM.l

CAIN
JRST

MOVE
MOVEI
IDPB
OUTSTR
JRST
NOTHNG:

POP
POP
POP
POP
DEBRK.

SP,T2
SP,Tl
SP,S2
SP,Sl

X25TPA:

MOVEI
CALL
EXIT
END

Sl,ARGBLK
X%TPA:fI:#
1,
START

;Pass access argument block
;Check current port status
;Get return code
;Is it successful?
, No, terminate
;Get old port state
;Get new port state
;From LISTENING state
Remain in LISTENING state
Check the port state again
Changes to CALLED state
Accept incoming call
; Otherwise, terminate
;From RUNNING state
Changes to any other states
Terminate
Get the port status word
Check incoming data indicator
Yes, there is a packet to be read
, No, done servicing interrupt
;Don't want to handle other states

;Initialize argument block entries

;Maximum packet size
;Destination buffer
;Read one packet
;Get return code
iIs it successful?
; No, is it No Data Available error?
; Yes, dismiss interrupt
;No, it is fatal error
;Get pointer to last received byte
;Make ASCIZ string
;Display text at terminal
;Read the next packet
iRestore registers

Terminate port access
Stop program
End Of Prog ram

B-13

SAMPLE MACRO-10 PROGRAMS
B.3

LISTING OF SAMPLE PROGRAM SVCXMI.MAC
SALL
TITLE
SEARCH

SVCXMI Communication Master program
UUOSYM,MACSYM,X25SYM

Accumulators
Sl=l
S2=2
S3=3
S4=4
Tl=5
T2=6
SP=17

;Scratch ACs

;Temporary ACs

; Push Down Stack
SIZE=1000
STACK: BLOCK

SIZE

; X.25 Access Argument Blocks
WSPSIZ=<128./4>+.PBSIZ
WSPACE: BLOCK
WSPSIZ
ARGBLK: BLOCK
~DI0
BUFFER: BLOCK
~D32
STATE: BLOCK
1
PROMPT: ASCIZ
/> /
HELP:
ASCIZ
/Enter text:

;Working area for the X.25 library
;Argument block
;Transmitted data buffer
;port state

/
Interrupt System Storage Definitions
CH.X25=0
PSIARG: EXP
XWD
XWD
PSIVEC: EXP
BLOCK
EXP
BLOCK
START:

RESET
MOVE

;Interrupt channel number
;Condition, interrupt on NSP. events
;Offset into PSIVEC"NOFLAGS
;priority of
;New PC
;Old PC
;NO Flags
;DECnet channel status word

SP,[IOWD SIZE,STACK]

;Reset the world
;Set up push down stack

.PCNSP
0,0
0,0
SRVCKT
1

PSIINI: MOVEI
PIINI.
HALT
MOVE
PISYS.
HALT

SI,PSIVEC
SI,

ARGINI: SETZM
MOVE
BLT

ARGBLK
Tl,[ARGBLK"ARGBLK+l]
Tl,ARGBLK+9.

X25ISC: MOVEI
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
EXIT
MOVEI
MOVEM

Tl,XS%UND
Tl,STATE
;Set port state to UNDEFINED
Tl,[CH.X25"WSPACE]
;Interrupt channel and work area
Tl,ARGBLK
Tl,[POINT 7, [ASCIZ/TELENET/]]
Tl,ARGBLK+2
;Network name
Tl,[POINT 7, [ASCIZ/X25-GATE/]]
Tl,ARGBLK+3
;Access password
Tl,[POINT 7, [ASCIZ/3II060700153/]]
Tl,ARGBLK+4
;Destination DTE address
SI,ARGBLK
X%ISC:fI::fI:
Tl,ARGBLK+l
;Get return code
Tl,XC%SUC
;IS it successful?
1,
; No, terminate
Tl,XS%CAG
;Yes,
Tl,STATE
;Change port state to CALLING

;Initialize software interrupt system
; Failed
Tl,[PS.FOF!PS.FAC+PSIARG]
Tl,
;Keep interrupt system off temporarily
; Failed
;Initialize entire argument block area

B-14

SAMPLE MACRO-I0 PROGRAMS
DISMIS: MOVE
PISYS.
EXIT
MOVEI
DSM.l:
HIBER
EXIT
JRST

Tl, [PS.FON]
Tl,
1,
Tl,O
Tl,
1,
OSM.l

SRVCKT: PUSH
PUSH
PUSH
PUSH

SP,Sl
SP,S2
SP,Tl
SP,T2

;Save registers

ARGBLK+l
Tl,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
Sl,ARGBLK
X%RPS##
Tl,ARGBLK+l
Tl,XC%SUC
X25TPA
Tl,STATE
T2,ARGBLK+2
Tl,XS%CAG
[CAIN
T2,XS%CAG
JRST NOTHNG
CAIN
T2,XS%RUN
JRST X25S0M
JRST
X25TPA]
Tl,XS%RUN
[CAIN
T2,XS%RUN
JRST NOTHNG
JRST
X25TPA]
X25TPA

;Initialize argument block entries

NOTHNG: POP
POP
POP
POP
OEBRK.

SP,T2
SP,Tl
SP,S2
SP,Sl

;Restore registers

X25S0M: MOVEI
MOVEM
OUTSTR

Tl,XS%RUN
Tl,STATE
HELP

SOM.l:

OUTSTR
MOVE
SETZ

PROMPT
Tl,[POINT 7,BUFFER]
T2,

;Receiving buffer
;Reset counter

SOM.2:

INCHWL
CAIN
JRST
IOPB
AOS
CAIE
JRST

Sl
Sl,32
X25TPA
Sl,Tl
T2
Sl,12
SOM.2

;Get one character from terminal
; End of text ?
; Yes, terminate circuit
;Stash character away
;Update counter
;End of text line?
; No, continue

SOM.3:

SETZM
MOVE
BLT
CAlLE
MOVEI
MOVEM
MOVE
MOVEM
MOVEI
CALL
MOVE
CAIE
JRST

ARGBLK+l
;Initialize argument block entries
Tl,[ARGBLK+l"ARGBLK+2]
Tl,ARGBLK+9.
T2,128.
;Set the maximum length of the string
T2,128.
; Truncate the text to 128 characters
T2,ARGBLK+2
Tl,[POINT 7,BUFFER]
Tl,ARGBLK+3
;Get pointer to the text string
Sl,ARGBLK
X%SOM##
;Send the string to the network
Tl,ARGBLK+l
;Get the return code
Tl,XC%SUC
;Is it successful?
[TXNN
Tl,XC%PER
;No, then is it procedure error?
JRST SOM.l
;No, it is non-fatal error
JRST
X25TPA]
;Yes, terminate
SOM.l
;Get next string from terminal

SETZM
MOVE
BLT
MOVEI
CALL
MOVE
CAIE
JRST
MOVE
HRRZ
CAIN
JRST

CAIN
JRST
JRST

JRST
X25TPA: MOVEI
CALL
EXIT
ENO

Sl,ARGBLK
X%TPA##
1,
START

;Turn interrupt system on
; Fa iled
;Oismiss the process
; Failed

;Pass access argument block
;Check port state
;Get return code
;Is it successful?
;No, terminate
;Get old port state
;Get new port state
;From CALLING state
;Remain in CALLING state
;00 nothing
;Changes to RUNNING state
;Transmit data to the network
;Otherwise, terminate
;From RUNNING state
;Remain in RUNNING state
;00 nothing
;Otherwise, terminate
;Oon't want to handle other states

;Update port state to RUNNING

;Terminate port access
;Stop program
;End Of program

B-15

APPENDIX C
BIBLIOGRAPHY

The following lists CCITT recommendations relevant to users of the
TOPS-10 PSI software and the CCITT publications in which those
recommendations are discussed. The information in this appendix is
subject to change. For more information, contact the CCITT.
Recommendation

Document

X.3

Document AP VII-No.

6-E

X.25

Document AP VII-No.

X.28, X.29

Document AP VII-No.

The following document contains a complete and unabridged form of the
key CCITT recommendations as they appear in Fascile VIII.2 of the
Yellow Book of the Consultative Committee for International Telegraph
and Telephone, 1981 edition.
The X.25 Protocol and Seven Other
X.1, X.2,
X.3, X.2l bis, X.28,
Publications. Belmont, California.

C-1

Key CCITT Recommendations:
and X.29. Lifetime Learning
1981

APPENDIX D
ERROR MESSAGES DISPLAYED BY X29SRV

Error Message

Section (s) in
Which Message
Is Discussed

BREAK

5.6

CONTINUE

5.6

CONNECTION IS NOT SUPPORTED

5.5.3

DISCONNECTING

5.5.2, 5.5.3

FAILED TO CONNECT

5.5.3

HOST SYSTEM DISCONNECTED

5.5.5

TIMED OUT

5.5.3

UNDEFINED X.3 PARAMETER SET

5.5.3, 5.5.4

D-1

APPENDIX E
GLOSSARY

Bilateral Closed User
Group (BCUG)

An optional PPSN facility that restricts
a pair of DTEs to communicating with
each
othero
The
basic BCUG also
prevents this pair from accessing or
being accessed by other DTEs. Additions
to the BCUG facility allow one or both
of the DTEs to access or be accessed by
DTEs outside the group. These additions
are known as BCUG with Outgoing Access
and
BCUG
with
Incoming
Access
respectively.

CCITT

Comite
Consultatif
International
Telegraphique
et
Telephonique.
An
international advisory committee that
sets international communications usage
standards.

Channel

A logical path between a DTE and a DCE
over
which data is transmitted.
A
unique reference number called a Logical
Channel Number
(LCN)
identifies each
channel.

Character Mode DTE

A DTE that is unable to handle data in
packet form.
This DTE must interface
through a Packet Assembly/Disassembly
(PAD)
facility to connect to a PPSN.
Also known as a Remote X.29 Terminal.

Closed User Group (CUG)

An optional PPSN facility that restricts
two or more DTEs in the same group to
communicating with each other.
The
basic CUG also prevents these DTEs from
accessing or being accessed by other
DTEs outside the group.
Additions to
the basic CUG facility allow one or more
DTEs to access or be accessed by DTEs
outside the group. These additions are
known as CUG with Outgoing Access and
CUG with Incoming Access respectively.

E-l

GLOSSARY
Data Circuit-terminating
Equipment (DCE)

A
CCITT X.25 term referring
to
the
network
equipment
that
provides
functions
to establish, maintain and
terminate a connection.
A DCE also
handles the signal conversion and coding
between the data terminal equipment and
the network.
The switching exchange of
the network to which DTEs are connected.
(In
non-X.25
usage,
the
term is
synonymous with 'modem'.)

Data Terminal Equipment
CDTE)

the user's
A CCITT term referring to
terminal)
equipment
(computer
or
connected to a DCE on a packet switching
sending
network for
the purpose of
and/or receiving data.

DCE

See Data Circuit-terminating Equipment.

DECnet

The collective name for the software and
hardware products that allow various
DIGITAL
operating
systems
to
be
interconnected
to
form
computer
networks.
A network is a configuration
of two or more independent computer
systems
linked
together
to
share
resources and/or exchange information.

DTE

See Data Terminal Equipment.

Duplex

Simultaneous,
independent transmission
in both directions.
Also referred to as
full-duplex.

Facility

A service or mode of operating that a
PPSN is able to provide for a user upon
subscription
and/or
request,
for
example,
fast
select
or
reverse
charging.

Fast Select

An optional PPSN facility that allows a
DTE to include a user data field of up
to 128 bytes when setting up a virtual
circuit.

Flag Sequence

A series of ones
and
zeros
that
indicates the start and end of a frame.

Flow Control

The mechanism which ensures that the
sending station does not overrun the
receiving station with more packets that
it can accept.

Flow Control Parameter
Negotiation

A
process that allows selection
of
packet sizes and window sizes in each
direction
of
a
particular virtual
circuit.

Frame

A unit delimited by flags that
includes
a header,
used by the link level to
exchange packets as well as control and
error information between the DTE and
the DCE.

E-2

GLOSSARY
16-bit,
error check pOlynomial
which
verifies that the bit content of a frame
is
the
same
before
and
after
transmission.

Frame Checking Sequence
(FCS)

x (X'5 + x + ... + x + 1)
k

FCS = R

x'· (con)

x'· + X + X + 1
12

x'· + X" + X + 1

mod
2

one's
complement
MR-S-2730-83

where k = number of bits
in the frame
not
including the flags and FCS itself
and con = the contents of the frame not
including the flags and the FCS itself.
Full-Duplex

See Duplex.

Gateway

The connection between two
individual
packet
switching
networks.
The
connection provides a link through which
a DTE can communicate with a DTE on a
different network.
A gateway is covered
in CCITT Recommendation X.7S.

Half-Duplex

A circuit designed for
transmission in
either direction but not both directions
simultaneously.

Header

The control information before a message
text; for example, source or destination
code,
priority,
or packet or
frame
identification.

Incoming Calls Barred

An optional PPSN facility that prevents
a DTE from accepting any calls.

Local DTE

A frame of reference; the DTE
the user is located.

Logical Channel

A logical link between a DTE and
its
DCE.
The physic:al communications line
between a DTE and DCE is divided into a
set of logical channels.

Logical Channel Number
(LCN)

A
unique
reference number
identifies a
logi:cal channel.
recognizes a virtual circuit
associated LCN.

E-3

which

A
by

that
DTE
its

GLOSSARY
Message

A
communication,
prepared
information
interchange
in
a
suitable
for
passage
through
interchange medium.
It includes:

for
form
the

•

All portions of the communications
such as machine sensible controls

•

An indication of the start of the
message and the end of the message

A header containing routing
and
• other
information, one or more texts
containing
originator-to-addressee
communication(s), and
the
text indicator

the
end

In packet switching, a message can be
segmented
into
several
packets to
traverse the network,
or
in
some
circumstances several messages can be
carried in one packet.
Modem
(Modulator-Demodulator)

A device that translates digital signals
(electrical
impulses)
generated by a
computer
into analogue signals (tones)
that can be transmitted over telephone
lines, and vice versa.

Non-packet-mode DTE

See Character Mode DTE.

Non-standard Default
Packet Size

An optional PPSN facility that permits a
DTE to specify a default packetsize that
is different from the PPSN's default.

Non-standard Default
Window Size

An optional PPSN facility that permits a
DTE to specify a default window size
that
is
different from the PPSN's
default.

Octet

A group of eight bits; a byte.

One-way Logical Channel
Incoming

An optional PPSN facility that prevents
a particular
logical
channel
from
handling outgoing calls.

One-way Logical Channel
Outgoing

An optional PPSN facility that prevents
a particular
logical
channel
from
handling incoming calls.

Outgoing Calls Barred

An optional PPSN facility that prevents
a DTE from initiating any calls.

Packet

The unit of data switched through a
PPSN;
normally
a
user data field
accompanied
by
a
header
carrying
destination and other information.

E-4

GLOSSARY
Packet Assembly/Disassembly
(PAD) Facility

i
A
device at a PPSN node that allows
access from an asynchronous terminal,
such as an LA36.
The terminal connects
to the PAD and the PAD
puts
the
terminal's
input
data
into packets
(assembles)
and takes the terminal's
output
data
out
of
packets
(disassembles) •

Packet Control

The functions concerned with the correct
routing
and reception of
individual
packets through the network.

Packet-mode DTE

A DTE that can handle data
in packet
form.
This implies a capability for
assembling and disassembling packets. A
computer is one type of packet-mode DTE.

Packet Receive Sequence
Number (P(R»

The
P(R) number indicates
that
all
packets up to that number minus one have
been received.
The P(R)
number thus
authorizes the transmission of further
packets by updating the lower window
edge.

Packet Send Sequence
Number (P(S»

The P(S) number specifies the position
of a packet
in a sequential stream.
The number starts at zero for the first
packet and increases by one for each
successive packet sent on one logical
channel
in one direction.
The P(S)
number can be either modulo 8 or modulo
128 although modulo 8 is the default for
all
PPSNs.
A packet can only be
transmitted if its P(S) is greater than
or equal to the lower window edge and
less than the upper window edge.

Packet switching

A data transmission process,
utilizing
addressed packets, whereby a channel is
occupied only for
the
duration
of
transmission of the packet.
NOTE
In certain data communication
networks,
the
data
can be
formatted
into a
packet
or
divided and then formatted into
a number of packets
(either by
the data terminal equipment or
by equipment within the network)
for
transmission
and
multiplexing purposes.

Packetnet System Interface
(PSI)

The collective name for the hardware and
software products that allow various
DIGITAL operating systems to participate
in a packet switching environment.

E-5

GLOSSARY
Permanent virtual Circuit
(PVC)

A permanent logical association between
two DTEs, which is analogous to a leased
line.
Transmission of packets on a PVC
needs no call set up or call clearing by
the DTE.
Packets are routed directly by
the network from one DTE to the other.

Port

A collection of resources that
a virtual circuit.

PPSN

See Public Packet Switching Network.

Protocol

An agreed set of rules governing
operation of a communications link.

Public Packet Switching
Network (PPSN)

A set of equipment and interconnecting
links that provides a
packet switching
set of equipment and
interconnecting
links that provides a
packet switching
communications service to subscribers
within a particular country.

PVC

See Permanent Virtual Circuit.

Qualified Data

Data transmitted in a
packet
in which
the Qualifier bit is set.
This bit is
usually
reserved
for
special
applications,
such
as higher
level
protocols.
For example,
X.29 protocol
messages are transmitted between PADs as
qualified data messages.

Remote DTE

A frame of reference:
any DTE in a
network other than the one at which the
user is located.

Remote virtual Terminal

A terminal connected
to
a
Packet
Assembly/Disassembly (PAD) facility.

Reset

A reset allows a DTE to re-initialize a
virtual circuit by resetting the lower
window edge and peS) and peR) numbers to
zero.
All Data and Interrupt packets
that may be
in
the
network
are
discarded.

Reverse Charging

An optional PPSN facility that allows a
DTE to request that the remote DTE is
charged for a particular call.

Start Element

A single O-bit that marks the start of a
character in start-stop transmission.

E-6

maintain

the

GLOSSARY
Start/stop Transmission

Asynchronous transmission in which a
group
of
bits
corresponding to a
character is preceded by a start element
and is followed by a stop element.

Stop Element

Either one or two I-bits that mark(s)
the end of a character in start-stop
transmission.

SVC

See Switched Virtual Circuit.

Switched Virtual Circuit
(SVC)

A temporary logical association between
two DTEs connected to a PPSN which
is
analogous to connection by a dial-up
line.
An SVC is set up only when there
is data to transmit and is cleared when
the data transfer is complete.

Tariff

A published rate for
services.

Throughput Class
Negotiation

An optional PPSN facility that indicates
the maximum data rate for a particular
virtual circuit.
The facility allows a
DTE to request a higher or lower data
rate depending on the throughput of the
packets.

Virtual Circuit

An
association
between
two
DTEs
connected to a PPSN whereby the two DTEs
are able to interact as
if a specific
circuit is dedicated to them throughout
the transmission.
In reality, a logical
connection
is
established,
and the
actual physical circuits are allocated
according
to
route
availability,
overload conditions, and so on.

window

The ordered set of consecutive data
packets authorized to cross the DTE/DCE
interface of the logical channel used
for an SVC or PVC in each direction of
transmission.
The
lowest
sequence
number in the window is called the lower
window edge~ When an SVC or PVC at the
DTE/DCE
interface
has
just
been
established, the window related to each
direction of data transmission has a
lower window edge equal to O.
The
packet send sequence number of the first
data packet not authorized to cross the
interface is the value of the upper
window edge; that is, the lower window
edge plus the window size.

X.3

A CCITT recommendation that specifies
the Packet Assembly/Disassembly
(PAD)
facility in a public data network.

E-7

telecommunications

GLOSSARY
X.2S

A CCITT recommendation that specifies
the
interface between Data Terminal
Equipment and Data Circuit-terminating
Equipment for equipment operating in the
packet mode on public data networks.

X.28

A CCITT recommendation that specifies
the DTE/DCE interface for a start-stop
mode
DTE
accessing
the
Packet
Assembly/Disassembly (PAD) facility in a
public data network situated in the same
country.

X.29

A CCITT recommendation that specifies
procedures for the exchange of control
information and user data between a
packet-mode
DTE
and
a
Packet
Assembly/Disassembly (PAD) facility.

X.7S

A CCITT recommendation
that specifies
the procedures for communicating between
PPSNs.

E-8

INDEX

36-bit binary data conversion,
3-3

Data types (Cont.)
8-bit byte array, 3-1
integer, 3-1
integer array, 3-1
logical, 3-1
Data-qualifier bit, 4-20, 4-31
DCE (Data Circuit-terminating
Equipment), 1-3, 1-4, 1-9,
1-11
DECnet logical link, 2-3
DEFINE command, 5-13
Diagnostic data, 3-31, 4-29
DISCONNECT command, 5-14
DTE (Data Terminal Equipment),
1-3, 1-4, 1-9 to 1-11
local, 2-3

-AACCEPT INCOMING CALL
FORTRAN-la, 3-5
MACRO-la, 4-4
Assembly/disassembly facility
packet, 1-3
-BBilateral Closed User Group
(BCUG), 1-13
Binary data conversion, 3-3
-C-

-ECCITT, 1-3
Clear cause, 3-18, 4-18
CLEAR command, 5-10
Clear data, 4-8
Clear diagnostic, 3-8, 3-18, 4-18
CLEAR SWITCHED CIRCUIT
FORTRAN-la, 3-8
MACRO-la, 4-7
Closed User Group (CUG) , 1-13
Comite Consultatif International
Telegraphique et Telephonique
(CCITT), 1-3
Command levels, 5-6 to 5-8
first level software, 5-7
second level software, 5-7
Command mode, 5-8
enter i ng, 5-16
Conclusion of program, 2-15, 2-16
CONFIRM INTERRUPT MESSAGE
FORTRAN-la, 3-7
MACRO-la, 4-6
CONNECT command, 5-11
Connecting to a PAD (Packet
assembly/disassembly
facility), 5-8
CUG (Closed User Group), 1-13,
1-14
-DData Circuit-terminating
Equipment (DCE), 1-3, 1-4,
1-9, 1-11
Data mode, 5-8
Data Terminal Equipment (DTE) ,
1-3, 1-4, 1-9 to 1-11
local, 2-3
Data types
ASCII string, 3-1
8-bi t byte, 3-1

Error conditions
fatal, 2-8, 3-28, 4-25
Error messages, 5-9

-FFast Select, 1-13
Fast Select Acceptance, 1-13
Fatal error conditions, 2-8, 3-28,
4-25
Flow control, 1-9 to 1-12, 1-14
for control packets, 1-10
for data packets, 1-11
Flow Control Parameter
Negotiation, 1-14
FORTRAN-la, 3-1 to 3-38
library, 3-4
sending and receiving data, 3-2
subroutine calls
X25AIC, 3-5
X25CIM, 3-7
X25CSC, 3-8
X25ISC, 3-10
X25NCS, 3-13
X250PC, 3-14
X25RAD, 3-16
X25RCD, 3-18
X25RDM, 3-20
X25RIC, 3-23
X25RIM, 3-25
X25RPS, 3-26
X25RRD, 3-29
X25RVC, 3-31
X25SDM, 3-33
X25SIM, 3-35
X25TPA, 3-36
X25WIC, 3-37

Index-l

Network devices (Cont.)
packet mode, 1-3
NO COMMUNICATION SEEN
FORTRAN-la, 3-13
MACRO-la, 4-12
Normal data, 3-20, 3-34, 4-20,
4-31

-GGateway Access Routines, 2-3
-1-

INFORMATION command, 5-15
Initialization, 2-14 to 2-16
INITIATE SWITCHED CIRCUIT
FORTRAN-la, 3-10
MACRO-la, 4-9
Interrupt, 1-12, 2-13 to 2-16,
4-1

-0-

OPEN PERMANENT CIRCUIT
FORTRAN-la, 3-14
MACRO-la, 4-13
Optional PPSN facilities, 1-12 to
1-14

-LLCN (Logical Channel Number), 1-2,
1-9
Link, DECnet logical, 2-3
Linking
a FORTRAN-10 program, 3-4
a MACRO-10 program, 4-3
Local DTE (Data Terminal
Equipment), 2-3
Logical Channel Number (LCN) , 1-2,
1-9
Logical link, DECnet, 2-3
-MMACRO-la, 4-1 to 4-36
library, 4-3
return code values, 4-2
subroutine calls
X%AIC, 4-4
X%CIM, 4-6
X%CSC, 4-7
X%ISC, 4-9
X%NCS, 4-12
X%OPC, 4-13
X%RAD, 4-15
X%RCD, 4-17
X%RDM, 4-19
X%RIC, 4-21
X%RIM, 4-23
X%RPS, 4-24
X%RRD, 4-27
X%RVC, 4-28
X%SDM, 4-30
X%SIM, 4-32
X%'I'PA, 4-33
X%WIC, 4-34
Mbit, 3-20, 3-33, 3-34
Messages
error, 5-9
protocol, 2-3
More bit, 3-20, 3-33, 3-34
More-data bit, 4-20, 4-31
-NNetwork devices
non-packet mode, 1-3

-PP(R), 1-11, 1-12, 1-14, 2-14
P(S), 1-11, 1-12, 1-14, 2-14
Packet, 1-1
control, 1-10 to 1-12
data, 1-11
header, 1-1, 1-7
receive sequence number, 1-11
send sequence number, 1-11
size, 1-14
swi tching, 1-1
Packet assembly/disassembly
facility, 1-3
Packet Switching Network, Public
(PPSN), 1-1
PAD (Packet assembly/disassembly
facility), 1-3, 1-8, 1-9, 5-1
to 5-17
communicating with, 5-8
sample terminal session, 5-4
Permanent Virtual Circuit (PVC),
1-2
using a, 2-16
Port, 2-6
number, 2-6
state, 2-6 to 2-13, 4-26
access routines and, 2-12
state changes, 2-8 to 2-11
PPSN (Public Packet Switching
Network), 1-1
Protocol, 1-4, 2-3
messages, 2-3
PSI Gateway Access Routines, 2-1
to 4-3
functions, 2-3 to 2-6
PSI Gateway Software, 2-1 to 2-3
contents, 2-1
FORTRAN-la, 3-1
MACRO-la, 4-1
Public Packet Switching Network
(PPSN), 1-1
pvc (Permanent Virtual Circuit),
1-2
using a, 2-16

Index-2

-Q-

-T-

Qualified data, 3-20, 3-34, 4-20,
4-31
-R-

READ ACCEPT DATA
FORTRAN-la, 3-16
MACRO-la, 4-15
READ CLEAR DATA
FORTRAN-la, 3-18
MACRO-la, 4-17
READ DATA MESSAGE
FORTRAN-la, 3-20
MACRO-la, 4-19
READ INCOMING CALL
FORTRAN-la, 3-23
MACRO-la, 4-21
READ INTERRUPT MESSAGE
FORTRAN-la, 3-25
MACRO-la, 4-23
READ PORT STATUS
FORTRAN-la, 3-26
MACRO-la, 4-24
READ RESET DATA
FORTRAN-la, 3-29
MACRO-la, 4-27
Receiving
data, 2-14 to 2-16
SVC call, 2-16
Recommendation
X.25, 5-6
X.28, 5-5
X.29, 5-6
X.3, 5-5
Reset, 1-12
Reset cause, 2-15, 3-29, 4-27
Reset diagnostic, 2-15, 3-29,
4-27
RESET VIRTUAL CIRCUIT
FORTRAN-la, 3-31
MACRO-la, 4-28
Restart, 1-12

-S-

SEND DATA MESSAGE
FORTRAN-la, 3-33
MACRO-la, 4-30
SEND INTERRUPT MESSAGE
FORTRAN-la, 3-35
MACRO-la, 4-32
Sending data, 2-14 to 2-16
SVC, 1-3
initiating a call, 2-14, 2-15
receiving a call, 2-15
using an, 2-14 to 2-16
Switched Virtual Circuit (SVC) ,
1-3

TERMINATE PORT ACCESS
FORTRAN-la, 3-36
MACRO-la, 4-33
Throughput Class Negotiation,
1-13

-uUniversal symbols, 4-2
User programs, 2-13
UUO calls, 2-3

-vvirtual circuit, 1-1 to 1-3, 1-9,
1-10, 2-3, 2-13
clearing a, 1-9
setting up a, 1-9
transferring data over a, 1-9
typical call, 1-10

-wWAIT INCOMING CALL
FORTRAN-la, 3-37
MACRO-la, 4-34
Window, 1-11, 1-12, 1-14
size, 1-11
-X-

X%AIC, 4-4
X%CIM, 4-6
X%CSC, 4-7
X%ISC, 4-9
X%NCS, 4-12
X%OPC, 4-13
X%RAD, 4-15
X%RCD, 4-17
X%RDM, 4-19
X%RIC, 4-21
X%RIM, 4-23
X%RPS, 4-24
X%RRD, 4-27
X%RVC, 4-28
X%SDM, 4-30
X%SIM, 4-32
X%TPA, 4-33
X%WIC, 4-34
X.25, 1-3, 1-4, 2-3, 5-6
levels, 1-4
protocol levell, 1-5, 1-7
protocol level 2, 1-5, 1-6, 1-7
protocol level 3, 1-6, 1-7
protocol levels, 1-4, 2-3
X.28, 1-3, 1-8, 5-5
X.29, 1-3, 1-8, 2-1, 5-1, 5-6
X.3, 1-3, 1-8, 5-5
X25AIC, 3-5
X25CIM, 3-7
X25CSC, 3-8

Index-3

X25GAF.REL,' 3-4
X25GAM.REL, 4-3
X25ISC, 3-10
X25NCS, 3-13
X250PC, 3-14
X25RAD, 3-16
X25RCD, 3-18
X25RDM, 3-2, 3-3, 3-20
X25RIC, 3-23
X25RIM, 3-25
X25RPS, 3-26
X25RRD, 3-29
X25RVC, 3-31

X25SDM, 3-2, 3-3, 3-33
X25SIM, 3-35
X25SYM.UNV, 4-2
X25TPA, 3-36
X2 5WIC, 3-37
X29SRV, 2-1, 5-1 to 5-17
CLEAR command, 5-10
communicating with, 5-8
CONNECT command, 5-11
DEFINE command, 5-13
DISCONNECT command, 5-14
error messages, 5-9
INFORMATION command, 5-15

Index-4

TOPS-10
PSI User's Guide
AA-CK81 A-TB
READER'S COMMENTS

NOTE:

This form is for document comments only. DIGITAL will use comments submitted on
this form at the company's discretion. If you require a written reply and are eligible to
receive one under Software Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of reader that you most nearly represent.

o Assembly language programmer
o Higher-level language programmer
o Occasional programmer (experienced)
o User with little programming experience
o Student programmer
o Other (please specify)~~~~~~~~~~~~~~~~~~~~~
Name __~~~~~~~~__~~~~_______ Date __~___________________
Organization
Telephone ______________
Street ___________________________________________________
City ________________________________ State _______ Zip Code ______
or Country

---~-.--0m00 N ot
• oTear

FOml.dHe,r e and Tape - - - - - - - - - - - - - - - - - - - - - -

rfl-Ill-------- ~~;:.;:;; ---

I
I
1
I

i'f Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SOFTWARE PUBLICATIONS

200 FOREST STREET MR01-2/L 12
MARLBOROUGH, MA 01752
I
I
1

I
1
1

1
1

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _I

I
1

1
1