Digital PDFs

AA-M581B-TK

May 1984

332 pages

Original

10MB

Document:	DIL User Reference Manual Nov84
Order Number:	AA-M581B-TK
Revision:	0
Pages:	332
Original Filename:	AA-M581B-TK_DIL_User_Reference_Manual_Nov84.pdf

OCR Text

OIL User Reference Manual
AA-M581 8-TK

November 1984

The OIL is a set of callable subroutines that enable you to
transfer data between TOPS-10, TOPS-20 and VMS systems.
This revised document supersedes the DIL User Reference
Manual, order numbers AA-M581 A-TK and AO-M581 A-T1 .
OPERATING SYSTEM:

SOFTWARE:

TOPS-20 V4.1 and later
for 2020 (KS) Systems
TOPS-20 V5.1 and later
for KL Systems
VAX/VMS V3.1 and later
TOPS-10 V7.02 and later

TOPS-10ITOPS-20 COBOL V12B or later
TOPS-10/TOPS-20 FORTRAN V7 or later
VAX/VMS COBOL V3.1 or later
VAX/VMS FORTRAN V3.0 or later

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.

Western Region

Northeast/Mid-Atlantic Region

Central 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
Schaumburg, Illinois 60195
Sunnyvale, California 94086
Telephone:(312)64Q--5612
Telephone:(408)734-4915

digital equipment corporation. marlboro. massachusetts

First Printing, February 1983
Updated, January 1984
Revised, November 1984
© Digital Equipment Corporation 1983, 1984. 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:

~D~DDmDTM
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

OIL USAGE MATERIAL

CHAPTER 1

OIL CONCEPTS AND CAPABILITIES

1.1
1..1.1
1.1.2

INTRODUCTION • • • • • • • • • • • • • • • • • • • 1-1
Data Interchange Library Status Codes
• • 1-4
The DIL Interface Support Files • • • • • • • • 1-6
DATA CONVERSION CONCEPTS AND CAPABILITIES

CHAPTER 2
2.1
2.1.1
2.1.2
2.1.3

CONVERTING FIELDS • • • • • • • • • • • •
• • 2-1
2-2
Conversion Using a Foreign Field Descriptor
• 2-4
Conversion Using a Detailed Description
2-4
Record Layouts and Byte Offsets • • • • • •

CHAPTER 3

TASK-TO-TASK CONCEPTS AND CAPABILITIES

CHAPTER 4

REMOTE FILE ACCESS CONCEPTS AND CAPABILITIES

4.1
PART II

OPENING A REMOTE FILE

• • • 4-2

USING THE OIL FROM TOPS-I0 AND TOPS-20

CHAPTER 5
5.1
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.3.8
5.3.9
5.3.10
5.3.11

TOPS-I0 AND TOPS-20 DATA CONVERSION
DATA CONVERSION FROM TOPS-I0/TOPS-20 COBOL
• 5-1
Compiling Programs • • • • • • • • • • • • • • • 5-1
Including the Interface Support Files
• 5-1
Storing an FFD • • • • • • • • • • • • • • • • • 5-2
Passing a Record to the XDESCR Routine ••
• 5-2
Checking For Errors • • • • • • • • • • • • • • 5-3
DATA CONVERSION FROM TOPS-10/TOPS-20 FORTRAN
• 5-4
Including the Interface Support Files • • • • • 5-4
Storing an FFD • • • • • • • • • • • • • • • • • 5-4
Passing a Record to the XDESCR Routine • •
• 5-5
Checking For Errors • • • • • • . • • • • • • • 5-6
TOPS-10/TOPS-20 DATA-CONVERSION REFERENCE • • • • 5-7
DILINI - Allow the OIL to Recognize Status Codes 5-7
XDESCR - To Create an FFD • • • • • • ••
• 5-8
XCGEN - To Perform General Purpose Conversion
5-10
XCVST - Convert String Fields • • • • • •
5-12
XCVFB - Convert Fixed-Point Binary Fields
5-13
XCVFP - Convert Floating-Point Fields
5-14
XCVPD - Convert Packed Decimal Fields
5-15
XCVDN - Convert Display Numeric Fields
5-17
XCFBDN - Convert Fixed-Point Binary Fields to
Display Numeric Fields • • • • • • • • • •
5-19
XCFBPD - Convert Fixed-Point Binary- Fields to
Packed Decimal Fields • • • • • • • •
5-21
XCPDDN - Convert Packed Decimal Fields to
Display Numeric Fields • • • • • • • •
5-22
iii

5.3.12
5.3.13
5.3.14
5.3.15
5.4
5.4.1
5.4.2
CHAPTER 6
6.1
6.1.1
6.1.2
6.1.3
6.1.4
6.1.5
6.1.6
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.2.5
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.3.9
6.3.10
6.3.11
6.3.12
6.3.13
6.4
6.4.1
6.4.2
CHAPTER 7
7.1
7.1.1
7.1.2
7.1.3
7.1.4
7.1.5
7.1.6
7.1.7
7.2
7.2.1
7.2.2

XCPDFB - Convert Packed Decimal Fields to
Fixed-Point Binary Fields
• • • • •
XCDNPD - Convert Display Numeric Fields to
Packed Decimal Fields • • • • • • • • • •
XCDNFB - Convert Display Numeric Fields to
Fixed-Point Binary Fields
• • • • •
CVGEN - Perform Conversion Without an FFD
TOPS-10/TOPS-20 DATA CONVERSION EXAMPLES • • • •
TOPS-10/TOPS-20 COBOL Data Conversion Example
TOPS-10/TOPS-20 FORTRAN Data Conversion Example

5-24
5-26
5-28
5-30
5-35
5-35
5-38

TOPS-20 AND TOPS-10 TASK-TO-TASK
• • 6-1
TASK-TO-TASK FROM TOPS-20 OR TOPS-10 COBOL
Compiling Programs • • • • • • • •
• • 6-1
Including the Interface Support Files
• 6-1
Storing a Network Logical Name (NLN) • •
• • 6-2
Storing Task and User Attributes • • • • • • • • 6-2
Checking the Status of a Task-to-Task Routine
• 6-3
The TOPS-10 Software Interrupt System • • • • • 6-3
TASK-TO-TASK FROM TOPS-20 AND TOPS-10 FORTRAN • • 6-3
Including the Interface Support Files
• • 6-4
Storing a Network Logical Name (NLN) • • • • • • 6-4
Storing Task and User Attributes • • • • ~ • • • 6-4
Checking the Status of a Task-to-Task Routine • 6-5
The TOPS-10 Software Interrupt System • • • • • 6-5
TOPS-10 AND TOPS-20 TASK-TO-TASK REFERENCE • • • • 6-6
NFGND - Return the Status of a Link • • • • • • 6-6
NFINF - Get Information About the Other End of a
Logical Link.
• • • • • • • • • • • • • • • • • 6-8
NFOPA - Open a Link From an Active Task (ASCII) 6-11
NFOPB - Open a Link From an Active Task
(Binary) • • • • • • • • • • • • • • • • • • • 6-14
NFOP8 - Open a Link From an Active Task (8-bit) 6-17
NFOPP - Open a Link From a Passive Task
6-20
NFACC - Accept a Connection
• • • •
6-22
NFREJ - Reject a Connection
6-24
NFRCV - Receive Data Over a Link •
• • ••
6-25
NFSND - Send Data Over a Link
6-28
NFINT - Send an Interrupt Data Message Over a
Li nk • • • • • • • • • • • •
6-30
NFRCI - Receive an Interrupt Data Message Over
a Link • • • • • • • • • • • • • • • • • • • • 6-31
NFCLS - Close a Link • • • • • • • • • • • • • 6-32
TOPS-10/TOPS-20 TASK-TO-TASK EXAMPLES
•••••
6-34
TOPS-10/TOPS-20 COBOL Task-to-Task Examples
6-34
TOPS-10/TOPS-20 FORTRAN Task-to-Task Examples
6-40
TOPS-10 AND TOPS-20 REMOTE FILE ACCESS
REMOTE FILE ACCESS FROM TOPS-10 OR TOPS-20 COBOL •
Compiling Programs • • • • • • • • • •
•••
Including the Interface Support Files
• • • • •
Storing a File Number • • • • • • •
•
Storing Accounting Information • • •
Reading and Writing Remote Data
•••
Checking the Status of a Remote File Access
Routine
•• • • • • • • • • • • • •
• •
The TOPS-10 Software Interrupt System
REMOTE FILE ACCESS FROM TOPS-20 OR TOPS-10 FORTRAN
•
Including the Interface Support Files
Storing a File Number • • • • • • • • • • • • •
iv

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

7.2.3
7.2.4
7.2.5
7.2.6
7.3
7.3.1
7~3.2

7.3.3
7.3.4
7.3.5
7.3.6
7.3.7
7.4
7.4.1
7.4.2
7.5
7.5.1
7.5.2
CHAPTER 8

LINKING A TOPS-10/TOPS-20 PROGRAM

8.1
8.2
8.3
PART III

Storing Account Information • • • • • • • • • • 7-4
Reading and Writing Remote Data
• • • • • • 7-4
Checking the Status of a Remote File Access
Routine • • • • • • • • • • • • • • • • • •
7-5
The TOPS-10 Software Interrupt System
• • 7-5
TOPS-20 AND TOPS-10 REMOTE FILE ACCESS REFERENCE • 7-6
ROPEN - Open a Remote File • • • • •
7-6
RREAD - Read Data From a Remote File •
• • 7-9
RWRITE - Write Data To a Remote File • •
7-10
RCLOSE - Close a Remote File • • • • •
7-11
RDEL - Delete a File • • • • • • • • • • • • • 7-13
RSUB - Submit a File For Batch Processing
7-15
RPRINT - Print a File • • • • • • • • • •
7-17
TOPS-20 REMOTE FILE ACCESS EXAMPLES • • • • • • 7-19
TOPS-20 COBOL Remote File Access Example • • • 7-19
TOPS-20 FORTRAN Remote File Access Example
7-21
TOPS-10 REMOTE FILE ACCESS EXAMPLES • • • •
7-24
TOPS-10 COBOL Remote File Access Example •
7-24
TOPS-10 FORTRAN Remote File Access Example
7-26

DECsystem-10 LINKAGE INSTRUCTIONS • • • • • • • • 8-1
DECSYSTEM-20 LINKAGE INSTRUCTIONS • • • • • • • • 8-1
DECSYSTEM-10 AND DECSYSTEM-20 OVERLAY INSTRUCTIONS 8-1

USING THE OIL FROM VMS

CHAPTER 9
9.1
9.1.1
9.1.2
9.1.3
9.1.4
9.2
9.2.1
9.2.2
9.2.3
9.2.4
9.3
9.3.1
9.3.2
9.3.3
9.4
9.4.1
9.4.2
CHAPTER 10
10.1
10.1.1
10.1.2
10.1.3
10.1.4
10.2
10.2.1
10.2.2
10.2.3
10.2.4

VMS DATA CONVERSION
DATA CONVERSION FROM VMS COBOL • • • • • • • • • • 9-1
Including the Interface Support Files • • • • • 9-1
Storing an FFD • • • • • • • • • • • • • • • • • 9-3
Passing a Record to the DIX$MAK DES DET Routine 9-3
Checking for Errors • • • • • -; • -; •
• • 9-3
DATA CONVERSION FROM VMS FORTRAN • • • • • • • • • 9-4
Including the Interface Support Files • • • • • 9-4
Storing an FFD • • • • • • • • • • • • • • • • • 9-5
Passing a Record to the Data Conversion Routines 9-6
Checking for Errors • • • • • • • • • • • • • • 9-6
VMS DATA CONVERSION REFERENCE •• • • • • • • • • 9-7
DIX$MAK DES DET - Create an FFD • • • • • • • • 9-7
DIX$BY DIX DES - Perform General Conversion • • 9-9
DIX$BY-DET-- Convert a Field Without an FFD
9-11
VMS DATA-CONVERSION EXAMPLES • • • • • •
9-15
VMS COBOL Data Conversion Example
9-15
VMS FORTRAN Data Conversion Example • • • • • 9-17
VMS TASK-TO-TASK
TASK-TO-TASK FROM VMS COBOL • • • • • •
Including the Interface Support Files
Storing a Network Logical Name • • • •
Storing Task and User Attributes • • •
Checking the Status of a Task-to-Task Routine
TASK-TO-TASK FROM VMS FORTRAN • • • • •
Including the Interface Support Files • • • •
Storing a Network Logical Name • • • • • • • •
Storing Task and User Attributes • • • • • • •
Checking the Status of a Task-to-Task Routine
v

10-1
10-1
10-3
10-3
10-3
10-4
10-4
10-5
10-6
10-6

10.3
10.3.1
10.3.2

VMS TASK-TO-TASK REFERENCE • • • • • • • • • • • 10-7
DIT$NFGND - Return the Status of Links • • • • 10-7
DIT$NFINF - Get Information About the Other End
10-9
of a Link.
10.3.3
DIT$NFOPA - Open an ASCII Link From an Active
10-12
Task
DIT$NFOPB - Open a Binary Link From an Active
1,0.3.4
10-15
Task
10.3.5
DIT$NFOP8
Open an 8-Bit Link From an Active
Task • • • • • • • • • • • • • • • • • • • • • 10-18
10-21
10.3.6
DIT$NFOPP - Open a Link From a Passive Task
10.3.7
DIT$NFACC - Accept a Connection
• • • • • 10-23
10-25
10.3.8
DIT$NFREJ - Reject a Connection
10-26
DIT$NFRCV - Receive Data • • • •
10.3.9
10-28
10.3.10
DIT$NFSND - Send Data • • • • • • • • •
10.3.11
DIT$NFRCI - Receive an Interrupt Data Message
Over a Link • • • • • • • • • • • • • • • • • 10-30
10.3.12
DIT$NFINT - Send an Interrupt Data Message
Over a Link
••• • • • • • • • • •
• • 10-31
10.3.13
DIT$NFCLS - Close a Link • • • • • • • • • • • 10-32
10.4
VMS TASK-TO-TASK EXAMPLES
•••••
• 10-33
10.4.1
VMS COBOL Task-to-Task Examples
• • • • • 10-33
VMS FORTRAN Task-to-Task Examples
10.4.2
• 10-39

··················

...··················
. . .- · · · · · · · · · · · · · · · · · ·

CHAPTER 11
11.1
11.1.1
11.1.2
11.1.3
11.1.4
11.1.5
11.2
11.2.1
11.2.2
11.2.3
11.2.4
11.2.5
11.3
11.3.1
11.3.2
11.3.3
11.3.4
11.3.5
11.3.6
11.3.7
11.4
11.4.1
11.4.2
CHAPTER 12

PART IV

VMS REMOTE FILE ACCESS
REMOTE FILE ACCESS FROM VMS COBOL • • • •
Including the Interface Support Files • • • •
Storing a File Number • • • • • • • • • • • •
Storing Account Information • • • •
Reading and Writing Remote Data
Checking the Status of a Remote File Access
Rou tine
•••••••• • • • • • • • • • • •
REMOTE FILE ACCESS FROM VMS FORTRAN
Including the Interface Support Files
Storing a File Number • • • • • • •
Storing Account Information • • • •
Reading and Writing Remote Data
•••••
Checking the Status of a Remote File Access
Routine
•••••••••••
VMS REMOTE FILE ACCESS REFERENCE • • •
DIT$ROPEN - Open a Remote File • • •
DIT$RREAD - Read Data From a Remote File
•
DIT$RWRITE - Write Data to a Remote File • • •
DIT$RCLOSE - Close a Remote File •
• • •
DIT$RDEL - Delete a File • • • • • • • • •
DIT$RSUB - Submit a File For Batch Processing
DIT$RPRINT - Print a File
• • • • ••
••
VMS REMOTE FILE ACCESS EXAMPLES
••••••••
VMS COBOL Remote File Access Examples • • • •
VMS FORTRAN Remote File Access 'Example
••

11-1
11-1
11-3
11-3
11-3
11-3
11-4
11-4
11-6
11-6
11-6
11-6
11-7
11-7
11-10
11-11
11-12
11-13
11-15
11-17
11-19
11-19
11-22

LINKING A VMS PROGRAM

APPENDIXES

APPENDIX A
A.l

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES
SPECIFYING DATA NAMES
vi

• • • • • • A-6

APPENDIX B
B.l
B.2
B.3
B.4
B.S

OIL DATA FORMATS
ALPHANUMERIC STRING DATA TYPES •
BINARY FIXED-POINT DATA TYPES
FLOATING-POINT DATA TYPES
DISPLAY NUMERIC DATA TYPES • •
PACKED DECIMAL DATA TYPES

APPENDIX C

THE OIL SAMPLE APPLICATION

APPENDIX 0

TASK IDENTIFICATION

0.1
0.2
0.3
0.4
0.4.1
0.4.2
0.4.3

ACCESSING A TASK BY NAME • • • • • • • • • • • • •
ACCESSING A TASK THAT PROVIDES A CLASS OF SERVICE
ACCESSING SPECIFIC TASK WHICH PROVIDES SERVICE
(TOPS-20 ONLY) • • • • • • • • • • • • •
•
VMS PASSIVE TASKS
••••••••••
•
Tasks that Wait for a Connect Request
• • •
Tasks Started as a Result of a Request • • · • •
Example of a Task Started as a Result of a
Request
• • • • • • • • • • • • • • • • •

APPENDIX E

OIL STATUS CODES

APPENDIX F

BIT TRANSPORT

F.l
F.2
F.3
APPENDIX G
G.l
G.l.l
G.l.2
G.l.3
G.l.4
G.l.S
G.l.6
G.l.7
G.2
G.2.l
G.2.2
G.2.3
G.2.4
G.2.S
G.2.6
G.2.7
G.2.8
G.2.9
G.2.l0

• • B-1
• B-3
• B-7
B-ll
B-19

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

NFOPB LINKS
• • • • • • •
• F-l
REMOTE FILE ACCESS IN ASCII MODE AND NFOPA LINKS • F-3
NFOP8 LINKS
• • • • • • •
• F-4
TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
REMOTE-FILE-ACCESS ERROR CODES AND THEIR MEANINGS: G-l
. . . .
. . . G-l
ROPEN/DIT$ROPEN Routine:
RREAD/DIT$RREAD: • •
• • • • • . • . • . • G- 3
RWRITE/DIT$RWRITE:
• • • •
• G-4
RCLOSE/DIT$RCLOSE: • • • • •
• G-S
RDEL/DIT$RDEL: • • •
• • • G-6
RSUB/DIT$RUB:
•••••
• G-7
RPRINT/DIT$RPRINT:
• • • • • • • G-8
G-IO
TASK-TO-TASK ERRORS AND THEIR MEANINGS:
NFOPA, NFOPB, NFOP8, NFOPP/DIT$NFOPA,
DIT$NFOPB, DIT$NFOP8, OIT$NFOPP: • • • • •
G-IO
NFGND/DIT$NFGND: • • • • •
• • • • • • • G-ll
G-12
NFACC/DIT$NFACC: • • • •
G-13
NFRCV/DIT$NFRCV:
G-14
NFSND/DIT$NFSND:
G-14
NFREJ/DI~$NFREJ: • • • • • .
G-IS
NFINT/OIT$NFINT: •
G-IS
NFRCI/DIT$NFRCI
••••
G-16
NFCLS/DIT$NFCLS: •
G-17
NFINF/DIT$NFINF: • • • • • • • •

INDEX

vii

FIGURES
1-1
1-2
1-3
2-1
2-2
3-1
3-2
C-l

A Sample DIL Application • • • • • • • • ••
• 1-3
Format of a VMS Status Code • • • • • • • • • • • 1-4
Format of a TOPS-IO or TOPS-20 Status Code
1-4
TOPS-IO or TOPS-20 Record Layout
••••
• 2-5
VMS Record Layout • • • • • ••
• • • • • • • 2-5
Simple Task-to-Task Application
• 3-3
Task-to-Task Application • • •
• • ••
• 3-4
Sample Application Flowchart • •
• C-l

viii

PREFACE

The Data Interchange Library (OIL) is a set of callable subroutines
that can be used by COBOL and FORTRAN programmers on TOPS-20, TOPS-IO
and VMS systems.
The OIL User Reference Manual describes the OIL and explains how to
use it.----The manual consists of three basic parts:
introductory
material, reference sections and appendices.
The
introductory
chapters (Chapters 1-4) present the concepts and capabilities of each
part of the Data Interchange Library. The reference portion of the
manual is divided first into TOPS-IO/TOPS-20 (Chapters 5-8) and VMS
(Chapters 9-12) sections. Each of these system-specific sections has
four subsections that explain:
•

The Data Conversion Routines

•

The Task-to-Task Routines

•

The Remote File Access Routines

•

Linking a program

The reference sections give specific instructions for
subroutines from your operating system.

using

the

OIL

Appendix A shows the language-specific values for OIL Names. Whenever
the manual refers to the OIL Name of a status code, argument value or
data type, check Appendix A to find its value for your language and
system.
Appendix 0 indicates the numerical value, OIL Name and
meaning for status codes returned by the Data Interchange Library
Routines.
Other appendices present more in-depth information about
the OIL.
Examples in this manual use lower case to indicate that you can supply
your own name for this variable.
In the following call, you can use
any names permitted by your system to represent the "nln" and "wait"
data items.
ENTER MACRO NFGNO USING nln, wait.

CHAPTER 1
OIL CONCEPTS AND CAPABILITIES

1.1

INTRODUCTION

The Data Interchange Library (DIL) is a set of callable subroutines
that enable you, the COBOL or FORTRAN programmer, to access and use
data that resides on another computer system. The DIL allows you to
pass data between programs on different systems or to directly access
records in files on other systems. You can use the DIL to access a
single record within a file and avoid having to transfer an entire
file to your system.
If the accessed data is not of the proper format
or data type, DIL provides the necessary data conversion facilities.
Transporting an entire file can be costly and time consuming,
particularly when you are dealing with a large file.
It is probably
not cost effective, for example, to spend hours transferring the
entire personnel file to your system when you only need the data for
one employee. If you have a small system, you probably don't even
have the capability to store such a big file.
To use the DIL in a multiple computer environment, the computers must
be connected by DECnet to form a network.
The network can be
homogeneous or heterogeneous. A homogeneous network ~onsists of two
or more systems of the same type. A heterogeneous network is made up
of computers of different types. The DIL can be used in a network
that supports any combination of VAX, DECSYSTEM-20 or DECsystem-lO
computers.
The DIL consists of three types of routines:
1.

Data Conversion Routines
The Data Conversion Routines provide you with the ability to
translate fields from one data type to another. These
routines are especially useful when you move data through a
heterogeneous network using the Task-to-Task Routines. A
record written in VMS binary format, for example, cannot be
used, as is, by a TOPS-20 system, because the two systems
have different methods of internal data representation.

1-1

DIL CONCEPTS AND CAPABILITIES

This release of the OIL supports "like-to-like" translation
of some COBOL and FORTRAN data types.
A like-to-like
translation is a translation between data types in a single
class.
The Data Conversion Routines support translation of
the following TOPS-IO, TOPS-20 and VMS data types:
•

Alphanumeric string

•

Fixed-point data (includes fixed-point
decimal and display numeric)

•

Floating-point binary

binary,

packed

You can, for example, use the Data Conversion Routines to
convert a VMS COBOL string data item to a TOPS-IO/TOPS-20
COBOL, VMS FORTRAN or TOPS-IO/TOPS-20 FORTRAN string data
item.
You cannot, however, use the routines to convert that
same data item to any non-string data item.
2.

Task-to-Task Routines
The Task-to-Task Routines allow you to move data between
programs on different systems.
To use the Task-to-Task
Routines, you establish a network connection between two
programs, rather than between a program and a file. This
network connection is called a logical link. Once you have
successfully established a logical link between programs, you
can transfer data over that link.
A program can use the
Task-to-Task Routines to perform the following functions:
•

Open a logical link to another program.

•

Wait for another program to request its services.

•

Get information about the status of network connections.

•

Get information about the other end of a logical link.

•

Accept a connection request from another program.

•

Reject a connection request from another program.

•

Receive data from another program over a logical link.

•

Send data to another program over a logical link.

•

Receive an interrupt data message
over a logical link.

•

Send an interrupt data message to another program over
logical link.

•

Close a logical link.

1-2

from

another

program
a

DIL CONCEPTS AND CAPABILITIES

Remote File Access Routines
The Remote File Access routines allow you to access and use
data that resides in a sequential ASCII file on another
computer.
The Remote File Access routines perform the
following functions:
•

Open a file for reading, writing or appending

•

Read a record from a file

•

Write a record to a file

•

Close a file

•

Delete a closed file

•

Submit a closed file for batch processing

•

Print a closed file

A practical OIL application might be used by a company that wants to
eliminate the collection of paper employee labor ticke~s. Each week,
every employee of the hypothetical company fills out a paper labor
ticket
(containing accounting information) and submits it to his or
her secretary. By using the OIL in a heterogeneous network, the
company could easily automate the labor ticket process. Figure 1-1
illustrates one method of using the OIL to collect weekly labor ticket
information.
A.

The user submits labor ticket information from a remote
terminal connected to either a VAX-II or DECSYSTEM-20.

The Task-to-Task Routines are used to ship data to a
on the DECSYSTEM-20.

The Data Conversion Routines are used to convert data,
if
necessary,
to DECSYSTEM-20 format. The data is then stored
on the DECSYSTEM-20.

The Remote File Access Routines are used by a program on the
VAX-II to access data in the file on the DECSYSTEM-20 in
order to write a summary report.

MR·S·3464·83

Figure 1-1:

A Sample DIL Application

1-3

program

DIL CONCEPTS AND CAPABILITIES
1.1.1

Data Interchange Library Status Codes

Each OIL routine returns a status code or condition value when it
finishes processing.
The status code lets you know whether the
routine ran successfully.
It alerts you to a problem by issuing
success, warning, error or fatal severity codes. See Appendix 0 for a
description of specific OIL status codes.
The OIL on VMS uses the standard VMS condition value.
A condition
value
(or status code)
is a word containing several fields that
describe the type of error and its severity. Besides. indicating the
success or failure of the called subroutine, the condition value can
provide the following information:
•

Severity of the failure

•

Error identification

•

Associated message text (VMS only)

•

Facility detecting the error

•

Control of error message printing (VMS only)

Figures 1-2 and 1-3, below, illustrate the format of the
returned by the OIL routines.

Condition Identification

16 15

Customer Definition Flag

Facility Specific Flag
MR-S-3463-83

Figure 1-2:

Format of a VMS Status Code
35

31
Condition Identification

Customer Definition Flag

Facility Specific Flag
MR-S-3465-83

Figure 1-3:

For.at of a TOPS-10 or TOPS-20 Status Code

1-4

status

code

DIL CONCEPTS AND CAPABILITIES

A status code is composed of the following parts:
Severity Code
The severity code indicates the seriousness of
The OIL returns the following severity codes:

o
1
2
3
4
5-7

the

error.

warning
success
error
information (considered a success code)
severe error
reserved for future use

Condition Identification
The condition identification
uniquely
identifies
the
condition on a system-wide basis. Condition identification
is composed of the facility number and the message number
(described on the following page).
Facility Number
The facility number identifies the subsystem that
the status code.

generates

•

Data Conversion routines return a facility number of 232
decimal.

•

Remote File Access and Task-to-Task
facility number of 233 decimal.

routines

Message Number
The message number identifies the specific
made in your call to the routine.

error

return

that

you

Control Bits
A condition value normally contains four control bits.
VMS
status codes contain four zeroes as the value for this
field. TOPS-IO and TOPS-20 status codes do not use this
field. These bits are reserved for Digital use.
On VMS systems, the LIB$MATCH COND function is available to compare
two status codes and determine if they refer to the same condition.
See the most recent version of the VAX-II Run-Time Library Reference
Manual for further information.

1-5

OIL CONCEPTS ANO CAPABILITIES
1.1.2

The OIL Interface Support Files

The OIL requires that you pass numeric values as parameters to the
routines.
These parameters can have different meanings, depending
upon the specific position of the parameter in a call to a DIL
routine. As a programmer, you may find it difficult to remember which
numeric values you will need to make the different OIL functions
occur.
You may also prefer to specify symbolic names rather than to
directly use the required numeric values. To simplify your use of the
OIL, several text files, called Interface Support files, are provided
with the OIL. These files define symbolic names for the parameters
for each of the OIL routines.
The names found in the Interface
Support files will make it easier for you to communicate with the OIL
routines.
There are two classes of Interface Support files, the "native" class
and the "compatible" class. The native class Interface Support files
define names that are native to the system for which the program is
written. The compatible class of support files, define names that are
compatible with both TOPS-IO/TOPS-20 and
VMS
language
names.
TOPS-IO/TOPS-20 systems do not have compatible class support files,
since the TOPS-IO/TOPS-20 native class names are already compatible
with VMS language names. A set of native class support files exists
for both COBOL and FORTRAN on TOPS-IO/TOPS-20 systems. On VMS systems
both the native and compatible classes of support files exist for both
FORTRAN and COBOL. For VMS FORTRAN, these compatible names are also
ANSI Standard names.
If you want to write a program that can be
easily transported to a TOPS-IO or TOPS-20 system, you may want to use
the compatible class Interface Support files.
For each language/system/class combination, the OIL has two
Interface Support files:

types

General OIL files that define terms applicable to all of the
OIL routines from the language and the operating system that
you plan to use.

Function-specific files which describe terms applicaole to
the type of OIL routines
(Data Conversion, Remote File
Access, or Task-to-Task), the language and the operating
system that you plan to use.
There are two types of
function-specific files:
OIX files, which include
• Conversion
Routines

terms

for

OIT files, which include the terms for
• Access
routines and the terms for

the
the

the

Data

Remote File
Task-to-Task

Routines
You must include both general and function-specific files when you
compile
your program.
If,
for example, you want to use the
Task-to-Task Routines, you should include the general OIL Interface
Support file and the function-specific OIT file~
The Interface Support files for TOPS-IO/TOPS-20 systems are provided
in an appropriate manner for the languages they support. On VMS
systems, the Interface Support files are provided as a single text
library called DIL.TLB.
You can use language-specific features to
extract the information from the VMS Text library for inclusion in
programs.

1-6

OIL CONCEPTS AND CAPABILITIES

Appendix A contains a listing of the names and values included in the
Interface Support files.
You can use the LIBARY system utility on
TOPS-IO or CPYLIB on TOPS-20 to either extract or modify individual
modules in the COBOL library file.
You can simply TYPE or PRINT the
individual TOPS-IO and TOPS-20 FORTRAN Interface Support files.
On
VMS systems you can use the LIBRARY DCL command to either extract the
individual modules in the Interface Support files as text files or to
modify the files.
For more information about using the DIL Interface Support files,
see
the language-specific sections of this manual. For information about
the names defined in the Interface Support files, refer to Appendix A.
Further Information:
To learn more about DECnet, see the most recent version of the
User's Guide for your operating system.
An overview of DECnet can be found
Introduction to DECnet.

the

most

recent

DECnet

version

To learn more about Status Codes, see the most recent version of The
VAX-II Guide to Creating Modular Library Procedures and the system
specific reference sections of this manual.

1-7

CHAPTER 2
DATA CONVERSION CONCEPTS AND CAPABILITIES

When you transfer records between heterogeneous systems, the data
formats
will
not
be understandable to both computers.
Data
representation in VMS memory differs from data representation in
TOPS-IO or TOPS-20 memory. This means that a VMS COBOL record (and
its fields), cannot be used, as is, by a TOPS-IO or TOPS-20 COBOL
program.
The Data Conversion Routines solve this problem by allowing
you to translate a field from one data type to another.
This release of the DIL supports "like-to-like" translation within the
following clagses of data types:
•

Alphanumeric string

•

Fixed-point data (includes fixed-point binary, packed decimal
and display numeric)

•

Floating-point binary

A like-to-like translation is a translation from a particular data
type to another data type within the same class. You can, for
example, use the Data Conversion Routines to convert a VMS COBOL
string data item to a TOPS-20 COBOL, TOPS-20 FORTRAN or VMS FORTRAN
string data item. You cannot, however, use the routines to convert
that same string data item to any type of non-string data item, such
as a floating-point number.

2.1

CONVERTING FIELDS

You can use the Data Conversion Routines to convert a field while it
still resides on its native system, before you transfer the field to
another system. You can also wait and perform any necessary data
conversion after you transfer the field.
No matter where the
conversion is done, the Data Conversion Routines require that you
describe two fields:
the source field and the destination field. The
Data Conversion Routines provide two basic ways of describing a field.

2-1

DATA CONVERSION CONCEPTS AND CAPABILITIES
2.1.1

Conversion Using a Foreign Field Descriptor

The Data Conversion Routines provide a convenient way to describe a
field in a record that requires conversion:
the Foreign Field
Descriptor (FFD). An FFD contains descriptive information about a
field, including:
•

the name of the record that contains the field

•

the record's native system

•

the position of the field within the record

•

the address of the record

This information allows the DIL to locate the field for conversion.
To build an FFD for a field, you must use one of the Data Conversion
Routines.
If you are working on a VMS system, the DIX$MAK DES DET
routine builds the FFD. If you are working on a TOPS-IO or -TOPS-20
system, the XDESCR routine builds the FFD.
To use the FFD method of data conversion you make two calls to the
XDESCR (or DIX$MAK DES DET) routine; one call is used to create an FFD
for the source field, the other to create an FFD for the destination
field.
The source field is the field that you want to convert. The
destination field is the field after it has been converted.
The
source and destination FFDs must be different fields. The FFDs are
data items that you define in your program and use when you call the
XDESCR routine. When the routine successfully finishes processing, it
returns an FFD value in the data item.
Once you have FFDs for the source and destination fields, you can use
one of the other Data Conversion Routines to convert the field. These
conversion routines require only two arguments: an FFD for the source
field and an FFD for the destination field.
If you are working on a TOPS-IO or TOPS-20 system, use one of the
following single-function conversion routines to convert the field
using FFDs.
XCVST
Use the XCVST routine if you want to convert a string field.
XCVFB
Use the XCVFB routine if you want to convert
binary field.

fixed-point

XCVFP
Use the XCVFP routine
floating-point field.

you

want

convert

Use the XCVPD routine
decimal field.

you

want

convert

Use the XCVDN routine if
numeric field.

you

want

convert

XCVPD
packed

XCVDN

2-2

display

DATA CONVERSION CONCEPTS AND CAPABILITIES

XCFBDN
Use the XCFBDN routine if you want to convert a fixed-point
binary source field to a display numeric destination field.
XCDNFB
Use the XCDNFB routine if you want to convert a display
numeric source field to a fixed-point binary destination
field.
XCPDDN
Use the XCPDDN routine if you want to convert a packed
decimal source field to a display numeric destination field.
XCDNPD
Use the XCDNPD routine if you want to convert a display
numeric source field to a packed decimal destination field.
XCPDFB
Use the XCPDFB routine if you want to convert a packed
decimal source field to a fixed-point binary destination
field.
XCFBPD
Use the XCFBPD routine if you want to convert a fixed-point
binary source field to a packed decimal destination field.
XCGEN
Use the XCGEN routine to perform any type of conversion
allowed by the DIL.
(When you link a program that calls
XCGEN with the OIL, the LINKER loads all of the conversion
routines.
When you use one of the single-function routines
described above, only the routines that convert the specific
data types are loaded.)
If you are working on a VMS system, use the DIX$BY OCR DES routine to
perform string, fixed-point binary, packed decimal~ display numeric or
floating-point conversions.
When you convert a field using an FFD, the DIL creates an FFD for the
field only once, no matter how many times you plan to convert the
field. After creating the FFDs, you only have to call the proper
sinqle-function (or DIX$BY DIX DES on VMS) routine whenever you want
to convert the field.
The -"De~ailed Description" method of data
conversion, described in the next section, processes location and
description information about the field each time you convert the
field.
If you plan to convert a field many times, your program will
run more efficiently if you convert the field using a Foreign Field
Descriptor. See Section 2.1.2, below.
Further Information:
TOPS-I0 and TOPS-20 users should read Sections 5.1, 5.2 and 5.3.2
further information.
VMS users should
information.

read

Sections

9.1,

2-3

9.2

and

9.3.1

for

further

DATA CONVERSION CONCEPTS AND CAPABILITIES
2.1.2

Conversion Using a Detailed Description

The detailed description method of data conversion allows you to
convert a field without first making a Foreign Field Descriptor for
the field.
If you are working on a TOPS-IO or TOPS-20 system, you can
use the CVGEN routine to convert a field without an FFD.
If you are
working on a VMS system, the DIX$BY DET routine converts the field
without an FFD.
CVGEN (DIX$BY DET on VMS) is a general purpose conversion routine:
it
accepts location and description arguments for both the source and
destination fields,
eliminating the need to explicitly create a
Foreign Field Descriptor.
When you call CVGEN (DIX$BY DET on VMS), you uniquely identify the
source and destination fields and supply the data type of the field to
be converted. Because you describe both the source and destination
fields in one routine, you don't have to use the single-function (or
DIX$BY DIX DES on VMS) routines to perform the actual conversion. The
CVGEN routIne itself performs the conversion.
Using the CVGEN routine to perfom data conversion is inappropriate if
you plan to perform a particular conversion more than a few times.
CVGEN calculates source and destination field locations each time it
is called by your program. If you convert a field using the CVGEN
routine eighty times during a program run, the routine must read the
same location and description arguments eighty times. Since an FFD is
created only once, it would be faster to describe the field with an
FFD.
You could then use one of the other routines to perform the
conversion.
If, on the other hand, you plan to convert the field only
once, or the program is table-driven, it may better to use the CVGEN
routine.
Further Information:
TOPS-IO and TOPS-20 users should read Section 5.3.15
about CVGEN.

for

information

VMS users should read Section 9.3.3 for information about DIX$BY DET.

2.1.3

Record Layouts and Byte Offsets

To convert a field, the conversion routine m~st know exactly where the
field resides in local memory.
It must have this information for both
the source and destination fields.
To describe the location of a field in a record to the Data Conversion
Routines, you must supply values for byte size, byte offset and bit
offset. The bit offset is always zero. The byte offset is the number
of bytes in a record that precede the field that you want to convert.
You must also know the data type of the field.
You can find these
values by checking or creating a detailed layout for the record.
See
Appendix A of this manual for a list of data type names.

2-4

DATA CONVERSION CONCEPTS AND CAPABILITIES
Since TOPS-IO/TOPS-20 systems represent data in 36 bit words and VMS
systems represent data in 8 bit bytes, the byte size, byte offset and
data type of a field will differ on the two systems. Figure 2-1 shows
a sample TOPS-IO or TOPS-20 COBOL record.
Figure 2-2 shows a very
similar record written in VMS COBOL format.
You use the same COBOL
picture clause for both records regardless of what type of system you
are using. The internal format of the record is controlled by the
system where it is used.
Both examples show the byte size, byte
offset, bit offset and data type for each field within the record.
ThE~ "(0)" shown in the Data Type column-represents the scale factor of
the field.
The scale factor is listed only for data types for which a
scale factor is valid. Note that the byte size of the fields in the
VMS record is always 8, while the byte size of the fields
in the
TOPS-IO/TOPS-20 record can vary.
The byte offset is calculated
relative to the byte size.

JOB-TICKET.
05 NAME
05 COST-CENTER
05 WD-END-DATE
05 TOTAL-HOURS
05 ACT IV-CODE
05 PL-NUM
05 DIS--NUM
05 MFG-NUM
05 HOURS
05 OP-CD

Fi4;Jure 2-1:

PIC X(30).
PIC X(5).
PIC 9 (6) •
COMP-l.
PIC XXX.
PIC XXX
PIC 9(5) COMPo
PIC 9(5) COMPo
COMP-l.
PIC X(5).

Byte
Size

Byte
Offset

Bit
Offset

6
6
6
36
6
6
36
36
36
6

0
30
35
7
48
51
9
10
11
72

0
0
0
0
0
0
0
0
0
0

JOB-TICKET.
05 NAME
05 COST-CENTER
05 WD-END-DATE
05 TOTAL-HOURS
05 ACT IV-CODE
05 PL-NUM
05 DIS-~:UM
05 MFG-NUM
05 HOURS
05 OP-CD

Figure 2-2:

Sixbit
Sixbit
Sixbit
Float-36
Sixbit
Sixbit
Sbf36(0)
Sbf36(0)
Float-36
Sixbit

TOPS-IO or TOPS-20 Record Layout
Byte
Size

Data
Type

PIC X(30}.
PIC X(5).
PIC 9(6).
COMP-l.
PIC XXX.
PIC XXX.
PIC 9(5) COMPo
PIC 9(5) COMPo
COMP-l.
PIC X(5).

VMS Record Layout

2-5

8
8
8
8
8
8
8
8
8
8

Byte
Offset

Bit
Offset

0
30
35
41
45
48
51
55
59
63

0
0
0
0
0
0
0
0
0
0

Data
Type
ASCII-8
ASCII-8
ASCII-8
F-Float
ASCII-8
ASCII-8
Sbf32(0)
Sbf32(0)
F-Float
ASCII-8

DATA CONVERSION CONCEPTS AND CAPABILITIES
Further information:
Data representation and record layout information can be found in
most recent version of the following manuals:
VAX-II COBOL Language Reference Manual
COBOL-74 Language Manual
TOPS-IO/TOPS-20 FORTRAN Language Manual
VAX-II FORTRAN Language Reference Manual

2-6

the

CHAPTER 3
TASK~TO-TASK CONCEPTS AND CAPABILITIES

CHAPTER 3 '
TASK-TO-TASK CONCEPTS AND CAPABILITIES

The Task-to-Task routines permit you to move data between programs on
different systems in a network. These routines differ from the Remote
File Access Routines because Task-to-Task allows communication between
programs whereas Remote File Access permits a program to access a file
on another system. The Task-to-Task routines are especially helpful
in a distributed data base environment, where a corporate data base
resides on a large computer, but you also have remote, satellite
systems using the data base.
A simple Task-to-Task application, for example, might be used by a
wholesale greengrocer and ;his company's central warehouse.
The
DECSYSTEM-20 at the warehouse contains information about the price and
quantity of all products on hand at the warehouse. The grocer, in his
shop, has a VAX-II connected by DECnet to the central machine at the
warehouse.
If a restauranteur walks into the store demanding 100
crates of mangoes for immediate delivery,
the shopkeeper runs a
program
on
his
VAX-II which queries a program on the main
DECSYSTEM-20:
"Do we have 100 crates of mangoes?" The program at the
warehouse sends a message to the grocer:
"OK, we have the mangoes,"
and updates its inventory to reflect the sale.
(See Figure 3-1,
at
the end of this chapter.)
The Task-to-Task Routines become even more useful if we expand this
example to include a chain of greengroceries, each connected, by
DECnet, to the central data base. A program using the Task-to-Tap::
routines
can connect with several other programs.
If anothLc
restauranteur simultaneously appears at a different grocery store
demanding 200 crates of mangoes, the owner of this store can run a
program on,his computer querying the data base:
"Do we have 200
crates of mangoes?" The program at the warehouse processes the first
request, for 100 cases.
It then reads the next request,
from
shopkeeper number two, and sends a messag~:
"Sorry, we're all sold
out." The program at the warehouse remains open, waiting for requests
from other grocers on the network.
(See Figure 3-2, at the end of
this chapter.)

3-1

TASK-TO-TASK CONCEPTS AND CAPABILITIES
The programs are able to transfer information via
a
network
connection. This connection is called a logical link. A logical link
is established with one of the four "open link" Task-to-Task Routines,
described below. Every program that uses the Task-to-Task Routines to
transfer data must establish a logical link. The program on one side
of the link is called a "passive task:" the other program is an
"active task." The passive task, also known as the server program,
waits for other programs to link to it and request its services. The
active task connects to the server program and requests its services.
A passive task can simultaneously serve many active tasks, but each
open link is between exactly two tasks:
the passive task and one
active task. A single task can, at the same time, be the active task
of one link, and the passive task of another link.
In the examples described above, the computer at the warehouse runs
the passive task.
This task always has an open link, waiting for
connections from the active tasks, run by the greengrocers. Once you
link the two programs, however,
there ceases to be any difference
between active and passive tasks. Both active and passive tasks can
send data, receive data or close the link.
These routines identify a logical link by its Network Logical Name
(NLN).
The NLN uniquely identifies the task to the routines. NLN is
set automatically by the "open link" routine when it successfully
finishes processing.
When you call any of the other Task-to-Task
routines:
to send data, check the link or disconnect the link, you
refer to the link by its Network Logical Name.
The Task-to-Task routines offer four open link routines:
•

NFOPA (DIT$NFOPA on VMS)
This routine opens an active link.
It establishes
a
connection which permits you to transfer ASCII data between
systems.

•

NFOPB (DIT$NFOPB on VMS)
This routine opens an active link.
It establishes
a
connection which permits you to transfer binary data between
systems.

•

NFOP8 (DIT$NFOP8 on VMS)
This routine opens an active link.
It establishes
a
connection which permits you to transfer data that is stored
in 8-bit bytes.

•

NFOPP (DIT$NFOPP on VMS)
This routine opens a passive link. NFOPP is always used in
combination with the NFACC (DIT$NFACC) routine. First, the
NFOPP routine opens the link. NFACC then accepts a network
connection and specifies the type of data that you plan to
move over the link.

The open link routine used by the active task requires you to pass
information on the location of the target passive task (system name,
object type and taskname of the passive task). The open link routine
used by the passive task identifies the passive link and indicates
that it is ready to accept network connections from active tasks. See
Appendix 0 for further information on task identification.
The NFACC (DIT$NFACC on VMS) routine, called from the passive
accepts the network connection requested by the active task.

3-2

task,

TASK-TO-TASK CONCEPTS AND CAPABILITIES
To che6k the status of one or more network connections, use the NFGND
(DIT$NFGND on VMS) routine. NFGND returns a value indicating the most
recent event for the link, for example, a connect request has arrived,
data is available or the link has abo~ted.
Once you have opened a link and connected the active and passive
tasks, you can use the NFSND (DIT$'NF~ND on VMS) routine to send data
and the NFRCV (DIT$NFRCV on VMS) routine to receive data.
You can
also use the NFINT (DIT$NFINT on VMS) t~ send an interrupt data
message and NFRCI (DIT$NFRCI on VMS) to recelve an interrupt data
message.
When the tasks have performed the necessary data transfer,
close the link by issuing a call to the NFCLS (DIT$NFCLS on VMS)
routine.
The task that receives the last piece of data should be the
first to close the link. When the other task notices the disconnect
(by calling NFGND) it aborts its end of the link. This method of
ending the communication between two tasks ensures that the last piece
of data is processed.
The following figures show the order of calls to the Task-to-Task
Routines that would be made by the shopkeeper(s) and the warehouse in
the sample application discussed above.
Node: SHOP
Program: Grocer
Calls to the
Task-to-Task Routines:

Node: HQTRS
Program: Warehouse
Action

NFOPA

Calls to the
Task-to-Task Routines:
NFOPP

Grocer Wants to L!rrk to
Warehouse to Transfer ASCII Data

NFSND

Warehouse Accepts
the Connection

NFACC

Grocer Sends Query:
"Do We Have Mangoes?",

NFRCV

Warehouse Sends Response:
"Yes, Mangoes Reserved For You."

NFSND

NFCLS

Grocer Closes
Active Link

.. -

Warehouse Closes
Passive Link
Active Task

NFCLS
Passive Task
(Server Program)
MH,S-254B-B3

Figure 3-1:,

Simple Task-to-Task Application

3-3

TASK-TO-TASK CONCEPTS AND CAPABILITIES
Node: HDQTRS
Program· Warehouse
CslIs:
NFOPP
NFOPP

NFOPP
NFOPP

no
walt

Node: SHOP1
Program: grocer1

Node: SHOP2
Program: grocer2
NFGND
walt

Calls:
NFOPA

Grocer1 Wants to
Link to Warehouse

If Connect, Then:
NFACC
Grocer2 Wanta to
Link to Warehouse

Warehouse Accepts
the Connection

If Abort or
Disconnect, Then:
NFCLS
NFOPP

Grocer1 Sends Query:
"Do We Have Mangoes?'

NFRCV

Warehouse Sends Response:
"Yes, We Have Mangoes."

Process and Reply
NFSND

NFCLS

Grocer1 Closes
Active Task

If Abort or
Disconnect, Then:
NFCLS
NFOPP

Warehouse Closes
Passive Task,
Releasing Link to be Used
for a New Connection

Warehouse Accepts
the Connection

Grocer2 Sends Query:
"DO we Have Mangoes?"

NFSND

Warehouse Sends Response:
"Sorry, sold Out.

NFRCV

Grocer2 Closes
Active Task

NFCLS

Warehouse Closes
Passive Task,
Releasing Link to be Used
for a New Connection

Active Task 1
Passive Task
(Server Program)

Task~to-Task

NFOPA

If Incoming Data, Then:
NFRCV

NFSND

Figure 3-2:

Calls:

Application

3-4

Active Task 2
MR-S-2S49-83

CHAPTER 4
REMOTE FILE ACCESS CONCEPTS AND CAPABILITIES

The Remote File Access (RFA) routines allow you to access and use
records that reside in an ASCII sequential file on another computer.
The RFA portion of the DIL consists of the following routines:
•

ROPEN (DIT$ROPEN on VMS)
The ROPEN routine opens an ASCII sequential file for reading,
writing or appendinn

(DIT$RREAD on VMS)
• RREAD
The RREAD routine reads a record from an ASCII

sequential

file
RWRITE (DIT$RWRITE on VMS)
• The
RWRITE routine writes a record

ASCII

sequential

file
•

RCLOSE (DIT$RCLOSE on VMS)
The RCLOSE routine closes an ASCII sequential file

•

RDEL (DIT$RDEL on. VMS)
The RDEL routine deletes a closed ASCII sequential file

•

RSUB (DIT$RSUB on VMS)
The RSUB routine submits a closed ASCII sequential file

•

RPRINT (DIT$RPRINT on VMS)
The RPRINT routine prints a closed ASCII sequential file

If you are working on a VMS system,
for example, you can access
records in a sequential ASCII file on a TOPS-20 system. Since the
file actually resides on another system, you have access to more data
than would ordinarily be available to you as a VMS user. This means
that if you have a large file on a TOPS-20 system, you can write
reports from the file on your VMS system using records that you access
with the RFA routines. When you use the RFA routines to access ASCII
records, you don't have to wovry about format translation. The RFA
routines automatically perform any necessary data conversion between
TOPS-10/TOPS-20 ASCII data and VMS ASCII data.

4-1

REMOTE FILE ACCESS CONCEPTS AND CAPABILITIES
4.1

OPENING A REMOTE FILE

The ROPEN (DIT.$ROPEN) routine opens a file on another system.
ROPEN
finds the proper system on the network and opens the correct file by
using location information that you supply in your call to the ROPEN
routine.
This location information is contained in the filename argument of the
ROPEN routine.
A valid network file name contains the following
information:
•

The node name of the system

•

The file structure or device which contains the file

•

TQe directory name

•

The file name, type and optional version number

KL2116::PS:(MORRILL)IN.DAT is an example of a valid TOPS-20 file name.
KL2116 is the node name. PS is the structure name. MORRILL is the
directory name. IN.DAT is the file name and extension.
When you call any of the other RFA routines
(to read a record, to
write a record, or to close a file) you refer to the file by its file
number, a unique value assigned by the ROPEN routine.
You define a
data item to store the file number, and use this data item as an
argument in your call to the ROPEN routine. When ROPEN successfully
finishes processing, it generates a file number value and places it in
the data item.
The RFA routines work by talking to the File Access Listener (FAL)
program on the remote system. To learn more about the FAL, see the
DECnet manual for the remote system. You cannot use the RFA routines
unless the FAL is available on the remote file's system. Before you
attempt to access records with the RFA, check with the remote system
manager to make sure that the FAL program is available and that it
supports the operation that you want to perform.

4-2

CHAPTER 5
TOP5-10 AND TOPg.;..,20 DATA CONVERSION

CHAPTER 5
TOPS-IO AND TOPS-20 DATA CONVERSION

5.1

DATA CONVERSION FROM TOPS-IO/TOPS-20 COBOL

The information included in this section assumes
- You are writing a COBOL program
- You plan to use the program on a TOPS-IO or TOPS-20 system
To store a Foreign Field Descriptor, pass a record or perform an error
check, you must represent several data items in your program. Users
generally allocate space for foreign
fields
and
records
in
WORKING-STORAGE.

5.1.1

Compiling Programs

To use the DIL Data Conversion Routines on TOPS-20 from a COBOL
program, you may need to compile your program with the /STACK compiler
switch to insure that you have an adequate pushdown list size.
If
your
program gets a stack overflow, compile the program with
/STACK:2000. TOPS-IO programmers should use the /D compiler switch.
If a TOPS-IO COBOL program gets a stack overflow, compile the program
with /D:2000.

5.1.2

Including the Interface Support Files

The Interface Support file provided for TOPS-IO and TOPS-20 COBOL is a
copy library called DIL.LIB.
You can use the COBOL COpy verb to
retrieve the information at compilation time. There are three library
elements in DIL.LIB. These elements are called DIL, DIT, and DIX.
The library element DIL defines general codes and names applicable to
the Data Conversion Routines, the Task-to-Task routines and the Remote
File Access routines. The general success status code
(DIL name
SS-NORMAL) is defined in element DIL. Severity codes and system codes
are defined in element DIL. To define these names in your program,
include the following statement in your WORKING-STORAGE section after
an Ol-level declaration:
COpy DIL OF "SYS:DIL.LIB".

5-1

TOPS-IO AND TOPS-20 DATA CONVERSION
In the following example, the DIL element of the library is
and included in your program:
01

retrieved

interface-files.
COpy DIL OF "SYS:DIL.LIB".

The library element DIX defines codes specific to the data conversion
routines.
This includes the DIX status codes as well as data type
names for each supported data type. To define these names in your
program,
include the following statement in your WORKING-STORAGE
section after an Ol-level declaration, such as that shown above for
the DIL element:
COPY DIX OF "SYS:DIL.LIB".
For programs which use the Data Conversion Routines, you must
both the DIL and DIX library elements.

5.1.3

include

Storing an FFD

An FFD occupies three full words of TOPS-IO or TOPS-20 memory.
To
store an FFD, you must define a data item with the following format:
01 your-ffd PIC S9(10) VSAGE COMPUTATIONAL OCCURS 3 TIMES.
When you call the XDESCR routine to build the FFD, use your-ffd as the
FFD to be returned.
To pass the FFD to the routine, pass your-ffd
with the subscript 1: your-ffd (1).

Passing a Record to the XDESCR Routine

5.1.4

To pass a record to the XDESCR routine, you must know how the record
(containing the field that you want to convert) would be declared on
its native system. You must then represent the record in your program
on
the
local system.
The record can be represented as any
word-aligned group level data item. To pass the record to XDESCR,
specify this group item as the record name ("rec") in the call to
XDESCR.
To figure the size of the record, count the number of bits on its
native system; make the record name on the foreign system at least
that large. In the following example, the TOPS-20 record REC contains
720 bits of information.
01

rec

PIC S9(10)

USAGE COMPUTATIONAL OCCURS 20 TIMgS.

To pass "rec" to the XDESCR routine simply include it in your call
the routine.

ENTER MACRO XDESCR USING ffd (1), rec, sysor, bysiz, byoff, bioff,
type, lngth, scale.

5-2

TOPS-10 AND TOPS-20 DATA CONVERSION

5.1.5

Checking For Errors

To check for errors in a COBOL program on TOPS-IO or TOPS-20,
should define the following data items in WORKING-STORAGE:
01
01
01
01

you

PIC S9(10) USAGE COMPUTATIONAL.
ini-stat
PIC S9(10) USAGE COMPUTATIONAL.
dil-stat
PIC S9(10) USAGE COMPUTATIONAL.
dil-msg
PIC S9(10) USAGE COMPUTATIONAL.
dil-sev
88 dil-warning
VALUE O.
88 dil-success
VALUE 1.
88 dil-error
VALUE 2.
88 dil-info
VALUE 3.
88 dil-severe
VALUE 4.
88 dil-ok
VALUES 1, 3.

You can choose your own names for the data items pictured above.
For the OIL to use these data items, you must first pass them to the
DILINI routine.
Before calling any other OIL routine, call the
initialization routine, DILINI. DILINI tells the OIL what data items
to use when it returns status information about a call to one of the
other routines. Call the DILINI routine using the following format:
ENTER MACRO DILINI USING ini-stat, dil-stat, dil-sev,
dil-msg.
The routine returns a value in ini-stat. If successful, the return
value is 1. Any other value indicates either an error in the call to
DILINI, or incorrect definition of dil-stat, dil-severity or dil-msg.
If you plan to use the OIL from a COBOL subroutine, you must also pass
the status data items to the subroutine:
otherwise the subroutine
cannot check for errors.
You only make this call to DILINI once in your program.
All other
calls to the conversion routines return their status codes in
dil-stat. The severity portion of the status code is placed in
dil-severity.
A unique identifier for the condition is placed in
dil-msg.
A call to the Conversion Routines with
might look like this:

simple

check

for

succeoJs

ENTER MACRO XDESCR USING ffd (1), rec, sysor, bysiz, byoff,
bioff, type, lngth, scale.
IF NOT dil-ok
DISPLAY "error status returned from XDESCR".
A call to the same routine with provisions
type of error might look like this:

for

handling

specific

ENTER MACRO XDESCR USING ffd (1), rec, sysor, bysiz, byoff,
bioff, type, lngth, scale.
IF NOT dil-ok
IF dil-msg = DIX-C-INVDATTYP
DISPLAY "invalid data type specified"
ELSE
DISPLAY "other error".

5-3

TOPS-IO AND TOPS-20 DATA CONVERSION
To determine which error occurred, compare dil-msg with the DIX
condition identifiers defined in the TOPS-IO/TOPS-20 COBOL Interface
Support fi~e. In the example above, DIX-C-INVDATTYP is the value
(defined ln the Interface Support file) indicating an invalid data
type was specified.

5.2

DATA CONVERSION FROM TOPS-IO/TOPS-20 FORTRAN

The information included in this section assumes
- You are writing a FORTRAN program
- You plan to use, the program on a TOPS-IO or TOPS-20 system
The section explains methods to store a Foreign Field Descriptor, pass
a record to the conversion routines and perform an error check.

5.2.1

Including the Interface Support Files

The Interface Support files provided for TOPS-IO and TOPS-20 FORTRAN
are text files called DILV7.FOR, DITV7.FOR and DIXV7.FOR.
The
information from these files may be included into your source programs
at compilati.on time using the FORTRAN INCLUDE statement.
The file DILV7 defines general codes and names applicable to the Data
Conversion Routines,
the Task-to-Task Routines and the Remote File
Access Routines. The general success status code (DIL name SS-NORMAL)
is defined in DILV7. Severity code~ and system codes are defined in
DILV7. To define these names in your program, include the following
statement in your program:
INCLUDE: 'SYS: DILV7 '
The file DIXV7 defines codes specific to the Data Conversion Routines.
These codes: include the DIX status codes and data type names for each
supported data type. To define these names in your program,
include
the following statement in your program:
INCLUDE 'SYS:DIXV7'
For programs which use the Data Conversion Routines, you must
both the DILV7 and DIXV7 files.

5.2.2

include

Stori.ng an FFD

An FFD occupies three full words of TOPS-IO or, TOPS-20 memory.
To
store an FFD, you must first dimension an array of type integer with
length 3.
INTEGER

dilffd (3)

When you call the XDESCR routine to build an FFD, use dilffd as the
FFD to be returned.
To pass this value to the routine, pass the
entire array as dilffd, not as dilffd (1).

5-4

TOPS-IO.AND TOPS-20 DATA·CONVERSION
5.2.3

Passing a Record to the XDESCR Routine

To convert a field in a record, you must know how the record would be
declared on its native system. You must then declare the record in
your program on the local system. You create a space for the record
on the foreign system by declaring an integer array big enough to
contain the record. To figure the array size, count the number of
bits used by the record on its native system1make the array on the
foreign system at least that large. In the following example, the
DECSYSTEM-20 record contains 720 bits of information.
INTEGER

rec

(20)

To pass the record to one of the Data Conversion Routines, pass the
entire array.
The following example shows "rec" being passed to the
XDESCR routine:
status = XDESCR (ffd, rec, sysor, bysiz, byoff,bioff, type,
I
lngth, scale)

5-5

TOPS-IO AND TOPS-20DATA CONVERSION
5.2.4

Checking For Errors

Each Data Conversion Routine returns a one-word integer status value
when it finishes processing.
To perform an error check on a Data
Conversion Routine, first declare an integer where the routine can
place the status value.
INTEGER

status

A simple call with an error check might then be:
status = XDESCR (ffd, rec, sysor, bysiz, byoff, bioff, type,
1
lngth, scale)
IF «status.AND.l).EQ.O) GO TO 20

20 WRITE (5,10)
10 FORMAT ('error')
A call to the same routine with provlslons
type of error might look like this:

for

handling

specific

status = XDESCR (ffd, rec, sysor, bysiz, byoff, bioff, dattyp,
1
Ingth, scale)
IF (status.AND.l) GO TO 30
IF (status.EQ.DATTYP) GO TO 20
other error

20 WRITE (5,10)
10 FORMAT ('invalid data type specified')

30 •
C

Success

To determine which error occurred, compare "status" to the DIX status
codes defined in the TOPS-IO/TOPS-20 FORTRAN Interface Support file.
In the example above, DATTYP is the value
(defined in the DIX
Interface Support file)
indicating that an invalid data type was
specified.

5-6

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3

TOPS-10/TOPS-20 DATA CONVERSION REFERENCE

5.3.1

DILINI - Allow the DIL to Recognize Status Codes

PURPOSE:
The OILINI routine allows status code data items in a TOPS-IO or
TOPS-20 COBOL program to be recognized by the OIL. You do not
need to use the OILINI routine if you plan to write a FORTRAN
program.
You only call the OILINI routine once in your program, before you
call any of the other OIL subroutines.
CALL FORMAT:
COBOL:

ENTER MACRO OILINI USING ini-stat, dil-stat, dil-msg,
dil-sev.

where:
ini-stat

is where the routine returns the results of the call to
the OILINI routine.
A return value of I indicates
success. Any other value indicates an incorrect call
or an incorrect definition of dil-stat, dil-msg or
dil-sev.

dil-stat

is a one-word integer that contains the status code for
a call to any other OIL- routine.

dil-msg

is a one-word integer that contains the
for a call to any other OIL routine.

error

message

dil-sev

is a one-word integer that
portion of a OIL status code.

the

severity

5-7

contains

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.2

XDESCR - To Create an FFD

PURPOSE:
The XDESCR routine accepts the detailed description information
which you supply and builds a Foreign Field Descriptor for a
native or foreign field.
CALL FORMAT:
COBOL:

ENTER MACRO XDESCRUSING ffd (1), rec, sysor, bysiz,
byoff, bioff, type, Ingth, scale.

FORTRAN: status = XDESCR (ffd, rec, sysor, bysiz, byoff, bioff,
1
type, Ingth, scale)
where:
ffd

is the Foreign Field Descriptor (FFD) to be returned.
The argument represents the data item where the routine
places the resultant FFD. An FFD consists of three
one-word integers.

rec

is the record that contains the field to be described.

sysor

COBOL:

This argument can be
item.

any

word-aligned

data

FORTRAN:

This argument is usually an integer array.

is a one-word integer showing the system of orlgln of
the record to be converted. Possible DIL Names for
this argument are:
SYS-IO-20

for a record
TOPS-20.

SYS-VAX

for a record defined for VMS.

defined

for

TOPS-IO

bysiz

is a one-word integer giving the byte size of the field
to be described. All VMS fields have a byte size of 8.
A TOPS-IO or TOPS-20 COBOL field can have a byte size
of 6,
7, 9 or 36. A TOPS-IO or TOPS-20 FORTRAN field
can have a byte size of 7 or 36. See Appendix A for
further information.

byoff

is a one-word integer that gives the byte offset to the
field within the record. The byte offset is the number
of bytes in the record (of byte size specified in
"bysiz") that precede the field that you want to
convert.

bioff

is a one-word integer that gives the bit offset.
This
argument is not currently used; it should always be
zero.

type

is a one-word integer that gives the data type of the
field that is being converted. See Appendix A for a
list of valid data type codes.

5-8

TOPS-IO AND TOPS-20 DATA CONVERSION

1ngth

is a one-word integer that shows the length of the
field:
in characters for string fields.
This argument
is required for some data types; it must be zero for
all other data types.
See Appendix A for further
information.

scale

is a one-word integer that gives the scale factor of
the field.
Scale factor indicates the number of
decimal digits to move the decimal point to the left.
A negative scale factor means that the decimal point
will be moved to the right. You must specify a scale
factor if you want to convert a fixed-point field.
Specify a scale factor of zero for any other type of
field.

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-INVBYTSIZ

Invalid byte size specified.

DIX-ALIGN

Invalid alignment for data type.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.

5-9

TOPS-IO AND TOPS-20 DATA CONVERSION
XCGEN - To Perform General Purpose Conversion

5.3.3

PURPOSE:
The XCGEN routine performs any type of data conversion
be done by the OIL.

that

can

XCGEN is a general purpose routine. XCGEN accepts Foreign Field
Descriptors for the source and destination fields and decides if
it can perform that conversion. If the specified conversion is
allowable, XCGEN converts the field.
NOTE
When you link a program that calls XCGEN with the DIL,
this causes all of the conversion routines to be
loaded.
If you use one of the single function
conversion routines (like XCVST), only the routines
which perform the specified conversion are loaded.
CALL FORMAT:
COBOL:

ENTER MACRO XCGEN USING sffd (1), dffd (1).

FORTRAN: status

= XCGEN (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the di1-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.

5-10

TOPS-IO AND TOPS-20 DATA CONVERSION

DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX~INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-INVALCHAR

Invalid character in source field or
conversion table.

DIX-GRAPHIC

Graphic charayter changed in conversion.

DIX-FMTLOST

Format effector gained or lost in
conversion.

DIX-NONPRINT

Non-printing character gained or lost
in conversion.

DIX-TRUNC

String too long for destination -truncated.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

DIX-ROUNDED

Result is rounded.

DIX-UNNORM

Floating-point number improperly
normalized.

DIX-INVDNUMCHR

Invalid display numeric character in
source field.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid ,packed decimal sign in
source field.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

5-11

TOPS-lO AND TOPS-20 DATA CONVERSION

XCVST - Convert String Fields

5.3.4

PURPOSE:
The XCVST routine converts string fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCVST USING sffd (1), dffd (1).

FORTRAN: status

= XCVST (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
DIL routines return status codes as an integer function value.
DIL Name

Meaning

DIX-INVALCHAR

Invalid character in source field or
conversion table.

DIX-GRAPHIC

Graphic character changed in conversion.

DIX-FMTLOST

Format effector gained or lost in
conversion.

DIX-NONPRINT

Non-printing character gained or lost
in conversion.

DIX-TRUNC

String too long for destination
truncated.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
converSlon allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-12

TOPS-lO AND TOPS-20 DATA CONVERSION

5.3.5

XCVFB - Convert Fixed-Point Binary Fields

PURPOSE
The XCVFB routine converts fixed-point binary fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCVFB USING sffd (1), dffd (1).

FORTRAN: status

= XCVFB (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

DIX-ROUNDED

Result is rounded.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
conversion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-13

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.6

XCVFP - Convert Floating-Point Fields

PURPOSE:
The XCVFP routine converts floating-point fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCVFP USING sffd (1), dffd (1).

FORTRAN: status

= XCVFP tsffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:,

---

For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
Meaning

DIL Name
DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-UNNORM

Floating-point number improperly
normalized.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
conversion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-14

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.7

XCVPD - Convert Packed Decimal Fields

PURPOSE:
The XCVPD routine converts packed decimal fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCVPD USING sffd (1), dffd (1).

FORTRAN:

status

= XCVPD (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routines.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

5-15

TOPS-IO AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
conversion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-16

TOPS-10 AND TOPS-20 DATA CONVERSION
5.3.8

XCVDN - Convert Display Numeric Fields

PURPOSE:
The XCVDN routine converts display numeric fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCVDN USING sffd (1), dffd (1).

FORTRAN:

status

= XCVDN (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

DIL Name
DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVDNUMCHR

Invalid display numeric character in
source field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

5-17

TOPS-10 AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
conversion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-18

TOPS-IO AND TOPS-20 DATA CONVERSION

5.3.9

XCFBDN - Convert Fixed-Point Binary Fields to
Fields

Display

Numeric

The XCFBDN routine converts Fixed-Point Binary fields to
Numeric Fields.

Display

PURPOSE:

CALL FORMAT:
COBOL:

ENTER MACRO XCFBDN USING sffd (1), dffd (1).

FORTRAN:

status

= XCFBDN (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:

---

For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid argument for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-UNSIGNED

Negative value moved to unsigned
field.

5-19

TOPS-lO AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This ge~eral purpose routine performs any type of
converSlon allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-20

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.10

XCFBPD - Convert Fixed-Point Binary Fields to
Fields

Packed

Decimal

PURPOSE:
The XCFBPD routine converts Fixed-Point Binary fields
Decimal Fields.

Packed

CALL FORMAT:
COBOL:

ENTER MACRO XCFBPD USING sffd (1), dffd (1).

FORTRAN:

status = XCFBPD (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
conversion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-21

TOPS-10 AND TOPS-20 DATA CONVERSION
5.3.11

Display

XCPDDN - Convert Packed
Fields

Decimal

Fields

The XCPDDN routine converts
Numeric Fields.

Packed

Decimal

fields

Numeric

PURPOSE:
to

Display

CALL FORMAT:
COBOL:

ENTER MACRO XCPDDN USING sffd (1), dffd (1).

FORTRAN:

status = XCPDDN (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

5-22

TOPS-.10ARD TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
converSlon allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-23

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.12

XCPDFB - Convert Packed Decimal Fields to
Fields

Fixed-Point

Binary

PURPOSE:
The XCPDFB routine converts Packed Decimal fields to IFixed-Point
Binary Fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCPDFB USING sffd (1), dffd (1).

FORTRAN:

status = XCPDFB (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

5-24

TOPS-IO AND TOPS-20 DATA CONVERSION
RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGEN:

This general purpose routine performs any type of
converSlon allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-25

TOPS-10 AND TOPS-20 DATA CONVERSION
5.3.13

XCDNPD - Convert Display
Fields

Numeric

Fields

Packed

The XCDNPD routine converts
Decimal Fields.

Display

Numeric

fields

Decimal

PURPOSE:
to

Packed

CALL FORMAT:
COBOL:

ENTER MACRO XCDNPD USING sffd (1), dffd (1).

FORTRAN:

status

= XCDNPD (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptor
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVDNUMCHR

Invalid display numeric character in
source field.

5-26

TOPS-IO AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field. See
Section 5.3.15 for a description of CVGEN.
This general purpose routine performs any type of
converSion allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-27

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.14

XCDNFB - Convert Display Numeric Fields to Fixed-Point
Fields

Binary

PURPOSE:
The XCDNFB routine converts Display Numeric fields to Fixed-Point
Binary Fields.
CALL FORMAT:
COBOL:

ENTER MACRO XCDNFB USING sffd (1), dffd (1).

FORTRAN:

status

= XCDNFB (sffd, dffd)

where:
sffd

is a Foreign Field Descriptor describing the source
field.
This argument consists of three one-word
integers.

dffd

is a
Foreign
Field
Descriptot
destination field.
This argument
one-word integers.

describing
the
consists of three

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-ROUNDED

Result is rounded.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVDNUMCHR

Invalid display numeric character in
source field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

5-28

TOPS-IO AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
CVGEN:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See
Section 5.3.15 for a description of CVGEN.

XCGENJ

This general purpose routine performs any type of
converSlon allowed by the Data Conversion Routines.
See Section 5.3.3 for a description of XCGEN.

5-29

TOPS-IO AND TOPS-20 DATA CONVERSION
5.3.15

CVGEN - Perform Conversion Without an FFD

PURPOSE:
The CVGEN routine allows you to convert a field without making an
FFD
for the field.
CVGEN requires a detailed series of
arguments; you must specify parameters for both the source and
destination fields.
You should only use CVGEl~ in cases where the field will be
converted
a
limited
number of times or the program is
table-driven. CVGEN creates a description for the field each
time it processes the field.
If you plan to convert a field many
times during a run, it is quicker to create an FFD for the field
and convert it with one of the other single function conversion
routines. Whereas CVGEN creates an FFD internally each time it
processes, if you perform the conversion with an FFD (built using
the XDESCR routine) you make an FFD only once.
CALL FORMAT:
COBOL:

ENTER MACRO CVGEN USING srec, ssysor, sbysiz, sbyoff,
sbioff, stype, slngth, sscale, drec, dsysor,
dbysiz, dbyoff, dbioff, dtype, dlngth, dscale.

FORTRAN:

status = CVGEN (srec, ssysor, sbysiz, sbyoff, sbioff,
1
stype, slngth, sscale, drec, dsysor, dbysiz,
2
dbyoff, dbioff, dtype, dlngth, dscale)

where:
srec

ssysor

is the source record that
described.

contains

the

field

COBOL:

This field can be any word-aligned data item.

FORTRAN:

This argument
array.

will

usually

integer

is a one-word integer giving the system of origin of
the
source record.
Possible DIL Names for this
argument are:
SYS-lO-20

for a record
TOPS-20.

defined

for

SYS-VAX

for a record defined for VMS.

TOPS-IO

sbysiz

is a one-word integer gIvIng the byte size of the
source field to be described. All VMS fields have a
byte size of 8. A TOPS-IO or TOPS-20 COBOL field can
have a byte size or 6,
7,
9 or 36. A TOPS-IO or
TOPS-20 FORTRAN field can have a byte size of 7 or 36.
See Appendix A for further information.

sbyoff

is a one-word integer giving the byte offset to the
field within the source record. The byte offset is the
number of bytes in the source record (of byte size
specified in "sbysiz") that precede the field that you
want to convert.

5-30

TOPS-IO AND TOPS-20 DATA CONVERSION

sbioff

is a one-word integer giving the bit offset.
This
argument is not currently necessary~ it should be zero.

stype

is a one-word integer giving the data type of the
source field. See Appendix A for a list of valid data
type codes.

slngth

is a one-word integer giving the length of the source
field:
in characters for string fields. This argument
is required for some data types~ it must be zero for
all other data types.
See Appendix A for further
information.

sscale

is a one-word integer giving the scale factor of the
source field.
It indicates the number of decimal
digits to move the decimal point to the left.
A
negative scale factor means that the decimal point will
be moved to the right. You must specify a scale factor
if you want to convert a fixed-point field. Specify a
scale factor of zero for any other type of field.

drec

is the destination record which contains the
be described.

dsysor

COBOL:

This argument can be
item.

any

FORTRAN:

This argument
array.

usually

will

field

word-aligned
be

to
data

integer

is a one-word integer showing the system of origin of
the destination record.
Possible DIL Names for this
argument are:
SYS-10-20

for a record defined TOPS-10 or TOPS-20.

SYS-VAX

for a record defined for VMS.

dbysiz

is a one-word integer giving the byte size of the
destination field to be described. All VMS fields have
a byte size of 8. A TOPS-10 or TOPS-20 COBOL field can
have a byte Size of 6,
7,
9 or 36. A TOPS-10 or
TOPS-20 FORTRAN field can have a byte size of 7 or 36.
See Appendix A for furth~r information.

dbyoff

is a one-word integer giving the byte offset of the
destination record.
The byte offset is the number of
bytes in the record
(of byte size specified
in
"dbysiz") that precede the field that you want to
convert.

dbioff

is a one-word integer that shows the bit offset.
This
argument is not currently used~ it is always zero.

dtype

is a one-word integer giving the data type of the
destination field.
See Appendix A for a list of valid
data type codes.

5-31

TOPS-IO AND TOPS-20 DATA CONVERSION

dlngth

is a one-word integer giving the length of
the
destination field:
in characters for string fields.
This argument is required for some data types, it must
be zero for all other data types. See Appendix A for
further information.

dscale

is a one-word integer giving the scale factor of the
destination field.
It indicates t.he number of decimal
digits to move the decimal point to the left.
A
negative scale factor means that the decimal point will
be moved to the right. Yqu must specify a scale factor
if you want to convert a fixed-point field. Specify a
scale factor of zero for any other type of field.

5-32

TOPS-10 AND TOPS-20 DATA CONVERSION
STATUS CODES:

---

For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function
value.

DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-INVBYSIZ

Invalid byte size specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-INVALCHAR

Invalid character in source field or
conversion table.

DIX-GRAPHIC

Graphic character changed in conversion.

DIX-FMTLOST

Format effector gained or lost in
conversion.

DIX-NONPRINT

Non-printing character gained or lost
in conversion.

DIX-TRUNC

String too long for destination -truncated.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

DIX-ROUNDED

Result is rounded.

DIX-UNNORM

Floating-point number improperly
normalized.

DIX-INVDNUMCHR

Invalid display numeric character in
source field.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

5-33

TOPS-IO AND TOPS-20 DATA CONVERSION

RELATED ROUTINES:
XDESCR:

This routine builds a Foreign Field Descriptor for the
field you wish to convert. See Section 5.3.2 for a
description of XDESCR.

5-34

TOPS-10 AND TOPS-20 DATA CONVERSION
5.4

TOPS-10/TOPS-20 DATA CONVERSION EXAMPLES

5.4.1

TOPS-IO/TOPS-20 COBOL Data Conversion Example

IDENTIFICATION DIVISION.
PROGRAM-ID.
CDCR36.
This program performs a single string data conversion.
ASCII-7 string value "ABCDE" will be converted to the
ASCII-8 value.

The
same

ENVIRONMENT DIVISION.

DATA DIVISION.
WORKING-STORAGE SECTION.

* source data field
01 SRCDAT PIC X(5) USAGE DISPLAY-7 VALUE "ABCDE".

* The destination data field must be large enough to hold the ASCII-8
* equivalent of the source data field:
* ASCII-7 PIC X(5) = 7 bits/character * 5 characters 35 bits
* ASCII-8 PIC X(5) = 8 bits/character * 5 characters 40 bits
01

DSTDAT PIC S9(10) COMP OCCURS 2.

* The value of the destination data, when considered as a numeric
* pattern, contains a large number (22620095041) which is

* acceptable to COBOL. Therefore we will
* for the destination data fields:

use the SIXBIT

bit
not
equivalents

SIXBIT-EQUIVALENTS REDEFINES DSTDAT.
05 SIXBIT-EQUIVl PIC X(6) USAGE DISPLAY-6.
05 SIXBIT-EQUIV2 PIC X(6) USAGE DISPLAY-6.

EXPECTED-VALUES.
05 EXPECTED-VALl PIC X(6) USAGE DISPLAY-6 VALUE 15$OT)!".
05 EXPECTED-VAL2 PIC X(6) USAGE DISPLAY-6 VALUE II
$".

5-35

TOPS-IO AND TOPS-20 DATA CORVERSION

* foreign field descriptors
01

FFDS.
05 SRCFFD PIC S9(10) COMP OCCURS 3.
05 DSTFFD PIC S9(10) COMP OCCURS 3.

INTERFACE-FILES.
COpy DIL OF "SYS:DIL.LIB".
COPY OIX OF "SYS:DIL.LIB".

DILINI-PARAMS.
05 OIL-INIT-STATUS PIC S9(10) COMPo
05 OIL-STATUS PIC S9(10) COMPo
05 OIL-MESSAGE PIC S9(10) COMPo
05 OIL-SEVERITY PIC S9(10) COMPo

PROCEDURE DIVISION.
INITIALIZE-STUFF.

* Set up for status code values, using OILINI routine
ENTER MACRO OILINI USING OIL-INIT-STATUS, OIL-STATUS,
OIL-MESSAGE, OIL-SEVERITY.
IF OIL-INIT-STATUS NOT = 1
DISPLAY"? Failure in OILINI. Oil-status

= " OIL-STATUS.

* initialize destination data field to zeros
MOVE
MOVE

OSTOAT(l).
°° TOTO OSTOAT(2).

MAKE-FFOS.
* make the foreign field descriptors for use by XCVST
ENTER MACRO XOESCR USING SRCFFO(1) , SRCDAT, OIX-SYS-10-20, 7,0, 0,
OIX-OT-ASCII-7, 5, O.
IF OIL-SEVERITY NOT = STS-K-SUCCESS AND
OIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? Failure in XOESCR. Oil-Status = " OIL-STATUS
STOP RUN.
ENTER MACRO XOESCR USING OSTFFO(l), OSTOAT(1), DIX-SYS-VAX, 8, 0, 0,
OIX-OT-ASCII-8, 5, 0.
IF OIL-SEVERITY NOT = STS-K-SUCCESS AND
OIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? Failure in XOESCR. Oil-status
STOP RUN.

" OIL-STATUS

DO-CONVERSION.
* Convert ASCII-7 value "ABCOE" to ASCII-8 value "ABCOE".
ENTER MACRO XCVST USING SRCFFO(1) , OSTFFO(l).
IF OIL-SEVERITY NOT = STS-K-SUCCESS AND
OIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? Failure in XCVST. Oil-status
STOP RUN.

5-36

" OIL-STATUS

TOPS-IO AND TOPS-20 DATA CONVERSION
CHECK-RESULTS.
* What should have been created is the VAX ASCII-a form of the source
* value "ABCDE".

** In VAX memory, this is represented as follows:
*
*
numeric (binary) representation:
symbolic representation:
*
1010000011 :m
IAAAAAAAAI :m
*
I BBBBBBBB I : m+1
1010000101 :m+1
*
1010000111 :m+2
I CCCCCCCC I : m+2
*
1010001001 :m+3
I DDDDDDDD I :m+3
*
1010001011 :m+4
I EEEEEEEE I : m+4
*
** Transposing this into DEC-20 memory we have:
*

*
symbolic representation:
* IEEEEDDDDDDDDCCCCCCCCBBBBBBBBAAAAAAAAI n
* I
EEEE I
n+1
*
*
numeric (binary) representation:
* 10101010001000100001101000010010000011 n
* I

01001 n+1

** in octal this is:
and in decimal:
** 12504206411011 n
I 22620095041 I :n
I
4
I :n+1
* 10000000000041 n+1
*
* Since this large number (22620095041) is not acceptable to COBOL, we will
* use the SIXBIT equivalents for the destination data fields:
*
5$OT) I
:n
*
$
: n+l
* IF SIXBIT-EQUIV1 NOT EQUAL EXPECTED-VALl
DISPLAY "1 Error in conversion:
"
DISPLAY " expected converted value not returned from conversion"
STOP RUN.
IF SIXBIT-EQUIV2 NOT EQUAL EXPECTED-VAL2
DISPLAY "1 Error in conversion:
DISPLAY " expected converted value not returned from conversion"
STOP RUN.
DISPLAY" CDCR36 successfully completed.".
STOP RUN.

5-37

TOPS-IO AND TOPS-20 DATA CONVERSION
5.4.2

TOPS-IO/TOPS-20 FORTRAN Data Conversion Example

C FDCR36
C
C

This program performs a single string data conversion.
ASCII-7 string value "ABCDE" will be converted to the
ASCII-8 value.

The
same

C Include interface files
INCLUDE 'SYS:DIXV7'
INCLUDE 'SYS:DILV7'
C Source and destination data fields.
C NOTE: The destination data field must be large enough to hold the
C ASCII-8 equivalent of the source data field:
C
ASCII-7 (5 chars) = 7 bits/character * 5 characters
35 bits
C
ASCII-8 (5 chars) = 8 bits/character * 5 characters
40 bits
INTEGER SRCDAT (1), DSTDAT (2)
C Foreign field descriptors (ffds)
INTEGER SRCFFD (3), DSTFFD (3)
C Status return code
INTEGER DILSTS
C Data for source and destination data fields
DATA SRCDAT /'ABCDE'/
DATA DSTDAT /0, 0/
C make the foreign field descriptors for use by XCVST
DILSTS = XDESCR (SRCFFD, SRCDAT, SYS36, 7, 0, 0, ASCII7, 5, 0)
IF (DILSTS.NE.NORMAL) GOTO 100
DILSTS = XDESCR (DSTFFD, DSTDAT, SYSVAX, 8, 0, 0, ASCII8, 5, 0)
IF (DILSTS.NE.NORMAL) GOTO 100
C Do conversions:

convert ASCII-7 value "ABCDE" to ASCII-8 value "ABCDE"

DILSTS = XCVST (SRCFFD, DSTFFD)
IF (DILSTS.NE.NORMAL) GOTO 102
C Check results:
C What should have been created is the VAX ASCII-8 form of the source
C value "ABCDE".
C
C In VAX memory, this is represented as follows:
C
C

C
C

C
C
C

symbolic representation:
AAAAAAAA : m
BBBBBBBB :m+1
CCCCCCCC :m+2
DDDDDDDD :m+3
EEEEEEEE :m+4

numeric (binary) representation:
01000001
:m
01000010 :m+1
01000011
:m+2
01000100 :m+3
01000101
:m+4

5-38

TOPS-IO AND TOPS-20 DATA CONVERSION

C Transposing this into DEC-20 memory we have:
C
C
C
C
C
C
C
C
C
C
C
C

symbolic representation:
EEEEDDDDDDDDCCCCCCCCBBBBBBBBAAAAAAAAI
. . EEEE

n+l

numeric (binary) representation:
0101010001000100001101000010010000011 n
0100 n+l
1
in octal this is:

and in decimal:

250420641101/ n
n+l

I 226200495041 I :n:n+l

C \ 000000000004
C

200

IF (DSTDAT (1) .NEQ. 22620095041) GOTO 104
IF (DSTDAT (2) .NEQ. 4) GOTO 104
FORMAT (' FDCR36 successfully completed.')
WRITE (5, 200)
STOP

C Print error information
100
WRITE (5, 101) DILSTS
101
FORMAT ('1 Failure in XDESCR.
STOP

Dil-status

110)

Dil-status

110)

102
103

WRITE (5, 103) DILSTS
FORMAT ('1 Failure in XCVST.
STOP

104
105

WRITE (5, 105)
FORMAT ('1 Error in conversion:')
WR I TE (5, 106)
FORMAT (' expected converted value not retured from conversion')
STOP

106

END

5-39

CHAPTER 6
TOPS-20 AND TOPS-10 TASK-TO-TASK

CHAPTER 6
TOPS-20 AND TOPS-IO TASK-TO-TASK

6.1

TASK-TO-TASK FROM TOPS-20 OR TOPS-IO COBOL

The information included in this section assumes
-You are writing a COBOL program
-You plan to use the program on a TOPS-20 or TOPS-IO system
To store a Network Logical Name (NLN), task characteristics or user
attributes, to send data or to perform a status check you must
represent several data items in your program.
Users generally
allocate space for these data items in WORKING-STORAGE.

6.1.1

Compiling Programs

To use the DIL Data Conversion Routines on TOPS-20 from a COBOL
program, you may need to compile your program with the /STACK compiler
switch to insure that you have an adequate pushdown list size.
If
your
program gets a stack overflow, compile the program with
/STACK:2000. On TOPS-IO, you may need to compile your COBOL program
with the /D compiler switch.
If your program gets a stack overflow,
compile it with /D:2000.

6.1.2

Including the Interface Support Files

The Interface Support file provided for TOPS-IO and TOPS-20 COBOL is a
copy library called DIL.LIB.
The COBOL COpy verb can be used to
retrieve the information in the library at compilation time.
There
are three library elements in DIL.LIB. The elements are DIL, DIT, and
DIX.
The library element DIL defines general codes and names applicable to
the Data Conversion Routines, the Task-to-Task routines and the Remote
File Access Routines. The general success status code (SS-NORMAL)
is
defined in element DIL. Severity codes and system codes are defined
in element DIL. To define these names in your program,
include the
following statement in your WORKING-STORAGE section after an Ol-level
declaration:
COpy DIL OF "SYS:DIL.LIB".

6-1

TOPS-20 AND TOPS-lO TASK-TO-TASK
In the following example, the OIL element of the library is
and included in your program:
01

retrieved

interface-files.
COPY OIL OF "SYS:OIL.LIB".

The library element OIT defines codes specific to the Task-to-Task and
Remote File Access Routines. These codes include the OIT condition
values Task-to-Task wait codes, Task-to-Task link types, Task-to-Task
message modes and VMS task fire-up codes. To define these names in
your program, include the following statement in your WORKING-STORAGE
section after an 01-level declaration, such as that shown above for
the OIL element:
COPY OIT OF "SYS:OIL.LIB".
For programs which use the Task-to-Task
both the OIL and OIT library elements.

6.1.3

routines,

you

must

include

Storing a Network Logical Name (NLN)

The NLN consists of one word of TOPS-10/TOPS-20 memory. To
NLN, you must define a data item with the following format:
01 your-nln PIC

store

S9(10) USAGE COMPUTATIONAL.

When you call the NFOPA, NFOPB, NFOP8 or NFOPP routine to create the
NLN, use your-nln as the NLN to be returned. When the routine
successfully finishes processing, it returns a value to your-nln.

6.1.4

Storing Task and User Attributes

To include task and user attributes in a call to NFOPA, NFOPB or NFOP8
or task attributes in a call to NFOPP you must describe these
attributes as data items in WORKING-STORAGE.
Task attributes are always OISPLAY-7 fields;
they always have the
picture clause PIC X(16). The format for the task attributes is as
follows:
01
01
01
01

target-name
object-type
desc-name
task-name

PIC X(16)
PIC X(16)
PIC X(16)
PIC X(16)

OISPLAY-7.
OISPLAY-7.
OISPLAY-7.
OISPLAY-7.

User attributes are always OISPLAY-7 fields;
they always have the
picture clause PIC X(39). The format for the user attributes is as
follows:
01
01
01

userid
passwd
acct

PIC X(39) OISPLAY-7.
PIC X(39) OISPLAY-7.
PIC X(39) OISPLAY-7.

6-2

TOPS-20 AND TOPS-10 TASK-TO-TASK
6.1.5

Checking the Status of a Task-to-Task Routine

Section 5.1.5 of this manual presents a method for checking the status
of any TOPS-10/TOPS-20 COBOL DIL Routine. Section 5.3.1 describes the
DILINI initialization routine.
A call to the Task-to-Task Routines with a simple
might look like this:

check

for

success

ENTER MACRO NFOPA USING nln, trgsys, objtyp, desc, tsknam,
userid, passwd, acct, usdat, wait.
IF NOT dil-ok
DISPLAY "fatal error".
A call to the same routine with prOV1Slons
type of error might look like this:

for

handling

specific

ENTER MACRO NFOPA USING nln, trgsys, objtyp,
desc, tsknam, userid, passwd, acct, usdat,
wait
IF NOT dil-ok
IF dil-msg = DIT-C-INVARG
DISPLAY "invalid data type error".
ELSE
DISPLAY "other error".
To determine which error occurred, compare dil-msg to the DIT
condition identifier defined in the TOPS-10/TOPS-20 COBOL Interface
Support files.
In the example above, DIT-C-INVARG is the value
(defined in the Interface Support file) indicating an invalid argument
was specified.

6.1.6

The TOPS-10 Software Interrupt System

The DIL task-to-task and remote file access routines need the services
of the TOPS-10 software interrupt system (PSI). Because the FORTRAN
and COBOL runtime systems do not provide a facility to share the use
of the software interrupt system between non-cooperating routines in
the same program, the user cannot use the software interrupt system in
a COBOL or FORTRAN program that uses the task-to-task or remote file
access routines.

6.2

TASK-TO-TASK FROM TOPS-20 AND TOPS-IO FORTRAN

The information included in this section assumes
-You are writing a FORTRAN program
-You plan to use the program on a TOPS-20 or TOPS-IO system
This section explains how
characteristics or user
status check.

to store a Network
attributes, to send

6-3

Logical Name, task
data or to perform a

TOPS-20 AND TOPS-lO TASK-TO-TASK
6.2.1

Including the Interface Support Files

The Interface Support files provided for TOPS-IO and TOPS-20 FORTRAN
are text files called DILV7.FOR, DITV7.FOR and DIXV7.FOR.
You can
include the information from these files into your source programs at
compilation time using the FORTRAN INCLUDE statement.
The file DILV7 defines general codes and names applicable to the Data
Conversion Routines,
the Task-to-Task Routines and the Remote File
Access Routines. The general success status code
(55-NORMAL)
is
defined in DILV7.
Severity codes and system codes are defined in
DILV7. To define these names in your program, include the following
statement in your program:
INCLUDE 'SYS:DILV7'
The file DITV7 defines codes specific to the Task-to-Task and Remote
File Access Routines.
These codes include the DIT status codes,
Task-to-Task wait codes, Task-to-Task link types, Task-to-Task message
modes and VMS task fire-up codes.
To define these names in your
program, include the following statement:
INCLUDE 'SYS:DITV7'
For programs which use the Task-to-Task
both the DILV7 and DITV7 files.

6.2.2

routines,

you

must

include

Storing a Network Logical Name (NLN)

The NLN consists of one word of TOPS-IO/TOPS-20 memory.
NLN, you must declare an integer, as shown below:

store

INTEGER nln

6.2.3

Storing Task and User Attributes

To include task and user attributes in a call to NFOPA, NFOPB or NFOP8
or task attributes in a call to NFOPP you must describe these
attributes in your program as follows:
INTEGER trgsys (4 )
INTEGER objtyp (4 )
INTEGER desc (4 )
INTEGER tsknam (4 )
INTEGER userid (8 )
INTEGER passwd ( 8 )
INTEGER acct (8 )
INTEGER usdat (4 )

or
or
or
or
or
or
or
or

CHARACTER*16
CHARACTER*16
CHARACTER*16
CHARACTER*16
CHARACTER*39
CHARACTER*39
CHARACTER*39
CHARACTER*16

6-4

trgsys
objtyp
desc
tsknam
userid
passwd
acct
usdat

TOPS-20 AND TOPS-lO TASK-TO-TASK
6.2.4

Checking the Status of a Task-to-Task Routine

To check the status of a call to one of the task-to task routines from
a TOPS-20 or TOPS-IO FORTRAN program, you should first declare an
integer (implicitly or explicitly) where the routine can place a
status value.
INTEGER

status

A normal call to one of the Task-to-Task Routines
Interface Support File), including provisions
might be:
status
1

(using the proper
for status checking

= NFOP8 (nln, trgsys, objtyp, desc, tsknam, userid,

passwd, acct, usdat, wait)
IF (status.EQ.NORMAL) GOTO 100
IF (status.EQ.INVARG) GOTO 50
TYPE 10
FORMAT (' error occurred')

50
51

TYPE 51
FORMAT (' invalid data type error')

100

To determine which error occurred, compare status to the DIT status
codes defined in the TOPS-lO/TOPS-20 FORTRAN Interface Support file.
In the example above, NORMAL and INVARG are status code values defined
in the Interface Support files.

6.2.5

The TOPS-lO Software Interrupt System

The DIL task-to-task and remote file access routines need the services
of the TOPS-IO software interrupt system (PSI). Because the FORTRAN
and COBOL runtime systems do not provide a facility to share the use
of the software interrupt system between non-cooperating routines in
the same program, the user cannot use the software interrupt system in
a COBOL or FORTRAN program that uses the task-to-task or remote file
access routines.

6-5

TOPS-20 AND TOPS-IO TASK-TO-TASK
6.3

TOPS-IO AND TOPS-20 TASK-TO-TASK REFERENCE

6.3.1

NFGND - Return the Status of a Link

PURPOSE:
The NFGND routine returns the status of a specific network
connection or the next network event (such as a connection, a
disconnect or an abort).
CALL FORMAT:
COBOL:

ENTER MACRO NFGND USING nln, wait.

FORTRAN:

status

= NFGND (nln, wait)

where:
nln

is the Network Logical Name of the link that you want
information about. The NLN is set by the NFOPA, NFOPB,
NFOP8 or NFOPP routines. The Network Logical Name is a
one-word integer.
If you want information about any event occurring on
any logical link, use -1 as the value for this
argument. NFGND finds the next network event and
returns the NLN of that link.
If NFGND cannot find an
event, it returns an undefined value.

wait

is a one-word integer that gives the wait code.
Set the wait code to "no" if you want the routine to
return only the current status of events on the
specified link. The DIL Name for this argument is:
WAIT-NO
Set the wait code to "yes" if you want the routine to
wait for a network event to occur involving the
specified link.
When an event occurs the routine
reports it.
Waiting uses minimal CPU time. The DIL
name for this argument is:
WAIT-YES

6-6

TOPS-20 AND TOPS-IO TASK-TO-TASK
STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function value
of status.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.
You receive this code
only if you don't wait for a new
event and no events have occured
since the last reported event.
If an
event has taken place, (connect,
data, abort, disconnect, interrupt
data) you receive the code for that
event.

DIT-CONNECTEVENT

This code is returned for a connect
event.
If you are checking the
status of a passive task, this code
indicates that the task has received
a connect request.
If you are
checking the status of an active
task, this code indicates that a
connect request issued by the active
task has been accepted by the passive
task.

DIT-ABREJEVENT

The routine returns this code if the
link is aborted or rejected.
You
should call NFCLS to do an abort and
release the resources of this link,
so it can be used again.

DIT-DATAEVENT

The routine returns this code when
data is available over the specified
link.
You should call NFRCV to receive the data.

DITDISCONNECTEVENT

The routine returns this code when
the specified link has been disconnected.
You should call NFCLS to do
an abort to release the resources of
this link, so it can be used again.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error~

DIT-INTERRUPT

The routine returns this code when an
interrupt data message is available.
You should call NFRCI to read the
interrupt data message.

6-7

TOPS-20 AND TOPS-IO TASK-TO-TASK
6.3.2

NFINF - Get Information About the Other End of a Logical Link.

PURPOSE:
The NFINF routine returns information about the remote node, the
remote process or the remote DECnet object associated with a
specific network connection.
You can also use the NFINF routine to read optional data sent by
a remote process. If the cooperating process is on a VMS system,
you can use NFINF to read optional data associated with a
disconnection or rejection of a process. If the cooperating
process is a TOPS-IO or TOPS-20 system, you can read any type of
optional data.
CALL FORMAT:
COBOL:

ENTER MACRO NFINF USING nln, inftyp, length, buffer.

FORTRAN:

status

= NFINF (nln, inftyp, length, buffer)

where:
nln

is the Network Logical Name of the link that you want
information about. The NLN is set by the NFOPA, NFOPB,
NFOP8, or NFOPP routine. The Network Logical Name is a
one-word integer.

inftyp

is a one-word integer
information wanted.

that

specifies

Refer to the DECnet User's Guide for
more information.

6-8

your

the

type

system

for

TOPS-20 AND TOPS~10

TAS~-TO-TASK

Information Type

DIL Name

Remote node name of the cooperating task.

INF-NODE

Remote object type. This information is only
available to the passive task.

INF-OBJECT

Remote object descriptor format (0 if the task
only requires an object id, 1 if the task only
requires a taskname, or 2 if the task requires a
project-programmer number) • This information is
only available to the passive task.

INF-DESCF

Remote DECnet object descriptor. This information
is only available to the passive task.

INF-DESC

Remote process user ide This information is only
available to the passive task.

INF-USERID

Remote process password. This information is only
available to the passive task.

INF-PASSWD

Remote process account. This information is only
available to the passive task.

INF-ACCT

Remote process optional data or disconnect optional
data or reject optional data.
If the cooperating
task is running on a VMS system, only disconnect
and reject optional data are available.

INF-OPT

Maximum segment size for the link in bytes. This
is not available for VMS systems. The information
can be used to determine the optimum size of
records to be transmitted over the link.

INF-SEG

Abort code or reject code. You can find the
meaning of the abort or reject code in the DECn~t
manual for the remote system.

INF-ABTCOD

length

is a one word integer in which the length of ASCII data
returned is specified.

buffer

is the area in which to place returned ASCII data.
This area must be at least 16 ASCII-7 characters long
to accomodate optional data, a taskname, or a DECnet
descriptor.
It must be at least 39 ASCII-7 characters
long to accommodate a userid,
a password, or an
account.

6-9

TOPS-20 AND TOPS-IO TASK-TO-TASK

STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the OILINI routine.
For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

OIT-INVARG

You passed an incorrect or invall.d
argument.

SS-NORMAL

The routine successfully completed
processing.

OIT-INFONOTAVAIL

The information you have requested
is not available to this task.

OIT-INFOOUTOFRANGE

The information you have requested
is not in the range of valid values.

OIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

6-10

- _.".

_.- -

TOPS-20 AND TOPS-lO TASK-TO-TASK
6.3.3

NFOPA - Open a Link From an Active Task (ASCII)

PURPOSE:
The NFOPA routine opens a logical link to a program on another
system.
You use this routine when you intend to transmit or
receive ASCII data.
CALL FORMAT:
COBOL:

ENTER MACRO NFOPA USING nln, trgsys, objtyp, desc,
tsknam, userid, passwd, acct, usdat, wait.

FORTRAN:

status = NFOPA (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

is the Network Logical Name (NLN) to be returned when
this routine successfully finishes processing. You use
the NLN to identify this link when you call other
Task-to-Task routines.
The Network Logical Name is a
one-word integer.

trgsys

is the node name of the target system.
The t~rget
system,
in this case,
is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-7
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type specifies the kind of service performed by the
passive task. This argument has a length of sixteen
ASCII-7 characters.
If the object type has less than
sixteen characters, left-justify the field.
The object type can be expressed as either a number or
a name. Most programs use an object type of 0 or TASK.
Server programs which perform a generic service (MAIL,
for example) have a non-zero· numeric object type. You
can find a list of valid DECnet object types and their
meanings in the appropriate DECnet User's Guide.

desc

is the DECnet descriptor.
You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system. For TOPS-20 to TOPS-20 communication when the
object type is not zero, you can provide a descriptor.
See Appendix D for further information. The descriptor
has a length of sixteen ASCII-7 characters. If your
descriptor
is
less
than
sixteen
characters,
left-justify the field.

6-11

TOPS-20 AND TOPS-IO TASK-TO-TASK

NOTE
For a TOPS-20 system, the name of the target system,
the object type and the DECnet descriptor cannot have
a combined total of more than thirty-seven non-blank
characters.
tsknam

is the DECnet taskname. Taskname is a unique sixteen
character ASCII-7 string that identifies this process
to the network. An active task never has to specify a
taskname.
If you pass a value of spaces for this
argument, the operating system assigns a unique name.
NOTE

The following three arguments are optional
user
attributes. The passive task may use these attributes
to· validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments are optional if you want to connect to
a passive TOPS-20 or TOPS-10 task, or a passive VMS
task that is already running.
The arguments are
required if you want to connect to a passive VMS task
that is to be started as a result of your request.
userid

is youruserid. Userid has a length of thirty-nine
ASCII-7 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass a value of spaces
for this argument.

passwd

is your password. Password has a length of thirty-nine
ASCII-7 characters.
If your password is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a password, pass a value of
spaces for this argument.

acct

is your account number or charge code. This field has
a length thirty-nine ASCII-7 characters.
If this
information is less than
thirty-nine
characters,
left-justify the field. Give this argument a value of
spaces if you plan to connect to a passive task on a
VMS system or you don't want to specify an account
number.

usdat

is sixteen optional ASCII-7 characters of user
See the NFINF routine for more information.

6-12

data.

TOPS-20 AND TOPS-lO TASK-TO-TASK
wait

is a one-word integer that gives the wait code.
Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task. Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted your connection, periodically call the NGFND
routine to check status.
The DIL Name for this
argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time. The DIL Name for this argument is:
WAIT-YES

Meaning

DIT-TOOMANY

You attempted too many links. The
DIL allows a maximum of 20 open
links. On TOPS-20 systems, however,
a non-privileged user can only open
a maximum of four links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

6-13

TOPS-20 AND TOPS-IO TASK-TO-TASK
6.3.4

NFOPB - Open a Link From an Active Task (Binary)

PURPOSE:
The NFOPB routine opens a logical link to a program on another
system.
You use this routine when you intend to transmit records
or blocks of data.
Data moved through the network on a link opened with NFOPB is
transmitted as a string of bits, sent eight bits at a time. This
format allows the data to be used by the Data Conversion
Routines. To learn more about bit transport, see Appendix F.
CALL FORMAT:
COBOL:

ENTER MACRO NFOPB USING nln, trgsys, objtyp, desc,
tsknam, userid, passwd, acct, usdat, wait.

FORTRAN:

status = NFOPB (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

is the Network Logical Name (NLN) to be returned when
this routine successfully finishes processing.
You use
the NLNto identify this link when you call other
Task-to-Task routines. The NLN is a one-word integer.

trgsys

is the node name of the target system.
The target
system,
in this case,
is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-7
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type tells the kind of service performed by the passive
task. This argument has a length of sixteen ASCII-7
characters.
If the object type has less than sixteen
characters, left-justify the field.
The object type can be expressed as either a number or
name.
Most programs use an object type of 0 or TASK.
Server programs which perform a generic service
(MAIL,
for example) have a non-zero numeric object type. You
can find a list of valid DECnet object types and their
meanings in the appropriate DECnet User's Guide.

desc

is the DECnet descriptor.
You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system.
For TOPS-20 to TOPS-20 communication when the
object type is not zero, you can provide a descriptor.
See Appendix D for further information. The descriptor
has a length of sixteen ASCII-7 characters. If your
descriptor
is
less
than
sixteen
characters,
left-justify the field.

6-14

TOPS-20 AND TOPS-IO TASK-TO-TASK

NOTE
For a TOPS-20 system, the name of the target system,
the object type and the DECnet descriptor cannot have
a combined total of more than thirty-seven non-blank
characters.
tsknam

The following three arguments are optional
user
attributes. The passive task may use these attributes
to validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments are optional if you want to connect to
a passive VMS task or a passive VMS task that is
already running. The arguments are required if you
want to connect to a passive VMS task that is to be
started as a result of your request. See Appendix 0
for further information.
userid

is your userid. Userid has a length of thirty-nine
ASCII-7 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass a value of spaces
for this argument.

passwd

acct

is your account number or charge code. This field has
a length thirty-nine ASCII-7 characters.
If this
information is less than
thirty-nine
characters,
left-justify the field. Give this argument a value of
spaces if you plan to connect to a VMS system or you
don't want to specify an account number.

usdat

is sixteen optional ASCII-7 characters of user
See the NFINF routine for more information.

6-15

data.

TOPS-20 AND TOPS-IO TASK-TO-TASK

is a one-word integer that gives the wait code.

wait

Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task. Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted your connection, periodically call the NGFND
routine to check status.
The DIL Name for this
argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time. The DIL Name for this argument is:
WAIT-YES
STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-TOOMANY

You attempted too many links. The
DIL allows a maximum of 20 open
links. On TOPS-20 systems, however,
a non-privileged user can only open a
maximum of four links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

6-16

TOPS-20 AND TOPS-lO TASK-TO-TASK
NFOP8 - Open a Link From an Active Task (8-bit)

6.3.5

PURPOSE:
The NFOP8 routine opens a logical link to a program on another
system.
You use this routine when you intend to transmit 8-bit
bytes of data. This type of link is used primarily to transmit
data between two VMS systems or to perform special operations.
Data is moved through a link opened with NFOP8 as a string of
8-bit bytes. The routine does not transmit any unused bits. The
target system stores the data in whatever way it normally stores
8-bit bytes of data.
To learn more about bit transport, see
Appendix F.
CALL FORMAT:
COBOL:

ENTER MACRO NFOP8 USING nln, trgsys, objtyp, desc,
tsknam~ userid, passwd, acct, usdat, wait.

FORTRAN:

status = NFOP8 (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

trgsys

is the node name of the target system.
The target
system,
in this case, is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-7
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type tells the kind of service performed by the passive
task. This argument has a length of sixteen ASCII
characters.
If the object type has less than sixteen
characters, left-justify the field.
The object type can b~ expressed as either a number or
name. General, one-purpose programs use an object type
of 0 or TASK. Server programs which perform a generic
service
(MAIL, for example) have a non-zero numeric
object type. You can find a list of valid DECnet
object types and their meanings in the appropriate
DECnet User's Guide.

6-17

TOPS-20 AND TOPS-IO TASK-TO-TASK

desc

is the DECnet descriptor. You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system. For TOPS-20 to TOPS-20 communication when the
object type is not zero, you can provide a descriptor.
See Appendix 0 for further information. The descriptor
has a length of sixteen ASCII-7 characters. If your
descriptor
is
less
than
sixteen
characters,
left-justify the field.
NOTE

For a TOPS-20 system, the name of the target system,
the object type and the DECnet descriptor cannot have
a combined total of more than thirty-seven non-blank
characters.
tsknam

The following three arguments are optional
user
attributes. The passive task may use these attributes
to validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments are optional if you want to connect to
a passive TOPS-20 or TOPS-10 task, or a passive VMS
task that is already running.
The arguments are
required if you want to connect to a passive VMS task
that starts up as a result of your request.
userid

is your userid. Userid has a length of thirty-nine
ASCII-7 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass a value of spaces
for this argument.

passwd

acct

is your account number or charge code. This field has
a length thirty-nine ASCII-7 characaters.
If this
information is less than
thirty-nine
characters,
left-justify the field. Give this argument a value of
spaces if you plan to connect to a VMS system or you
don't want to specify an account number.

usdat

is sixteen optional ASCII-7 characters of user
See the NFINF routine for more information.

6-18

data.

TOPS-20 AND TOPS-lO TASK-TO-TASK

wait

is a one-word integer that gives the wait code.
Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task. Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted your connection, periodically call the NFGNO
routine to check status.
The OIL Name for this
argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time. The OIL Name for this argument is:
WAIT-YES

STATUS COOES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the OILINI routine.
For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

OIT-TOOMANY

You attempted too many links. The
OIL allows a maximum of 20 open
links. On TOPS-20 systems, however,
a non-privileged user can only open
a maximum of four links.

OIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

OIT-ABORTREJECT

The link was aborted or rejected.

OIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

6-19

TOPS-20 AND TOPS-lO TASK-TO-TASK
NFOPP - Open a Link From a Passive Task

6.3.6

PURPOSE:
The NFOPP routine opens a logical link from a passive task.
It
indicates that the server program is ready to accept connections
from active programs.
Data can be moved through the network in different ways.
You
must make sure that both the active and passive tasks specify the
same method of data transfer. The active task which connects to
NFOPP establishes the way data actually moves through the
network.
(NFOPA moves ASCII data, NFOPB moves binary data, NFOP8
moves 8-bit bytes of data.) When it receives a connect request,
the passive task calls the NFACC routine to accept the request.
The "lnktyp" argument in the call to NFACC specifies the type of
data to be transfered over the connection. If the active task
and the NFACC routine specify different data types, the results
are undefined. To learn more about bit transport, see Appendix
F.
CALL FORMAT:
COBOL:

ENTER MACRO NFOPP USING nln, objtyp, desc, tsknam,
wait.

FORTRAN:

status

= NFOPP (nln, objtyp, desc, tasknam, wait)

where:
nln

objtyp

is the object type of the passive task.
The object
type tells the kind of service performed by this task.
This argument has a length
of
sixteen
ASCII-7
characters.
If the object type has less than sixteen
characters, left-justify the field.
The object type can be expressed as either a number or
name. General, one-purpose programs use an object type
of 0 or TASK. Server programs which perform a generic
service (MAIL,
for example) have a non-zero numeric
object type.
You can find a list of valid DECnet
object types and their meanings in the appropriate
DECnet User's Guide.

desc

is the DECnet descriptor.
A passive task can only
specify
a
descriptor
for
TOPS-20
to
TOPS-20
communication when the object type is not zero. For a
TOPS-IO system, this argument is ignored. See Appendix
D for examples of proper task identification.
A descriptor has a
length
of
sixteen
ASCII-7
characters.
If your descriptor is less than sixteen
characters, left-justify the field.
If you don't want
to specify a descriptor, pass a value of spaces for
this argument.

6-20

TOPS-20 AND TOPS-IO TASK-TO-TASK

tsknam

is the DECnet taskname. Taskname is a unique sixteen
character ASCII-7 string that identifies this process
to the network. Normally, a passive task must specify
a taskname. Active tasks use the taskname to identify
the passive task.
See Appendix
D
for
further
information.
If you don't specify a taskname, the
operating system assigns a unique taskname.

wait

is a one-word integer that gives the wait code.
Set the wait code to "no" if you you want to set up a
server task, but you do not want to wait until an
active task requests its services.
Using this code
leaves your program free to perform other duties. To
find out if the an active wants to connect to the
server, call the NFGND routine to check status. The
DIL Name of this argument is:
WAIT-NO
Set the wait code to "yes" if you want to set up a
server task that waits until an active task requests
its services. The routine returns a status value when
an active task tries to connect to the server. While
it waits, you cannot use the server program to perform
any other processing functions. Waiting uses minimal
CPU time. The ~IL Name of this argument is:
WAIT-YES

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-TOOMANY

You attempted too many links. The
DIL allows a maximum of 20 open
links. On TOPS-20 systems, however,
a non-privileged user can only open
a maximum of four links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
system or unexpected error.

6-21

TOPS-20 AND TOPS-lO TASK-TO-TASK
6.3.7

~FACC

- Accept a Connection

PURPOSE:
The NFACC routine is used by the passive task to accept a
connection from an active task and to specify how data will be
moved through the network. The NFACC routine is always used
following the NFOPP routine, which opens the logical link.
CALL FORMAT:
COBOL:

ENTER MACRO NFACC USING nln, lnktyp, char, opdat.

FORTRAN:

status

= NFACC (nln, lnktyp, char, opdat)

where:
nln

is the Network Logical Name set by the NFOPP routine
when it successfully finishes processing. NLN is a
one-word integer.

lnktyp

is a one-word intger that specifies the type of data
that you want to transfer over the link.
If the active
task specifies a different type of data, the results
will be undefined.
You must specify one of the
following values:
Link Data Type

OIL Name

ASCII.
To transfer ASCII
data, use the
NFOPA routine to
open the link.

LTYPE-ASCII

Binary data.
To transfer binary
data, use the
NFOPB routine to
open the link.

LTYPE-BINARY

8-bit bytes.
To transfer 8-bit
bytes of data,
use the NFOP8 routo open the link.

LTYPE-8BIT

char

is a one word-integer that specifies the number of
characters
(0-16) of optional data that you plan to
send (see below).

opdat

is sixteen optional ASCII-7 characters of user
See the NFINF routine for more information.

6-22

data.

TOPS-20 AND TOPS-IO TASK-TO-TASK

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

-_._.

DIT-HORRIBLE

---

_...

This code is returned in the event of
a system or unexpected error.

6-23

TOPS-20 AND TOPS-I0 TASK-TO-TASK

6.3.8

NFREJ - Reject a Connection

PURPOSE:
The NFREJ routine is used by the passive
connection request from an active task.

task

reject

CALL FORMAT:
COBOL:

ENTER MACRO NFREJ USING nln, rejcod, char, opdat.

FORTRAN:

status

= NFREJ (nln, rejcod, char, opdat)

where:
nln

is the Network Logical Name set by the NFOPP routine
when it successfully finishes processing. NLN is a one
word integer.

rejcod

is a one-word integer that specifies the type of reject
requested.
You should use nine for this code, which
means "User Program Abort." See your DECnet User's
Guide for a list of abort/reject codes. This parameter
is not used on either VMS or TOPS-10 systems.

char

is a one-word integer that specifies the number of
characters (0-16) of optional data that you plan to
send (see below.)

opdat

is sixteen ASCII-7 characters of optional user
For more information, see the NFINF routine.

data.

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

6-24

TOPS-20 AND TOPS-lO TASK-TO-TASK
6.3.9

NFRCV - Receive Data Over a Link

PURPOSE:
The NFRCV routine receives data (DECnet messages) over a
link.

logical

If you specify message mode, this routine reads
message. Message mode is the recommended mode.

DECnet

one

If you specify stream mode, NFRCV reads a stream of as many
characters as you request (in mxunit, below).
It reads these
characters from as many DECnet messages as are required to equal
the numerical value shown in mxunit. The routine stops reading
in the middle of a message once it has read the correct number of
characters.
VMS users cannot specify stream mode; VMS systems always send and
receive messages. You must use message mode to communicate with
tasks that run on VMS systems. If you use a DECSYSTEM-20 or a
DECsystem-lO, you have the capability to specify stream mode.
On a DECSYSTEM-20, using message mode, if the user's buffer is
not large enough to receive the message, DIT-OVERRUN will be
returned. You may call NFRCV again with a larger buffer to
receive the message with no loss of data.
On a DECsystem-lO, using message mode, if the user buffer is not
large enough to receive the message, the message is truncated to
the size of the buffer and a status of DIT-OVERRUN is returned to
indicate the loss of data.
Normally, this should not happen
because cooperating tasks can agree on the message size.
To
create a task that can receive messages without loss of data, you
should use stream mode. After each call to NFRCV in stream mode,
the task can inspect the value returned for msmode to determine
if an end-of-message was detected while filling the user buffer.
CALL FORMAT:
COBOL:

ENTER MACRO NFRCV USING nln, msunit, mxunit, bufloc,
msmode, wait.

FORTRAN:

status = NFRCV (nln, msunit, mxunit, bufloc, msmode,
1 wait)

where:
nln

is the Network Logical Name set by the NFOPA, NFOPB,
NFOP8 or NFOPP routine when the routine successfully
finished processing. The NLN is a one-word integer.

msunit

is the message unit size. It tells the byte size, in
bits, of messages written in binary format (with links
opened through NFOPB).
A value of zero for this
argument indicates the data is to be transferred as
words.
If you open the active side of the link with
NFOPA or NFOP8, the routine ignores this argument.

6-25

TOPS-20 AND TOPS-IO TASK-TO-TASK

mxunit

is a one-word integer that gives the maximum number of
units to be read by the routine. When NFRCV returns,
it replaces this value with the actual number of units
that it read.
•

For links opened with NFOPA, this is the
number of ASCII characters in the message.

maximum

•

For links opened with NFOP8, this is the maximum
number of sequential 8-bit bytes in the message.

•

For links opened with NFOPB, this is the maximum
number of bytes (of the unit size shown in msunit)
or words in the message. NFRCV pads the last byte
or word sent with zero bits if it does not divide
evenly into bytes of the specified size.

If you use stream mode, set the value of this argument
to the actual number of characters, bytes or words to
be read.
bufloc

is the location of the user buffer where the message
will be placed after it is read. This buffer must be
at least as large as the number of bytes, characters or
words specified in mxunit.

msmode

is a one-word integer that indicates the message-mode
flag.
You can set this argument to message mode or
stream mode.
If you want to read the data in message mode,
Name for this argument is:

the

OIL

MSG-MSG
If you want to read the required number of characters
or bytes in stream mode, the OIL Name for this argument
is:
MSG-STM
On a OECsystem-lO, if the user specifies msmode as
MSG-STM
and the end-of-message is detected while
filling the user's buffer, msmode will be returned with
a value of MSG-MSG.
wait

is a one-word integer that gives the wait code.
Set the wait cod, to "no" if you want the routine to
If no
return whatever data is currently available.
data is available the routine returns and you can use
the program to perform other duties. The OIL name for
this argument is:
WAIT-NO
Set the wait code to "yes" if you want the routine to
wait until data is received or the read fails. Waiting
uses minimal CPU time. The OIL name for this argument
is:
WAIT-YES

6-26

DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

This code is returned if the link is
disconnected or aborted. The character count area contains the number
of units, by'tes or words, that the
routine reads before the disconnect.

DIT-OVERRUN

This code is returned if you try to
send too much data to the routine.

DIT-NOTENOUGH

This code is returned if
of data you requested is
able. This error occurs
you use stream mode with
code.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

DIT-INTERRUPT

Interrupt data must be read first
using NFRCI.

the amount
not availonly when
a no-wait

6-27

TOPS-20 AND TOPS-10 TASK-TO-TASK
6.3.10

NFSND - Send Data Over a Link

PURPOSE:
The NFSND routine sends data over a logical link.
If you open the logical link with NFOPA, the routine sends the
data in ASCII format. The receiving task can directly read ASCII
data from another system, even if the tasks are on heterogeneous
systems.
If you open the logical link with NFOP8, the routine sends the
data as sequential 8-bit bytes. The local system treats the data
as it normally treats 8-bit bytes of data.
The remote system
treats the data it receives in the way it normally stores 8-bit
bytes of data.
If you open the logical link with NFOPB, the routine sends the
data in binary format.
If the sending and receiving tasks are on
homogeneous systems, the receiving system can directly read the
data.
If the sending and receiving tasks are on heterogeneous
systems, you must convert the data using the Data Conversion
Routines.
The sending task can perform the conversion before it
sends the data or the receiving task can convert the data it
receives.
If you specify message mode, this routine sends one DECnet
message. To send more than one message, set up a loop to perform
this routine until it has sent all of the messages.
If you specify stream mode, NFSND sends the data in a stream of
as many characters as you request (in length, below).
It sends
the data in as many DECnet messages as are required to equal the
numerical value shown in length. The routine stops sending in
the middle of a message if it has sent the correct number of
characters, bytes or words.
VMS users cannot specify stream mode; VMS systems always send and
receive messages. You must use message mode to communicate with
tasks that run on VMS systems. If you use a DECSYSTEM-20 or a
DECsystem-IO, you have the capability to specify stream mode.
CALL FORMAT:
COBOL:

ENTER MACRO NFSND USING nln, msunit, length, buffer,
msmode.

FORTRAN:

status

= NFSND (nln, msunit, length, buffer, msmode)

where:
nln

is the Network Logical Name set by the NFOPA, NFOPB,
NFOP8 or NFOPP routine when the routine successfully
finished processing. The NLN is a one-word integer.

msunit

is a one-word integer that specifies the message unit
size.
It tells the byte size, in bits, of messages
written in binary format
(with links opened through
NFOPB).
A value of zero for this argument indicates
that the data is to be sent as words.
If you open the
active side of the link with NFOPA or NFOP8, the
routine ignores this argument.

6-28

TOPS-20 AND TOPS-IO TASK-TO-TASK

length

is a one-word integer that gives the length of the data
that you want to send. This argument must have a value
that is greater than zero.
•

For links opened with NFOPA,
ASCII characters.

length

given

•

For links opened with NFOP8,
sequential 8-bit bytes.

length

given

•

For links opened with NFOPB,
length is given in
bytes (of the unit size shown in msunit) or words.

buffer

is the buffer containing the
send.

msmode

is a one word integer that gives the message-mode flag.
You can set this argument to send data in message mode
or in stream mode.

data

that

you

want

If you want to send data in message mode, the DIL
for this argument is:

Name

MSG-MSG
If you want to send the required number of characters
or bytes in stream mode, the DIL Name for this argument
is:
MSG-STM
A TOPS-20 or TOPS-lO system permits you to send data in
message mode or stream mode.
It is advised, however,
that you always send data in message mode.
VMS users
must send data in message mode.
STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event of
a system or 'unexpected error.

6-29

TOPS-20 AND TOPS-10 TASK-TO-TASK
6.3.11

NFINT - Send an Interrupt Data Message Over a Link

PURPOSE
The NFINT routine sends a single interrupt data
logical link.

message

over

Unlike NFSND, NFINT data is always send in message mode, so a
prompt attempt to send the data is guaranteed.
Data sent in this
mode is not sent in synchronization with data sent by NFSND.
Only one interrupt data message can be outstanding from each end
of a logical link at one time.
If an interrupt data message is
sent over a logical link by one process, a second interrupt data
message cannot be sent by that process until the first one has
been received at the other end of the logical link.
If a second
interrupt data message is sent before the first one has been
received at the other side of the link, then the first interrupt
data message may be lost at the receiving end of the link.
CALL FORMAT:
COBOL:

ENTER MARCO NFINT USING nln, char, buffer

FORTRAN:

status

= NFINT (nln, char, buffer)

where:
nln

is the Network Logical Name set by the NFOPP routine
when it successfully finishes processing. NLN is a one
word integer.

char

is a one-word integer that specifies the number of
ASCII-7 characters (1-16) of interrupt data to send.

buffer

is the buffer that contains the 1-16
ASCII-7 data that you want to send.

characters

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

6-30

TOPS-20 AND TOPS-10 TASK-TO-TASK
6.3.12

NFRCI - Receive an Interrupt Data Message Over a Link

PURPOSE:
The NFRCI routine receives a single interrupt data message over a
logical link.
Receipt of an interrupt data message is an asynchronous event.
You should check for asynchronous events by using NFGND which
will announce interrupt data messages before it will announce
"regular" data messages (sent by NFSND).
Interrupt data mesiages
must be read before NFGND will announce any lower-level events
(regular data messages or disconnections). NFRCV will return the
DIT-INTERRUPT error and refuse to return data if an interrupt
message is available which has not yet been read by NFRCI.
CALL FORMAT:
COBOL:

ENTER MACRO NFRCI USING nln, char, buffer.

FORTRAN:

status

= NFRCI (nln, char, buffer)

where:
nln

is the Network Logical Name set by the NFOPP routine
when it successfully finishes processing. NLN is a one
word integer.

char

is a one-word integer into which the number of ASCII-7
characters (1-16) of interrupt data read is returned.

buffer

is the location of the user buffer where the message
will be placed after it is read. The length of this
buffer must be at least 16 ASCII-7 characters.

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
Meaning

DIL Name
DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NODATAAVAILABLE

No interrupt data is available to be
read at this time.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

6-31

TOPS-20 AND TOPS-10 TASK-TO-TASK
6.3.13

NFCLS - Close a Link

PURPOSE:
The NFCLS routine disconnects or aborts a logical link, releasing
its resources to be used by another link.
A "synchronous disconnect" is the normal way to close a link:
it
disconnects the link after it performs all outstanding data
transmission. An abort would be used on a logical link if the
remote program terminated abnormally, or if fatal errors occurred
on the link. An abort instantaneously disconnects the link.
You can call the NFCLS routine to disconnect the link before or
after receiving a disconnect from the other end of the link. To
preserve data integrity, the recipient of the last piece of data
should be the first to disconnect the link (using a synchronous
disconnect). The program that sent the data recognizes that its
data was read when it receives the disconnect: it then aborts its
end of the link.
CALL FORMAT:
COBOL:

ENTER MACRO NFCLS USING nln, disc, char, opdat.

FORTRAN:

status

= NFCLS (nln, disc, char, opdat)

where:
nln

is the Network Logical Name, set by the NFOPA, NFOPB,
NFOP8
or
the
NFOPP
routine
when the routine
successfully finished processing.
The NLN
is
a
one-word integer.

disc

is a one-word integer that specifies the type of
disconnect requested.
Use zero for this argument if
you want a synchronous disconnect.
A non-zero value
for this argument indicates an abort.
The DECnet
User's Guide for your system shows a list of abort
codes. ----cocre 9 ("User Program Abort") signifies a
normal abort.

char

is a one-word integer that gives the number
of
characters (0 to 16) of optional data to be sent (see
opdat, below).

opdat

is sixteen optional ASCII-7 characters of user
See the NFINF routine for more information.

6-32

data.

TOPS-20 AND TOPS-lO TASK-TO-TASK

STATUS CODES:
For COBOL programs, the DIL·returns status codes in the dil-stat
variable defined by the DILINI routine. For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

6-33

TOPS-20 AND TOPS-IO TASK-TO-TASK
6.4

TOPS-IO/TOPS-20 TASK-TO-TASK EXAMPLES

6.4.1

TOPS-IO/TOPS-20 COBOL Task-to-Task Examples

IDENTIFICATION DIVISION.
PROGRAM-ID.
PASC36.
AUTHOR.
SOFTWARE ENGINEERING.
This program opens a passive link and then waits for a
connection from an active task
(created by the program
ACTC36). Once a link is established, user specified messages
are sent in both directions across the link.
The link is
closed by the program ACTC36 and this program waits for a
confirmation of the close.
INSTALLATION.
DEC MARLBOROUGH.
ENVIRONMENT DIVISION.

DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE FILES.
COPY DIT OF "SYS:DIL.LIB".
COpy OIL OF "SYS:DIL.LIB".

DILINI-PARAMETERS.

* Di1ini is necessary for DECsystem-10 and DECSYSTEM-20 Cobol only.
05
05
05
05

DIL-INIT-STATUS PIC S9(10) COMPo
OIL-STATUS PIC S9 (10) COMPo
OIL-MESSAGE PIC S9(10) COMPo
OIL-SEVERITY PIC S9(10) COMPo

DATA-RECORDS.
05 SEND-DATA PIC X(100) USAGE DISPLAY-7.
05 RECEIVE-DATA PIC X(100) USAGE DISPLAY-7.

01
01
01
01
01
01
01
01

COUNT-OPT-DATA PIC S9(10) COMP VALUE O.
OPT-DATA PIC X(16) DISPLAY-7 VALUE SPACES.
NETLN PIC S9(10) COMPo
OBJECT-ID PIC X(16) DISPLAY-7 VALUE SPACES.
DESCRIPTOR PIC X(16) DISPLAY-7 VALUE SPACES.
TASKNAME PIC X(16) DISPLAY-7.
MESSAGE-UNITS-SIZE PIC S9(10) COMP VALUE 7.
MESSAGE-SIZE PIC S9(10) COMP VALUE 100.

6-34

TOPS-a YD TOPS-IG TASK-TO-TASI(

PROCEDURE DIVISION.
SETUP-RETURN-CODES.
* Set up for status code values, using DILINI routine
ENTER MACRO DILINI USING DIL-INIT-STATUS, DIL-STATUS,
DIL-MESSAGE, DIL-SEVERITY.
IF DIL-INIT-STATUS NOT
1
DISPLAY "1 Invalid return code from DILINI routine

= " DIL-INIT-STATUS.

OPEN-PASSIVE
* Open a passive link.
MOVE "SERVER" TO TASKNAME.
MOVE "0" TO OBJECT-ID.
ENTER MACRO NFOPP USING NETLN, OBJECT-ID, DESCRIPTOR,
TASKNAME, DIT-WAIT-NO.
DISPLAY" NFOPP Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY "1 NFOPP: unsuccessful status return "
STOP RUN.
CHECK-FOR-CONNECT.
* Wait for a connect request
ENTER MACRO NFGND USING NETLN, DIT-WAIT-YES.
DISPLAY" NFGND Status return: " DIL-STATUS.
IF DIL-MESSAGE = DIT-C-CONNECTEVENT NEXT SENTENCE
ELSE
DISPLAY "1 NFGND: Unexpected or invalid status returned: " DIL-STATUS
STOP RUN.
ACCEPT-LINK
* Accept link
ENTER MACRO NFACC USING NETLN, DIT-LTYPE-ASCII, COUNT-OPT-DATA, OPT-DATA.
DISPLAY" NFACC Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY "1 NFACC: unsuccessful status return"
STOP RUN.
CHECK-FOR-DATA
* Wait for a data event on the link
ENTER MACRO NFGND USING NETLN, DIT-WAIT-YES.
DISPLAY" NFGND Status return: " DIL-STATUS.
IF DIL-MESSAGE = DIT-C-DATAEVENT NEXT SENTENCE
ELSE
DISPLAY "1 NFGND: Unexpected or invalid status returned: " DIL-STATUS
STOP RUN.

6-35

TOPS-20 AND TOPS-IO TASK-TO-TASK

READ-THE-DATA.
* Read the data received over the link
MOVE 100 TO MESSAGE-SIZE.
ENTER MACRO NFRCV USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
RECEIVE-DATA, DIT-MSG-MSG, DIT-WAIT-YES.
DISPLAY " NFRCV Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFRCV: unsuccessful status return "
STOP RUN.
DISPLAY" Data received: "
DISPLAY RECEIVE-DATA.
SEND-SOME-DATA.
* Send some data over the link
MOVE 100 TO MESSAGE-SIZE
DISPLAY" Enter some data to be sent over the link: "
ACCEPT SEND-DATA.
ENTER MACRO NFSND USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
SEND-DATA, DIT-MSG-MSG.
DISPLAY" NFSND Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFSND: unsuccessful status return"
STOP RUN.
CHECK-FOR-CLOSE.
ENTER MACRO NFGND USING NETLN, DIT-WAIT-YES.
DISPLAY" NFGND Status return: " DIL-STATUS.
IF DIL-MESSAGE NOT = DIT-C-ABREJEVENT AND
DIL-MESSAGE NOT = DIT-C-DISCONNECTEVENT AND
DIL-SEVERITY NOT = STS-K-SUCCESS AND
DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFGND: Invalid status returned"
STOP RUN.
DISPLAY" PASC36 successful. "
STOP RUN.

6-36

TOPS-20 AND TOPS-IO TASK-TO-TASK
IDENTIFICATION DIVISION.
PROGRAM-ID.
ACTC36.
AUTHOR.
SOFTWARE ENGINEERING.
This program opens an active link by connecting to the passive task set up
by the program PASC36. Once the link is established, user specified
messages are sent in both directions across the link. Then the link is
closed.
INSTALLATION.
DEC MARLBOROUGH.
ENVIRONMENT DIVISION.

DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COpy DIT OF "SYS:DIL.LIB".
COpy DIL OF "SYS"DIL.LIB".

DILINI-PARAMETERS.

* Dilini is necessary for DECsystem-10 and DECSYSTEM-20 COBOL only.
05
05
05
05

DIL-INIT-STATUS PIC S9(10) COMPo
DIL-STATUS-PIC S9(10) COMPo
DIL-MESSAGE PIC S9(10) COMPo
DIL-SEVERITY PIC S9(10) COMPo

DATA-RECORDS.
05 SEND-DATA PIC X(lOO) USAGE DISPLAY-7.
05 RECEIVE-DATA PIC X(lOO) USAGE DISPLAY-7.

01
01
01
01
01
01
01
01
01
01
01
01

COUNT-OPT-DATA PIC S9(10) COMP VALUE O.
OPT-DATA PIC X(16) DISPLAY-7 VALUE SPACES.
NETLN PIC S9(10) COMPo
HOSTNAME PIC X(06) DISPLAY-7 VALUE SPACES.
OBJECT-ID PIC X(16) DISPLAY-7 VALUE SPACES.
DESCRIPTOR PIC X(16) DISPLAY-7 VALUE SPACES.
TASKNAME PIC X(16) DISPLAY-7.
USERID PIC X(39) DISPLAY-7 VALUE SPACES.
PASSWD PIC X(39) DISPLAY-7.
ACCT PIC X(39) DISPLAY-7 VALUE SPACES.
MESSAGE-UNITS-SIZE PIC S9(10) COMP VALUE 7.
MESSAGE-SIZE PIC S9(10) COMP VALUE 100.

SYNCH-DISCONN PIC S9(10) COMP VALUE O.

6-37

TOPS-20 AND TOPS-IO TASK-TO-TASK
PROCEDURE OIVISION.
SETUP-RETURN-CODES.
* Set up for status code values, using DILINI routine
ENTER MACRO DILINI USING DIL-INIT-STATUS, OIL-STATUS
OIL-MESSAGE, OIL-SEVERITY.
IF DIL-INIT-STATUS NOT
1
DISPLAY"? Invalid return code from DILINI routine

= " DIL-INIT-STATUS.

CONNECT-TO-PASSIVE
* Ask for a connection to the passive link
MOVE "0" TO OBJECT-ID.
MOVE "SERVER" TO DESCRIPTOR.
MOVE SPACES TO TASKNAME.
ENTER MACRO NFOPA USING NETLN, HOSTNAME, OBJECT-ID, DESCRIPTOR, TASKNAME,
USERID, PASSWD, ACCT, OPT-DATA, DIT-WAIT-NO.
DISPLAY" NFOPA Status return: ", DIL-STATUS.
IF OIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFOPA: unsuccessful status return"
STOP RUN.
CHECK-FOR-CONNECT.
* Wait for confirmation of the connection
ENTER MACRO NFGND USING NETLN, DIT-WAIT-YES.
DISPLAY" NFGND Status return: " OIL-STATUS.
IF DIL-MESSAGE = DIT-C-CONNECTEVENT NEXT SENTENCE
ELSE
DISPLAY"? NFGND: Unexpected or invalid status returned: " DIL-STATUS
STOP RUN.
SEND-SOME-DATA
* Send some data over the link
MOVE 100 TO MESSAGE-SIZE.
DISPLAY" Enter some data to be sent over the link: ".
ACCEPT SEND-DATA.
ENTER MACRO NFSND USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
SEND-DATA, DIT-MSG-MSG.
DISPLAY" NFSND Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFSND: unsuccessful status return "
STOP RUN.

6-38

TOPS-20 AND TOPS-IO TASK-TO-TASK

CHECK-FOR-OATA.
*Wait for a data event on the link
ENTER MACRO NFGNO USING NETLN, OIT-WAIT-YES.
DISPLAY n NFGNO Status. return: " OIL-STATUS
IF OIL-MESSAGE = DIT-C-DATAEVENT NEXT SENTENCE
ELSE
DISPLAY"? NFGND: Unexpected or invalid status returned:
STOP RUN.

DIL-STATUS

REAO-THE-OATA.
* Read .the data received over the link
MOVE 100 TO MESSAGE-SIZE
ENTER MACRO NFRCV USING.NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
RECEIVE-DATA, DIT-MSG-MSG, DIT-WAIT-YES.
DISPLAY" NFRCV Status return: n DIL-STATUS.
IF OIL-SEVERITY NOT = STS-K-SUCCESS
AND OIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFRCV: unsuccessful status return n
STOP RUN.
DISPLAY n Data received:
DISPLAY RECEIVE-DATA.

CLOSE-LINK.
* Close the link
ENTER MACRO NFCLS USING NETLN, SYNCH-OISCONN, COUNT-OPT-DATA, OPT-DATA.
DISPLAY n NFCLS Status return: " OIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? NFCLS: unsuccessful status return"
STOP RUN.
DISPLAY" CTTT36 successful. "
STOP RUN.

6-39

TOPS-20 AND TOPS-IO TASK-TO-TASK
6.4.2

TOPS-IO/TOPS-20 FORTRAN Task-to-Task Examples

C PASF36
C
C
C
C
C
C

This program opens a passive link and then waits for a
connection from an active task (created by the program
ACTC36). Once a link is established, user specified messages
are sent in both directions across the link. The link is
closed by the program ACTC36 and this program waits for a
confirmation of the close.

C Use the OIL interface files.
INCLUDE 'SYS:DITV7'
INCLUDE 'SYS:DILV7'
C Data records
DIMENSION SENDD (20), RECD (20)
C DIL task to task routine parameters
DIMENSION OPTDAT (4), OBJID (4), DESCR (4), TASKN (4)
INTEGER NETLN, DILSTS, MSGSIZ, MUNTSZ, CNTOPD
C

Link description fields

passive end

DATA OBJID /'
,
DATA DESCR /'
DATA TASKN /'SERVE' , 'R

'I
'I

DATA OPTDAT /'

C Program messages
777
778
779
200
202
203
204
205

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

initialize sending and receiving message data fields

100

DO 100 I = 1, 20
SENDD (I) = 0
RECD (I) = 0

Open a passive link
DILSTS

(

Invalid status returned ••.
Enter some data to be sent over the link:
Data received:
I12)
NFOPP Status return:
I12)
NFGND Status return:
I12)
NFACC Status return:
I12)
NFSND Status return:
I12)
NFRCV Status return:
I

)

I
I

= NFOPP (NETLN, OBJID, DESCR, TASKN, WAITLN)

WRITE (5, 200) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 110
WRITE (5, 777)
STOP

6-40

)

TOPS-20 AND TOPS-IO TASK-TO-TASK
C

Wait for a connect request

110

DILSTS

= NFGND (NETLN, WAITLY)

WRITE (5, 202) DILSTS
IF (DILSTS .EO. CONEVT) GO TO 120
WRITE (5, 777)
STOP
C

Accept link

120

CNTOPD
DILSTS

=0
= NFACC (NETLN, LASCII, CNTOPD, OPTDAT)

WRITE (5, 203) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 130
WRITE (5, 777)
STOP
C

Wait for a data event on the link

130

DILSTS

= NFGND

(NETLN, WAITLY)

WRITE (5, 202) DILSTS
IF (DILSTS .EO. DATEVT) GO TO 140
WRITE (5, 777)
STOP
C

Read the data received over the link

140

MSGSIZ

100

DILSTS

NFRCV (NETLN, MUNTSZ, MSGSIZ, RECD, MSGMSG, WAITLY)

'WRITE (5, 205) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 150
WRITE (5, 777)
STOP
150
155

WRITE (5, 779)
FORMAT (' , 20A5)
WRITE (5, ISS) RECD

Send some data over the link

157

WR IT E (5 , 7 7 8 )
FORMAT (20A5)
ACCEPT 157, SENDD
MSGSIZ

100

DILSTS

NFSND (NETLN, MUNTSZ, MSGSIZ, SENDD, MSGMSG)

WRITE (5, 204) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 160
WRITE (5, 777)
STOP

6-41

TOPS-20 AND TOPS-IO TASK-TO-TASK
C

Check for the link being closed

160

DILSTS

= NFGND (NETLN, WAITLY)

WRITE (5, 202) DILSTS
IF (DILSTS .EO. ARJEVT) GO TO 170
IF (DILSTS .EO. DSCEVT) GO TO 170
IF (DILSTS .EO. NORMAL) GO TO 170
WRITE (5, 777)
STOP
170
175

WRITE (5, 175)
FORMAT (' PASF36 test successful ')
STOP
END

C ACTF36
C
C
C
C

This program opens an active link by connecting to the passive
task set up by the program PASC36. Once the link is
established, user specified messages are sent in both
directions across the link. Then the link is closed.

C Use the DIL interface files
INCLUDE 'SYS:DITV7 '
INCLUDE 'SYS:DILV7 '
C Data records
DIMENSION SENDD (20), RECD (20)
C DIL task to task routine parameters
DIMENSION HSTNAM (4), OPTDAT (4), OBJID (4), DESCR (4)
DIMENSION PASSWD (8), ACCT (8), USERID (8), TASKN (4)
INTEGER NETLN, DILSTS, MSGSIZ, MUNTSZ, CNTOPD, SYNCDS
C

Link description fields

DATA OBJID I'TASK I , I
DATA DESCR I'SERVE ' , 'R
DATA TASKN I'
DATA HSTNAM I'
DATA PASSWD I'
DATA USERID

1
DATA ACCT
1

'I
'I
'I
'I
,
'I
,
'I
,
'I

DATA OPTDAT I'

6-42

TOPS-20 AND TOPS-10 TASK-TO-TASK

C Program messages
(
(
(
(

, Invalid status returned ••• ' )
, Enter some data to be sent over the link: ' )
, Data received: ' )
, NFOPA Status return: , 112)

777
778
779
201
202
204
205
206

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

initialize sending and receiving message data fields

100

DO 100 I = 1, 20
SENDO (I) = 0
RECD (I) = 0

Ask for a connection to the passive link
DILSTS
1

(
(
(
(

, NFGND Status return: ,,

, NFSND Status return: ,
, NFRCV Status return: ,
, NFCLS Status return:

112)
112)
112)
112)

= NFOPA (NETLN, HSTNAM, OBJID, DESCR, TASKN,

USERID, PASSWD, ACCT, OPTDAT, WAITLN)

WRITE (5, 201) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 110
WR I T E (5, 7 7 7 )
STOP
C

Wait for confirmation of the connection

110

DILSTS

= NFGND (NETLN, WAITLY)

WRITE (5, 202) DILSTS
IF (DILSTS .EO. CONEVT) GO TO 120
WRITE (5, 777)
STOP
C

Send some data over the link

120
125

WRITE (5, 778)
FORMAT (20A5)
ACCEPT 125, SENDD

Initialize number of bytes
MSGSIZ

DILSTS

NFSND (NETLN, MUNTSZ, MSGSIZ, SENDD, MSGMSG)

WRITE (5, 204) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 130
WRITE (5, 777)
STOP
C

Wait for a data event on the link

130

DILSTS

NFGND (NETLN, WAITLY)

WRITE (5, 202) DILSTS
IF (DILSTS .EO. DATEVT) GO TO 140
WRITE (5, 777)
STOP

6-43

TOPS-20 AND TOPS-IO TASK-TO-TASK

Read the data received over the link

140

MSGSIZ

= 100

DILSTS

= NFRCV (NETLN, MUNTSZ, MSGSIZ, RECD, MSGMSG, WAITLY)

WRITE (5, 205) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 150
WRITE (5, 777)
STOP
150
155

WRITE (5, 779)
FORMAT (' '20A5)
WRITE (5, 155) RECD

Close the link
SYNCDS = 0
DILSTS = NFCLS (NETLN, SYNCDS, CNTOPD, OPTDAT)
WRITE (5, 206) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 160
WRITE (5, 777)
STOP

160
165

WRITE (5, 165)
FORMAT (' ACTF36 test successful ')
STOP
END

6-44

CHAPTER 7
TOPS-10 AND TOP5-20 REMOTE FILE ACCESS

CHAPTER 7
TOPS-IO AND TOPS-20 REMOTE FILE ACCESS

7.1

REMOTE FILE ACCESS FROM TOPS-IO OR TOPS-20 COBOL

The information included in this section assumes
-You are writing a COBOL program
-You plan to use the program on a TOPS-20 or TOPS-IO system
To store a file number, file name and user attributes, to read or
write a record or to perform a status check you must represent several
data items in your program. Users generally, but not necessarily,
allocate space for these data items in Working-Storage.

7.1.1

Compiling Programs

To use the DIL Remote File Access Routines on TOPS-20 from a COBOL
program, you may need to compile your program with the /STACK compiler
switch to insure that you have an adequate pushdown list size.
If
your
program gets a stack overflow, compile the program with
/STACK:2000. On TOPS-IO you may need to compile your COBOL program
with the /D compiler switch.
If your program gets a stack overflow,
compile it with /D:2000.

7.1.2

Including the Interface Support Files

The Interface Support file provided for TOPS-IO and TOPS-20 COBOL is a
copy library called DIL.LIB.
The COBOL COpy verb can be used to
retrieve the information in the library at compilation time.
There
are three library elements in DIL.LIB. The elements are DIL, DIT, and
DIX.
The library element DIL defines general codes and names applicable to
the Data Conversion Routines, the Task-to-Task routines and the remote
file access routines. The general success status code (SS-NORMAL) is
defined in element DIL. Severity codes and system codes are defined
in element DIL. To define these names in your program,
include the
following statement in your WORKING-STORAGE section after an Ol-level
declaration:
COpy DIL OF "SYS:DIL.LIB".

7-1

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
In the following example, the DIL element of the library is
and included in your program.
01

retrieved

Interface-files.
COPYDIL OF "SYS:DIL!LIB".

The library element DIT defines codes specific to the Task-to-Task and
Remote File Access Routines.
This includes the DIT status codes,
Remote File Access file types, Remote File Access open modes, Remote
File Access record formats, Remote File Access record attributes and
Remote File Access close options.
To define these names in your
program,
include the following statement in your WORKING-STORAGE
section after an Ol-level declaration, as shown above for element DIL:
COPY DIT OF "SYS:DIL.LIB".
For programs which use the remote file access
include both the DIL and DIT library elements.

7.1.3

routines,

you

must

Storing a File Number

A file number consists of one word of TOPS-10/TOPS-20 memory.
To
store a file number, you must define a data item with the following
format:
01

your-fnum

PIC S9(10) USAGE COMPUTATIONAL.

When you call the ROPEN routine use your-fnum as the value for fnum,
file number to be returned. When the routine successfully finishes
processing, it returns a value in your-fnum.

7.1.4

Storing Accounting Information

To include your user code, password and account or charge code in a
call to the ROPEN routine, you must describe these attributes as data
items in WORKING-STORAGE. These arguments are always DISPLAY-7 data
items; they must always have a length of PIC X(39). The format for
these data items is as follows:
01
01
01

7.1.5

userid
passwd
acct

PIC X(39)
PIC X(39)
PIC X(39)

USAGE DISPLAY-7.
USAGE DISPLAY-7.
USAGE DISPLAY-7.

Reading and Writing Remote Data

To read or write data in a file on a remote system, the program on the
local system must define an area to accept the data and a one-word
computational item for the length of the data.
01
01

the-record
dlength

PIC X(lOO)
PIC S9(10)

7-2

USAGE DISPLAY-7.
USAGE COMPUTATIONAL VALUE 100.

TOPS-10 AND TOPS-20 REMOTE FILE ACCESS
7.1.6

Checking the Status of a Remote File Access Routine

Section 5.1.3 of this manual presents a method for checking the status
of a TOPS-IO/TOPS-20 COBOL DIL Routine. Section 5.3.1 describes the
DILINI initialization routine.
A call to one of the Remote File Access Routines with a
for success might look like this:

simple

check

ENTER MACRO RCLOSE USING fnum, close.
IF NOT dil-ok THEN
DISPLAY nfatal error".
A call to the same routine with provisions
type of error might look like this:

for

handling

specific

ENTER MACRO RCLOSE USING fnum, close.
IF NOT dil-ok
IF dil-stat = DIT-C-INVARG
DISPLAY ninvalid argument error"
ELSE
DISPLAY "other error".
To determine which error occurred, compare dil-stat to the DIT
condition identifier defined in the TOPS-lO/TOPS-20 COBOL Interface
Support files.
In the example above, DIT-C-INVARG is the value
(defined in the Interface Support file) indicating an invalid argument
was specified.

7.1.7

The TOPS-lO Software Interrupt System

The DIL task-to-task and remote file access routines need the services
of the TOPS-lO software interrupt system (PSI). Because the FORTRAN
and COBOL runtime systems do not provide a facility to share the use
of the software interrupt system between non-cooperating routines in
the same program, the user cannot use the software interrupt system in
a COBOL or FORTRAN program that uses the task-to-task or remote file
access routinese

7.2

REMOTE FILE ACCESS FROM TOPS-20 OR TOPS-lO FORTRAN

The information included in this section assumes
-You are writing a FORTRAN program
-You plan to use the program on a TOPS-20 or TOPS-lO system
This section explains how to store a file number, file name and user
attributes.
It also tells how to read or write a record or to perform
a status check.

7-3

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7.2.1

Including the Interface Support Files

The Interface Support files provided for TOPS-IO and TOPS-20 FORTRAN
are text files called DILV7.FOR, DITV7.FOR and DIXV7.FOR. You can
include the information from these files into your source programs at
compilation time using the FORTRAN INCLUDE statement.
The file DILV7 defines general codes and names applicable to the Data
Conversion Routines, the Task-to-Task Routines and the Remote File
Access routines. The general success status code (SS-NORMAL)
is
defined in DILV7.
Severity codes and system codes are defined in
DILV7. To define these names in your program, include the following
statement in your program:
INCLUDE 'SYS:DILV7'
The file DITV7 defines codes specific to the Task-to-Task and Remote
File Access Routines. This includes the DIT status codes, Remote File
Access file types, Remote File Access open modes, Remote File Access
record formats,
Remote File Access record attributes and Remote File
Access close options. To define these names in your program,
include
the following statement:
INCLUDE 'SYS:DITV7'
For programs which use the remote file
include both the DILV7 and DITV7 files.

you

must

declare

Use fnum as the value for the file number argument in the call to
ROPEN routine.

the

7.2.2

access

routines,

Storing a File Number

To store a file number, you must implicitly or explicitly
integer with the following format:
INTEGER

7.2.3

fnum

Storing Account Information

To include your user code, password, account number (or charge code)
in a call to the ROPEN routine, you must first declare these values in
your program. The format for these data items is as follows:
INTEGER
INTEGER
INTEGER

7.2.4

userid (8)
passwd (8)
acct
(8)

or
or
or

CHARACTER*39
CHARACTER*39
CHARACTER*39

userid
passwd
acct

Reading and Writing Remote Data

To read or write data from a file on a remote system, you must declare
an area on the local system to accept the data, and an integer for the
length of the data.
INTEGER
DATA

therec (20), recl
recl/IOO/

7-4

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7.2.5

Checking the Status of a Remote File Access Routine

The Remote File Access Routines return status values as their function
values.
To perform an error check on a Remote File Access Routine,
first declare an integer where the routine can place a status value.
INTEGER

status

A simple call with an error check might then be:

50
51
100

status = RREAO (fnum, dunit, maxsiz, bufnam)
IF (status .EQ. NORMAL) GOTO 100
IF (status .EQ. INVARG) GOTO 50
TYPE 10
FORMAT (' error occurred')

TYPE 51
FORMAT (' invalid data type error')

To determine which error occurred, compare status with the OIT status
codes defined in the TOPS-IO/TOPS-20 FORTRAN Interface Support files.
In the example above, NORMAL and INVARG are status code values defined
in the Interface Support file.

7.2.6

The TOPS-IO Software Interrupt System

7-5

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7.3

TOPS-20 AND TOPS-IO REMOTE FILE ACCESS REFERENCE

7.3.1

ROPEN - Open a Remote File

PURPOSE:
This routine opens a remote, sequential
ASCII
file
for
processing.
It also assigns a file number to the opened file.
CALL FORMAT:
COBOL:

ENTER MACRO ROPEN USING fnum, fnam, userid, passwd,
acct, mode, dattyp, recfor, recatt, recsiz, runit.

FORTRAN:

status = ROPEN (fnum, fnam, userid, passwd, acct,
1 mode, dattyp, recfor, recatt, recsiz, runit)

where:
fnum

is a one-word integer that gives the file number of the
file that you want to open. This number is assigned by
the subroutine.

fnam

is an ASCII-7 character string that gives the name of
the file to be opened. The file name must also include
the node name of the file's system of origin.
NOTE

The
next
three
arguments
supply
accounting
information.
If the remote node is a OECSYSTEM-20 or
a OECsystem-lO, you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account.
If the remote node is
a VAX,
these parameters are optional.
If you do not
specify accounting information, the VMS system uses
the default OECnet directory.
userid

is your user code.
This field contains thirty-nine
ASCII-7 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-7 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account or charge code.
This field contains
thirty-nine ASCII-7 characters.
If your account is
less than thirty-nine characters,
left-justify the
field.
If you don't plan to specify an account, pass
spaces for this argument.

mode

is a one-word integer that indicates the mode in which
you plan to use the file after it is opened. This
version of the OIL allows you to read the file, write
the file or append data to the file.
Check with your
system manager to make sure that the FAL on the file's
computer allows the access mode that you have in mind.

7-6

TOPS-lO AND TOPS-20 REMOTE FILE ACCESS

DIL Name

Mode

dattyp

Read

MODE-READ

Write

MODE-WRITE

Append data to
this file

MODE-APPEND

is a one-word integer that indicates the data
the file.
The DIL name for this argument is:

type

TYPE-ASCII
recfor

is a one-word integer that gives the record format.
This argument, and the next three arguments, refer to
the record which you plan to process after opening the
file with the ROPEN routine.
DIL Name

Record Format

recatt

Undefined

RFM-UNDEFINED

Fixed length

RFM-FIXED

Variable length

RFM-VARIABLE

Variable length
with fixed length
control (VFC)

RFM-VFC

Stream

RFM-STREAM

is a one-word integer that indicates the
attributes of the file you plan to process.
DIL Name

Record Attribute
Unspecified

RATUNSPECIFIED

Implied <LF><CR>
envelope

RAT-ENVELOPE

VMS printer
carriage control

RAT-PRINT

FORTRAN carriage
control

RAT-FORTRAN

7-7

record

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
NOTE
If you plan to use the RFA Routines to read a record
from another system, you can use RFM-UNDEFINED or
RAT-UNSPECIFIED values for the "recfor" and "recatt"
arguments.
You only have to specify values for these
arguments if you plan to write a file on a VMS system.
recsiz

is a one-word integer that gives the record size,
measured in bytes of the size listed as the record size
unit (below).
If you plan to write the file,
this
is
its maximum record size.
If you plan to read or append
data to the file or if you don't specify a maximum
record size, this argument must be zero.

runit

is a one-word integer that gives the record size
An ASCII record ignores this argument.

unit.

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
Meaning

DIL Name
DIT-TOOMANY

You attempted too many links.
The
DIL allows a maximum of 20 open
links. On TOPS-20 systems, however,
a non-privileged user can only open
a maximum of four links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-UNSFILETYPE

You attempted to write a file whose
file type is unsupported on the remote system.

DIT-FILEINUSE

The file is already being processed
by another program.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

7-8

TOPS-lO AND TOPS-20 REMOTE FILE ACCESS
7.3.2

RREAD - Read Data From a Remote File

PURPOSE:
The RREAD routine reads a record from
ROPEN routine.

file

opened

with

the

CALL FORMAT:
COBOL:

ENTER MACRO RREAD USING fnum, dunit, maxsiz, bufnam.

FORTRAN:

status

= RREAD (fnum, dunit, maxsiz, bufnam)

where:
fnum

is a one-word integer that gives the number of the file
that you want to read.
File number is assigned by the
ROPEN routine.

dunit

is a one-word integer that gives the
This argument is always zero.

maxsiz

is a one-word integer that specifies the maximum record
size,
in characters. When RREAD finishes processing,
this argument contains the number
of
characters
actually read by the routine.

bufnam

is an ASCII-7 character string.
This argument
where the routine places the data that it reads.

data

unit

size.

tells

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status. codes as an integer function
value.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-EOF

The routine reached the end of the
file it was reading.

DIT-OVERRUN

The record being read is too large to
fit into the user buffer area.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

7-9

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7.3.3

RWRITE - Write Data To a Remote File

PURPOSE:
The RWRITE routine writes a record into a file opened by ROPEN.
CALL FORMAT:
COBOL:

ENTER MACRO RWRITE USING fnum, dunit, length, data.

FORTRAN:

status

= RWRITE (fnum, dunit, length, data)

where:
fnum

is a one-word integer that gives the file number of the
file that you want to write.
File number is assigned
by the ROPEN routine.

dunit

is a one-word integer that gives the
This argument is always zero.

length

is a one-word integer that specifies the
in characters.

data

is an ASCII-7 character string.
data to write.

data

unit
data

This argument

size.
length,
is

the

STATUS CODES:
For COBOL programs, the DIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines return status codes as an integer function
value.
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

7-10

TOPS-lO AND TOPS-20 REMOTE FILE ACCESS
7.3.4

RCLOSE - Close a Remote File

PURPOSE:
The RCLOSE routine closes the file that you opened with the ROPEN
routine.
CALL FORMAT:
COBOL:

ENTER MACRO RCLOSE USING fnum, clopt.

FORTRAN:

status = RCLOSE (fnum, clopt)

where:
fnum

is a one-word integer that gives the file number of the
file that you want to close.
File number is assigned
by the ROPEN routine.

clopt

is a one~word integer that specifies the close option.
This argument tells what to do with the file once it's
closed.

Close Option

DIL Name

No special action

OPT-NOTHING

Submit file for
remote batch processing

OPT-SUBMIT

Submit file for
remote printing

OPT-PRINT

Delete the remote
file

OPT-DELETE

7-11

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the DIL routines returns status codes as an integer function
value.
OIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

""\.

7-12

TOPS-lO AND TOPS~20 REMOTE FILE ACCESS
7.3.5

RDEL - Delete a File

PURPOSE:
The RDEL routine deletes a file.
You can only delete a closed
file.
If you want to delete an open file, delete it using the
RCLOSE routine with the OPT-DELETE close option.
CALL FORMAT:
COBOL:

ENTER MACRO

FORTRAN:

STATUS

RDEL~ pSING

fnam, userid, passwd, acct.

= RDEL (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-7 character string that gives the name of
the file to be deleted.
The file name must also
include the node name of the file's system of origin.
NOTE

The
next
three
arguments
supply
accounting
information.
If the remote node is a DECSYSTEM-20 or
DECsystem-10, you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account. If the remote node is
a VAX,
these parameters are optional.
If you do not
specify accounting information, the VMS system uses
the default DECnet directory.
userid

is your user code.
This field contains thirty-nine
ASCII-7 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-7 characters.
If your password is less than
thirty-nine characters, left-justify the field.

-acct

is your account.
This field contains thirty-nine
ASCII-7 characters.
If your account is less than
thirty-nine characters, left-justify the field.

7-13

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the DILINI routine.
For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

S8-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

- -

7-14

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7~3.6

RSUB - Submit a File For Batch Processing

PURPOSE:
The RSUB routine submits a remote file for batch processing on
the remote system.
You may only submit closed files for
processing.
If you want to submit an open file for batch
processing, use the RCLOSE routine with the OPT-SUBMIT close
option.
CALL FORMAT:
COBOL:

ENTER MACRO RSUB USING fnam, userid, passwd, acct.

FORTRAN:

status

= RSUB (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-7 character string that gives the name of
the file to be submitted.
The file name must also
include the nod~ name of the file's system of origin.
NOTE

The
next
three
arguments
supply
accounting
information.
If the remote node is a DECSYSTEM-20 or
DECsystem-lO, you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account. If the remote node is
a VAX,
these parameters are optional.
If you do not
specify accounting information, the VMS system uses
the default DECnet directory.
userid

is your user code.
This field contains thirty-nine
ASCII-7 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-7 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
This field contains thirty-nine
ASCII-7 characters.
If your account is less than
thirty-nine characters, left-justify the field.

7-15

TOPS-l,O AND TOPS-20 REMOTE FILE ACCESS

STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the OILINI routine. For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

OIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

OIT-NETOPRFAIL

You attempted an impossible network
operation.

OIT-CHECKSUM

The network returned a network checksum error.

OIT-NOFILE

The file does not exist or is not
available to you.

OIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

7-16

TOPS-lO AND TOPS-20 REMOTE FILE ACCESS
RPRINT - Print a File

7.3.7

PURPOSE:
The RPRINT routine prints a remote file at the remote system.
You can only print closed files • . If you want to print an open
file use the RCLOSE routine with the OPT-PRINT close option.
CALL FORMAT:
COBOL:

ENTER MACRO RPRINT USING fnam, userid, passwd, acct.

FORTRAN:

status = RPRINT (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-7 character string that gives the name of
the file to be printed.
The file name must also
include the node name of the file's system of origin.
NOTE

The
next
three
arguments
supply
accounting
information.
If the remote node is a DECSYSTEM-20 or
DECsystem-lO, you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account. If the remote node is
a VAX, these parameters are optional. If you do not
specify accounting information, the VMS system uses
the default DECnet directory.
userid

is your user code.
This field contains thirty-nine
ASCII-7 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-7 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
This field contains thirty-nine
ASCII-7 characters.
If your account is less than
thirty-nine characters, left-justify the field.

7-17

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
STATUS CODES:
For COBOL programs, the OIL returns status codes in the dil-stat
variable defined by the OILINI routine.
For FORTRAN programs,
the OIL routines return status codes as an integer function
value.
OIL Name

Meaning

OIT-INVARG

You passed an incorrect or invalid
argument.

S8-NORMAL

The routine successfully completed
processing.

OIT-NETOPRFAIL

You attempted an impossible network
operation.

OIT-CHECKSUM

The network returned a network checksum error.

OIT-NOFILE

The file does not exist or is not
available to you.

OIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

7-18

TOPS-10 AND TOPS-20 REMOTE FILE ACCESS
7.4

TOPS-20 REMOTE FILE ACCESS EXAMPLES

7.4.1

TOPS-20 COBOL ReJaOte· File Access Exa.ple

IDENTIFICATION DIVISION.
PROGRAM-ID.
CDAP36.
This program opens a remote file named DAP.TST and writes an
ASCII record into it, closes the file,
reopens the file and
reads the record back and then closes the file again.
Note,
this program tries to write and read the file DAP.TST using a
directory called PS:(DIL-TEST>.
If this directory does not
exist, it must be created as a valid LOGIN directory.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
DECSYSTEM-20.
OBJECT-COMPUTER.
DECSYSTEM-20.
DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COPY DIT OF "SYS:DIL.LIB".
COPY DIL OF "SYS:DIL.LIB".

DILINI-PARAMETERS.

* Dilini is necessary for DECsystem-IO and DECSYSTEM-20 COBOL only.
05
05
05
05

DIL-INIT-STATUS PIC S9(10) COMPo
DIL-STATUS PIC S9(10) COMPo
DIL-MESSAGE PIC S9(10) COMPo
DIL-SEVERITY PIC S9(10) COMPo

* File and directory description fields
01
01
01
01

FILE-NAME PIC X(39) VALUE 'PS:(DIL-TEST)DAP.TST' DISPLAY-7.
USERID USAGE DISPLAY-7 PIC X(39) VALUE 'DIL-TEST'.
PASSWD USAGE DISPLAY-7 PIC X(39) VALUE SPACES.
ACCT USAGE DISPLAY-7 PIC X(39) VALUE SPACES.

* Record and file description fields
01
01
01

FILE-NUMBER USAGE COMP PIC S9(10).
RECORD-UNIT-SIZE USAGE COMP PIC S9(10) VALUE O.
RECORD-SIZE USAGE COMP PIC S9 (10) VALUE 100.

DATA-RECORD USAGE DISPLAY-7 PIC X(lOO).

7-19

TOPS-le ABD TOPS-20 R!ROTI FILE ACCESS

PROCEDURE DIVISION.

* Set up for status code values, using DILINI routine
ENTER MACRO DILINI USING DIL-INIT~STATUS, DIL-STATUS,
DIL-MESSAGE, DIL-SEVERITY.
IF DIL-INIT-STATUS NOT
1
DISPLAY"? Invalid return code from DILINI routine

DIL-INIT-STATUS.

* Request the password
DISPLAY" Enter the password:

WITH NO ADVANCING ACCEPT PASSWD.

* Open file DAP.TST for output
ENTER MACRO ROPEN USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIT-MODE-WRITE, DIT-TYPE-ASCII, DIT-RFM-STREAM,
DIT-RAT-UNSPECIFIED, RECORD-SIZE, RECORD-UNIT-SIZE.
DISPLAY" ROPEN Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? ROPEN: unsuccessful status return "
STOP RUN.

* Accept a record and write it to the file
DISPLAY" Enter data for the record for the remote file: "
ACCEPT DATA-RECORD.
ENTER MACRO RWRITE USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-SIZE, DATA-RECORD.
DISPLAY" RWRITE Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? RWRITE: unsuccessful status return. "
STOP RUN.

* Close the file
ENTER MACRO RCLOSE USING FILE-NUMBER, DIT-OPT-NOTHING.
DISPLAY" RCLOSE Status return: ", DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? RCLOSE: unsuccessful status return."
STOP RUN.

* Open the file to read the record
ENTER MACRO ROPEN USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIT-MODE-READ, DIT-TYPE-ASCII, DIT-RFM-STREAM,
DIT-RAT-UNSPECIFIED, RECORD-SIZE, RECORD-UNIT-SIZE.
DISPLAY" ROPEN Status return: ", DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? ROPEN: unsuccessful status return."
STOP RUN.

7-20

TOPS-lO AND TOPS-20 REMOTE FILE ACCBSS

* Read the record
MOVE SPACES TO DATA-RECORD.
ENTER MACRO RREAD USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-S:IZ E, DATA-RECORD.
DISPLAY" RREAD returned ", DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY "1 RREAD: unsuccesful status return."
STOP RUN.
DISPLAY" The record was: "
DISPLAY DATA-RECORD.

7.4.2

TOPS-20 FORTRAN Remote File Access Example

C FDAP36
C
C
C

C
C
C

This program opens a remote file named DAP.TST and writes an
ASCII record into it, closes the file,
reopens the file and
reads the record back and then closes the file again.
Note,
this program tries to write and read the file DAP.TST from a
directory called PS:<DIL-TEST).
If· this directory does not
exist, it must be created as a LOGIN directory.

C Use the OIL interface support files.
INCLUDE 'SYS:DITV7'
INCLUDE 'SYS:DILV7'
C File and directory description fields
INTEGER FILNAM (8), USERID (8), PASSWD (8), ACCT (8), FILNUM
C Sending and receiving data records
INTEGER DATAl (20), DATA2 (20)
C OIL Status code
INTEGER DILSTS

7-21

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
C Record size and record unit size
INTEGER RECSIZ, RUNTSZ
DATA FILNAM I'PS:(D', 'IL-TE',
1

'ST)DA',

'P.TST',

DATA USERID I'DIL-T' ,'EST

1
1

DATA PASSWD I'

DATA ACCT I'
1

C Program messages
200
201
202
203
700

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

('
('
('
('
('

ROPEN status return: ',112)
RWRITE status return: " 112)
RCLOSE status return: " 112)
RREAD status return: " 112)
? Invalid status returned ••• ')

C Request the password
100

FORMAT (' Enter the
WRITE (5,100)
FORMAT (8A5)
ACCEPT 105, PASSWD

105

pas~word:

C Open file DAP.TST for output
RUNTSZ
RECSIZ

0
100

DILSTS

ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT, MWRITE,
TASCII, FSTM, AUNSPC, RECSIZ, RUNTSZ)

WRITE (5,200) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 115
WRITE (5,700)
STOP
C Accept a record and write it to the file
110
115
120

FORMAT (' Enter data for the record:
WRITE (5,110)
FORMAT (20A5)
ACCEPT 120, DATAl
DILSTS

= RWRITE (FILNUM, RUNTSZ, RECSIZ, DATAl)

WRITE (5,201) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 125
WRITE (5,700)
STOP

7-22

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS

C Close the file
125

DILSTS

= RCLOSE (FILNUM, ONTHNG)

WRITE (5,202) DILSTS
IF (DILSTS .EO. NORMA~) GO TO 130
WRITE (5,700)
STOP
C Open the file to read the record
130

DILSTS

= ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT, MREAD,

TASCII, FSTM, AUNSPC, RECSIZ, RUNTSZ)
WRITE (5,200) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 135
WRITE (5,700)
STOP

C Read the record
135

DILSTS

= RREAD (FILNUM, RUNTSZ, RECSIZ, DATA2)

WRITE (5,203) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 145
WRITE (5,700)
STOP
140
145
146

FORMAT (' The record read was:
WRITE (5, 140)
FORMAT (' " 20A5)
WRITE (5,146) DATA2

C Close the file
DILSTS

= RCLOSE (FILNUM, ONTHNG)

WRITE (5,202) DILSTS
IF (DILSTS .EO. NORMAL) GO TO 155
WRITE (5,700)
STOP
150
155

FORMAT (' FDAP36 successful ')
WRITE (5,150)
STOP
END

7-23

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
7.5

TOPS-IO REMOTE FILE ACCESS EXAMPLES

7.5.1

TOPS-IO COBOL Remote File Access Example

IDENTIFICATION DIVISION.
PROGRAM-ID.
CDAP36.
This program opens a remote file named DAP.TST and writes an
ASCII record into it, closes the file, reopens the file and
reads the record back and then closes the file again. Note,
this program tries to write and read the file DAP.TST using a
directory called MYNODE:: [10,105].
If this directory does not
exist, it must be created as a valid LOGIN directory.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
DECSYSTEM-lO.
OBJECT-COMPUTER.
DECSYSTEM-lO.
DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COpy DIT OF "SYS:DIL,LIB".
COPY DIL OF "SYS:DIL,LIB".

DILINI-PARAMETERS.

* Dilini is necessary for DECsystem-lO and DECSYSTEM-20 COBOL only.
05
05
05
05

DIL-INIT-STATUS PIC S9(10) COMPo
DIL-STATUS PIC S9(10) COMPo
DIL-MESSAGE PIC S9(10) COMPo
DIL-SEVERITY PIC S9(10) COMPo

* File and directory description fields
01
01
01
01

FILE-NAME PIC X(39) VALUE IMYNODE::DAP.TST I DISPLAY-7.
USERID USAGE DISPLAY-7 PIC X(39) VALUE I [10,105] I .
PASSWD USAGE DISPLAY-7 PIC X(39) VALUE SPACES.
ACCT USAGE DISPLAY-7 PIC X(39) VALUE SPACES.

* Record and file description fields
01
01
01

FILE-NUMBER USAGE COMP PIC S9(10).
RECORD-UNIT-SIZE USAGE COMP PIC S9(10) VALUE O.
RECORD-SIZE USAGE COMP PIC S9(10) VALUE 95.

DATA-RECORD USAGE DISPLAY-7 PIC X(100).

7-24

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS
PROCEDURE DIVISION.

* Set up for status code values, using DILINI routine
ENTER MACRO DILINI USING DIL-INIT-STATUS, DIL-STATUS,
DI L-MESSAGE , DIL-SEVERITY.
IF DIL-INIT-STATUS NOT
1
DISPLAY"? Invalid return code from DILINI routine

DIL-INIT-STATUS.

* Request the password
DISPLAY" Enter the password:

WITH NO ADVANCING ACCEPT PASSWD.

* Open file DAP.TST for output
ENTER MACRO ROPEN USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIT-MODE-WRITE, DIT-TYPE-ASCII, DIT-RFM-STREAM,
DIT-RAT-UNSPECIFIED, RECORD-SIZE, RECORD-UNIT-SIZE.
DISPLAY" ROPEN Status return: n DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? ROPEN: unsuccessful status return "
STOP RUN.

* Accept a record and write it to the file
DISPLAY" Enter data for the record for the remote file: "
ACCEPT DATA-RECORD.
ENTER MACRO REWRITE USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-SIZE, DATA-RECORD.
DISPLAY" RWRITE Status return: " DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? RWRITE: unsuccessful status return, "
STOP RUN.

* Close the file
ENTER MACRO RCLOSE USING FILE-NUMBER,

DIT-O~T-NOTHING.

DISPLAY" RCLOSE Status return: ", DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY "1 RCLOSE: un<successful status return."
STOP RUN.

* Open the file to read the record
MOVE 100 TO RECORD-SIZE.
ENTER MACRO ROPEN USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIL-MODE-READ, DIT-TYPE-ASCII, DIT-RFM-STREAM,
DIT-RAT-UNSPECIFIED, RECORD-SIZE, RECORD-UNIT-SIZE.
DISPLAY" ROPEN Status return: ", DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY "1 ROPEN: unsuccessful status return."
STOP RUN.

7-25

TOPS-IO AND TOPS-20 REMOTE FILE ACCESS

* Read the record
MOVE SPACES TO DATA-RECORD.
ENTER MACRO RREAD USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-SIZE, DATA-RECORD.
DISPLAY" RREAD returned II, DIL-STATUS.
IF DIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY II? RREAD: unsuccessful status return. 1I
STOP RUN.
DISPLAY" The record was:
DISPLAY DATA-RECORD.

* Close the file
ENTER MACRO RCLOSE USING FILE-NUMBER, DIT-OPT-NOTHING.
OISPLAY " RCLOSE status return: II, DIL-STATUS.
IF OIL-SEVERITY NOT = STS-K-SUCCESS
AND DIL-SEVERITY NOT = STS-K-INFO
DISPLAY"? RCLOSE: unsuccessful status return. 1I
STOP RUN.
OISPLAY " COAP36 successful. "
STOP RUN.

7.5.2

TOPS-IO FORTRAN Remote File Access Example

C FDAP36
C
C
C

C
C
C

This program opens a remote file named DAP.TST and writes an
ASCII record onto it. Closes the file, reopens the file and
reads the record back and then closes the file again. Note,
this program tries to write and read the file DAP.TST from a
directory called MYNODE:: [10,105].
If this directory does not
exist, it must be created as a LOGIN directory.

C Use the DIL interface support files.
INCLUDE 'SYS:DITV7'
INCLUDE 'SYS:DILV7'
C File and directory description fields
INTEGER FILNAM (8), USERID (8), PASSWD (8), ACCT (8), FILNUM
C Sending and receiving data records
INTEGER DATAl (20), DATA2 (20)
C DIL Status code
INTEGER DILSTS

7-26

TOPS-10 AND TOPS-20 REMOTE FILE ACCESS

C Record size and record unit size
INTEGER RECSIZ, RUNTSZ
, E: : DA' , , P. TST' , ,
'/
DATA USERID /'10,10','5
,
'/
DATA PASSWD /'
,
'/
,
DATA ACCT /'
DATA FILNAM /' MYNOD' ,
1
1
1
1

,, ,

C Program messages
200
201
202
203
700

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

('
('
('
('
('

ROPEN status return: " 112)
RWRITE status return: ',112)
RCLOSE status return: I, 112)
RREAD status return: I, 112)
? Invalid status returned ••• ')

C Request the password
100

FORMAT (' Enter the password:
WRITE (5,100)
FORMAT (8A5)
ACCEPT 105, PASSWD

105

C Open file DAP.TST for output
RUNTSZ
RECSIZ

0
95

DILSTS

ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT, MWRITE,
TASCII, FSTM, AUNSPC, RECSIZ, RUNTSZ)

WRITE (5,200) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 115
WRITE (5,700)
STOP
C Accept a record and write it to the file
110
115
120

FORMAT (' Enter data for the record:
WRITE (5,110)
FORMAT (20A5)
ACCEPT 120, DATAl
DILSTS

= RWRITE (FILNUM, RUNTSZ, RECSIZ, DATAl)

WRITE (5,201) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 125
WRITE (5,700)
STOP

7-27

TOPS-10 AND TOPS-20 REMOTE FILE ACCESS
C Close the file
125

DILSTS

= RCLOSE (FILNUM, ONTHNG)

WRITE (5,202) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 130
WRITE (5,700)
STOP
C Open the file to read the record
130

RECSIZ

100

DILSTS

ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT, MREAD,
TASCII, FSTM, AUNSPC, RECSIZ, RUNTSZ)

WRITE (5,200) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 135
WRITE (5,700)
STOP
C Read the record
135

DILSTS

= RREAD (FILNUM, RUNTSZ, RECSIZ, DATA2)

WRITE (5,203) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 145
WRITE (5,700)
STOP
140
145
146

FORMAT (' The record read was:
WRITE (5, 140)
FORMAT (' " 20A5)
WRITE (5,146) DATA2

C Close the file
DILSTS

= RECLOSE (FILNUM, ONTHNG)

WRITE (5,202) DILSTS
IF (DILSTS .EQ. NORMAL) GO TO 155
WRITE (5,700)
STOP
150
155

FORMAT (' FDAP36 successful ')
WRITE (5,150)
STOP
END

7-28

CHAPTER 8
LINKING A TOP5-10/TOP5-20 PROGRAM

CHAPTER 8
LINKING A TOPS-IO/TOPS-20 PROGRAM

8.1

DECsystem-lO LINKAGE INSTRUCTIONS

The linker associates your program with the Data Interchange Library
routines called by the program. When you have successfully compiled
your program, link it by typing the following command sequence:
.R LINK
*PROG
*/SEGMENT:LOW/SEARCH SYS:DIL,#SYS:B361LB, #SYS:XPORT/EXCLUDE:XFUNCT/GO
EXIT
.SAVE PROG
where:

8.2

"PROG" is the name of your program.

DECSYSTEM-20 LINKAGE INSTRUCTIONS

The linker associates your program with the Data Interchange Library
routines that your program calls. When you have successfully compiled
your program, link it by typing the following command string:
@LINK
*USRPRG, SYS:DIL/SEARCH, SYS:XPORT/SEARCH/EXCLUDE:XFUNCT/GO
where:

8.3

"USRPRG" is the name of your program.

DECSYSTEM-IO AND DECSYSTEM-20 OVERLAY INSTRUCTIONS

If your program is very large, you may want to overlay the program.
For general information on overlaying programs, refer to the Link
Manual and the language specific manuals for your system.
When
building an overlay tree, you must include the following modules in
the root segment:
1.

.LOPEN (for Task-to-Task Routines)

.UPEVT (for Task-to-Task Routines)

XPNUTL (for Remote File Access Routines)

XPNPSI (for Remote File Access Routines)

8-1

CHAPTER 9
VMS DATA CONVERSION

9.1

DATA CONVERSION FROM VMS COBOL

The information included in this section assumes:
-You are writing a COBOL program
-You plan to use the program on a VMS system
To store an FFD, pass a record or perform an error check, you must
represent several data items in your program.
Users generally
allocate space for foreign fields and records in WORKING-STORAGE.

9.1.1

Including the Interface Support Files

On VMS systems, there are two different classes of Interface Support
files for each supported language. The first class of files includes
native VMS-type names for each of the various codes for VMS COBOL and
VMS FORTRAN.
The second class includes files with TOPS-IO/TOPS-20
COBOL compatible names for VMS COBOL, and files which include ANSI
Standard names for the interface to VMS FORTRAN. The Interface
Support files for VMS are provided as a text library called DIL.TLB.
This library includes the support files for both VMS COBOL and VMS
FORTRAN.
Native VMS COBOL
You can use the COBOL COPY verb to retrieve information from DIL.TLB
at compilation time. There are three library elements for Native VMS
COBOL in DIL.TLB.
The elements are DIL$COBOL, DIT$COBOL,
and
DIX$COBOL.
The library element DIL$COBOL defines general codes and
names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$COBOL.
Severity codes and
system codes are defined in element DIL$COBOL. To define these names
in
your
program,
include
the
following
statement in your
WORKING-STORAGE section after an Ol-level declaration:
COpy DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".
In the following example the DIL$COBOL
retrieved and included in your program:
01

element

Interface-files.
COPY DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

9-1

the

library

VMS DATA CONVERSION

The library element DIX$COBOL defines codes specific to the Data
Conversion Routines.
These codes include the DIX status codes which
are standard VMS condition values. Also included are data type names
for each supported data type. To define these names in your program,
include the following statement in your WORKING-STORAGE section after
an Ol-level declaration as described above for the DIL$COBOL element:
COPY DIX$COBOL OF "SYS$LIBRARY:DIL.TLB".
For programs which use the Data Conversion Routines with native VMS
names, you must include both the DIL$COBOL and DIX$COBOL library
elements.
TOPS-IO/TOPS-20 Compatible COBOL
If you want to write a program which can be easily transported to a
DECsystem-lO
or
a DECSYSTEM-20, you may want to include the
TOPS--IO/TOPS-20 compatible names in your program rather than the
native VMS names.
You can use the COBOL COpy verb to retrieve information from DIL.TLB
at
compilation
time.
There
are three library elements for
TOPS-IO/TOPS-20 compatible COBOL in DIL.TLB.
The elements
are
DIL$COBOL_20, DIT$COBOL_20, and DIX$COBOL_20.
The library element DIL$COBOL 20 defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)is defined in element DIL$COBOL 20. Severity codes and
system codes are defined in element DIL$COBOL-20.
To define these
names in your program,
include the following statement in your
WORKING-STORAGE section after an Ol-level declaration:
COPY DIL$COBOL 20 OF "SYS$LIBRARY:DIL.TLB".
In the following example, the DIL$COBOL_20 element of the
retrieved and included in your program:
01

library

Interface-files.
COPY DIL$COBOL 20 OF "SYS$LIBRARY:DIL.TLB".

The library element DIX$COBOL 20 defines codes specific to the data
conversion routines.
The codes include the DIX status codes in the
compatible COBOL
format
which
provides
only
the
condition
identification portion of the status code. Also included are data
type names for each supported data type. To define these names in
your program, include the following statement in your WORKING-STORAGE
section after an Ol-level declaration as shown above for
the
DIL$COBOL 20 element:
COPY DIX$COBOL 20 OF "SYS$LIBRARY:DIL.TLB".
For programs which use the data conversion routines with
compatible
names,
you must include both the DIL$COBOL 20
DIX$COBOL 20 library elements.

9-2

the
and

VMS DATA CONVERSION
9.1.2

Storing an FFD

The FFD occupies three full longwords of VMS memory. To store an
you must define a data item with the following format:
01

your-ffd.
03 your-ffd-tbl

FFD

PIC S9(9) USAGE COMPUTATIONAL OCCURS 3.

When you call the DIX$MAK DES DET routine to build the FFD, use
your-ffd-tbl as the FFD- to be returned.
To pass the FFD to the
routine, pass your-ffd-tbl with the subscript 1: your-ffd-tbl (1).

9.1.3

Passing a Record to the DIX$MAK_DES_DET Routine

To pass a record to the DIX$MAK DES DET routine, you must know how the
record (containing the field- that you want to convert) would be
declared on its native system. You must then represent the record in
your program on the local system. The record can be represented as
any word-aligned group level data item.
To pass the record to
DIX$MAK DES DET, specify this group item as the record name ("rec") in
the call to-DIX$MAK_DES_DET.
To figure the size of the record, count the number of bits on its
native system: make the record name on the foreign system at least
that large. In the following example, the VAX/VMS record "rec"
contains 640 bits of information.
01

rec

PIC S9(9)

USAGE COMPUTATIONAL OCCURS 20 TIMES.

To pass "rec" to the DIX$MAK_DES_DET routine simply include it in your
call to the routine.
CALL "DIX$MAK DES DET" USING ffd (1), rec, sysor, bysiz, byoff,
bioff, type,-lngth, scale GIVING stat.

9.1.4

Checking for Errors

A call to the Data Conversion Routines from VMS COBOL looks
following example:

the

CALL "DIX$MAK DES DET" USING ffd (1), rec, sysor, bysiz, byoff,
bioff, type,-lngth, scale GIVING stat.
"Stat", used above, is a standard VMS condition value
defined as:
01

stat

and

should

PIC S9(9) USAGE COMPUTATIONAL.

The routine performs the error check and places the resultant status
value into the data item stat. The following example shows a simple
error check:
CALL "DIX$MAK DES DET" USING ffd (1), rec, sysor, bysiz, byoff,
bioff, type,-lngth, scale GIVING stat.
IF stat IS FAILURE
THEN DISPLAY "failure".

9-3

VMS DATA CONVERSION
On VMS systems, the LIB$MATCH COND function is available to compare
two status codes and determine if they refer to the same condition.
See the most recent version of the VAX-II Run-Time Library Reference
Manual for further information.
Using LIB$MATCH COND, you can compare "stat" to the DIX status values
defined in the DIL Interface Support files to identify which error
occurred.
NOTE
If you are using the TOPS-lO/TOPS-20 Compatible COBOL
Interface Support files, you cannot use LIB$MATCH COND
to compare the status codes.
Use the error checking
procedure
described in the TOPS-lO/TOPS-20 COBOL
section of this manual.

9.2

DATA CONVERSION FROM VMS FORTRAN

The information included in this section assumes
-You are writing a FORTRAN program
-You plan to use the program on a VMS system
The section explains methods to store a Foreign Field Descriptor, pass
a record to the conversion routines and perform an error check.

9.2.1

Including the Interface Support Files

VMS systems have two different classes of Interface Support files for
each supported language.
The first class of files includes native
VMS-type names for each of the various codes for VMS COBOL and VMS
FORTRAN.
The second class includes files with TOPS-lO/TOP8-20 COBOL
compatible names for VMS COBOL, and files which include ANSI Standard
names for the interface to VMS FORTRAN. The Interface Support files
for VMS are provided as a text library called DIL.TLB.
This library
includes the support files for both VMS COBOL and VMS FORTRAN.
Native VMS FORTRAN
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
native VMS FORTRAN in DIL.TLB.
The elements are
DIL$FORTRAN,
DIT$FORTRAN, and DIX$FORTRAN.
The library element DIL$FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(S8-NORMAL)
is defined in element DIL$FORTRAN. Severity codes and
system codes are defined in element DIL$FORTRAN.
To define these
names in your program, include the statement:
INCLUDE '8YS$LIBRARY:DIL.TLB (DIL$FORTRAN)'
This retrieves the DIL$FORTRAN
includes it in your program.

element

9-4

the

library

file

and

VMS DATA CONVERSION
The library element DIX$FORTRAN defines codes specific to the Data
Conversion Routines. The codes include the DIX status codes which are
standard VMS condition values. Also included are data type names for
each supported data type.
To define these names in your program,
include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIX$FORTRAN)'
For programs which use the Data Conversion routines with the native
VMS names, you must include both the DIL$FORTRAN and DIX$FORTRAN
library elements.
ANSI Standard Compatible FORTRAN
If you want to write a program which can be easily transported to
another system, you may want to include the ANSI Standard FORTRAN
names in your program rather than the native VMS names.
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
ANSI Standard FORTRAN in DIL.TLB. The elements are DIL$ANSI FORTRAN,
DIT$ANSI_FORTRAN, and DIX$ANSI_FORTRAN.
The library element DIL$ANSI FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$ANSI FORTRAN. Severity codes
and system codes are defined in element DIL$ANSI FORTRAN.
To define
these names in your program, include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$ANSI_FORTRAN)'
This retrieves the DIL$ANSI_FORTRAN element of the
includes it in your program.

library

file

and

The library element DIX$ANSI FORTRAN defines codes specific to the
Data Conversion Routines.
The codes include the DIX status codes
which are standard VMS condition values. Also included are data type
names for each supported data type. To define these names in your
program, include the following statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIX$ANSI_FORTRAN)
For programs which use the data' conversion routines with
the
compatible names, you must include both the DIL$ANSI FORTRAN and
DIX$ANSI_FORTRAN library elements.

9.2.2

Storing an FFD

The FFD occupies three full longwords of VMS memory. To store an FFD,
you must first dimension an array of type integer with length 3.
INTEGER

dilffd

(3)

When you call the DIX$MAK DES DET routine to build an FFD, use dilffd
as the value for the FFD to be returned. To pass this value to the
routine, always pass the entire array, specifying just the variable
name, dilffd, not the array entry dilffd (1).

9-5

VMS DATA CONVERSION
9.2.3

Passing a Record to the Data Conversion Routines

To convert a field in a record, you must know how that field is
represented on both its own system and the system where you plan to
use the converted field.
You create a space for the record on the
local system by declaring an integer array big enough to contain the
record. To figure the array size, count the number of bits used by
the record on its native system; make the array on the local system at
least that large.
In the following example, this VAX/VMS record
contains 640 bits of information:
INTEGER

rec

(20)

To pass the record to one of the Data Conversion Routines, pass the
entire array.
The example, below, shows rec being passed to the
DIX$MAK- DES - DET routine.
status
1

9.2.4

DIX$MAK DES DET (ffd, rec, sysor, bysiz, byoff, bioff,
type, Ingth; scale)

Checking for Errors

The Data Conversion Routines return a status value when called.
To
perform an error check on a Data Conversion Routine, first declare an
integer where the routine can place a status value.
INTEGER

status

A simple call with an error check might then be:
status = DIX$MAK DES DET (ffd, rec, sysor, bysiz, byoff, bioff
1
type, Ingth~ scale)
IF (status .NE. SS$_NORMAL) GOTO 100

100
101

TYPE 101
FORMAT (' error occurred')

On VMS systems, the LIB$MATCH COND function is available to compare
two status codes and determine if they refer to the same condition.
See the most recent version of the VAX-II Run-Time Library Reference
Manual for further information.
Using LIB$MATCH COND you can compare status to the DIX status values
defined in the-VMS FORTRAN Interface Support file, to determine which
error occurred. Note that SS$ NORMAL, used above,
is ~he success
status defined in the VMS FORTRAN Interface Support files.

9-6

VMS DATA CONVERSION
9.3

VMS DATA CONVERSION REFERENCE

9.3.1

DIX$MAK_DES_DET - Create an FFD

PURPOSE:
The DIX$MAK DES DET routine reads the detailed
description
information - which
you
supply and builds a Foreign Field
Descriptor for a native or foreign field.
CALL FORMAT:
COBOL:

CALL "DIX$MAK DES DET" USING ffd (1), rec, sysor,
bysiz, byoff; bioff, type, lngth, scale GIVING
stat.
-

FORTRAN:

status = DIX$MAK DES DET (ffd, rec, sysor, bysiz,
1 byoff, bioff, type; lngth, scale)

where:
ffd

is the Foreign Field Descriptor to be returned.
This
argument is the data item where the routine places the
resultant FFD. A Foreign Field Descriptor consists of
three one-word integers.

rec

is the record that contains the field being described.

sysor

COBOL:

This argument can be
item.

FORTRAN:

This argument is usually an integer array.

any

word-aligned

data

is a long integer that gives the system of origin of
the field to be converted. OIL Names that can be used
for this argument are:
SYS-IO-20

for a- record
TOPS-20.

defined

for

TOPS-IO

for a record defined for VMS.
bysiz

is a long integer that gives the byte size of the
record for this call to DIX$MAK DES DET.
All VMS
records have a byte size of 8. A TOPS-IO or TOPS-20
COBOL record can have a byte size of 6, 7, 9 or 36. A
TOPS-IO or TOPS-20 FORTRAN record can have a byte size
of 7 or 36. See Appendix A for further information.

byoff

is a long integer that gives the byte offset to the
field within the record. The byte offset is the number
of bytes in the record (of the size specified in
"bysiz") that precede the field that you want to
convert.

bioff

is a long integer that gives the bit offset.
This
argument is not currently necessary; it should always
be zero.

9-7

VMS DATA CONVERSION
type

is a long integer that gives the data type of the field
that is being converted. See Appendix A for a list of
valid data type codes.

lngth

is a long integer that gives the length of the field:
in characters for string fields.
This argument is
required for some data types, it must be zero for all
other
data
types.
See Appendix A for further
information.

scale

is a long integer that gives the scale factor of a
fixed-point binary field.
This argument tells how many
decimal places the decimal point should be moved to the
left.
A negative scale factor means that you want to
move the decimal point to the right. You must specify
a scale factor for fixed-point conversions.
Do not
specify scale factor for any other type of field.

STATUS CODES:
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-INVBYTSIZ

Invalid byte size specified.

RELATED ROUTINES:
DIX$BY DET:

This routine allows you to convert a field without
making a Foreign Field· Descriptor for the field.
See Section 9.3.3 for a description of DIX$BY_DET.

9-8

VMS DATA CONVERSION
DIX$BY_DIX_DES - Perform General Conversion

9.3.2

PURPOSE:
The DIX$BY DIX DES routine performs any type of
that can be done by the DIL.

data

conversion

DIX$BY DIX DES is a general purpose routine.
DIX$BY DIX DES
accepts a Foreign Field Descriptor for the source and destination
fields.
If the DIL has the capability to convert that type of
field, DIX$BY_DIX_DES converts the field.
CALL FORMAT:
COBOL:

CALL "DIX$BY DIX DES USING" sffd (1), dffd (1)
GIVING stat.-

FORTRAN:

status

where:
sffd

is a Foreign Field Descriptor describing the source
field.
A Foreign Field Descriptor consists of three
long integers.

dffd

is a
Foreign
Field
Descriptor
describing
the
destination field. A Foreign Field Descriptor consists
of three long integers.

9-9

VMS DATA CONVERSION
STATUS CODES:
Meaning

DIL Name
DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-INVALCHAR

Invalid character in source field or
conversion table.

DIX-GRAPHIC

Graphic character changed in conversion.

DIX-FMTLOST

Format effector gained or lost in
conversion.

DIX-NONPRINT

Non-printing character gained or lost
in conversion.

DIX-TRUNC

String too long for destination -truncated.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

DIX-ROUNDED

Result is rounded.

DIX-UNNORM

Floating-point number improperly
normalized.

DIX-INVDNUMCHR

Invalid display numeric character
in source field.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

RELATED ROUTINES:
DIX$BY DET:

This routine allows you to convert a field without
making a Foreign Field Descriptor for the field.
See Section 9.3.3 for a description of DIX$BY_DET.

9-10

VMS DATA CONVERSION
9.3.3

DIX$BY_DET - Convert a Field Without an FFD

PURPOSE:
The DIX$BY DET routine allows you to convert a field without
making an- FFD for the field.
DIX$BY DET requires a detailed
series of arguments; you must specify parameters for both the
source and destination fields.
You should only use DIX$BY DET in cases where the field will be
converted
a
limited
number of times or the program is
table-driven. DIX$BY DET creates a description for the field
each time it processes the field.
If you plan to convert a field
many times during a run, it is quicker to create an FFD for the
field and convert it with one of the other single function
conversion routines.
Whereas
DIX$BY DET
creates
an
FFD
internally each time it processes, if you perform the conversion
with an FFD (built using the DIX$MAK DES DET routine) you make
the FFD only once.
CALL FORMAT:
COBOL:

CALL "DIX$BY DET" USING srec, ssysor, sbysiz, sbyoff,
sbioff,-stype, slength, sscale, drec, dsysor,
dbysiz, dbyoff, dbioff, dtype, dlngth, dscale
GIVING stat.

FORTRAN:

status = DIX$BY DET (srec, ssysor, sbysiz, sbyoff,
1 sbioff, stype, slength, sscale, drec, dsysor,
2 dbysiz, dbyoff, dbioff, dtype, dlngth, dscale)

where:
srec

ssysor

sbysiz

is the source record
described.

that

contains

the

field

being

word-aligned

data

COBOL:

This argument can be
item.

FORTRAN:

This argument is usually an integer array.

any

is a long integer that gives the system of origin of
the
source record.
Possible DIL Names for this
argument are:
SYS-IO-20

for a record
TOPS-20.

SYS-VMS

for a record defined for VMS.

defined

for

TOPS-IO

is a long integer that gives the byte size of the
source record for this call to the DIX$BY DET routine.
All VMS records have a byte size of 8.
A- TOPS-IO or
TOPS-20 COBOL record can have a byte size of 6, 7, 9 or
36. A TOPS-IO or TOPS-20 FORTRAN record can have a
byte size of 7 or 36.
See Appendix A for further
information.

9-11

VMS DATA CONVERSION
sbyoff

is a long integer that gives the byte offset to the
field within the source record. The byte offset is the
number of bytes in the source record
(of the size
specified in "sbysiz") that precede the field which you
want to convert.

sbioff

is a long integer that gives the bit offset.
This
argument is not currently used; it should always be
zero.

stype

is a long integer that gives the data type of the
source field.
See Appendix A for a list of valid data
type codes.

slngth

is a long integer that
indicates the length of the
source field:
in characters for string fields.
This
argument is required for some data types,
it must be
zero for all other data types.
See Appendix A for
further information.

sscale

is a long integer that gives the scale factor of the
source field.
It indicates the number of decimal
places to move the decimal point to the left.
A
negative scale factor means that the decimal point will
be moved to the right.
You must specify a scale factor
if you want to convert a fixed-point field.
Specify
zero for all other classes of data.

drec

is the record that contains the record to be described.
This argument is a long integer.
COBOL:
FORTRAN:

dsysor

This argument can be any word-aligned data
item.
This argument will usually be an integer
array.
You can pass either the whole array
or an element of the array.

is a long integer that gives the system of origin of
the destination record.
Possible OIL Names for this
argument are:
SYS-10-20

for a
record
TOPS-20.

SYS-VMS

for a record defined eor VMS.

defined

for

TOPS-IO

dbysiz

is a long integer that gives the byte size of the
destination record for this call to OIX$BY OET. All
VMS records have a
byte size of 8.
A TOPS-IO or
TOPS-20 COBOL record can have a byte size of 6, 7, 9 or
36. A TOPS-10 or TOPS-20 FORTRAN record can have a
byte size of 7 or 36.
See Appendix A for further
information.

dbyoff

is a long integer that gives the byte offset of the
destination record.
The byte offset is the number of
bytes in the record (of the size specified in "dbysiz")
that precede the field that you want to convert.

dbioff

is a long integer that gives the bit offset.
This
argument is not currently necessary; it should always
be zero.

9-12

VMS DATA CONVERSION

dtype

is a long integer that gives the data type of the
destination field.
See Appendix A for a list of valid
data type codes.

dlngth

is a long integer that gives the length of the
destination field:
in characters for string fields.
This argument is required for some data types, it must
be zero for all other data types. See Appendix A for
further information.

dscale

is a long integer that gives the scale factor of the
destination field.
It indicates the number of decimal
digits to move the decimal point to the left.
A
negative scale factor means that the decimal point will
be moved to the right. You must specify a scale factor
if you want to convert a fixed-point field. Specify
zero for all other classes of data.

9-13

VMS DATA CONVERSION
STATUS CODES:
DIL Name

Meaning

DIX-INVDATTYP

Invalid data type code.

DIX-INVLNG

Length invalid or unspecified.

DIX-INVSCAL

Scale factor invalid or unspecified.

DIX-UNKSYS

Unknown system of origin specified.

DIX-ALIGN

Invalid alignment for data type.

DIX-INVBYSIZ

Invalid byte size specified.

DIX-INVALCHAR

Invalid character in source field or
conversion table.

DIX-GRAPHIC

Graphic character changed in conversion.

DIX-FMTLOST

Format effector gained or lost in
conversion.

DIX-NONPRINT

Non-printing character gained or lost
in conversion.

DIX-TRUNC

String too long for destination
truncated.

DIX-TOOBIG

Converted source field too large for
destination field.

DIX-UNSIGNED

Negative value moved to unsigned
field.

DIX-ROUNDED

Result is rounded.

DIX-UNNORM

Floating-point number improperly normalized.

DIX-INVDNUMCHR

Invalid display numeric character
in source field.

DIX-INVDNUMSGN

Invalid display numeric sign in
source field.

DIX-INVPDDGT

Invalid packed decimal digit in
source field.

DIX-INVPDSGN

Invalid packed decimal sign in
source field.

RELATED ROUTINES:
DIX$MAK_DES_DET:

This routine builds an FFD for the field that
you wish to convert. See Section 9.3.1 for a
description of DIX$MAK_DES_DET.

9-14

VMS DATA CONVERSION
9.4

VMS DATA CONVERSION EXAMPLES

9.4.1

VMS COBOL Data Conversion Example

IDENTIFICATION DIVISION.
PROGRAM-ID.
CDCR32.
This program performs a single string data conversion. The
ASCII-8 string value "ABCDE" will be converted to the same
ASCII-7 value.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
VAX-II.
OBJECT-COMPUTER.
VAX-II.
DATA DIVISION.
WORKING-STORAGE SECTION.

* source data field
01

SRCDAT PIC X(5) USAGE DISPLAY VALUE "ABCDE".

* The destination data field must be large enough to hold the ASCII-8

* equivalent of the source data field:
* ASCII-8 PIC X(5) = 8 bits/character * 5 characters
* ASCII-7 PIC X(5) = 7 bits/character * 5 characters
01

DESTINATION-DATA.
02 DSTDAT PIC S9(9) COMP OCCURS 2.

* foreign field descriptors
01

FFDS.
05 SRCFFD PIC S9(9) COMP OCCURS 3.
05 DSTFFD PIC S9(9) COMP OCCURS 3.

INTERFACE-FILES.
COPY DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".
COPY DIX$COBOL OF "SYS$LIBRARY:DIL.TLB".

* Dix call parameters.
01
01
01
01
01
01
01
01
01

DIX-SYS PIC S9(9) COMPo
DIX-DT PIC S9(9) COMPo
DIX-BYSZ PIC S9(9) COMPo
DIX-BYO PIC S9(9) COMPo
DIX-BTO PIC S9(9) COMP VALUE O.
DIX-LEN PIC S9(9) COMPo
DIX-SCAL PIC S9(9) COMPo
DIL-DISPLAY PIC X(9).
DIL-STATUS PIC S9(9) COMPo

9-15

40 bits
35 bits

VMS DATA CONVERSION
PROCEDURE DIVISION.
INITIALIZE-STUFF.

* initialize destination buffer to zeros
MOVE 0 TO DSTDAT(l).
MOVE 0 TO DSTDAT(2).
MAKE-FFDS.
MOVE
MOVE
MOVE
MOVE

7 TO OIX-BYSZ.
0 TO DIX-BYO.
5 TO DIX-LEN.
0 TO DIX-SCAL.

CALL "DIX$MAK_DES_DET" USING DSTFFD(l), DSTOAT(l}, DIX$K SYS 10 20,
DIX-BYSZ, DIX-BYO, OIX-BTO,-OIX$K DT ASCII 7, DIX-LEN, OIX-SCAL
GIVING OIL-STATUS. IF DIL-STATUS IS NOT SUCCESS
MOVE OIL-STATUS TO OIL-OISPLAY
DISPLAY"? Failure in OIX$MAK OES DET.
MOVE
MOVE
MOVE
MOVE

Oil-status

" DIL-DISPLAY.

8 TO OIX-BYSZ.
0 TO DIX-BYO.
5 TO DIX-LEN.
0 TO OIX-SCAL.

CALL "OIX$MAK_DES_OET" USING SRCFFO(l), SRCDAT, OIX$K SYS VAX,
DIX-BYSZ, DIX-BYO, OIX-BTO, DIX$K DT ASCII 8, DIX-LEN, OIX-SCAL
GIVING OIL-STATUS. IF OIL-STATUS IS NOT SUCCESS
MOVE OIL-STATUS TO OIL-DISPLAY
DISPLAY"? Failure in OIX$MAK_DES DET.

Oil-status

" OIL-OISPLAY.

DO-CONVERSION.
* Convert ASCII-8 value "ABCDE" to ASCII-7 value "ABCDE".
CALL "DIX$BY DIX DES" USING SRCFFD(l), DSTFFD(l}
GIVING OIL-STATUS.
IF DIL-STATUS IS NOT SUCCESS
MOVE DIL-STATUS TO OIL-OISPLAY
DISPLAY"? Failure in DIX$BY_OIX_DES.
CHECK-RESULTS.

9-16

Oil-s.tatus

" DIL-OISPLAY.

VMS DATA CONVERSION

* What should have been created is the TOPS-10/TOPS-20 form of the
* source value "ABCDE".
** In DEC-10/DEC-20 memory this looks like the following:
*
**
numeric (binary) representation:
symbolic representation:
110000011000010100001110001001000101 1 :m
* IAAAAABBBBBCCCCCDDDDDEEEEE 1 :m
** Transposing this into VAX memory we have:
numer ic (binary) representation:
*
symbolic representation:
11000101 1 :n
*
1EEEEEEE 1 : n
1110001001 : n+1
*
ICDDDDDDDI :n+l
1101000011 :n+2
*
IBBCCCCCCI :n+2
1001100001 :n+3
*
IAAABBBBBI :n+3
1
10001 :n+4
*
1
AAAAI :n+4
** if you consider the numeric values as longwords in VAX memory:
* 1001100001010000111000100100010101 :n
* 1000000000000000000000000000010001 :n+4
*

decimal equivalent:
1 815907978 1 :n
1
8
1 :n+4

*
*
*
*

IF DSTDAT(l) NOT = 815907978
DISPLAY"? Error (n conversion:
"
DISPLAY " expected converted value not returned from conversion"
STOP RUN.
IF DSTDAT(2) NOT = 8
DISPLAY"? Error in conversion:
"
DISPLAY " expect~d converted value not returned from conversion"
STOP RUN.
DISPLAY" CDCR32 successfully completed.".
STOP RUN.

9.4.2

VMS FORTRAN Data Conversion Example

C FDCR32
C
This program performs a single string data conversion.
C
ASCII-8 string value "ABCDE" will be converted to the
C
ASCII-7 value.
C Include interface support files
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$ANSI FORTRAN)'
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIX$ANSI=FORTRAN)'

The
same

C Source and destination data fields.
C NOTE: The destination data field must be large enough to hold the
C ASCII-8 equivalent of the source data field:
C
ASCII-8 (5 chars) = 8 bits/character * 5 characters
40 bits
C
ASCII-7 (5 chars) = 7 bits/character * 5 characters = 35 bits
INTEGER SRCDAT (2), DSTDAT (2)

9-17

VMS DATA CONVERSION
C Foreign field descriptors (ffds)
INTEGER SRCFFD (3), DSTFFD (3)
C Status return code
INTEGER DILSTS
C Data for source and destination data fields
DATA SRCDAT I'ABCD', 'E
'I
DATA DSTDAT 10, 01
C make the foreign field descriptors for use by DIX$BY_DIX_DES
DILSTS = DIX$MAK DES DET (SRCFFD, SRCDAT, SYSVAX, 8, 0, 0,
1
ASCII8, 5, oT
IF (DILSTS.NE.NORMAL) GOTO 100
DILSTS = DIX$MAK DES DET (DSTFFD, DSTDAT, SYS36, 7, 0, 0,
1
ASCII7, 5, 0)
IF (DILSTS.NE.NORMAL) GOTO 100
C Do conversions: convert ASCII-8 value "ABCDE" to ASCII-7 value ftABCDE"
DILSTS = DIX$BY DIX DES (SRCFFD, DSTFFD)
IF (DILSTS.NE.NORMAL) GOTO 102
C Check results:
C What should have been created is the TOPS-10/TOPS-20 form of the
C source value "ABCDE".
C
C In DEC-10/DEC-20 memory this looks like the following:
C
C
symbolic representation:
numer ic (binary) representa tion:
C
110000011000010100001110001001000101
C IAAAAABBBBBCCCCCDDDDDEEEEE I :m
C

Transposing this into VAX memory we have:
symbolic representation:
numeric (binary) representation:
C
I EEEEEEE I : n
11000101 I :n
I CDDDDDDD I : n+1
111000100 I :n+1
C
1101000011 : n+2
C
I BBCCCCCC I : n+2
IAAABBBBBI :n+3
100110000 I :n+3
C
C
I
AAAAI :n+4
I
10001 :n+4
C

C
C if you consider the binary values as longwords in VAX memory:
C 100110000101~000111000100100010101 :n
C 1000000000000000000000000000010001 :n+4
C
decimal equivalent:
C
C
I 815907978 I :n
C
C

200

I :n+4

IF (DSTDAT (1) .NE. 815907978) GOTO 104
IF (DSTDAT (2) • NE. 8) GOTO 104
FORMAT (' FDCR32 successfully completed.')
WRITE (6, 200)
STOP

9-18

I :m

VMS DATA CONVERSION
C Print error information
100
WRITE (6, 101) OILSTS
101
FORMAT (' ? Failure in XOESCR. Oil-status
STOP

I10)

102
103

WRITE (6, 103) DILSTS
FORMAT ('? Failure in XCVST.
STOP

104
105

WRITE (6, 105)
FORMAT ('? Error in conversion:')
WRITE (6, 106)
FORMAT (' expected converted value not returned from conversion')
STOP

106

Oil-status

ENO

9-19

I10)

CHAPTER 10
VMS TASK-TO-TASK

10.1

TASK-TO-TASK FROM VMS COBOL

The information included in this section assumes
-You are writing a COBOL program
-You plan to use the program on a VMS system
To store a Network Logical Name,
task characteristics or user
attributes,
to send data or to perform a status check you must
Users generally,
but
represent several data items in your program.
these
data
items in
not
necessarily,
allocate
space
for
WORKING-STORAGE.

10.1.1

Including the Interface Support Files

VMS systems have two different classes of Interface Support files for
each supported language.
The first class of files include native
VMS-type names for each of the various codes for VMS COBOL and VMS
FORTRAN.
The second class includes files with TOPS-IO/TOPS-20 COBOL
compatible names for VMS COBOL, and files which include ANSI Standard
names for the interface to VMS FORTRAN. The Interface Support files
for VMS are provided as a text library called DIL.TLB.
This library
includes the support files for both VMS COBOL and VMS FORTRAN.
Native VMS COBOL
You can use the COBOL COPY verb to retrieve information from DIL.TLB
at compilation time. There are three library elements for native VMS
COBOL in DIL.TLB.
The elements are DIL$COBOL, DIT$COBOL,
and
DIX$COBOL.
The library element DIL$COBOL defines general codes and
names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$COBOL.
Severity codes and
system codes are defined in element DIL$COBOL. To define these names
in
your
program,
include
the
following
statement in your
WORKING-STORAGE section after an Ol-level declaration:
COpy DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

10-1

VMS TASK-TO-TASK

In the following example, the DIL$COBOL
retrieved and included in your program:
01

element

the

library

interface-files.
COPY DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

The library element DIT$COBOL defines codes
specific
to
the
Task-to-Task and Remote File Access Routines. The codes include the
DIT status codes, which are standard VMS condition values.
Also
included
are Task-to-Task wait codes, Task-to-Task link types,
Task-to-Task message modes and VMS task fire-up codes.
To define
these names in your program, include the following statement in your
WORKING-STORAGE section after an Ol-level declaration as described
above for the DIL$COBOL element:
COpy DIT$COBOL OF "SYS$LIBRARY:DIL.TLB".
For programs which use the Task-to-Task routines with the native VMS
names, you must include both the DIL$COBOL and DIT$COBOL library
elements.
TOPS-IO/TOPS-20 Compatible COBOL
If you want to write a program that can be easily transported to a
DECsystem-lO
or
a DECSYSTEM-20, you may want to include the
TOPS-IO/TOPS-20 compatible names in your program rather than the
native VMS names.
You can use the COBOL COPY verb to retrieve information from DIL.TLB
at
compilation
time.
There
are three library elements for
TOPS-IO/TOPS-20 compatible COBOL in DIL.TLB.
The elements
are
DIL$COBOL_20, DIT$COBOL_20, and DIX$COBOL_20.
The library element DIL$COBOL 20 defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$COBOL 20. Severity codes and
system codes are defined in element DIL$COBOL-20.
To define these
names in your program,
include the follo;ing statement in your
WORKING-STORAGE section after an Ol-level declaration:
COPY DIL$COBOL 20 OF "SYS$LIBRARY:DIL.TLB".
n the following example, the DIL$COBOL 20 element of
retrieved and included in your program:
1

interface-files.
COPY DIL$COBOL 20 OF "SYS$LIBRARY:DIL.TLB".

10-2

the

library

VMS TASK-TO-TASK
The library element DIT$COBOL 20 defines codes specific to the
Task-to-Task and Remote File Access Routines. This includes the DIT
status codes, in the compatible COBOL format which provides only the
condition identification portion of the status code. Also included
are Task-to~Task wait codes, Task-to-Task link types, Task-to-Task
message modes and VMS task fire-up codes. To define these names in
your program, include the following statement in your WORKING-STORAGE
section
after an Ol-level declaration as shown above for the
DIL$COBOL_20 element:
COpy DIT$COBOL_20 OF "SYS$LIBRARY:DIL.TLB".
For programs which use the Task-to-Task routines with the compatible
names, you must include both the DIL$COBOL 20 and DIT$COBOL 20 library
elements.

10.1.2

Storing a Network Logical Name

The NLN occupies one longword of VMS memory. To store
must define a data item with the fo~lowing format:
01

your-nln

NLN,

you

PIC S9(9) COMPUTATIONAL.

When you call the DIT$NFOPA, DIT$NFOPB, DIT$NFOP8 or DIT$NFOPP routine
to create the NLN, use your-nln as the value for NLN to be returned.
When the routine successfully finishes processing, it returns a value
to your-nln.

10.1.3

Storing Task and User Attributes

To include task and user attributes in a call to DIT$NFOPA, DIT$NFOPB
or DIT$NFOP8 or task attributes in a call to DIT$NFOPP you must
These
describe these attributes as data items in WORKING-STORAGE.
attributes must always be DISPLAY items with a length of PIC X(16) or
PIC X(39), as shown below:
01
01
01
01
01
01
01

10.1.4

target-name
object-type
desc-name
task-name
userid
passwd
acct

PIC X(16)
PIC X(16)
PIC X(16)
PIC X(16)
PIC X(39)
PIC X(39)
PIC X(39)

USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE

DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.
DISPLAY.

Checking the Status of a Task-to-Task Routine

Section 9.1.4 explains how to check the status of a DIL
VMS COBOL.
A simple call to the Task-to-Task Routines from
error check, looks like the following example:

VMS

Routine

COBOL,

with

from
an

CALL "DIT$NFOPA" USING nln, trgsys, objtyp, desc, tsknam, userid,
passwd, acct, usdat, wait GIVING status.
IF status is FAILURE
THEN DISPLAY "error occurred".

10-3

VMS TASK-TO-TASK
10.2

TASK-TO-TASK FROM VMS FORTRAN

The information included in this section assumes
-You are writing a FORTRAN program
-You plan to use the program on a VMS system
This section explains how
characteristics or user
status check.

10.2.1

to store a Network
attributes, to send

Logical Name, task
data or to perform a

Including the Interface Support Files

VMS systems have two different classes of Interface Support files for
each supported language. The first class of files include native VMS
type names for each of the various codes for VMS COBOL and VMS
FORTRAN.
The second class includes files with TOPS-10/TOPS-20 COBOL
compatible names for VMS COBOL, and files that include ANSI Standard
names for the interface to VMS FORTRAN. The Interface Support files
for the VMS are provided as a text library called DIL.TLB.
The
library includes the support files for both VMS COBOL and VMS FORTRAN.
Native VMS FORTRAN
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
native VMS FORTRAN in DIL.TLB.
The elements are
DIL$FORTRAN,
DIT$FORTRAN, and DIX$FORTRAN.
The library element DIL$FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$FORTRAN. Severity codes and
system codes are defined in element DIL$FORTRAN.
To define these
names in your program, include the following statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$FORTRAN),
This retrieves the DIL$FORTRAN element of the library file
system area SYS$LIBRARY and includes it in your program.

from

the

The library element DIT$FORTRAN defines codes specific to
the
Task-to-Task and Remote File Access Routines. This includes the DIT
status codes, which are standard VMS condition values. Also included
are Task-to-Task wait codes, Task-to-Task link types, Task-to-Task
message modes and VMS task fire-up codes. To define these names in
your program, include the following statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$FORTRAN)'
For programs which use the Task-to-Task routines with the native VMS
names, you must include both the DIL$FORTRAN and DIT$FORTRAN library
elements.

10-4

VMS TASK-TO-TASK
ANSI Standard Compatible FORTRAN
If you want to write a program that can be easily transported to
another system, you may want to include the ANSI Standard FORTRAN
names in your program rather than the native VMS names.
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
ANSI Standard FORTRAN in DIL.TLB. The elements are DIL$ANSI FORTRAN,
DIT$ANSI_FORTRAN, and DIX$ANSI_FORTRAN.
The library element DIL$ANSI FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$ANSI FORTRAN. Severity codes
and system codes are defined in element DIL$ANSI FORTRAN.
To define
these names in your program, include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$ANSI_FORTRAN),
This retrieves the DIL$ANSI_FORTRAN element of the
includes it in your program.

library

file

and

The library element DIT$ANSI FORTRAN defines codes specific to the
Task-to-Task and Remote File Access Routines. The codes include the
DIT status codes, which are standard VMS condition values.
Also
included
are Task-to-Task wait codes, Task-to-Task link types,
Task-to-Task message modes and VMS task fire-up codes.
To define
these names in your program, include the following statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$ANSI_FORTRAN)
For programs which use the Task-to-Task routines with the compatible
names, you must include both the DIL$ANSI FORTRAN and DIT$ANSI FORTRAN
library elements.
-

10.2.2

Storing a Network Logical Name

The NLN occupies one longword of VMS memory.
must declare an integer, as shown below:
INTEGER nln

10-5

store

NLN,

you

VMS TASK-TO-TASK
10.2.3

Storing Task and User Attributes

To include task and user attributes in a call to DIT$NFOPA, DIT$NFOPB
or DIT$NFOP8 or task attributes in a call to DIT$NFOPP you must
describe these attributes in your program as follows:
INTEGER trgsys (4 )
INTEGER objtyp (4 )
INTEGER desc ( 4 )
INTEGER tsknam (4)
INTEGER userid (10)
INTEGER passwd (10)
INTEGER acct (10)
INTEGER usdat (4 )

or
or
or
or
or
or
or
or

CHARACTER*16
CHARACTER*16
CHARACTER*16
CHARACTER*16
CHARACTER*39
CHARACTER*39
CHARACTER*39
CHARACTER*16

trgsys
objtyp
desc
tsknam
use rid
passwd
acct
usdat

NOTE
By default, VAX-II FORTRAN passes arguments of type
CHARACTER by descriptor.
In order to use CHARACTER
type variables as arguments to DIL (on VMS), the %REF
built-in function .must be used because DIL string
arguments must be passed by reference.

10.2.4

Checking the Status of a Task-to-Task Routine

Section 9.2.4 explains how to check the status of a DIL
VMS FORTRAN.

Routine

A simple call to the Task-to-Task routines from VMS FORTRAN,
error check, might be:
status = DIT$NFOPA (nin, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)
IF (status .NE. SS$_NORMAL) GOTO 100

100
101

TYPE 101
FORMAT (' error occurred')

10-6

with

from
an

VMS TASK-TO-TASK
10.3

VMS TASK-TO-TASK REFERENCE

10.3.1

DIT$NFGND - Return the Status of Links

PURPOSE:
The DIT$NFGND routine returns the status of network events
as connect requests, available data or aborted links.

such

CALL FORMAT:
COBOL:

CALL "DIT$NFGND" USING nln, wait GIVING stat.

FORTRAN:

status = DIT$NFGND (nln, wait)

where:
nln

is the Network Logical Name of the link that you want
information about.
An NLN is a long integer.
It is
set by the DIT$NFOPA, DIT$NFOPB, DIT$NFOP8 or DIT$NFOPP
routine.
If you want information about any event occuring on any
logical link, use -1 as the value for this argument.
DIT$NFGND finds the next network event and returns the
NLN of that link.
If DIT$NFGND cannot find an event
the value of this argument is undefined.

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you want the routine to
return only the current status of events on the
specified link. The DIL Name for this argument is:
WAIT-NO
Set the wait code to "yes" if you want the routine to
wait for a network event to occur involving the
specified link.
When an event occurs the routine
reports it.
Waiting uses minimal CPU time. The DIL
Name for this argument is:
WAIT-YES

10-7

VMS TASK-TO-TASK

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.
You receive this code
only if you don't wait for a new
event and no events have occured
since the last reported event~
If an
event has taken place, (connect,
abort, disconnect, data event) you
receive the code for that event.

DIT-CONNECTEVENT

This code is returned for a connect
event.
If you are checking the
status of a passive task, this code
indicates that the task has received
a connect request.
If you are checking the status of an active task,
~his code indicates that a connect
request issued by the active task has
been accepted by the passive task.

DIT-ABREJEVENT

The routine returns this code if the
link is aborted or rejected.
You
should call NFCLS to do an abort and
release the resources of this link,
so it can be used again.

DIT-DATAEVENT

The routine returns this code when
data is available over the specified
link. You should call NFRCV to receive the data.

DITDISCONNECTEVENT

The routine returns this code when
the specified link has been disconnected.
You should call NFCLS to do
an abort to release the resources of
this link, so it can be used again.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

DIT-INTDATAEVENT

The routine returns this code
when an interrupt data message is
available.
You should call NFRCI
to read the interrupt data message.

10-8

VMS TASK-TO-TASK
10.3.2

DIT$NFINF - Get Information About the Other End of a Link.

PURPOSE:
The DIT$NFINF routine returns information about the remote node,
the remote process of the remote DECnet object associated with a
specific network connection.
You can also use the DIT$NFINF routine to read optional data sent
by a remote process.
If the cooperating process is on a VMS
system, you can use DIT$NFINF to read optional data associated
with
a disconnection or rejection of a process.
If the
cooperating process is a TOPS-10 or TOPS-20 system, you can read
any type of optional data.
CALL FORMAT:
COBOL:

CALL "DIT$NFINF" USING
GIVING stat.

FORTRAN:

status

nln,

inftyp,

length,

buffer,

= DIT$NFINF (nln, inftyp, length, buffer)

where:
nln

is the Network Logical Name of the link that you want
information about.
The NLN is set by the DIT$NFOPA,
DIT$NFOBPB, DIT$NFOP8, or DIT$NFOPP routine.
The
Network Logical Name is a long integer.

inftyp

is a long integer
information wanted.

specifies

the

type

Refer to the DECnet User's Guide for
more information.

your

system

for

10-9

that

VMS TASK-TO-TASK
Information Type

DIL Name

Remote node name of the._; cooperating task.

INF-NODE

Remote object type. This information is only
available to the passive task.

INF-OBJECT

INF-DESCF

Remote DECnet object descriptor. This information
is only available to the passive task.

INF-DESC

Remote process user ide This information is only
available to the passive task.

INF-USERID

Remote process password. This information is only
available to the passive task.

INF-PASSWD

Remote process account. This information is only
available to the passive task.

INF-ACCT

Remote process optional data or disconnect optional
data or reject optional data.
If the cooperating
task is running on a VMS system, only disconnect
and reject optional data are available.

INF-OPT

Maximum segment size for the link in bytes. This
is not available for VMS systems. The information
can be used to determine the optimum size of
records to be transmitted over the link.

INF-SEG

Abort code or reject code.
You can find the
meaning of the abort or reject code in the DECnet
manual for your system.

INF-ABTCOD

length

is a long integer in which the
returned is specified.

buffer

is the area in which to place returned ASCII data.
This area must be at least 16 ASCII-8 characters long
to accomodate optional data, a taskname, or a DECnet
descriptor.
It must be at least 39 ASCII-8 characters
long to accommodate a userid,
a password, or an
account.

10-10

length

ASCII

data

VMS TASK-TO-TASK

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-INFONOTAVAIL

The information you have requested
is not available to this task.

DIT-INFOOUTOFRANGE

The information you have requested
is not in the range of valid values.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

10-11

VMS TASK-TO-TASK
10.3.3

DIT$NFOPA - Open an ASCII Link From an Active Task

PURPOSE:
The DIT$NFOPA routine opens a logical link to a program on
another system. You use this routine when you intend to transmit
or receive ASCII data.
CALL FORMAT:
COBOL:

CALL "DIT$NFOPA" USING nln, trgsys, objtyp, desc,
tsknam,userid, passwd, acct, usdat, wait GIVING
stat.

FORTRAN:

status = DIT$NFOPA (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

trgsys

is the node name of the target system.
The target
system,
in this case,
is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-8
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type specifies the kind of service performed by the
passive task. This argument has a length of sixteen
ASCII-8 characters.
If the object type has less than
sixteen characters, left-justify the field.
The object type can be expressed as either a number or
name.
Most programs use an object type of 0 or TASK.
Server programs which perform a generic service (MAIL,
for example) have a non-zero object type. You can find
a list of valid DECnet object types and their meanings
in the appropriate DECnet User's Guide.

desc

is the DECnet descriptor.
You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system. For TOPS-20 to TOPS-20 communication, when the
object type is not 0, you can provide a descriptor.
See Appendix D for further information. The descriptor
has a length of sixteen ASCII-8 characters. If your
descriptor
is
less
than
sixteen
characters,
left-justify the field.

10-12

VMS TASK-TO-TASK
tsknam

is the OECnet taskname. Taskname is a unique sixteen
character ASCII-8 string that identifies this process
to the network. VMS ignores this argument for active
tasks.
It generates a unique name.
If you don't want
to specify a taskname, pass spaces as the value for
taskname.
NOTE

The following three arguments are optional
user
attributes. The passive task may use these attributes
to validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments may be given a value of spaces if you
want to connect to a passive task on a TOPS-20 or
TOPS-IO system~ they are required if you want to
connect to a passive task on a VMS system.
userid

is your userid.
Userid has a
length of thirty-nine
ASCII-8 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass spaces as the
value of this argument.

passwd

is your password.
Password has a length of thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify justify the field.
If you don't want to specify a password, pass spaces as
the value of the argument.

acct

is your account number or charge code. This field has
a length of thirty-nine ASCII-8 characters.
If the
account
has
less
than
thirty-nine
characters,
left-justify the field.
If you don't want to specify
an account number, pass spaces as the value for this
argument.

usdat

is reserved for sixteen characters of ASCII-8 user
data.
Not currently usedon VMS systems; this argument
must be spaces.

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task.
Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted
your
connection,
periodically call the
OIT$NGFNO routine to check status. The OIL Name for
this argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time.
The OIL Name for this argument is:
WAIT-YES

10-13

VMS TASK-TO-TASK
STATUS CODES:

---

OIL Name

Meaning

DIT-TOOMANY

You attempted too many links. The
OIL allows a maximum of 20 open
links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-14

VMS TASK-TO-TASK
10.3.4

DIT$NFOPB - Open a Binary Link From an Active Task

PURPOSE:
The DIT$NFOPB routine opens a
logical link to a program on
another system.
You use this routine when you intend to transmit
records or blocks of data.
Data moved through the network on a link opened with DIT$NFOPB is
transmitted as a string of bits, sent eight bits at a time. This
format allows the data to be used by the Data Conversion
Routines. To learn more about bit transport, see Appendix F.
CALL FORMAT:
COBOL:

CALL "DIT$NFOPB" USING nln, trgsys, objtyp, desc,
tsknam, userid, passwd, acct, usdat, wait GIVING
stat.

FORTRAN:

status = DIT$NFOPB (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

is the Network Logical Name (NLN) to be returned when
this routine successfully finishes processing.
You use
the NLN to identify this link when you call other
Task-to-Task routines.
The NLN is a long integer.

trgsys

is the node name of the target system.
The target
system,
in this case,
is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-B
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type specifies the kind of service performed by the
passive task. This argument has a
length of sixteen
ASCII-B characters.
If the object type has less than
sixteen characters, left-justify the field.
The object type can be expressed as either number or
name.
Most programs use an object type of 0 or TASK.
Server programs which perform a generic service
(MAIL,
for example) have a non-zero object type.
You can find
a list of valid DECnet object types and their meanings
in the appropriate DECnet Guide.

desc

is the DECnet descriptor.
You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system.
See Appendix D for further information.
The
descriptor has a length of sixteen ASCII-8 characters.
If your descriptor is less than sixteen characters,
left-justify the field.

10-15

VMS TASK-TO-TASK

tsknam

is the DECnet taskname. Taskname is a unique string of
sixteen ASCII-8 characters.
The taskname identifies
this process to the network. VMS ignores this argument
for active tasks.
It generates a unique name.
If you
don't want to specify a taskname, pass spaces as the
value for this argument.
NOTE

The following three arguments are optional
user
attributes. The passive task may use these attributes
to validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments may be given a value name of spaces if
you want to connect to a passive task on a TOPS-20 or
TOPS-IO system: they are required if you want to
connect to a passive task on a VMS system.
userid

is your userid. Userid has a length of thirty-nine
ASCII-8 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass spaces as the
value for this argument.

passwd

is your password. Password has a length of thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a password, pass spaces as the
value for this argument.

acct

is your account number or charge code. This field has
a length of thirty-nine ASCII-8 characters. If this
information is less than
thirty-nine
characters,
left-justify the field.
If you don't want to specify
an account number, pass spaces as the value for this
argument.

usdat

is reserved for sixteen ASCII-8 characters of user
data. Not currently used on VMS systems; this argument
must be spaces.

10-16

VMS TASK-TO-TASK

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task. Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted
your
connection,
periodically call the
DIT$NGFND routine to check status. The DIL Name for
this argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time. The DIL Name for this argument is:
WAIT-YES

STATUS CODES:
DIL Name

Meaning

DIT-TOOMANY

You attempted too many links. The
DIL allows a maximum of 20 open
links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-17

VMS TASK-TO-TASK
10.3.5

DIT$NFOP8 - Open an 8-Bit Link From an Active Task

PURPOSE:
The DIT$NFOPS routine opens a logical link to a program on
another system. You use this routine to transmit S-bit bytes of
data. This routine is especially useful for transmitting data
between VMS systems and for performing special operations.
Data is moved through a link opened with DIT$NFOPS as a string of
S-bit bytes. The routine does not transmit any unused bits. The
target system stores the data in whatever way it normally stores
S-bit bytes of data.
To learn more about bit transport, see
Appendix F.
CALL FORMAT:
COBOL:

CALL "DIT$NFOPS" USING nln, trgsys, objtyp, desc,
tsknam, userid, passwd, acct, usdat, wait GIVING
stat.

FORTRAN:

status = DIT$NFOPS (nln, trgsys, objtyp, desc, tsknam,
1 userid, passwd, acct, usdat, wait)

where:
nln

trgsys

is the node name of the target system.
The target
system,
in this case,
is the system which runs the
passive task that you want to access with this link.
The node name has a length of
sixteen
ASCII-S
characters.
If your node name is less than sixteen
characters, left-justify the field.
If you give this
argument a value of spaces, it defaults to the local
system's node name.

objtyp

is the object type of the passive task.
The object
type specifies the kind of service performed by the
passive task. This argument has a length of sixteen
ASCII-S characters.
If the object type has less than
sixteen characters, left-justify the field.
The object type can be expressed as either a number or
name.
Most programs use an object type of a or TASK.
Server programs which perform a generic service (MAIL,
for example) have a non-zero object type. You can find
a list of valid DECnet object types and their meanings
in the appropriate DECnet User's Guide.

desc

is the DECnet descriptor.
You must use a descriptor
when you plan to access a task with object type 0 or
object name TASK.
The descriptor must contain the
DECnet taskname of the passive task on the remote
system. See Appendix D for further information.
The
descriptor has a length of sixteen ASCII-8 characters.
If your descriptor is less than iixteen characters,
left-justify the field.

la-IS

VMS TASK-TO-TASK
tsknam

is the DECnet taskname. Taskname is a unique sixteen
character ASCII-8 string that identifies this process
to the network. VMS ignores this argument for active
tasks.
It generates a unique name.
If you don't want
to specify a taskname, pass spaces as the value for
this argument.
NOTE

The following three arguments are optional
user
attributes. The passive task may· use these attributes
to validate a network connection, or to perform any
other recognition function agreed to by both tasks.
These arguments may be given a value name of spaces if
you want to connect to a passive task on a TOPS-20 or
TOPS-lO system~ they are required if you want to
connect to a passive task on a VMS system.
userid

is your userid.
Userid has a length of thirty-nine
ASCII-8 characters.
If your userid is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a userid, pass spaces as the
value for this argument.

passwd

is your password.
Password has a length of thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.
If you
don't want to specify a password, pass spaces as the
value for this argument.

acct

is your account- number or charge code.
This field has
a
length of thirty-nine ASCII-8 characters.
If this
information is less than
thirty-nine
characters,
left-justify the field.
If you don't want to specify
an account number, pass spaces as the value for this
argument.

usdat

is reserved for sixteen characters of ASCII-8 user
data.
Not currently used on VMS systems~ this argument
must be spaces.

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you do not want your
program to wait until it establishes a connection to
the passive task.
Using this code enables your program
to perform other duties while waiting for the network
connection. To find out if the passive task has
accepted
your
connection,
periodically call the
DIT$NGFND routine to check status. The DIL Name for
this argument is:
WAIT-NO
Set the wait code to "yes" if you want your program to
wait until the passive task has accepted your link.
The routine does not return to your program until
it
establishes the specified link. While it waits, you
can not use the active task. Waiting uses minimal CPU
time.
The DIL Name for this argument is:
WAIT-YES

10-19

VMS TASK-TO-TASK
STATUS CODES:

DIL Name

Meaning

DIT-TOOMANY

You attempted too many links. The
DIL allows a maximum of 20 open
links.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-20

VMS TASK-TO-TASK
10.3.6

DIT$NFOPP - Open a Link From a Passive Task

PURPOSE:
The DIT$NFOPP routine opens a logical link from a passive task.
It
indicates that the server program is ready to accept
connections from active programs.
There are different ways to move data through the network.
The
cooperating tasks must both specify the same method of data
transfer.
The active task
which
connects
to
DIT$NFOPP
establishes the way data actually moves through the network.
(DIT$NFOPA moves ASCII-8 data, DIT$NFOPB moves binary data and
DIT$NFOP8 moves 8-bit bytes of data.) When it receives a connect
request, The passive task calls the DIT$NFACC routine to accept
the request.
The "lnktyp" argument in the call to DIT$NFACC
specifies the type of data to be transferred over the connection.
If the active task and the DIT$NFACC routine specify different
data types, results are undefined.
To learn more about bit
transport, see Appendix F.
CALL FORMAT:
COBOL:

CALL "DIT$NFOPP" USING nln, objtyp, desc, tsknam, wait
GIVING stat.

FORTRAN:

status

= DIT$NFOPP (nln, objtyp, desc, tsknam, wait)

where:
nln

is the Network Logical Name (NLN) to be returned when
this routine successfully finishes processing.
You use
the NLN to identify this link when you call other
Task-to-Task routines.
The NLN is a long integer.
Possible DIL Names for this argument are:
PAS-FIREUP

if the task can
accept
connection on this link.

PAS-NFIREUP

if the task can accept more than one
connection on this link.
You must have
SYSNAM privileges
to
specify
this
parameter.

only

one

See Appendix D for further information.
objtyp

is the DECnet object type of the passive task.
The
object type tells the kind of service performed by this
task.
This argument has a length of sixteen ASCII-8
characters.
If the object type has less than sixteen
characters, left-justify the field.
The object type can be expressed as either a a number
or name.
Most programs use an object type of 0 or
TASK. Server programs which perform a generic service
(MAIL,
for example) have a non-zero object type.
You
can find a list of valid DECnet object types and their
meanings in the appropriate DECnet User's Guide.

10-21

VMS TASK-TO-TASK
desc

is the DECnet descriptor.
See Appendix D for examples
of task identification. The descriptor has a length of
sixteen ASCII-8 characters.
If your descriptor is less
than sixteen characters, left-justify the field.

tsknam

is the DECnet taskname.
Taskname is a unique sixteen
character ASCII-8 string that identifies this process
to the network.
An active task may identify the
passive task
it wants to connect to by specifying the
passive task's taskname.
For this reason, most passive
tasks are given specific task names.
If you pass
spaces for this argument, the operating system assigns
a unique task name.
See Appendix D for further
information.

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you you want to set up a
server task,
but you do not want to wait until an
active task requests its services.
Using this code
leaves your program free to perform other duties.
To
find out if the an active task wants to connect to the
server,
call the DIT$NFGND routine to check status.
The DIL Name for this argument is:
WAIT-NO
Set the wait code to "yes" if you want to set up a
server task that waits until an active task requests
its services.
The routine returns a status value when
an active task tries to connect to the server. While
it waits, you can not use the server program to perform
any other processing functions.
Waiting uses minimal
CPU time.
The DIL Name for this argument is:
WAIT-YES

STATUS CODES:
DIL Name

Meaning

DIT-TOOMANY

You attempted too many links.
The
DIL allows a maximum of 20 open
links.

DIT-INVARG

You passed an incorrect or invalid
argument.

5S-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

The link was aborted or rejected.

DIT-HORRIBLE

This code is returned in the event of
system or unexpected error.

10-22

VMS TASK-TO-TASK
10.3.7

DIT$NFACC - Accept a Connection

PURPOSE:
The DIT$NFACC routine accepts a connection from an active task
and specifies the type of data to be transferred over the link.
It is used in conjunction with the DIT$NFOPP routine, which opens
the logical link.
CALL FORMAT:
COBOL:

CALL "DIT$NFACC" USING nln, lnktyp, char, opdat
GIVING stat.

FORTRAN:

status

= DIT$NFACC (nln, lnktyp, char, opdat)

where:
nln

is the Network Logical Name set by the DIT$NFOPP
routine when it successfully finishes processing. The
NLN is a long integer.

lnktyp

is a long integer that indicates the type of data that
you want to transfer over the link.
You must specify
one of the following values:
LINK Data Type

OIL Name

ASCII-8 data.
To transfer ASCII
data, use the
DIT$NFOPA routine
to open the link.

LTYPE-ASCII

Binary data.
To transfer binary
data, use the
DIT$NFOPB routine
to open the link.

LTYPE-BINARY

8-bit bytes.
To transfer 8-bit
bytes of data,
use the DIT$NFOP8
routine to open
the link.

LTYPE-8BIT

char

is the number of characters of optional data
plan to send (see below).

that

opdat

sixteen ASCII-8 characters of optional user data.
the DIT$NFINF routine for more information.

you
See

VMS TASK-TO-TASK
STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-24

VMS TASK-TO-TASK
DIT$NFREJ - Reject a Connection

10.3.8
PURPOSE:

The DIT$NFREJ routine is used by the passive
connection request from an active task.

task

reject

CALL FORMAT:
COBOL:

CALL

"DIT$NFREJ" USING
GIVING stat.

nln,

rejcod,

FORTRAN:

status

= DIT$NFREJ (nln, rejcod, char, opdat)

char,

opdat

where:
nln

is the Network Logical Name set by the DIT$NFOPP
routine when it successfully finishes processing. NLN
is a long integer.

rejcod

is a long integer that specifies the type of reject
requested.
You should not use nine for this code,
which means "User Program Abort." See your DECnet
User's Guide for a list of abort/reject codes. This
parameter is not used either VMS OR TOPS-lO systems.

char

is a long integer that specifies the number
of
characters
(0-16) of 'opt ional data that you plan to
send (see below).

opdat

is 16 ASCII-8 characters of optional user data.
the DIT$NFINF routine for more information.

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

55-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

10-25

See

VMS TASK-TO-TASK
10.3.9

DIT$NFRCV - Receive Data

PURPOSE:
The DIT$NFRCV routine receives data (DECnet messages) sent over a
logical link.
The routine reads one DECnet message each time it is
called.

sucessfully

CALL FORMAT:
COBOL:

CALL "DIT$NFRCV" USING nln, msunit, mxunit, bufloc,
msmode, wait GIVING stat.

FORTRAN:

status = DIT$NFRCV (nln, msunit, mxunit, bufloc,
I msmode, wait)

where:
nln

is the Network Logical Name set by the DIT$NFOPA,
DIT$NFOPB, DIT$NFOP8 or DIT$NFOPP routine when the
routine successfully finished processing. The NLN is a
long integer.

msunit

is a long integer that gives the message unit size.
It
tells the byte size, in bits, of messages written in
binary format (with links opened through DIT$NFOPB). A
value of zero for this argument indicates that you plan
to transfer data as words. If you open the active side
of the link with DIT$NFOPA or DIT$NFOP8, the routine
ignores this argument (both routines send 8-bit bytes
of data).

mxunit

is a long integer that specifies the maximum number
units to be read by the routine.

For links opened with DIT$NFOPA, this
• maximum
of ASCII-8 characters
number

the
the

is
in

message.
this is the
For links opened with DIT$NFOP8,
• maximum
number of sequential 8-bit bytes in the
message.
•

For links opened with DIT$NFOPB,
this is the
maximum number of bytes (of the unit size shown in
msunit) or words in the message.
DIT$NFRCV pads
the last byte or word sent with zero bits if it
does not divide evenly into bytes of the specified
size.

bufloc

is the location of the user buffer where the message
will be placed after it is read. This buffer must be
at least as large as the number of bytes, characters or
words specified in the mxunit argument, above.

msmode

is the message-mode flag.
The message-mode is
integer. The DIL Name for this argument is:
MSG-MSG

10-26

long

VMS TASK-TO-TASK

wait

is a long integer that gives the wait code.
Set the wait code to "no" if you want the routine to
return whatever data is currently available.
If data
is not available, the routine returns and you can use
the program to perform other duties. The DIL Name for
this argument is:
WAIT-NO
Set the wait code to Hies" if you want the routine to
wait until data is received or the read fails.
The DIL
Name for this argument is:
WAIT-YES

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-ABORTREJECT

This code is returned if the link is
disconnected or aborted. The character count area contains the number
of units, bytes or words that the
routine read before the disconnect.

DIT-OVERRUN

This code is returned if you try to
send too much data to the routine.

DIT-NOTENOUGH

This code is returned if the amount
of data you requested is not available.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

DIT-INTERRUPT

Interrupt data must be read first
using NFRCI.

10-27

VMS TASK-TO-TASK
10.3.10

DIT$NFSND - Send Data

PURPOSE:
The DIT$NFSND routine sends data over a logical link.
If you open the logical link with DIT$NFOPA,
the routine sends
the data in ASCII format. The receiving task can directly read
ASCII data from another system, even if the tasks are on
heterogeneous systems.
If you open the logical link with DIT$NFOP8,
the routine sends
the data as sequential 8-bit bytes. The local system treats the
data as it normally treats 8-bit bytes of data.
The remote
system treats the data it receives in the way it normally stores
8-bit bytes of data.
If you open the logical link with DIT$NFOPB, the routine sends
the data in binary format.
If the sending and receIvIng tasks
are on homogeneous systems, the receiving system can directly
read the data.
If the sending and receiving tasks are on
heterogeneous systems, you must convert the data using the Data
Conversion Routines. The sending task can perform the conversion
before it sends the data or the receiving task can convert the
data it receives.
This routine sends one DECnet message each time it is sucessfully
called.
CALL FORMAT:
COBOL:

CALL "DIT$NFSND" USING nln, msunit, length, buffer,
msmode GIVING stat.

FORTRAN:

status = DIT$NFSND (nln, msunit, length, buffer,
1
msmode)

where:
nln

is the Network Logical Name set by the DIT$NFOPA,
DIT$NFOPB, DIT$NFOP8 or DIT$NFOPP routine when the
routine successfully finished processing. The NLN is a
long intl::.!ger.

msunit

is a long integer that gives the message unit size. It
tells the byte size, in bits, of messages written in
binary format (with links opened through DIT$NFOPB). A
value of zero for this argument indicates that the data
is to be sent as words. If you open the active side of
the link with DIT$NFOPA or DIT$NFOP8, the routine
ignores this argument.

length

is a long integer that specifies the length of the data
that you want to send. This argument must have a value
that is greater than zero.
•

For links opened with DIT$NFOPA, length is given in
ASCII-8 characters.

10-28

VMS TASK-TO-TASK

•

For links opened with DIT$NFOP8, length is given in
sequential 8-bit bytes.

•

For links opened with DIT$NFOPB, length is given in
bytes (of the unit size shown in the msunit
argument, above) or in words.

buffer

is the buffer containing the data you want to send.

msmode

is the message-mode flag.
The message-mode is a
one-word integer. The DIL Name for this argument is:
MSG-MSG

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-29

VMS TASK-TO-TASK
10.3.11

DIT$NFRCI - Receive an Interrupt Data Message Over a Link

PURPOSE:
The DIT$NFRCI routine receives a single interrupt data message over
logical link.

Receipt of an interrupt data message is an asynchronous event.
You
should check for asynchronous events by using DIT$NFGND which will
announce interrupt data messages before it will announce "regular"
data messages
(sent by DIT$NFSND).
Interrupt data messages must be
read before DIT$NFGND will announce any lower-level events (regular
data
messages
or
disconnections).
DIT$NFRCV will return the
DIT-INTERRUPT error and refuse to return data if an interrupt message
is available which has not yet been read by DIT$NFRCI.
CALL FORMAT:
COBOL:

CALL "DIT$NFRCI" USING nln, char, buffer GIVING stat.

FORTRAN:

status

= DIT$NFRCI (nln, char, buffer)

where:
nln

is the Network Logical Name set by the DIT$NFOPP
routine when it successfully finishes processing. NLN
is a long integer.

char

is a long integer into which the number of ASCII-8
characters (1-16) of interrupt data read is returned.

buffer

is the location of the user buffer where the message
will be placed after it is read. The length of this
buffer must be 16 ASCII-8 characters.

STATUS CODES:
OIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NODATAAVAILABLE

No interrupt data is available to be
read at this time.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

10-30

VMS TASK-TO-TASK
10.3.12

DIT$NFINT - Send an Interrupt Data Message Over a Link

PURPOSE:
The DIT$NFINT routine sends a single interrupt data message
a logical link.

over

Unlike DIT$NFSND, DIT$NFINT data is always sent in message mode,
so a prompt attempt to send the data is guaranteed. Data sent in
this mode is not sent in synchronization with data sent by
DIT$NFSND.
Only one interrupt data message can be outstanding
from each end of a logical link at one time.
If an interrupt
data message is sent over a logical link by one process, a second
interrupt data message cannot be sent by that process until the
first one has been received at the other end of the logical link.
If a second interrupt data message is sent before the first one
has been received at the other side of the link, then the first
interrupt data message may be lost at the receiving end of the
link •.
CALL FORMAT:
COBOL:

CALL "DIT$NFINT" USING nln, char, buffer GIVING stat.

FORTRAN:

status = DIT$NFINT (nln, char, buffer)

where:
nln

is the Network Logical Name set by the DIT$NFOPP
routine when it successfully finishes processing. The
NLN is a long integer.

char

is a long integer that specifies the number of
characters (1-16) of interrupt data to send.

ASCII-8

buffer

is the buffer that contains the data that you
send.

want

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event
of a system or unexpected error.

DIT-INTERRUPT

Available interrupt data must be
read first. See the DIT$NFRCI
routine.

10-31

VMS TASK-TO-TASK
10.3.13

DIT$NFCLS - Close a Link

PURPOSE:
The DIT$NFCLS routine disconnects or aborts a logical
releasing its resources to be used by another link.

link,

A "synchronous disconnect" is the normal way to close a link~
it
disconnects the link after it performs all outstanding data
transmission. An abort instantaneously disconnects the link.
You can call the DIT$NFCLS routine to disconnect the link before
or after receiving a disconnec~ from the other end of the link.
To preserve data integrity, the recipient of the last piece of
data should be the first to disconnect the link (using a
synchronous disconnect).
The program that sent
the
data
recognizes that its data was read when it receives the other
program's disconnect.
It should then abort its end of the link,
to free the resources for another use.
CALL FORMAT:
COBOL:

CALL "DIT$NFCLS" USING nln, disc, char, opdat
GIVING stat.

FORTRAN:

status

= DIT$NFCLS (nln, disc, char, opdat)

where:
nln

is the Network Logical Name, set by the DIT$NFOPA,
DIT$NFOPB, DIT$NFOP8 or the DIT$NFOPP routine when the
routine successfully finished processing. The NLN is a
long integer.

disc

is a long integer that indicates the type of disconnect
requested.
Use zero for this argument if you want a
synchronous disconnect.
A non-zero value for this
argument indicates an abort.
"9" is the normal value
for an abort. The DECnet User's Guide for your system
gives a list of possible abort codes.

char

is a long integer that specifies the number
of
characters (0 to 16) of optional data to be sent (see
the opdat argument, below).

opdat

is sixteen ASCII-8 characters of optional user
See the DIT$NFINF rou~ine for more information.

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

10-32

data.

VMS TASK-TO-TASK
10.4
10.4.1

VMS TASK-TO-TASK EXAMPLES
VMS COBOL Task-to-Task Examples

IDENTIFICATION DIVISION.
PROGRAM-ID.
PASC32.
AUTHOR.
SOFTWARE ENGINEERING.
This program opens a passive link and then waits for a
connection from an active task (created by the program
ACTC32). Once a link is established, user specified messages
are sent in both directions across the link. The link is
closed by the program ACTC32 and this program waits for a
confirmation of the close.
INSTALLATION
DEC MARLBORO.
ENVIRONMENT DIVISION.

DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COPY DIT$COBOL OF "SYS$LIBRARY:DIL.TLB".
COPY DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

* DIL status return or condition value
01

DIL-STATUS PIC S9(9) COMPo

DATA-RECORDS.
05 SEND-DATA PIC X(100).
05 RECEIVE-DATA PIC X(100).

01
01
01
01
01
01
01
01

COUNT-OPT-DATA PIC S9(9) COMP VALUE O.
OPT-DATA PIC X(16) VALUE SPACES.
NETLN PIC S9(9) COMPo
OBJECT-ID PIC X(16).
DESCRIPT PIC X(16) VALUE SPACES.
TASKNAME PIC X(16).
MESSAGE-UNITS-SIZE PIC S9(9) COMP VALUE 8.
MESSAGE-SIZE PIC S9(9) COMP VALUE 100.

DIL-DISPLAY PIC X(12).

DIL-MATCH-COND PIC S9(9) COMPo
88 NO-MATCH VALUE O.
88 MATCH-1 VALUE 1.

10-33

VMS TASIC-TO-TASK

PROCEDURE DIVISION.
OPEN-PASSIVE.
* Open a passive link.
MOVE "SERVER" TO TASKNAME.
MOVE "0" TO OBJECT-ID.
MOVE DIT$K_PAS_NFIREUP TO NETLN.
CALL "DIT$NFOPP" USING NETLN, OBJECT-ID, DESCRIPT,
TASKNAME, DIT$K WAIT NO
GIVING DIL-STATUS.
MOVE OIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFOPP Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? NFOPP: unsuccessful status return "
STOP RUN.
CHECK-FOR-CONNECT

* Wait for a connect request
CALL "DIT$NFGND" USING NETLN, DIT$K WAIT YES
GIVING DIL-STATUS.MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY " NFGND Status return: " DIL-DISPLAY.
CALL "LIB$MATCH_COND" USING DIL-STATUS,
DIT$ CONNECTEVENT
GIVING DIL=MATCH-COND.
IF NO-MATCH
DISPLAY"? NFGND: Unexpected or invalid status returned: "
STOP RUN.
ACCEPT-LINK
* Accept link
CALL "DIT$NFACC" USING NETLN, DIT$K LTYPE ASCII, COUNT-OPT-DATA, OPT-DATA
GIVING DIL-STATUS.MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFACC Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? NFACC: unsuccessful status return"
STOP RUN.
CHECK-FOR-DATA.
* Wait for a data event on the link
CALL "DIT$NFGND" USING NETLN, DIT$K WAIT YES
GIVING DIL-STATUS.MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFGND Status return: " DIL-DISPLAY.
CALL "LIB$MATCH_COND" USING DIL-STATUS,
DIT$ DATAEVENT
GIVING DIL=MATCH-COND.
IF NO-MATCH
DISPLAY"? NFGND: Unexpected or invalid status returned: "
STOP RUN.

10-34

VMS TASK-TO-TASK
READ-THE DATA.
* Read the data received over the link
MOVE 100 TO MESSAGE-SIZE.
CALL "DIT$NFRCV" USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
RECEIVE-DATA, DIT$K MSG MSG, DIT$K_WAIT_YES
-GIVING OIL-STATUS.
DISPLAY" NFRCV Status return: " OIL-STATUS.
IF OIL-STATUS IS NOT SUCCESS
DISPLAY ~? NFRCV: unsuccessful status return"
STOP RUN.
DISPLAY" Data received: "
DISPLAY RECEIVE-DATA.
SEND-SOME-DATA.
* Send some data over the link
MOVE 100 TO MESSAGE-SIZE.
DISPLAY" Enter some data to be sent over the link: ".
ACCEPT SEND-DATA.
CALL "DIT$NFSND" USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
SEND-DATA, DIT$K MSG MSG
GIVING OIL-STATUS.
MOVE OIL-STATUS TO OIL-DISPLAY.
DISPLAY" NFSND Status return: " OIL-DISPLAY.
IF OIL-STATUS IS NOT SUCCESS
DISPLAY"? NFSND: unsuccessful status return "
STOP RUN.
CHECK-FOR-CLOSE.
CALL "DIT$NFGND" USING NETLN, DIT$K WAIT YES
GIVING DIL-STATUS.MOVE OIL-STATUS TO OIL-DISPLAY.
DISPLAY" NFGND status return: " OIL-DISPLAY.
CALL "LIB$MATCH_COND" USING OIL-STATUS,
DIT$ ABREJEVENT,
DIT$-DISCONNECTEVENT
GIVING DIL=MATCH-COND.
IF NO-MATCH
DISPLAY"? NFGND: Invalid status returned on link close"
STOP RUN.
DISPLAY" PASC32 successful".
STOP RUN.

10-35

VMS TASK-TO-TASK

INDENTIFICATION DIVISION.
PROGRAM-ID.
ACTC32.
AUTHOR.
SOFTWARE ENGINEERING.
This program opens an active link by connecting to the passive
task set up by the program PASC32. Once the link is
established, user specified messages are sent in both
directions across the link. Then the link is closed.
INSTALLATION.
DEC MARLBORO.
ENVIRONMENT DIVISION.

DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COpy DIT$COBOL OF "SYS$LIBRARY:DIL.TLB".
COPY DIL$COBOL OF " SYS$LIBRARY:DIL.TLB".

* DIL status return
01

DIL-STATUS PIC S9(9) COMPo

DATA-RECORDS.
05 SEND-DATA PIC X(100).
05 RECEIVE-DATA PIC X(100).

01
01
01
01
01
01
01
01
01
01
01
01

COUNT-OPT-DATA PIC S9(9) COMP VALUE O.
OPT-DATA PIC X(16) VALUE SPACES.
NETLN PIC S9(9) COMPo
HOSTNAME PIC X(06).
OBJECT-ID PIC X(16).
DESCRIPT PIC X(16) VALUE SPACES.
TASKNAME PIC X(16).
USERID PIC X(39) VALUE SPACES.
PASSWD PIC X(39) VALUE SPACES.
ACCT PIC X(39) VALUE SPACES.
MESSAGE-UNITS-SIZE PIC S9(9) COMP VALUE 8.
MESSAGE-SIZE PIC S9(9) COMP VALUE 100.

01
01

SYNCH-DISCONN PIC S9(9) COMP VALUE O.
DIL-DISPLAY PIC X(12).

DIL-MATCH-COND PIC S9(9) COMPo
88 NO-MATCH VALUE O.
88 MATCH-1 VALUE 1.
88 MATCH-2 VALUE 2.

10-36

VMS TASK-TO-TASK
PROCEDURE DIVISION.
CONNECT-TO-PASSIVE.
* Ask for a connection to the passive link
MOVE "0" TO OBJECT-ID.
MOVE "SERVER" TO DESCRIPT.
MOVE SPACES TO TASKNAME.
CALL "DIT$NFOPA" USING NETLN, HOSTNAME, OBJECT-ID, DESCRIPT, TASKNAME,
USERID, PASSWD, ACCT, OPT-DATA, DlT$K_WAIT_NO
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFOPA Status return: ", DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DIS~LAY "? NFOPA: unsuccessful status return "
STOP RUN.
CHECK-FOR-CONNECT.
* wait for confirmation of the connection
CALL "DIT$NFGND" USING NETLN, DIT$K WAIT YES
GIVING DIL-STATUS.MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY " NFGND Status return: " DIL-DISPLAY.
CALL "LIB$MATCH_COND" USING DIL-STATUS,
DIT$ CONNECTEVENT
GIVING DIL-MATCH-COND.
IF NO-MATCH
DISPLAY"? NFGND: Unexpected or invalid status returned: "
STOP RUN.
SEND-SOME-DATA.
* Send some data over the link
MOVE 100 TO MESSAGE-SIZE.
DISPLAY" Enter some data to be sent over the link: "
ACCEPT SEND-DATA.
CALL "DIT$NFSND" USING NETLN, MESSAGE-UNITS-SIZS, MESSAGE-SIZE,
SEND-DATA, DIT$K MSG MSG
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFSND Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? NFSND: unsuccessful status return "
STOP RUN.

10-37

VMS TASK-TO-TASK
CHECK-FOR-DATA.
* Wait for a data event on the link
CALL "DIT$NFGND" USING NETLN, DIT$K WAIT YES
GIVING DIL-STATUS.MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFGND Status return: " DIL-DISPLAY.
CALL "LIB$MATCH_COND" USING DIL-STATUS,
DIT$ DATAEVENT
GIVING DIL=MATCH-COND.
IF NO-MATCH
DISPLAY"? NFGND: Unexpected or invalid status returned: "
STOP RUN.
READ-THE-DATA.
* Read the data received over the link
MOVE 100 TO MESSAGE-SIZE.
CALL "DIT$NFRCV" USING NETLN, MESSAGE-UNITS-SIZE, MESSAGE-SIZE,
RECEIVE-DATA, DIT$K MSG MSG, DIT$K WAIT YES
GIVING DIL-STATUS.
-MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" NFRCV Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? NFRCV: un~uccessful status return "
STOP RUN.
DISPLAY" Data received: "
DISPLAY RECEIVE-DATA.
CLOSE-LINK.
* Close the link
CALL "DIT$NFCLS" USING NETLN, SYNCH-DISCONN, COUNT-OPT-DATA, OPT-DATA
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY " NFCLS Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? NFCLS: unsuccessful status return"
STOP RUN.
DISPLAY" ACTC32 successful".
STOP RUN.

10-38

VMS TASK-TO-TASK
10.4.2

VMS FORTRAN Task-to-Task Examples

C PASF32
C
C
C
C
C
C

C Use the DIL interface files.
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$FORTRAN),
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$FORTRAN),
C Data records
DIMENSION SENDD (25), RECD (25)
C DIL task to task routine parameters
DIMENSION OPTDAT (4), OBJID (4), DESCR (4), TASKN (4)
INTEGER NETLN, DILSTS, MSGSIZ, MUNTSZ, CNTOPD
C

Link description fields -- passive end

'I
'I
'I
'I

DATA OBJID 1'0
,
DATA DESCR I'
DATA TASKN I 'SERV' , 'ER
DATA OPTDAT

C Program messages
( ,

Invalid status returned •••

777
778
779
200
202
203
204
205

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

initialize sending and receiving message data fields

100

DO 100 I = 1, 25
SENDD (I) = 0
RECD (I) = 0

Open a passive link

(

, Enter some data to be sent over the link: ' )

, Data received: ' )

(
( ,
( ,

NFOPP Status
NFGND Status
( , NFACC Status
( , NFSND Status
( , NFRCV Status

return:
return:
return:
return:
return:

,
,
,
,
,

I12)
I12)
I12)
I12)
I12)

NETLN = DIT$K PAS NFIREUP
DILSTS = DIT$NFOPP (NETLN, OBJID, DESCR, TASKN, DIT$K_WAIT_NO)
WRITE (6, 200) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 110
WRITE (5, 777)
STOP

10-39

VMS TASK-TO-TASK
C

Wait for a connect request

110

DILSTS

= DIT$NFGND (NETLN, DIT$K_WAIT_YES)

WRITE (6,202) DILSTS
IF (DILSTS .EQ. DIT$ CONNECTEVENT) GO TO 120
WRITE (6, 777)
STOP
C

Accept link

120

CNTOPD
DILSTS

=0
= DIT$NFACC (NETLN, DIT$K_LTYPE_ASCII, CNTOPD, OPTDAT)

WRITE (6, 203) bILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 130
WRITE (6, 777)
STOP
C

Wait for a data event on the link

130

DILSTS

= DIT$NFGND (NETLN, DIT$K_WAIT_YES)

WRITE (6,202) DILSTS
IF (DILSTS .EQ. DIT$ DATAEVENT) GO TO 140
WRITE (6, 777)
STOP
C

Read the data received over the link

140

MSGSIZ
MUNTSZ

100

=8
DILSTS = DIT$NFRCV (NETLN, MUNTSZ, MSGSIZ, RECD, DIT$K_MSG_MSG,

1 DIT$K_WAIT_YES)
WRITE (6, 205) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 150
WRITE (6, 777)
STOP
150
155

WRITE (6, 779)
FORMAT (' , 25A4)
WRITE (6, 155) RECD

Send some data over the link

157

WRITE (6, 778)
FORMAT (25A4)
ACCEPT 157, SENDD
MSGSIZ
MUNTSZ

100
8

DILSTS

DIT$NFSND (NETLN, MUNTSZ, MSGSIZ, SENDD, DIT$K_MSG_MSG)

WRITE (6, 204) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 160
WRITE (6, 777)
STOP

10-40

VMS TASK-TO-TASK

Check for the link being closed

160

DILSTS

= DIT$NF'GND (NETLN, DIT$K_WAIT YES)

WRITE (6, 202) DILSTS
IF (DILSTS .EO. DIT$ ABREJEVENT) GO TO 170
IF (DILSTS .EO. DIT$-DISCONNECTEVENT) GO TO 170
IF (DILSTS .EO. SS$_NORMAL) GO TO 170
WRITE (6, 777)
STOP
170
175

WRITE (6,175)
FORMAT (' PASF32 test successful
STOP
END

C ACTF32
C
C
C
C

This program .opens an active link by connecting to the passive
task set up by the programPASC36. Once the link is
established, user specified messages are sent in both
directions across the link. Then the link is closed.

C Use the DIL interface files.
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$FORTRAN)'
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$FORTRAN)'
C Data records
DIMENSION SENDD (25), RECD (25)
C DIL task to task routine parameters
DIMENSION HSTNAM (4), OPTDAT (4), OBJID (4), DESCR (4)
DIMENSION PASSWD (10), ACCT (10), USERID (10), TASKN (4)
INTEGER NETLN, DILSTS, MSGSIZ, MUNTSZ, CNTOPD, SYNCDS
C

Link description fields

DATA OBJID 1'0',
DATA DESCR I' SERV' ,
DATA TASKN I'
DATA HSTNAM I'
DATA PASSWD I'
1
DATA USERID I'
1
DATA ACCT I'
1
DATA OPTDAT

'ER

'I
, I·
'I
,,

10-41

,
'I

'I
,
'I

VMS TASK-TO-TASK
C Program messages
( ,
( ,
(

Invalid status returned ••• ' )
Enter some data to be sent over the link:
, Data rec.eived: ' )
( , NFOPA Status return: ,
112)
( , NFGND Status return: ,
112)
( , NFSND Status return: ,
112)
,
( , NFRCV Status return:
112)
( , NFCLS Status return: ,
112)

777
778
779
201
202
204
205
206

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

initialize sending and receiving message data fields

100

DO 100 I = 1, 25
SENDD (I) = 0
RECD (I) = 0

Ask for a connection to the passive link
1

DILSTS = DIT$NFOPA (NETLN, HSTNAM, OBJID, DESCR, TASKN,
USERID, PASSWD, ACCT, OPTDAT, DIT$K_WAIT_NO)
WRITE (6, 201) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 110
WRITE (6, 777)
STOP

Wait for confirmation of the connection

110

DILSTS

= DIT$NFGND (NETLN, DIT$K_WAIT_YES)

WRITE (6, 202) DILSTS
IF (DILSTS .EO. DIT$ CONNECTEVENT) GO TO 120
WRITE (6, 777)
STOP
C

Send some data over the link

120
125

WRITE (6, 778)
FORMAT (25A4)
ACCEPT 125, SENDD

= 100
=8
DILSTS = DIT$NFSND (NETLN, MUNTSZ, MSGSIZ, SENDD, DIT$K_MSG_MSG)

MSGSIZ
MUNTSZ

WRITE (6, 204) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 130
WRITE (6, 777)
STOP
C

Wait for a data event on the link

130

DILSTS

= DIT$NFGND (NELTN, DIT$K_WAIT_YES)

WRITE (6,202) DILSTS
IF (DILSTS .EQ. DIT$ DATAEVENT) GO TO 140
WRITE (6, 777)
STOP

10-42

VMS TASK-TO-TASK

Read the data received over the link

140

MSGSIZ
MUNTSZ

100
8

DILSTS
DIT$NFRCV (NETLN, MUNTSZ, MSGSIZ, RECD, DIT$K_MSG_MSG,
1 DIT$K_WAIT_YES)
WRITE (6, 205) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 150
WRITE (6, 777)
STOP
150
155

WRITE (6, 779)
FORMAT (' , 25A4)
WRITE (6, 155) RECD

Close the link to self
SYNCDS

DILSTS

DIT$NFCLS (NETLN, SYNCDS, CNTOPD, OPTDAT)

WRITE (6, 206) DILSTS
IF (DILSTS .EO. SS$ NORMAL) GO TO 160
WRITE (6, 777)
STOP
160
165

WRITE (6,165)
FORMAT (' ACTF32 test successful ')
STOP
END

10-43

CHAPTER 11
VMS REMOTE FILE ACCESS

11.1

REMOTE FILE ACCESS FROM VMS COBOL

The information included in this section assumes
-You are writing a COBOL program
-You plan to use the program on a VMS system
To store a file number, file name and user attributes, to read or
write a record you must represent several data items in your program.
Users generally, but not necessarily, allocate space for these data
items in WORKING-STORAGE.

11.1.1

Including the Interface Support Files

VMS systems have two different classes of Interface Support files for
each supported language.
The first class of files include native
VMS-type names for each of the various codes for VMS COBOL and VMS
FORTRAN.
The second class includes files with TOPS-IO/TOPS-20 COBOL
compatible names for VMS COBOL, and files that include ANSI Standard
names for the interface to VMS FORTRAN. The Interface Support files
for VMS are provided as a text library called DIL.TLB.
The library
includes the support files for both VMS COBOL and VMS FORTRAN.
Native VMS COBOL
You can use the COBOL COpy verb to retrieve information from DIL.TLB
at compilation time. There are three library elements for Native VMS
COBOL in DIL.TLB.
The elements are DIL$COBOL, DIT$COBOL,
and
DIX$COBOL.
The library element DIL$COBOL defines general codes and
names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(S8-NORMAL)
is defined in element DIL$COBOL.
Severity codes and
system codes are defined in element DIL$COBOL. To define these names
in
your
program,
include
the
following
statement in your
WORKING-STORAGE section after an Ol-level declaration:
COpy DIL$COBOL OF

~SYS$LIBRARY:DIL.TLB".

11-1

VMS REMOTE FILE ACCESS
In the following example, the DIL$COBOL
retrieved and included in your program:
01

element

the

library

interface-files.
COpy DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

The library element DIT$COBOL defines codes
specific
to
the
Task-to-Task and Remote File Access Routines. This includes the DIT
status codes which are standard VMS condition values.
Also included
are Remote File Access file types, Remote File Access open modes,
Remote File Access record formats,
Remote File
Access
record
attributes and Remote File Access close options. To define these
names in your program,
include the following statement in your
WORKING-STORAGE section after an 01-level declaration as shown above
for the DIL$COBOL element:
COpy DIT$COBOL OF "SYS$LIBRARY:DIL.TLB".
For programs which use the Remote File Access Routines with the native
VMS names, you must include both the DIL$COBOL and DIT$COBOL library
elements.
TOPS-I0/TOPS-20 Compatible COBOL
If you want to write a program that can be easily transported to a
DECsystem-IO
or
a DECSYSTEM-20, you may want to include the
TOPS-I0/TOPS-20 compatible names in your program rather than the
native VMS names.
You can use the COBOL COpy verb to retrieve information from DIL.TLB
at
compilation
time.
There
are three library elements for
are
TOPS-I0/TOPS-20 compatible COBOL in DIL.TLB.
The elements
DIL$COBOL_20, DIT$COBOL_20, and DIX$COBOL_20.
The library element DIL$COBOL 20 defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$COBOL 20. Severity codes and
system codes are defined in element DIL$COBOL-20.
To define these
names in your program, include the folloiing statement i~ your
WORKING-STORAGE section after an 01-level declaration:
COpy DIL$COBOL_20 OF "SYS$LIBRARY:DIL.TLB".
In the following example, the DIL$COBOL_20 element of the
retrieved and included in your program:
01

library

interface-files.
COpy DIL$COBOL_20 OF "SYS$LIBRARY:DIL.TLB".

The library element DIT$COBOL 20 defines codes specific to the
Task-to-Task and Remote File Access Routines. The codes include the
DIT status codes in the compatible COBOL format which provides only
the condition identification portion of the status code.
Also
included are Remote File Access file types, Remote File Access open
modes, Remote File Access record formats, Remote File Access record
attributes and Remote File Access close options.
To define these
names in your program,
include the following statement in your
WORKING-STORAGE section after an 01-level declaration as shown above
for the DIL$COBOL_20 element.
COPY DIT$COBOL_20 OF "SYS$LIBRARY:DIL.TLB".

11-2

VMS REMOTE FILE ACCESS

For programs that use the Remote File Access Routines with
compatible
names,
you must include both the DIL$COBOL 20
DIT$COBOL_20 library elements.

11.1.2

the
and

Storing a File Number

A file number consists of one longword of VMS memory. To store a file
number, you must define a data item with the following format:
01

your-fnum

PIC S9(9) USAGE COMPUTATIONAL.

When you call the DIT$ROPEN routine use your-fnum as the value for the
file number to be returned. When the routine successfully finishes
processing, it returns a value in your-fnum.

11.1.3

Storing Account Information

To include your user code, password and account number or charge code
in a call to the DIT$ROPEN routine, you must describe these attributes
as data items in Working-Storage. The format for ~hese data items
must be exactly as follows:
01
01
01

11.1.4

userid
passwd
acct

PIC X(39)
PIC X(39)
PIC X(39)

USAGE DISPLAY.
USAGE DISPLAY.
USAGE DISPLAY.

Reading and Writing Remote Data

To read or write data from a file on a remote system, the program on
the local system must define an area to accept the data and a one-word
computational item for the length of the data.

11.1.5

Checking the Status of a Remote File Access Routine

Section 9.1.4 explains how to check the status of a DIL
VMS COBOL.

routine

from

A simple call to the RFA Routines with an error check might be:
CALL "DIT$ROPEN" USING fnum, fnam, userid, passwd, acct, mode,
dattyp, recfor, recatt, recsiz, runit GIVING stat.
IF stat IS FAILURE
THEN DISPLAY "error".

11-3

VMS REMOTE FILE ACCESS
11.2

REMOTE FILE ACCESS FROM VMS FORTRAN

The information included in this section assumes
-You are writing a FORTRAN program
-You plan to use the program on a VMS system
This section explains how to store a file number, file name and user
attributes.
It also explains how to read or write a record or to
perform a status check.

11.2.1

Including the Interface Support Files

VMS systems have two different types of Interface Support files
for
each supported language.
The first class of files includes native VMS
type names for each of the various codes for VMS COBOL and VMS
FORTRAN.
The second class includes files with TOPS-lO/TOPS-20 COBOL
compatible names for VMS COBOL, and files that include ANSI Standard
names for the interface to VMS FORTRAN.
The Interface Support files
for the VMS are provided as a text library called DIL.TLB.
The
library includes the support files for both VMS COBOL and VMS FORTRAN.
Native VMS FORTRAN
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
Native VMS FORTRAN in DIL.TLB.
The elements are
DIL$FORTRAN,
DIT$FORTRAN, and DIX$FORTRAN.
The library element DIL$FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$FORTRAN.
Severity codes and
system codes are defined in element DIL$FORTRAN.
To define these
names in your program, include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIL$FORTRAN)'
This retrieves the
includes it in your

DIL$FORTRAN

element

the

library

file

and

program~

The library element DIT$FORTRAN defines codes· specific to
the
Task-to-Task and Remote File Access Routines.
The codes include the
DIT status codes which are standard VMS condition values.
Also
included are Remote File Access file types, Remote File Access open
modes, Remote File Access record formats, Remote File Access record
attributes and Remote File Access close options. To define these
names in your program, include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$FORTRAN)'
For programs which use the Remote File Access Routines with the native
VMS names, you must include both the DIL$FORTRAN and DIT$FORTRAN
library elements.

11-4

VMS REMOTE FILE ACCESS

ANSI Standard Compatible FORTRAN
If you want to write a program that can be easily transported to
another system, you may want to include the ANSI Standard FORTRAN
names in your program rather than the native VMS names.
You can use the FORTRAN INCLUDE statement to retrieve information from
DIL.TLB at compilation time.
There are three library elements for
ANSI Standard FORTRAN in DIL.TLB. The elements are DIL$ANSI_FORTRAN,
DIT$ANSI_FORTRAN, and DIX$ANSI_FORTRAN.
The library element DIL$ANSI FORTRAN defines general codes and names
applicable to the Data Conversion Routines, the Task-to-Task Routines
and the Remote File Access Routines. The general success status code
(SS-NORMAL)
is defined in element DIL$ANSI FORTRAN. Severity codes
and system codes are defined in element DIL$ANSI FORTRAN.
To define
these names in your program, include the statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB- (DIL$ANSI_FORTRAN) ,
This retrieves the DIL$ANSI_FORT~N element of the
includes it in your program.

library

file

and

The library element DIT$ANSI FORTRAN defines codes specific to the
Task-to-Task and Remote File Access Rout"ines. This includes the DIT
status codes which are standard VMS condition values.
Also included
are Remote File Access file types, Remote File Access open modes,
Remote File Access Record formats, Remote File
Access
record
attributes and Remote File Access close options. To define these
names in your program, include the following statement:
INCLUDE 'SYS$LIBRARY:DIL.TLB (DIT$ANSI_FORTRAN)'
For programs that use the remote file access routines with the
compatible names, you must include both the DIL$ANSI FORTRAN and
DIT$ANSI FORTRAN library elements.

11-5

VMS REMOTE FILE ACCESS
11.2.2

Storing a File Number

To store a file number, you must implicitly or explicitly
integer with the following format:

declare

When you call the DIT$ROPEN routine use fnum as the file number to
returned.

INTEGER

11.2.3

fnum

Storing Account Information

To include your user code, password, account number (or charge code)
in a call to the DIT$ROPEN routine, you must first declare these
values in your program.
The format for these data items is as
follows:
INTEGER userid (10)
INTEGER passwd (10)
INTEGER acct (10)

or
or
or

CHARACTER*39
CHARACTER*39
CHARACTER*39

userid
passwd
acct

NOTE
By default, VAX-II FORTRAN passes arguments of type
CHARACTER by descriptor.
In order to use CHARACTER
type variables as arguments to DIL (on VMS), the %REF
built-in function must be used because DIL string
arguments must be passed by reference.

11.2.4

Reading and Writing Remote Data

To read or write data from a file on a remote system, you must declare
an area on the local system to accept the data, and an integer for the
length of the data.

11.2.5

Checking the Status of a Remote File Access Routine

Section 9.2.4 explains how to check the status of a DIL
VMS FORTRAN.
A simple call with an error check might then be:
status = DIT$RREAD (fnum,dunit,rnaxsiz,bufnarn)
IF (status .NE. SS$_NORMAL) GOTO 100

100
101

TYPE 101
FORMAT (' error occurred')

11-6

Routine

from

VMS REMOTE FILE ACCESS

11.3

VMS REMOTE FILE ACCESS REFERENCE

11.3.1

DIT$ROPEN - Open a Remote File

PURPOSE:
This routine opens a remote, sequential
ASCII
file
for
processing.
It also assigns a file number to the opened file.
CALL FORMAT:
COBOL:

CALL "DIT$ROPEN" USING fnum, fnam, userid, passwd,
acct, mode, dattyp, recfor, recatt, recsiz, runit
GIVING stat.

FORTRAN:

status = DIT$ROPEN (fnum, fnam, userid, passwd, acct,
1 mode, dattyp, recfor, recatt, recsiz, runit)

where:
fnum

is a long integer that gives the file number of the
file that you want to open. This number is assigned by
the subroutine.

fnam

is an ASCII-8 character string that gives the name of
the file to be opened. The file name must also include
the node name of the file's system of origin.
See
Section 4.1 of this manual for further information.
NOTE

The
next
three
arguments
supply
accounting
information.
If the remote node is a DECSYSTEM-20 or
DECsystem-lO you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account.
If the remote node is
a VAX,
these parameters are optional.
If you do not
specify accounting information, the VMS system uses
the default DECnet directory.
userid

is your user code. A user code contains thirty-nine
ASCII-8 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
A password contains thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
An account contains thirty-nine
ASCII-8 characters.
If your account is less than
thirty-nine characters, left-justify the field.

mode

is a long integer that indicates the mode in which you
plan to use the file after it is opened. This version
of the DIL allows you to read the file, write the file
or append data to the file. Check with your system
manager to make sure the FAL on the file's computer
allows the type of access you have in mind.

11-7

VMS REMOTE FILE ACCESS

Mode

dattyp

DIL Name

Read

MODE-READ

Write

MODE-WRITE

Append data to
this file

MODE-APPEND

is a long integer that indicates the data type
file.
The DIL name for this argument is:

the

TYPE-ASCII
recfor

is a long integer that gives the record format.
This
argument, and the next three arguments, refer to the
records which you plan to process after opening the
file with the DIT$ROPEN routine.
Record Format

recatt

DIL Name

Undefined

RFM-UNDEFINED

Fixed length

RFM-FIXED

Variable length

RFM-VARIABLE

Variable length
with fixed length
control (VFC)

RFM-VFC

Stream

RFM-STREAM

is a long integer that indicates the record
of the file that you plan to process.
Record Attribute

attributes

DIL Name

Unspecified

RAT-UNSPECIFIED

Implied <LF><CR>
envelope

RAT-ENVELOPE

VMS printer
carriage control

RAT-PRINT

FORTRAN carriage
control

RAT-FORTRAN

Record attribute
RAT-PRINT is only valid for record format RFM-VFC.

11-8

VMS REMOTE FILE ACCESS
NOTE
If you plan to use the RFA routines to read a record
from another system, you can use the RFM-UNDEFINED or
RAT-UNSPECIFIED values for the "recfor" and "recatt"
arguments.
You only have to specify values for these
arguments if you want to write a file on a VMS system.
recsiz

is a long integer that gives the record size, in bytes.
If you plan to write the fila, this will be its maximum
record size.
Use zero if you want to read or append to
the file.
Use zero if you don't want to give the file
a maximum record size.

runit

is a long integer that gives the record size unit.
value of this argument is always zero.

STATUS CODES:
OIL Name

Meaning

DIT-TOOMANY

VerYou can't open any more files.
sion 2.0 of the OIL allows a maximu~
of 20 open files.

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-UNSFILETYPE

You attempted to write a file whose
file type is unsupported on the remote system.

DIT-FILEINUSE

The file is already being processed
by another program.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-9

The

VMS REMOTE FILE ACCESS
11.3.2

DIT$RREAD - Read Data From a Remote File

PURPOSE:
The DIT$RREAD routine reads a record from a file opened with
DIT$ROPEN routine.

the

CALL FORMAT:
COBOL:

CALL "DIT$RREAD" USING fnum, dunit, maxsiz, bufnam
GIVING stat.

FORTRAN:

status = DIT$RREAD (fnum, dunit, maxsiz, bufnam)

where:
fnum

is a long integer that gives the number of the file
that you want to read. File number is assigned by the
DIT$ROPEN routine.

dunit

is a long integer that gives the data unit
value for this argument is always zero.

maxsiz

is a long integer that specifies the maximum record
size
in
characters.
When
DIT$RREAD
finishes
processing, this argument contains the number
of
characters actually read by the routine.

bufnam

is where the routine places the data that it reads. It
is an ASCII-8 character string that must contain room
for at least the number of characters specified in
"maxsiz," above.

size.

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

OIT-EOF

The routine reached the end of the
file it was reading.

DIT-OVERRUN

The record being read is too large to
fit into the user buffer area.

OIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-10

The

VMS REMOTE FILE ACCESS
11.3.3

DIT$RWRITE - Write Data to a Remote File

PURPOSE:
The DIT$RWRITE routine writes a record
DIT$ROPEN.

into

file

opened

CALL FORMAT:
COBOL:

CALL "DIT$RWRITE" USING fnum, dunit, length, data
GIVING stat.

FORTRAN:

status

= DIT$RWRITE (fnum, dunit, length, data)

where:
fnum

is a long integer that gives the file number of the
file that you want to write.
File number is assigned
by the DIT$ROPEN routine.

dunit

is a long integer that specifies the data
The value of this argument is always zero.

unit

length

is a long integer
characters.

length,

data

is an ASCII-8 character string that represents the data
to write.

that

gives

the

data

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-11

size.
in

VMS REMOTE FILE ACCESS
11.3.4

DIT$RCLOSE - Close a Remote File

PURPOSE:
The DIT$RCLOSE routine closes the file that you opened
DIT$ROPEN routine.

with

the

CALL FORMAT:
COBOL:

CALL "DIT$RCLOSE" USING fnum, clopt GIVING stat.

FORTRAN:

status

= DIT$RCLOSE (fnum, clopt)

where:
fnum

is a long integer that gives the file number of the
file that you want to close.
File number is assigned
by the DIT$ROPEN routine.

clopt

is a long integer that gives the close option.
This
argument tells what you want to do with the file once
it's closed.
Close Option

DIL Name

No special action

OPT-NOTHING

Submit file for
remote batch processing

OPT-SUBMIT

Submit file for
remote printing

OPT-PRINT

Delete the remote
file

OPT-DELETE

STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

S8-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-12

VMS REMOTE FILE ACCESS
11.3.5

DIT$RDEL - Delete a File

PURPOSE:
The DIT$RDEL routine deletes a file.
You can only delete a
closed file.
If you want to delete an open file, delete it with
the DIT$CLOSE routine using the OPT-DELETE close option.
CALL FORMAT:
COBOL:

CALL "DIT$RDEL" USING fnam, userid, passwd, acct
GIVING stat.

FORTRAN:

status

= DIT$RDEL (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-8 character string that gives the name of
the file to be deleted.
The file name must also
include the node name of the file's system of origin.
NOTE

The
next
three
arguments
supply
accouQting
information.
If the remote node is a DECSYSTEM-20 or
DECsystem-lO you must supply a userid and password.
You must also specify an account unless the remote
system sets a default account.
If the remote node is
a VAX,
these parameters are optional.
If you do not
specify accounting information, the VMS system uses
the default DECnet directory.
userid

is your user code.
This field contains thirty-nine
ASCII-8 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
This field contains thirty-nine
ASCII-8 characters.
If your account is less than
thirty-nine characters, left-justify the field.

11-13

VMS REMOTE FILE ACCESS
STATUS CODES:
~1eaning

OIL Name
DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-14

VMS REMOTE FILE ACCESS
11.3.6

DIT$RSUB - Submit a File For Batch Processing

PURPOSE:
The DIT$RSUB routine submits a remote file -for batch processing
on the remote system.
You may only submit closed files for
processing.
If you want to submit an open file for batch
processing, use the DIT$RCLOSE routine with the OPT-SUBMIT close
option.
CALL FORMAT:
COBOL:

CALL "DIT$RSUB" USING fnam, userid, passwd, acct
GIVING stat.

FORTRAN:

status

= DIT$RSUB (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-8 character string that gives the name of
the file to be submitted.
The file name must also
include the node name of the file's system of origin.
NOTE

is your user code.
This field contains thirty-nine
ASCII-8 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
This field contains thirty-nine
ASCII-8 characters.
If your account is less than
thirty-nine characters, left-justify the field.

11-15

VMS REMOTE FILE ACCESS
STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-16

VMS REMOTE FILE ACCESS
11.3.7

DIT$RPRINT - Print a File

PURPOSE:
The DIT$RPRINT routine prints a remote file at the remote system.
If you want to print an open file, use the DIT$RCLOSE routine
with the OPT-PRINT close option.
CALL FORMAT:
COBOL:

CALL "DIT$RPRINT" USING fnam, userid, passwd, acct
GIVING stat.

FORTRAN:

status

= DIT$RPRINT (fnam, userid, passwd, acct)

where:
fnam

is an ASCII-8 character string that gives the name of
the file to be printed.
The file name must also
include the node name of the file's system of origin.
NOTE

is your user code.
This field contains thirty-nine
ASCII-8 characters.
If your user code is less than
thirty-nine characters, left-justify the field.

passwd

is your password.
This field contains thirty-nine
ASCII-8 characters.
If your password is less than
thirty-nine characters, left-justify the field.

acct

is your account.
This field contains thirty-nine
ASCII-8 characters.
If your account is less than
thirty-nine characters, left-justify the field.

11-17

VMS REMOTE FILE ACCESS
STATUS CODES:
DIL Name

Meaning

DIT-INVARG

You passed an incorrect or invalid
argument.

SS-NORMAL

The routine successfully completed
processing.

DIT-NETOPRFAIL

You attempted an impossible network
operation.

DIT-CHECKSUM

The network returned a network checksum error.

DIT-NOFILE

The file does not exist or is not
available to you.

DIT-HORRIBLE

This code is returned in the event of
a system or unexpected error.

11-18

VMS REMOTE FILE ACCESS
11.4

VMS REMOTE

11.4.1

FIL~

ACCESS EXAMPLES

VMS COBOL Remote File Access Examples

IDENTIFICATION DIVISION.
PROGRAM-ID.
CDAP32.
This program opens a remote file named DAP.TST and writes an
ASCII record into it, closes the file,
reopens the file and
reads the record back and then closes the file again.
This
program tries to write and read the file DAP.TST using the
default DECnet directory.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
VAX-II.
,'"'BJECT-COMPUTER.
VAX-II.
DATA DIVISION.
WORKING-STORAGE SECTION.
01

INTERFACE-FILES.
COpy DIT$COBOL OF "SYS$LIBRARY:DIL.TLB".
COpy DIL$COBOL OF "SYS$LIBRARY:DIL.TLB".

* DIL status return
01

DIL-STATUS PIC S9(9) COMPo

* File and directory description fields
01
01
01
01

FILE-NAME PIC X(39) VALUE "DAP.TST".
USERID PIC X(39) VALUE SPACES.
PASSWD PIC X(39) VALUE SPACES.
ACCT PIC X(39) VALUE SPACES.

* Record and file description fields
01
01
01

FILE-NUMBER USAGE COMP PIC S9(9).
RECORD-UNIT-SIZE USAGE COMP PIC S9(9) VALUE O.
RECORD-SIZE USAGE COMP PIC S9(9) VALUE 100.

DATA-RECORD PIC X(lOO).

DIL-DISPLAY PIC X(12).

11-19

VMS REMOTE FILE ACCESS
PROCEDURE DIVISION.
BEGIN-CDAP32.

* Open file DAP.TST for output; note:

for remote file access, if you
the connected directory

* leave the passwd and userid blank on a VAX,

* will be used

CALL "DIT$ROPEN" USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIT$K MODE WRITE, DIT$K TYPE ASCII,
DIT$K-RFM STREAM, DIT$K-RAT UNSPECIFIED,
RECORD-SIZE, RECORD-UNIT-SIZE
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" ROPEN Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? ROPEN: unsuccessful status return"
STOP RUN.

* Accept a record and write it to the file
DISPLAY" Enter data for the record for the remote file:
ACCEPT DATA-RECORD.

CALL "DIT$RWRITE" USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-SIZE, DATA-RECORD
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" RWRITE Status return: " DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? RWRITE: unsuccessful status return. "
STOP RUN.

* Close the file
CALL "DIT$RCLOSE" USING FILE-NUMBER, DIT$K_OPT_NOTHING
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" RCLOSE Status return: ", DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY"? RCLOSE: unsuccessful status return."
STOP RUN.

* Open the file to read the record
CALL "DIT$ROPEN" USING FILE-NUMBER, FILE-NAME, USERID, PASSWD, ACCT,
DIT$K MODE READ, DIT$K TYPE ASCII,
DIT$K-RFM STREAM, DIT$K RAT-UNSPECIFIED,
RECORD-SIZE, RECORD-UNIT-SIZE
GIVING DIL-STATUS.
MOVE OIL-STATUS TO DIL-DISPLAY.
DISPLAY" ROPEN Status return: ", DIL-DISPLAY.
IF OIL-STATUS IS NOT SUCCESS
DISPLAY"? ROPEN: unsuccessful status return."
STOP RUN.

11-20

VMS REMOTE FILE ACCESS

* Read the record
MOVE SPACES TO DATA-RECORD.
CALL "DIT$RREAD" USING FILE-NUMBER, RECORD-UNIT-SIZE,
RECORD-SIZE, DATA-RECORD
GIVING DIL-STATUS.
MOVE DIL-STATUS TO DIL-DISPLAY.
DISPLAY" RREAD returned ", DIL-DISPLAY.
IF DIL-STATUS IS NOT SUCCESS
DISPLAY "1 RREAD: unsuccesfu1 status return."
STOP RUN.
DISPLAY" The record was: "
DISPLAY DATA-RECORD.

11-21

VMS REMOTE FILE ACCESS
11.4.2

VMS FORTRAN Remote File Access Example

C FDAP32
C
C

This program opens a remote file named DAP.TST and writes an
ASCII record into it, closes the file,
reopens the file and
reads the record back and then closes the file again.

C Use the DIL interface files.
INCLUDE 'SYS$LIBRARY:DIL.TBL (DIT$FORTRAN)'
INCLUDE 'SYS$LIBRARY:DIL.TBL (DIL$FORTRAN),
C File and directory description fields
INTEGER FILNAM (10), USERID (10), PASSWD (10), ACCT (10), FILNUM
C Sending and receiving data records
INTEGER DATAl (25), DATA2 (25)
C DIL Status code
INTEGER DILSTS
C Record size and record unit size
INTEGER RECSIZ, RUNTSZ
DATA FILNAM I'DAP.',
1

'TST '

C Note: For remote file access on the VAX, if you leave the userid and
C passwd blank, the connected directory will be used.

,,,

DATA USERID I'
1
DATA PASSWD I'
1
DATA ACCT I'
1

'I
'I

C Program messages
200
201
202
203
700

FORMAT
FORMAT
FORMAT
FORMAT
FORMAT

(' ROPEN status return: " lID)
(' RWRITE status return: " lID)
(' RCLOSE status return: " lID)
(' RREAD status return: " lID)
('1 Invalid status returned ••• ')

C Request the password
100
105

FORMAT (' Enter the password:')
WRITE (6,100)
FORMAT (10A4)
ACCEPT 105, PASSWD

11-22

VMS REMOTE FILE ACCESS

COpen fi1eDAP.TST for output.
RUNTSZ
RECSIZ
DILSTS
1
2

= 100

= DIT$ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT,

DIT$K MODE WRITE, DIT$K TYPE ASCII, DIT$K_RFM_STREAM,
DIT$K=UNSPECIFIED, RECSIZ, RUN~SZ)

WRITE (6,200) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 115
WRITE (6,700)
STOP
C Accept a record and write it to the file
110
115
120

FORMAT (' Enter data for the record:')
WRITE (6,110)
FORMAT (25A4)
ACCEPT 120, DATAl
DILSTS

= DIT$RWRITE (FILNUM, RUNTSZ, RECSIZ, DATAl)

WRITE (6,201) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 125
WRITE (6,700)
STOP
C Close the file.
125

DILSTS

= DIT$RCLOSE (FILNUM, DIT$K_OPT_NOTHING)

WRITE (6,202) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 130
WRITE (6,700)
STOP
C Open the file to read the record
130

DILSTS

DIT$ROPEN (FILNUM, FILNAM, USERID, PASSWD, ACCT,

DIT$K MODE READ, DIT$K TYPE ASCII, DIT$K RFM STREAM,
DIT$K=RAT_UNSPECIFIED,-RECSIZ, RUNTSZ) -

WRITE (6,200) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 135
WRITE (6,700)
STOP

11-23

VMS REMOTE FILE ACCESS
C Read the record
135

DILSTS

= DIT$RREAD (FILNUM, RUNTSZ, RECSIZ, DATA2)

WRITE (6,203) DILSTS
IF (DILSTS .EQ. SS$ NORMAL) GO TO 145
WRITE (6,700)
STOP
140
145
146

FORMAT (' The record read was:
WRITE (6,140)
FORMAT (' " 25A4)
WRITE (6,146) DATA2

C Close the file
DILSTS

= DIT$RCLOSE (FILNUM, DIT$K_OPT_NOTHING)

WRITE (6,202) DILSTS
IF (DILSTS .EQ. SS$_NORMAL) GO TO 155
WRITE (6,700)
STOP
150
155

FORMAT (' FDAP32 successful ')
WRITE (6,150)
STOP
END

11-24

CHAPTER 12
LINKING A VMS PROGRAM

The linker associates your program with the Data Interchange Library
routines that your program calls. VMS supports two forms of the OIL,
an object library and a shareable image. When you have successfully
compiled your program,
link it by typing the following command
sequence:
For object library:
$ LINK usrprg, SYS$LIBRARY:DIL/LIBRARY, SYS$LIBRARY:XPORT/LIBRARY
where usrprg is the name of your program.
For sharable image:
$ LINK usrprg, SYS$LIBRARY:DIL/OPTIONS
where:
usrprg is the name of your program, and
SYS$LIBRARY:DIL.OPT
as
a
file
containing
specifications.

12-1

OPTIONS identifies
VMS linker option

APPENDIX A
LANGUAGE-SPECIFIC VALUES FOR OIL NAMES

This appendix shows the DIL Names for status codes, severity codes,
data type names and routine parame~er values as defined in the OIL
Interface Support files.
It then gives the equivalent names for COBOL
and FORTRAN on the VAX, the DECsystem-IO and the DECSYSTEM-20.
If you plan to write a COBOL program on a TOPS-IO or TOPS-20 syst~m,
use the ANSI COBOL names.
If you plan to write a FORTRAN program on a
TOPS-IO or TOPS-20 system, use the ANSI FORTRAN names. If you want to
write a program on a VMS system use the Native Vax names. If you plan
to write a program which can be
easily
transported
between
TOPS-IO/TOPS-20 and VMS, use the ANSI COBOL or ANSI FORTRAN names.

A-I

LANGUAGE-SPECIFIC VALUES FOR OIL NAMES

1STATUS CODES:

DIL NAME

ANSI COBOL

ANSI
FORTRAN

NATIVE VAX

DIT-ABORTREJECT
DIT-ABREJEVENT
DIT-CHECKSUM
DIT-CONNECTEVENT
DIT-DATAEVENT
DIT-DISCONNECTEVENT
DIT-EOF
DIT-FILEINUSE
DIT-HORRIBLE
DIT-INFONOTAVAIL
DIT-INFOOUTOFRANGE
DIT-INTDATAEVENT
DIT-INTERRUPT
DIT-INVARG
DIT-NETOPRFAIL
DIT-NODATAAVAILABLE
DIT-NOFILE
DIT-NOMOREFILES
DIT-NOTENOUGH
DIT-OVERRUN
DIT-TOOMANY
DIT-UNSFILETYPE
DIX-ALIGN
DIX-FMTLOST
DIX-GRAPHIC
DIX-IMPOSSIBLE
DIX-INVALCHAR
DIX-INVBYTSIZ
DIX-INVDATTYP
DIX-INVPDDGT
DIX-INVPDSGN
DIX-INVLNG
DIX-INVDNCHR
DIX-INVDNSGN
DIX-INVSCAL
DIX-NONPRINT
DIX-ROUNDED
DIX-TOOBIG
DIX-TRUNC
DIX-UNIMP
DIX-UNKARGTYP
DIX-UNKSYS
DIX-UNNORM
DIX-UNSIGNED
SS-NORMAL

DIT-C-ABORTREJECT
DIT-C-ABREJEVENT
DIT-C-CHECKSUM
DIT-C-CONNECTEVENT
DIT-C-DATAEVENT
DIT-C-DISCONNECTEVENT
DIT-C-EOF
DIT-C-FILEINUSE
DIT-C-HORRIBLE
DIT-C-INFONOTAVAIL
DIT-C-INFOOUTOFRANGE
DIT-C-INTDATAEVENT
DIT-C-INTERRUPT
DIT-C-INVARG
DIT-C-NETOPRFAIL
DIT-C-NODATAAVAILABLE
DIT-C-NOFILE.
DIT-C-NOMOREFILES
DIT-C-NOTENOUGH
DIT-C-OVERRUN
DIT-C-TOOMANY
DIT-C-UNSFILETYPE
DIX-C-ALIGN
DIX-C-FMTLOST
DIX-C-GRAPHIC
DIX-C-IMPOSSIBLE
DIX-C-INVALCHAR
DIX-C-INVBYTSIZ
DIX-C-INVDATTYP
DIX-C-INVPDDGT
DIX-C-INVPDSGN
DIX-C-INVLNG
DIX-C-INVDNCHR
DIX-C-INVDNSGN
DIX-C-INVSCAL
DIX-C-NONPRINT
DIX-C-ROUNDED
DIX-C-TOOBIG
DIX-C-TRUNC
DIX-C-UNIMP
DIX-C-UNKARGTYP
DIX-C-UNKSYS
DIX-C-UNNORM
DIX-C-UNSIGNED
SS-C-NORMAL

ABRTRJ
ARJEVT
CHKSUM
CONEVT
DATEVT
DSCEVT
DITEOF
FILIU
SYSERR
NOTAVL
INFOUR
INTEVT
INTRCV
INVARG
NETFAL
NODATA
NOFILE
NOM ORE
NOTENF
OVRRUN
TOOMNY
UNSTYP
ALIGN
FMTLST
GRAPHC
IMPOSS
INVCHR
BYTSIZ
DATTYP
PDDGT
PDSGN
INVLNG
DNMCHR
DNMSGN
INVSCL
NONPRN
RNDED
TOOBIG
TRUNC
UNIMP
ARGTYP
UNKSYS
UNNORM
UNSIGN
NORMAL

DIT$ ABORTREJECT
DIT$-ABREJEVENT
DIT$-CHECKSUM
DIT$-CONNECTEVENT
DIT$-DATAEVENT
DIT$-DISCONNECTEVENT
DIT$-EOF
.
DIT$-FILEINUSE
DIT$-HORRIBLE
DIT$-INFONOTAVAIL
DIT$-INFOOUTOFRANGE
DIT$-INTDATAEVENT
DIT$-INTERRUPT
DIT$-INVARG
DIT$-NETOPRFAIL
DIT$-NODATAAVAILABLE
DITS-NOFILE
DIT$-NOMOREFILES
DIT$-NOTENOUGH
DIT$-OVERRUN
DIT$-TOOMANY
DIT$-UNSFILETYPE
DIX$-ALIGN
DIXS-FMTLOST
DIX$-GRAPHIC
DIX$-IMPOSSIBLE
DIXS-INVALCHAR
DIX$-INVBYTSIZ
DIXS-INVDATTYP
DIX$-INVPDDGT
DIX$-INVPDSGN
DIXS-INVLNG
DIX$-INVDNCHR
DIX$-INVDNSGN
DIX$ INVSCAL
DIX$-NONPRINT
DIXS-ROUNDED
DIX$-TOOBIG
DIXS-TRUNC
DIX$-UNIMP
DIX$-UNKARGTYP
DIXS-UNKSYS
DIX$-UNNORM
DIXS-UNSIGNED
SSS_NORMAL

A-2

LANGUAGE-SPECIFIC VALUES FOR OIL NAMES
ISEVERITY CODES:)
OIL NAME

ANSI COBOL

STS-WARNING
STS-SUCCESS
STS-ERROR
STS-INFO
STS-SEVERE

STS-K-WARNING
STS-K-SUCCESS
STS-K-ERROR
STS-K-INFO
STS-K-SEVERE

ANSI FORTRAN
STSWRN
STSSUC
STSERR
STSINF
STSSEV

Is YSTEM
OIL NAME

ANSI COBOL

SYS-10-20
SYS-VAX

DIX-SYS-10-20
DIX-SYS-VAX

CODES:

NATIVE VAX
STS$K WARNING
STS$K-SUCCESS
STS$K-ERROR
STS$K-INFO
STS$K-SEVERE

VALUE

o
1
2
3
4

ANSI FORTRAN
SYS36
SYSVAX

NATIVE VAX
DIX$K SYS 10 20
DIX$K-SYS-VAX
-

VALUE
1
2

IREMOTE FILE ACCESS FILE TYPES:I
OIL NAME

ANSI COBOL

TYPE-ASCII

DIT-TYPE-ASCII

ANSI FORTRAN

NATIVE VAX

TASCII

VALUE
1

(REMOTE FILE ACCESS OPEN MODES:I
OIL NAME

ANSI COBOL

ANSI FORTRAN

MODE-READ
MODE-WRITE
MODE-APPEND

DIT-MODE-READ
DIT-MODE-WRITE
DIT-MODE-APPEND

MREAD
~1WRITE

MAPPND

NATIVE VAX
DIT$K MODE READ
DIT$K-MODE-WRITE
DIT$K-MODE-APPEND
-

VALUE
1
2
3

IREMOTE FILE ACCESS RECORD FORMATS:I
OIL NAME

ANSI COBOL

ANSI FORTRAN

RFM-UNDEFINED
RFM-FIXED
RFM-VARIABLE
RFM-VFC
RFM-STREAM

DIT-RFM-UNDEFINED FUNDEF
DIT-RFM-FIXED
FFIXED
DIT-RFM-VARIABLE FVAR
DIT-RFM-VFC
FVFC
DIT-RFM-STREAM
FSTM

A-3

NATIVE VAX
DIT$K RFM UNDEFINED
DIT$K-RFM-FIXED
DIT$K-RFM-VARIABLE
DIT$K-RFM-VFC
DIT$K=RFM=STREAM

VALUE

o
1
2
3
4

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES

I REMOTE FILE ACCESS RECORD ATTRIBUTES: I
OIL NAME

ANSI COBOL

ANSI FORTRAN

NATIVE VAX

VALUE

RAT-UNSPECIFIED
RAT-ENVELOPE
RAT-PRINT
RAT-FORTRAN

OIT-RAT-UNSPECIFIEO
OIT-RAT-ENVELOPE
DIT-RAT-PRINT
DIT-RAT-FORTRAN

AUNSPC
AENVLP
APRINT
AFTN

OIT$K RAT UNSPECIFIED

0
1
2
3

OIT$K-~AT-ENVELOPE

DIT$K-RAT-PRINT
DIT$K:RAT:FORTRAN

I REMOTE FILE ACCESS CLOSE OPTIONS: I
DIL NAME

ANSI COBOL

OPT-NOTHING
OPT-SUBMIT
OPT-PRINT
OPT-DELETE

OIT-OPT-NOTHING
OIT-OPT-SUBMIT
DIT-OPT-PRINT
OIT-OPT-DELETE

ANSI FORTRAN
ONTHNG
OSBMIT
OPRINT
ODLETE

ITASK-TO-TASK WAIT CODES:
DIL NAME

ANSI COBOL

ANSI FORTRAN

WAIT-NO
WAIT-YES

OIT-WAIT-NO
DIT-WAIT-YES

WAITLN
WAITLY

NATIVE VAX
DIT$K OPT NOTHING
DIT$K-OPT-SUBMIT
DIT$K-OPT-PRINT
OIT$K=OPT=DELETE

VALUE

o
1
2

I
NATIVE VAX
DIT$K WAIT NO
DIT$K=WAIT=YES

VALUE

o
1

I TASK-TO-TASK LINK TYPES for NFACC:I
OIL NAME

ANSI COBOL

ANS I. FORTRAN

LTYPE-ASCII
LTYPE-BINARY
LTYPE-SBIT

DIT-LTYPE-ASCII
DIT-LTYPE-BINARY
DIT-LTYPE-SBIT

OIL NAME

ANSI COBOL

ANSI FORTRAN

MSG-MSG
MSG-STM

DIT-MSG-MSG
DIT-MSG-STM

MSGMSG
MSGSTM

VAX
VALUE

NATIVE VAX

LASCII
LBIN
LSBIT

DIT$K LTYPE ASCII
DIT$K-LTYPE-BINARY
OIT$K=LTYPE=SBIT

I TASK-TO-TASK MESSAGE MODES: I
NATIVE VAX
DIT$K MSG MSG

OIT$(~MS(::STM

A-4

VALUE

1
2
3

TOPS-1O/20
VALUE
0
1
2

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES
[VMS TASK FIRE-UP CODES:
DIL NAME

ANSI COBOL

PAS-FIREUP
PAS-NFIREUP

OIT-PAS-FIREUP
OIT-PAS-NFIREUP

DIL NAME

ANSI COBOL

ASCII-7
ASCII-S
ASCIZ
D-FLOAT
DN6LO
DN6LS
DN6TO
DN6TS
DN6U
DN7LO
DN7LS
DN7TO
DN7TS
DN7U
DNSLO
DNSLS
DNSTO
DNSTS
DNSO
DN9LO
DN9LS
DN9TO
DN9TS
DN9U
EBCDIC-S
EBCDIC-9
F-FLOAT
FLOAT-36
FLOAT-72
G-FLOAT
G-FLOAT72
H-FLOAT
PDS
PD9
SIXBI,T
SBF12S
SBF16
SBF32
SBF36
SBFlS
SBF64
SBF72
SBFS
UBF16
UBF32
UBFS

DIX-DT-ASCII-7
OIX-OT-ASCII-S
OIX-OT-ASCIZ
OIX-OT-O-FLOAT
DIX-OT-DN6LO
OIX-OT-ON6LS
DIX-OT-ON6TO
OIX-OT-DN6TS
OIX-OT-DN6U
DIX-OT-ON7LO
OIX-OT-ON7LS
OIX-OT-ON7TO
OIX-OT-ON7TS
OIX-OT-DN7U
OIX-OT-DNSLO
OIX-DT-ONSLS
OIX-OT-ONSTO
OIX-OT-DNSTS
OIX-OT-ONSU
OIX-OT-ON9LO
OIX-OT-ON9LS
OIX-OT-ON9TO
OIX-OT-ON9TS
OIX-OT-ON9U
OIX-OT-EBCDIC-S
DIX-OT-EBCOIC-9
OIX-OT-F-FLOAT
OIX-OT-FLOAT-36
OIX-OT-FLOAT-72
DIX-DT-G-FLOAT
DIX OT G FLOAT72
OIX=OT=H=FLOAT
DIX-OT-PDS
OIX-DT-PD9
OIX-OT-SIXBIT
DIX-OT-SBFI2S
OIX-OT-SBFI6
DIX-OT-SBF32
DIX-OT-SBF36
OIX-OT-SBF4S
OIX-DT-SBF64
DIX-DT-SBF72
DIX-OT-~BFS

OIX-DT-UBFI6
DIX-OT-UBF32
DIX-OT-UBFS

ANSI FORTRAN
FIREUP
NFREUP

IDATA TYPESI

ANSI FORTRAN
ASCII7
ASCIIS
ASCIZ
OF LOAT
DN6LO
ON6LS
ON6TO
ON6TS
ON6U
ON7LO
DN7LS
ON7TO
DN7TS
ON7U
ONSLO
DNSLS
ONSTO
DNSTS
DNSU
ON9LO
ON9LS
ON9TO
DN9TS
DN9U
EBCDCS
EBCOC9
FFLOAT
FLOT36
FLOT72
GFLOAT
GFL072
HFLOAT
POS
P09
SIXBIT
SBF12S
SBF16
SBF32
SBF36
SBF4S
SBF64
SBF72
SBFS
UBF16
UBF32
UBFS

A-5

I
NATIVE VAX
OIT$K PAS FIREUP
OIT$K-PAS-NFIREUP

NATIVE VAX
DIX$K DT ASCII 7
OIX$K-OT-ASCII-S
OIX$K-OT-ASCIZOIX$K-OT-O FLOAT
DIX$K-OT-ON6LO
OIX$K-OT-ON6LS
OIX$K-OT-ON6TO
OIX$K-OT-ON6TS
DIX$K-DT-ON6U
OIX$K-OT-DN7LO
OIX$K-OT-ON7LS
OIX$K-OT-ON7TO
OIX$K-DT-ON7TS
OIX$K-DT-DN7U
DIX$K-OT-DNSLO
OIX$!(-OT-ONSLS
OIX$K-DT-ONSTO
OIX$K-OT-ONSTS
DIX$K-OT-ONSU
OIX$K-OT-ON9LO
OIX$K-OT-DN9LS
OIX$K-OT-ON9TO
OIX$K-OT-ON9TS
OIX$K-OT-DN9U
OIX$K-OT-EBCOIC S
OIX$K-OT-EBCOIC-9
DIX$K-OT-F FLOAT
OIX$K-DT-FLOAT 36
DIX$K-DT-FLOAT-72
DIX$K-OT-G FLOAT
DIX$K-DT-G-FLOAT72
DI X$K-OT-H-F LOAT
DIX$K-OT-PDS
DIX$K-:OT-PD9
OIX$K-OT-SIXBIT
DIX$K-DT-SBFI2S
DIX$K-OT-SBFI6
DIX$K-OT-SBF32
DIX$K-OT-SBF36
DIX$K-OT-SBF4S
DIX$K-OT-SBF64
DIX$K-DT-SBF72
DIX$K-OT-SBFS
OIX$K-OT-UBFI6
DIX$K-DT-UBF32
DIX$K-DT-UBFS

VALUE

o
1

VALUE
257
25S
259
769
1025
1026
1027
102S
1029
1030
1031
1032
1033
1034
1035
1036
1037
103S
1039
1040
1041
1042
1043
1044
260
261
770
771
772
773
774
775
12S1
12S2
262
513
514
515
516
517
51S
519
520
522
523
524

LANGUAGE-SPECIFIC VALUES FOR OIL NAMES
A.I

SPECIFYING DATA NAMES

TOPS-IO/TOPS-20 COBOL:
in

Character sets as specified in the
ALPHABET
clause
SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION:
APLHABET clause specification

DIL data type

ASCII
STANDARD-l
NATIVE
EBCDIC
user specified literals

ASCII-7
ASCII-7
ASCII-7
EBCDIC-9
unsupported

DIL DATA TYPE

SIGN clause

DIL FIELD LENGTH

PICTURE clause

USAGE clause

9 (n)
where l<=n<=l8

unspecified or
DISPLAY or
DISPLAY-6

DN6u
(or SIXBIT)

S9 (n)
where l<=n<=l8

unspecified or
DISPLAY or
DISPLAY-6

DN6TO
(or SIXBIT)

S9 (n)
where l<=n<=18

unspecified or
DISPLAY or
DISPLAY-6

LEADING
or
LEADING OVER PUNCHED

DN6LO
(or SIXBIT)

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY or
DISPLAY-6

TRAILING
or
TRAILING OVER PUNCHED

DN6TO
(or SIXBIT)

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY or
DISPLAY-6

LEADING SEPARATE

DN6LS
(or SIXBIT)

n + 1

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY or
DISPLAY-6

TRAILING SEPARATE

DN6TS
(or SIXBIT)

n + 1

9 (n)
where 1<=n<=18

DISPLAY-7

DN7U
(or A5CII-7)

59 (n)
where 1<=n<=18

DI5PLAY-7

DN7TO
(or ASCII-7)

59 (n)
where 1<=n<=18

DI5PLAY-7

LEADING
or
LEADING OVERPUNCHED

DN7LO
(or A5CII-7)

59(n)
where 1<=n<'=18

DISPLAY-7

TRAILING
or
TRAILING OVER PUNCHED

DN7TO
(or ASCII-7)

59 (n)
where 1<=n<=18

DI5PLAY-7

LEADING SEPARATE

DN7LS
(or A5CII-7 )

n + 1

A-6

the

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES

PICTURE clause

USAGE clause

SIGN clause

DIL DATA TYPE

TRAILING SEPARATE

DN7TS
(or ASCII-7 )

n + 1

DISPLAY-9

DN9U
(or EBCDIC)

S9 (n)
where 1<=n<=18

DISPLAY-9

DN9TO
(or EBCDIC)

S9 (n)
where 1<=n<=18

DISPLAY-9

LEADING
or
LEADING OVER PUNCHED

DN9LO
(or EBCDIC)

S9 (n)
where 1<=n<=18

DISPLAY'-9

TRAILING
or
TRAILING OVEHPUNCHED

DN9TO
(or EBCDIC)

S9(n)
where 1<=n<=18

DISPLAY-9

LEADING SEPARATE

DN9LS
(or EBCDIC)

n + 1

S9 (n)
where 1<=n<=18

DISPLAY-9

TRAILING SEPARATE

DN9TS
(or EBCDIC)

n + 1

9 (n) or S9 (n)
where l<=n<=lO

COMP or
COMPUTATIONAL

SBF36

9 (n) or s9 (n)
where lO<=n<=18

COMP or
COMPUTATIONAL

SBF72

COMP-l or
COMPUTATIONAL-l

FLOAT-36

9 (n) or S9 (n)
where 1<=n<=18

COMP-3 or
COMPUTATIONAL-3

PD9

X (n)

unspecified or
DISPLAY or
DISPLAY-6

SIXBIT

X (n)

DISPLAY'-7

ASCII-7

X (n)

DISPLAY-9

EBCDIC

INDEX

SBF36

S9(n)
where 1<=n<=18

DISPLAY-7

9 (n)
where 1<=n<=18

DIL FIELD LENGTH

DATABASE-KEY'

SBF36

DBKEY

SBF36

A-7

LANGUAGE-SPECIFIC VALUES FOR OIL NAMES
TOPS-IO/TOPS-20 FORTRAN
DATA TYPES

COMPILER SWITCH

DIL
DESCRIPTION

FIELD
LENGTH

CHARACTER * M

ASCII-7

INTEGER

SBF36

INTEGER * 2

SBF36

INTEGER * 4

SBF36

INTEGER
read in with:
FORMAT (nA5)

ASCII-7

n * 5

LOGICAL

SBF36

LOGICAL * 1

SBF36

LOGICAL * 4

SBF36

LOGICAL * 2

SBF36

REAL

FLOAT-36

REAL * 4

FLOAT-36

REAL * a

FLOAT-72

G-FLOAT72

ASCII-7

n * 5

REAL * a

/GFLOATING
(Produces extended
range DOUBLE
PRECISION)

REAL
read in with:
FORMAT (nA5)

A-a

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES
VMS COBOL:
Character sets as
specified in
the ALPHABET
SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISON:

clause

APLHABET clause specification

DIL data type

ASCII
STANDARD-l
STANDARD-2
NATIVE
EBCDIC
user specified literals

ASCII-8
ASCII-8
unsupported
ASCII-8
EBCDIC-8
unsupported

DIL DATA TYPE

SIGN clause

DIL FIELD
LENGTH

PICTURE clause

USAGE clause

9 (n)
where 1<=n<=18

unspecified or
DISPLAY

DN8U
(or ASCII-8 )

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY

DN8TO
(or ASCII-8 )

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY

LEADING or
LEADING OVER PUNCHED

DN8LO
(or ASCII-8 )

S9 (n)
where 1<=n<=18

unspecified or
DISPLAY

TRAILING or
TRAILING OVERPUNCHED

DN8TO
(or ASCII-8 )

S9 (n)

unspecified or
DISPLAY

LEADING SEPARATE

DN8LS
(or ASCII-8 )

n + 1

S9 (n)

unspecified or
DISPLAY

TRAILING SEPARATE

DN8TS
(or ASCII-8 )

n + 1

9 (n) or S9 (n)
where 1<=n<=4

COMP or
COMPUTATIONAL

SBF16

9 (n) or S9(n)
where S<=n<=9

COMP or
COMPUTATIONAL

SBF32

9 (n) or S9 (n)
where lO<=n<=18

COMP or
COMPUTATIONAL

SBF64

F-FLOAT

COMP-2 or
COMPUTATIONAL-2

D-FLOAT

COMP-3 or
COMPUTATIONAL-3

PD8

unspecified or
DISPLAY

ASCII-8

n x (n)

INDEX

SBF32

POINTER

SBF32

COMP-l or
COMPUTATIONAL-l

9 (n) or S9 (n)
where 1<=n<=18

A-9

the

LANGUAGE-SPECIFIC VALUES FOR DIL NAMES
VMS FORTRAN
DATA TYPES

COMPILER
SWITCH

BYTE
CHARACTER

* M

DIL
DESCRIPTION

FIELD
LENGTH

SBF8

ASCII-8

NOTE
By default, VAX-II FORTRAN passes arguments of type
CHARACTER by descriptor.
In order to use CHARACTER
type variables as arguments to DIL (on VMS),
the
%REF built-in function must be used because DIL
string arguments must be passed by reference.
DATA TYPES

COMPILER
SWITCH

DIL
DESCRIPTION

FIELD
LENGTH

SBF32

SBF16

INTEGER * 2

SBF16

INTEGER * 4

SBF32

INTEGER
read in with:
FORMAT (nA4)

ASCII-8

n * 4

LOGICAL

SBF32

SBF16

LOGICAL * 1

SBF8

LOGICAL * 4

SBF32

LOGICAL * 2

SBF16

REAL

F-FLOAT

REAL * 4

F-FLOAT

REAL * 8

D-FLOAT

G-FLOAT

REAL * 16

H-FLOAT

REAL
read in with:
FORMAT (nA4)

ASCII-8

n * 4

INTEGER
INTEGER

LOGICAL

REAL

* 8

/NOI4

/G-FLOATING

A-I0

APPENDIX... B
OIL DATA FORMATS

APPENDIX B
DIL DATA FORMATS

This appendix describes, in bit-by-bit detail, the formats of all of
the data types referred to in this document.
Bit numbering is
specified with the least significant bit having the lowest number.
In the diagrams for each type, the following notation is used:
d or 0
s or S
e or E
m or M
x or X
c

A data bit
A sign bit
An exponent bit
A mantissa (fraction) bit
An unused bit
Characters

All diagrams show bits grouped into bytes or words with the more
significant bits towards the left. They show bit numbering across the
top of each diagram.
For string-based data types, the "normal" order of the characters is
indicated at the bottom of the diagram.
"Cl" indicates the first
character, "C2" the second character, etc.

B.1

ALPHANUMERIC STRING DATA TYPES

ASCII-7 -- DEC-I0/20 7-bit ASCII
7-bit characters, packed 5 to a 36-bit word. The first character in a
word occupies the highest-order 7 bits. The lowest-order bit is not
used. ASCII representation is used.
Any byte alignment supported by the hardware byte-pointer instructions
is acceptable. A string may start anywhere, but if it crosses a word
boundary, the first byte in the new word must occupy the first 7 bits.
The length of the string in characters must be explicitly specified.
33333322222222221111111111
543210987654321098765432109876543210
dddddddDDDDDDDdddddddDDDDDDDdddddddX
C1

8-1

OIL DATA FORMATS
ASCII-8 -- PDP-II/VAX 8-bit ASCII
Each character occupies one 8-bit byte. The first, or leftmost, byte
of a string occupies the lowest~addressed byte of the storage
allocated to the string.
Following bytes in the string occupy
sequentially higher addresses.
The length of the string in characters must be explicitly specified.
The standard 7-bit ASCII character set is used.
76543210
xDDDDDDD

ASCIZ -- ASCII-7 with terminating null
This is the same as ASCII-7, except that instead of specifying the
length of the string, the string is terminated with a null byte at the
end.
EBCDIC-8 -- 8-bit EBCDIC
Each character occupies one 8-bit byte.
The
first
character
(leftmost)
in a string occupies the lowest-addressed byte of storage
allocated to that string. Succeeding characters occupy sequentially
higher-addressed bytes.
8-bit EBCDIC character coding is used.
The length of the string in characters must be explicitly specified.
76543210
dddddddd

EBCDIC-9 -- DEC-10/20 9-bit EBCDIC
Each character occupies one 9-bit byte.
4 characters are packed into
each 36-bit word.
The first
(leftmost) character in the string
occupies the high-order byte (most significant bits) of the word.
Any byte alignment supported by the hardware byte-pointer instructions
is acceptable. A string may start anywhere, but if it crosses a word
boundary, the first byte in the new word must occupy the first 9 bits.
8-bit EBCDIC character coding is used.
byte is not used.

The

high-order

bit

each

The length of the string in characters must be explicitly specified.
33333322222222221111111111
543210987654321098765432109876543210
XddddddddXddddddddXddddddddXdddddddd
C1

C4
B-2

DIL DATA FORMATS
SIXBIT -- SIXBIT Character String
Characters are packed 6 per 36-bit word.
The first character in a
word occupies the 6 highest-order bits.
The length of the string in
characters must be explicitly specified.
33333322222222221111111111
543210987654321098765432109876543210
ddddddDDDDDDddddddDDDDDDddddddDDDDDD
C1

B.2

BINARY FIXED-POINT DATA TYPES

SBF128 -- 128-bit signed binary fixed-point
128-bit signed fixed-point number represented in twos-complement
notation.
Higher-order
bytes
come
at higher addresses than
lower-order bytes.
Significance increases from right to left within
each byte.
The scale factor (number of decimal places to shift
must be specified.
3322222222221111111111
10987654321098765432109876543210
dddddddddddddddddddddddddddddddd

: A

66665555555555444444444433333333
32109876543210987654321098765432

A + 4

dddddddddddddddddddddddddddddddd
99999988888888887777777777666666
54321098765432109876543210987654
dddddddddddddddddddddddddddddddd

+ 8

1111111111111111111111111111
22222222111111111100000000009999
76543210987654321098765432109876
A + 12

sddddddddddddddddddddddddddddddd

B-3

the

point

left)

DIL DATA FORMATS
SBF16 -- 16-bit signed

bina~y

fixed-point

A 16-bit signed fixed-point number represented in twos-complement
notation.
The range of values possible is -32768.
to +32767.
before
scaling.
The high-order byte comes after (at a higher address than)
the low-order byte.
The scale factor (number of decimal places to shift
must be specified.

the

point

left)

111111
5432109876543210
sddddddddddddddd

SBF32 -- 32-bit signed binary fixed-point
A 32-bit signed fixed-point number represented in twos-complement
notation.
The
range
of values possible
is -2147483648.
to
+2147483647.
before scaling.
The bytes are stored at
increasing
addresses in order of increasing significance.
The scale factor (number of decimal places to shift
must be specified.

the

point

left)

3322222222221111111111
10987654321098765432109876543210
sddddddddddddddddddddddddddddddd

SBF36 -- 36-bit signed binary fixed-point

A 36-bit signed

fixed-point number represented in twos-complement
notation.
The range of values possible
is -2-35
(-34359738368
decimal) to 2-35 - 1 (34359738367 decimal) before scaling.

The scale factor (number of decimal places to shift
must be specified.
33333322222222221111111111
543210987654321098765432109876543210
sddddddddddddddddddddddddddddddddddd

B-4

the

point

left)

DIL·· DATA FORMATS

SBF64 -- 64-bit signed binary fixed-point
A 64-bit signed fixed-point number represented in twos-complement
notation. The range of values possible is -2-63 (-9223372036854775808
decimal) to (2-63)-1
(9223377036854775807 decimal)
before scaling.
The bytes are stored at increasing addresses in order of increasing
significance.
The scale factor (number of decimal places to shift
must be specified.

the

point

left)

3322222222221111111111
10987654321098765432109876543210

dddddddddddddddddddddddddddddddd
66665555555555444444444433333333
32109876543210987654321098765432
sddddddddddddddddddddddddddddddd

+ 4

SBF72 -- 72-bit signed binary fixed-point
A 72-bit signed

fixed-point number represented in twos-complement
notation.
The
range
of
values
possible
is
-2-70
(-1180591620717411303424 decimal) to (2-70)-1
(1180591620717411303423
decimal) before scaling.

The scale factor (number of decimal places to shift
must be specified.

the

point

left)

776666666666555555555544444444443333
109876543210987654321098765432109876
sddddddddddddddddddddddddddddddddddd

33333322222222221111111111
543210987654321098765432109876543210
xddddddddddddddddddddddddddddddddddd

A + 1

SBF8 -- 8-bit signed binary fixed-point
An 8-bit signed
notation.
The
scaling.

fixed-point number represented in twos-complement
range of values possible is -128.
to +127. before

The scale factor (number of decimal places to shift
must be specified.
76543210
sddddddd

B-5

the

point

left)

DIL DATA FORMATS
UBF16 -- 16-bit unsigned binary fixed-point
A 16-bit unsigned fixed-point number represented in binary notation.
The range of values possible is 0 to 65535 before scaling. The bytes
are stored at increasing
addresses
in
order
of
increasing
significance.
The scale factor (number of decimal places to shift
must be specified.

the

point

left)

111111
5432109876543210
dddddddddddddddd

UBF32 -- 32-bit unsigned binary fixed-point
A 32-bit unsigned fixed-point number represented in binary notation.
The range of values possible is 0 to 4294967295 before scaling. The
bytes are stored at increasing addresses in order of increasing
significance.
The scale factor (number of decimal places to shift
must be specified.

the

point

left)

3322222222221111111111
10987654321098765432109876543210
dddddddddddddddddddddddddddddddd

UBF8 -- 8-bit unsigned binary fixed-point
An 8-bit unsigned fixed-point number represented in binary
The range of values possible is 0 to 255 before scaling.
The scale factor (number of decimal places to shift
must be specified.
76543210
dddddddd

B-6

the

notation.

point

left)

OIL DATA FORMATS
B.3

FLOATING-POINT DATA TYPES

D-FLOAT -- 64-bit D-floating
A signed floating-point number represented
in exponential notation.
The magnitude of the item is in the approximate range .29 * (10--38)
to 1.7 * (10-38).
The precision is approximately 16 decimal digits.
3322222222221111111111
10987654321098765432109876543210
mmmmmmmmmmmmmmmmSeeeeeeeemmmmmmm

: A

4444444433333333
7654321098765432

Significance of mantissa bits

5555544
4321098

66665555555555444444444433333333
32109876543210987654321098765432
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

: A + 4

111111
3322222222221111
54321098765432101098765432109876

Significance of mantissa bits

The value of the data represented is <.lm> * 2-(e - 128) where
<.lm>
means add a one bit at the most significant end of the mantissa, and
consider the resulting string of bits to fall after a binary point.
A value of 0 is represented by s
operand.

= e = O.

= 1 e = 0 is

reserved

F-FLOAT -- 32-bit F-floating
A signed floating-point number represented
in exponential notation.
The magnitude of the item is in the approximate range .29*(10--38) to
1.7*(10-38). The precision is approximately 7 decimal digits.
The
bytes are stored at increasing addresses
in order of increasing
significance.
3322222222221111111111
10987654321098765432109876543210
mmmmmmmmmmmmmmmmSeeeeeeeemmmmmmm
111111
5432109876543210

2221111
2109876

Significance of mantissa bits

The value of the data represented is
<.lm>*(2-(e-128») where
<.lm>
means add a one bit at the most significant end of the mantissa, and
consider the resulting string of bits to fall after a binary point.
A value of 0 is represented by s
operand.

= e = O.

B-7

= 1 e = 0 is

reserved

DIL DATA FORMATS
FLOAT-36 -- 36-bit DEC-10/20 floating
A signed floating-point number represented
in exponential notation.
The magnitude of the
item is in the approximate range .5*(2--128)
(1.47*10--39 decimal) to (1-(2--27»
* (2-127)
(1.70*10-38 decimal).
The precision is approximately 7 decimal digits.
33333322222222221111111111
543210987654321098765432109876543210

SeeeeeeeeMMMMMMMMMMMMMMMMMMMMMMMMMMM
22222221111111111
654321098765432109876543210

Significance of mantissa bits

If the value is positive (sign = 0), the value of the data represented
is
<.m>*(2-(e-128»
where <.m> means take the mantissa, and consider
the resulting string of bits to fall after a binary point.
If the value is negative (sign = 1), the value of the data represented
is the negative of the value you get by taking the twos-complement of
the representation and proceeding as above.
FLOAT-72 -- 72-bit DEC-10/20 hardware floating (D-Float)
A signed floating-point number represented in exponential notation.
The magnitude of the
item is in the approximate range .5*(2--128)
(1.47*10--39 decimal) to (1-(2--27»*(2-127)(1.70*10-38 decimal).
The
precision is approximately 18 decimal digits.
33333322222222221111111111
543210987654321098765432109876543210

SeeeeeeeeMMMMMMMMMMMMMMMMMMMMMMMMMMM
665555555555444444444433313
109876543210987654321098765

: A
Significance of mantissa bits

33333322222222221111111111
543210987654321098765432109876543210
Xmrnrnrnrnrnrnrnrnrnrnrnrnrnrnmrnrnmmrnrnrnrnmmmrnrnmrnrnrnrnm

: A + 1

3333322222222221111111111
43210987654321098765432109876543210

Significance of mantissa bits

B-8

DIL DATA FORMATS
G-FLOAT -- 64-bit G-floating
A signed floating-point number represented in exponential notation.
The magnitude of the item is in the approximate range .56 *(10--308)
to .9 *(10-308).
The precision is typically 15 decimal digits.
3322222222221111111111
10987654321098765432109876543210
mmmmmmmmmmmmmmmmSeeeeeeeeeeemmmm

: A

4444444433333333
7654321098765432

Significance of mantissa bits

5544
1098

66665555555555444444444433333333
32109876543210987654321098765432
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

: A + 4

111111
3322222222221111
54321098765432101098765432109876

Significance of mantissa bits

The value of the data represented is <.lm> * (2-(e-l024» where
<.lm>
means add a one bit at the most significant end of the mantissa, and
consider the resulting string of bits to fall after a binary point.
A value of 0 is represented by s
operand.

= e = O.

= 1 e = 0 is

reserved

G-FLOAT72 -- 72-bit DEC-I0/20 G-floating
A signed floating-point number represented in exponential notation.
The magnitude of the item is in the approximate range .5 * (2--1024)
(2.78*10--309 decimal) to (1 -(2--59»*(2-1023) (8.99*10-307 decimal).
The precision is approximately 17 decimal digits.
33333322222222221111111111
543210987654321098765432109876543210
SeeeeeeeeeeeMMMMMMMMMMMMMMMMMMMMMMMM
555555555444444444433333
876543210987654321098765

: A
S~gnificance

of mantissa bits

33333322222222221111111111
543210987654321098765432109876543210
Xmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm
3333322222222221111111111
43210987654321098765432109876543210

: A + 1
Significance of mantissa bits

If the value is positive (sign = 0), the value of the data represented
is
<.m>*(2-(e-l024» where <.m> means take the mantissa, and consider
the resulting string of bits to fall after a binary point.
If the value is negative (sign = 1), the value of the data represented
is the negative of the value you get·by taking the twos-complement of
the representation and proceeding as above.

B-9

DIL DATA FORMATS
H-FLOAT -- 128-bit H-f1oating
A signed floating-point number represented in exponential notation.
The magnitude of the item is in the approximate range .84 * (10--4932)
to .59 * (10-4932). The precision is typically 33 decimal digits.
3322222222221111111111
10987654321098765432109876543210
mmmmmmmmmmmmmmmmseeeeeeeeeeeeeee

: A

111111111111
1100000000009999
1098765432109876

Significance of mantissa bits

6666555555S555444444444433333333
32109876543210987654321098765432
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

: A + 4

77777777776666669999998888888888
98765432109876545432109876543210

Significance of mantissa bits

99999988888888887777777777666666
54321098765432109876543210987654
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

: A + 8

44444444333333336666555555555544
76543210987654323210987654321098

Significance of mantissa bits

1111111111111111111111111111
22222222111111111100000000009999
76543210987654321098765432109876
mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

: A + 12

111111
3322222222221111
54321098765432101098765432109876

Significance of mantissa bits

The value of the data represented is <.lm> * (2~(e-l024)) where <.lm>
means add a one bit at the most significant end of the mantissa, and
consider the resulting strint of bits to fall after a binary point.
A value of 0 is represented by s = e = O. S = 1 e = 0 is a reserved
operand.
A value of 0 is represented by s = e = O. S = 1 e = 0 is a
reserved operand.

B-I0

DIL DATA FORMATS
8.4

DISPLAY NUMERIC DATA TYPES

DN6LO - Sixbit signed leading overpunched
A string of type SIXBIT
(described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in SIXBIT coding) decimal digits and spaces
(interpreted as zeroes), and at most one sign character. The sign
character, if present, must be the first character in the field.
The
sign characters and their meanings are listed:
]

J
K

L
M

N
0

P
Q
R

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

first
first
first
first
first
first
first
first
first
first

digit
digit
digit
digit
digit
digit
digit
digit
digit
digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4
5
6
7
8
9

The string is interpreted as a decimal number, right-justified in the
field.
The string may contain a maximum of 18 digits (19 characters
including the separate sign) .
NOTE
COBOL-IO/20 will accept any character code in a DN6LO
field and interpret it as some digit, or as a sign and
a digit.
The Data Conversion Routines will consider a
DN6LO field invalid if it contains characters other
than those listed above.
DN6LS -- Sixbit signed leading separate

A string of type SIXBIT (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The sign is represented by the character "+" for positive or
negative before the first significant digit in the field.

"-"

for

The string should contain (in SIXBIT coding) decimal digits and spaces
(interpreted as zeroes), and the sign characters.
The string is interpreted as a decimal number, right-justified in
field.
NOTE
COBOL-I0/20 will accept any ,character code in a DN6LS
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN6LS field
invalid if it contains characters other
than those listed above.

B-ll

the

OIL DATA FORMATS
DN6TO -- Sixbit signed trailing overpunched
A string of type SIXBIT
(described above)
with
interpreted
as
a
signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in SIXBIT coding) decimal digits and spaces
(interpreted as zeroes),
and at most one sign character.
The sign
character, if present, must be the last character in the field.
the
sign characters and their meanings are listed:
]

J
K

L
M

N
0
p

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

last
last
last
last
last
last
last
last
last
last

digit
digit
digit
digit
digit
digit
digit
digit
digit
digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4

5
6
7

8
9

The string is interpreted as a decimal number, right-justified in the
field.
The string may contain a maximim of 18 digits (19 characters
including the separate sign) •
NOTE
COBOL-I0/20 will accept any character code in a DN6TO
field and interpret it as some digit, or as a sign and
a digit.
The Data Conversion Routines will consider a
DN6TO field
invalid if it contains characters other
than those listed above.
DN6TS -- Sixbit signed trailing separate
A string of type SIXBIT
(described above) with
interpreted
as
a
signed fixed-point number
separa tely) •

some restrictions,
(scaling specified

The string should contain (in SIXBIT coding) decimal digits and spaces
(interpreted as zeroes),
and at most one sign character.
The sign
character is always present, and must be the
last character in the
field.
A "+" indicates a positive field, a "-" a negative field.
The string is interpreted as a decimal number, right-justified in
field.
The string may contain a maximum of 18 digits.
NOTE
COBOL-I0/20 will accept any character code in a DN6TS
field and interpret it as some digit, or as a sign and
a digit.
The Data Conversion Routines will consider a
DN6TS field
invalid if it contains characters other
than those listed above.

B-12

the

OIL DATA FORMATS

DN6U -- Sixbit unsigned display numeric
A string of type SIXBIT (described above) with some restrictions,
interpreted as an unsigned fixed-point number (scaling specified
separately).
The string should contain (in SIXBIT coding) decimal digits and spaces
(interpreted as zeroes).
The string may contain a maximum of 18
characters (digits).
The string is interpreted as a decimal number, right-justified in
field.

the

NOTE
COBOL-IO/20 will accept any character code in a DN6U
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN6U field invalid if it contains characters other
than those listed above.
DN7LO -- ASCII 7-bit signed leading overpunched
A string of type ASCII-7 (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in ASCII-7 coding) decimal digits and
spaces (interpreted as zeroes), and at most one sign character. The
sign character, if present, must be the first character in the field.
The sign characters and their meanings are listed:
]

J
K

L
M

a
p

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative·,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

first
first
first
first
first
first
first
first
first
first

digit
digit
digit
digit
digit
digit
digit
digit
digit
digit

is
is
is
is
is
"is
is
is
is
is

0
1
2
3
4
5

6
7
8
9

The string is interpreted as a decimal number, right-justified in
field.
The string may contain a maximum of 18 digits.

the

NOTE
COBOL-IO/20 will accept any character code in a DN7LO
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN7LO field invalid if it contains characters other
than those listed above.
DN7LS -- ASCII 7-bit signed leading separate
A string of type ASCII-7 (described above) with
interpreted
as
a signed fixed-point number
separately) •

B-13

some restrictions,
(scaling specified

DIL DATA FORMATS
The sign is represented by the character "+" for positive or
negative before the first significant digit in the field.

"-"

for

The string should contain (in ASCII-7 coding) decimal digits and
spaces (interpreted as zeroes), and the sign characters. The string
may contain a maximum of 18 digits
(19 characters including the
separate sign).
The string is interpreted as a decimal number, right-justified in
field.

the

NOTE
COBOL-IO/20 will accept any character code in a DN7LS
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN7LS field invalid if it contains characters other
than those listed above.
DN7TO -- ASCII 7-bit signed trailing overpunched
A string of type ASCII-7 (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in ASCII-7 coding) decimal digits and
spaces
(interpreted as zeroes), and at most one sign character. The
sign character, if present, must be the last character in the field.
The sign characters and their meanings are listed:
]

J
K

L
M

N
0
p

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

last digit
last digit
last digit
last digit
last digit
last digit
last digit
last digit
last digit
last digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4
5
6

7
8
9

The string is interpreted as a decimal number, right-justified in
field.
The string may contain a maximum of 18 digits.

the

NOTE
COBOL-IO/20 will accept any character code in a DN7TO
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN7TO field
invalid if it contains characters other
than those listed above.
DN7TS -- ASCII 7-bit signed trailing separate
A string of type ASCII-7 (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in ASCII-7 coding) decimal digits and
spaces
(interpreted as zeroes), and at most one ~ign character. The
sign character is always present, and must be the last character in
the field. A "+" indicates a positive field, a "-" a negative field.
B-14

DIL DATA FORMATS

The string is interpreted as a decimal number, right-justified in the
field.
The string may contain a maximum of 18 digits (19 characters
including the separate sign).
'
NOTE
COBOL-IO/20 will accept any character code in a DN7TS
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN7TS field invalid if it contains characters other
than those listed above.
DN7U -- ASCII 7-bit unsigned disp}ay numeric
A string of type ASCII-7 (described above) with some restrictions,
interpreted as an unsigned fixed-point number
(scaling specified
separately).
The string should contain (in ASCII-7
spaces (interpreted as zeroes).

coding)

decimal

digits

and

The string is interpreted as a decimal number, right-justified in
field.
The string may contain a maximum of 18 digits.

the

NOTE
COBOL-IO/20 will accept any character code in a DN7J
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN7U field invalid if it contains characters other
than those listed above.
DN8LO -- ASCII 8-bit signed leading overpunched
A string of type ASCII-8 (described above) with
interpreted
as a signed (fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in ASCII-8 coding) decimal digits and at
most one sign character. The sign character, if present, must be the
first character in the field.
The sign characters and their meanings
are listed:
]

J
K
L

a
p

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

first
first
first
first
first
first
first
first
first
first

digit
digit
digit
digit
digit
digit
digit
digit
digit
digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4
5
6

7
8
9

The string is interpreted as a decimal number, right-justified in
field.
The string may not contain more than 31 digits.

B-15

the

OIL DATA FORMATS
DN8LS -- ASCII 8-bit signed leading separate
A string of type ASCII-8 (described above)
with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The sign is represented by the character "+" for positive or "_" for
negative before the first significant digit in the field.
A sign of
" " (space) is also acceptable, and is interpreted as positive.
The string should contain (in ASCII-8 coding) decimal digits only, and
the sign character. The sign character must be the first character of
the field.
The string may not contain more than 31 digits
(32
characters including the separate sign).
The string is interpreted as a decimal number, right-justified in
field.

the

DN8TO -- ASCII 8-bit signed trailing overpunched
A string of type ASCII-8 (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should corttain
(in ASCII-8 coding)
decimal digits and
exactly one sign character.
The sign character must be the last
character in the field.
The sign character and their meanings are:
OVERPUNCHED CHARACTERS
Sign
VALUE

Digit
VALUE

DIL
DEFAULT
CHAR
Char

+
+
+
+
+
+
+
+
+
+

0
1
2
3

5
6
7
8

H
I

]

0
1
2
3
4
5
6
7
8
9

K
L
M

N
0
p

Q
R

Char

?
A
B
C
D
E
F
G

q
r
s
t
u
v
w
x

The string is interpreted as a decimal number, right-justified in
field.
The string may not contain more than 31 digits.

B-16

the

DIL DATA FORMATS
DN8TS -- ASCII 8-bit signed trailing separate
A string of type ASCII-8 (described above) with
interpreted
as
a signed fixed-point number
separately) •

some restrictions,
(scaling specified

The string should contain (in ASCII-8 coding) decimal digits and at
most one sign character. The sign character is always present, and
must be the last character in the field.
A "+" indicates a positive
field, a "-" a negative field.
The string is interpreted as a decimal number, right-justified in the
field.
The string may not contain more than 31 digits (32 characters
including the separate sign).
DN8U -- ASCII 8-bit unsigned diplay numeric
A string of type ASCII-8 (described above) with some restrictions,
interpreted as an unsigned fixed-point number
(scaling specified
separately).
The string should contain (in ASCII-8 coding)
The string may not have more than 31 digits.

decimal

digits

only.

The string is interpreted as a decimal number, right-justified in
field.

the

DN9LO -- EBCDIC 9-BIT signed leading overpunched
A string of type EBCDIC-9 (described above) with
interpreted
as
a signed fixed-point number
separately) •

some restrictions,
(scaling specified

The string should contain (in EBCDIC-9 coding)
decimal digits and
spaces
(interpreted as zeroes), and at most one sign character.
The
sign character, if present, must be the first character in the field.
The sign characters and their meanings are listed:
]
J
K
L
M

a
P

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

first digit
first digit
first digit
first digit
first-digit
first digit
first digit
first digit
first digit
first digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4
5
6
7
8
9

The string is interpreted as a decimal number, right-justified in
field.
The string may not contain more than 18 digits.
NOTE
COBOL-lO/20 will accept any character code in a DN9LO
field and interpret it as some/digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN9LO field
invalid if it contains characters other
than those listed above.
B-17

the

OIL DATA FORMATS
DN9LS -- EBCDIC 9-BIT signed leading separate
A string of type EBCDIC-9 (described above)
with
interpreted
as
a
signed fixed-point number
separately).

some restrictions,
(scaling specified

The sign is represented by the character "+" for positive or
negative before the first significant digit in the field.

"_"

for

The string should contain (in EBCDIC-9 coding)
decimal digits and
spaces
(interpreted as zeroes), and the sign characters.
The string
may not contain more than 18 digits
(19 characters
including the
separate sign).
The string is interpreted as a decimal number, right-justified in
field.

the

NOTE
COBOL-lO/20 will accept any character code in a DN9LS
field and interpret it as some digit, or as a sign and
a digit.
The Data Conversion Routines will consider a
DN9LS field
invalid if it contains characters other
than those listed above.
DN9TO -- EBCDIC 9-BIT signed trailing overpunched
A string of type EBCDIC-9 (described above) with
interpreted
as
a
signed fixed-point
number
separately).

some restrictions,
(scaling specified

The string should contain (in EBCDIC-9 coding)
decimal digits and
spaces
(interpreted as zeroes), and at most one sign character.
The
sign character, if present, must be the last character in the field.
The sign characters and their meanings are listed:
]

J
K

L
M

N
0

P
Q

Field
Field
Field
Field
Field
Field
Field
Field
Field
Field

is
is
is
is
is
is
is
is
is
is

negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,
negative,

last
last
last
last
last
last
last
last
last
last

digit
digit
digit
digit
digit
digit
digit
digit
digit
digit

is
is
is
is
is
is
is
is
is
is

0
1
2
3
4
5
6
7
8
9

The string is interpreted as a decimal number, right-justified in
field.
The string may not contain more than 18 digits.
NOTE
COBOL-lO/20 will accept any character code in a DN9TO
field and interpret it as some digit, or as a sign and
a digit.
The Data Conversion Routines will consider a
DN9TO field
invalid
if it contains characters other
than those listed above.

B-18

the

DIL DATA FORMATS
DN9TS -- EBCDIC 9-BIT signed trailing separate
A string of type EBCDIC-9 (described above) with
interpreted
as
a signed fixed-point number
separately).

some restrictions,
(scaling specified

The string should contain (in EBCDIC-9 coding) decimal digits and
spaces (interpreted as zeroes), and at most one sign character. The
sign character is always present, and must be the last character in
the field. A "+" indicates a positive field, a "-" a negative field.
The string is interpreted as a decimal number, right-justified in the
field.
The string may not contain more than 18 digits (19 characters
including the separate sign).
NOTE
COBOL-I0/20 will accept any character code in a DN9TS
field and interpret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN9TS field invalid if it contains characters other
than those listed above.
DN9U -- EBCDIC 9-BIT unsigned display numeric
A string of type EBCDIC-9 (described above) with some restrictions,
interpreted as an unsigned fixed-point number (scaling specified
separately).
The string should contain (in EBCDIC~9 coding) decimal digits and
spaces (interpreted as zeroes). The string may not contain more than
18 digits.
The string is interpreted as a decimal number, right-justified in
field.

the

-NOTE
COBOL-lO/20 will accept any character code in a DN9U
field and inte~pret it as some digit, or as a sign and
a digit. The Data Conversion Routines will consider a
DN9U field invalid if it contains characters other
than those listed above.

B.5

PACKED DECIMAL DATA TYPES

PD8 -- Packed decimal 8-bit
A string of 4-bit bytes, packed two per 8-bit byte, representing a
decimal number.
Bttes at higher addresses hold less significant
digits.
In each byte, the higher-numbered bits hold the more
significant digit.
3322222222221111111111
10987654321098765432109876543210
ddddDDDDddddDDDDddddDDDDddddDDDD
D7

D2
B-19

DIL DATA FORMATS
The sign is stored in the low-numbered bits of the highest-addressed
byte 1n the string. The digits are represented by unsigned numeric
values of 0 through 9 in the 4-bit bytes. The sign is represented as
follows:
DECIMAL
VALUE
10
11
12
13
14
15

SIGN
Positive
Negative
Positive (preferred representation)
Negative (preferred representation)
Positive
Positive

The length of the string may not exceed 31
including sign).

digits

(32

4-bit

bytes,

PD9 -- Packed decimal 9-bit
A strangely arranged string of 4-bit bytes,
representing a decimal
number.
The string may not exceed 19 bytes (the number represented
may not exceed 18 digits).
33333322222222221111111111
543210987654321098765432109876543210
XddddDDDDxDDDDddddXddddDDDDxDDDDdddd
Dl

The sign of the field is stored in the low-order byte of the field
(least significant).
The field is right justified on a 9-bit byte
boundary.
The digits are represented as unsigned numeric quantities in the 4-bit
bytes.
The legal sign values (given as the decimal value of
containing them) and their meanings are as follows:
DECIMAL
VALUE
10
11
12
13
14
15

the

4-bit

SIGN
Positive
Negative
Positve (preferred representation)
Negative (preferred representation)
Positive
"Nonprinting plus sign" -- forces absolute value

B-20

byte

ApPENDIX C
THE OIL SAMPLE ApPLICATION

APPENDIX C
THE OIL SAMPLE APPLICATION

The DIL package includes a sample application.
found on the installation tape.

The application may be

The application is a "Job Ticket" program.
This program eliminates
the collection of paper job labor tickets and enables each employee to
enter weekly job labor information from a terminal, either on a VMS,
TOPS-IO or TOPS-20 system. The information is stored in an ISAM file
on a TOPS-IO/TOPS-20 system.
When prompted by the program, the user either enters a new badge
number (and creates a new entry into the ISAM file) or an old badge
number (and updates an existing entry in the ISAM file).
A summary
report,
in the form of a sequential file stored on a VMS system, is
written from a separate report program on the DECSYSTEM-20 or
DECsystem-IO.
A server program keeps a passive link open at all times, waiting for
links from any other task.
The server program keeps a table of
information about the different links and their relative statuses at
all times.
All of the programs in this application use the DIL Interface
files.
DECSYSTEM-20

VAX-11

MR-S-2597-83

Figure C-I:

Sample Application Flowchart

C-I

Support

APPENDIX D
TASK IDENTIFICATION

This section shows sets of compatible task identification parameters
for use by the Task-to-Task Routines. Before a link can be completed,
active and passive tasks must accurately identify the link. The task
identification parameters issued by the active and passive tasks must
have matching values. The examples, below, illustrate the three types
of connections and show proper matching task identification for those
connections.
NOTE
When both the passive and active tasks run on the same
node, the active task can leave the hostname argument
blank.
NOTE
Specifying the taskname of an active task is not
meaningful on a VMS system; the VMS operating system
assigns a unique taskname.
It is also not generally
useful on a TOPS20 system, but you may want to supply
a taskname for debugging purposes.
If you do specify
a taskname,
that name must be unique.
If you do not
specify a taskname, the operating system assigns a
unique taskname.

D.l

ACCESSING A TASK BY NAME

passive task

active task

objectid: 0
descriptor: <spaces>
taskname: SERVER

hostname: BOSTON
objectid: 0
descriptor: SERVER
taskname: USER

SERVER is the task name of a general TASK (object type 0) running on
node BOSTON.
The active task USER can communicate with SERVER by
using objectid 0 (or TASK) and the unique taskname SERVER as its
descriptor.
SERVER must be the only TASK (objectid 0) on node BOSTON
whose taskname is SERVER, since taskname must always be unique.
If
you plan to have several identical passive tasks running on 9ne node,
you should use a nonzero objectid (as described in the second example,
below.)

0-1

TASK IDENTIFICATION
0.2

ACCESSING A TASK THAT PROVIDES A CLASS OF SERVICE

passive task

active task

objectid: 128
descriptor: <spaces>
taskname: <spaces>

hostname: MAINE
objectid: 128
descriptor: <spaces>
taskname: SOURCE

The active task SOURCE requests a connection to a passive task of
object type 128 on node MAINE.
There can be many passive tasks
running on one node, all with object type 128. SOURCE can connect to
any of the passive tasks that provide the generic service defined by
object type 128.

0.3

ACCESSING SPECIFIC TASK WHICH PROVIDES SERVICE (TOPS-20 ONLY)

passive task

active task

objectid: 17
descriptor: REB
taskname: AID

hostname: LONDON
objectid: 17
descriptor: REB
taskname: NFT

NFT is the active task; AID is the passive task,
running on node
LONDON.
NFT indicates that it wants to communicate with AID rather
than any other passive task on node LONDON which has objectid 17 by
specifying REB as the descriptor; this matches the descriptor used by
AID.
You can only do this if both tasks are running on TOPS20
systems. The objectid is 17. An object type of 17 indicates that the
passive task AID behaves as a FAL and that it provides the generic
services provided by passive tasks with object type 17.
(See the
TOPS20 DECnet User's Guide for a list of object types).

0.4

VMS PASSIVE TASKS

VMS systems can initiate a passive task in two ways.
When a VMS
system receives a connect request from an active task, the system
looks for an existing passive task that has the same task name (or
object number) as that specified by the active task.
If it finds a
passive task with matching DECnet taskname, that passive task receives
the connect request. This type of Task-to-Task behavior is the same
as the behavior of a passive task on a TOPS-20 system;
the passive
task runs continuously and waits for network connections from active
tasks. Section D.4.1 describes this type of VMS passive task.
If the
operating system does not find a task with a matching taskname, it
can, if requested, use the accounting information provided by the
active task to log in a new job. The new job then receives the
connect request from the active task. Section D.4.2 describes this
method of VMS task initiation.

D-2

TASK IDENTIFICATION
0.4.1

Tasks that Wait for a Connect Request

To create a passive task that waits for connections, you must:
•

Set the Network Logical Name to
call to the DIT$NFOPP routine

DIT$K PAS NFIREUP

your

•

Use the DIT$NFGND routine to check for network connections

•

Have SYSNAM privileges

This type of passive task can accept multiple connections.

D.4.2

Tasks Started as a Result of a Request

To create a passive task as a result of a request from an active task,
you must specify a valid password, userid and account when the active
task calls DIT$NFOPA, DIT$NFOPB or DIT$NFOP8.
The operating system
logs in a job using this information.
The newly-created job then runs a command file.
The command file
contains instructions to run the program that calls the passive task
open routine, DIT$NFOPP. The command file can also be used to perform
other tasks
(as shown in the example, below). You must create the
command file and put it in the proper directory.
The operating system determines where to look for the command file
based on the object type indicated by the active task in its call to
DIT$NFOPA, DIT$NFOPB or DIT$NFOP8.
If the passive task specifies an
object type of zero (object name TASK), put the command file in the
default directory that corresponds to the indicated userid. Give the
command file the name:
<taskname>.com
where

<taskname> is the task name of the
want to run.

passive

task

that

you

If the passive task has a non-zero object type, put the command file
in the Configuration Data Base in SYS$SYSTEM. See the DECnet-VAX
System Manager's Guide for information about the Configuration Data
Base and SYS$SYSTEM.
To create this type of passive task, you must set the Network Logical
Name to DIT$K PAS FIREUP in the call to DIT$NFOPP. You do not have to
use the DIT$NFGND-routine. The passive task starts only as a result
of a request from an active task; it does not wait. You do not need
SYSNAM privileges.
This type of passive task only accepts one connect request:
the
request that caused it to start. A VMS passive task started as a
result of a connect request may, however, declare a task name or
object type.
By declaring a taskname, the passive task can serve
other requests once it completes the request that caused it to start.
You need SYSNAM privileges to create this type of passive task.

D-3

TASK IDENTIFICATION
D.4.3

Example of a Task Started as a Result of a Request

An active task on another
following parameters:
hostname:
object type:
descriptor:
userid:
password:
account:

node

calls

DIT$NFOPA

and

passes

the

VELDT
0
IMPALA
PHONE
SWORDFISH
<spaces>

This task wants to communicate with a passive task called IMPALA on
the VELDT node, a VMS system. When the operating system receives this
request it checks to see whether a task named IMPALA is running on the
VELDT node.
It cannot find a running IMPALA, so it logs in a task
using the userid, password and account provided by the active task.
The operating system then searches the PHONE directory for a command
file with the name IMPALA.COM.
It finds a file containing the
following information:
$ SET NOON
$ RUN IMPALA.EXE
$ PURGE/KEEP=6 SYS$LOGIN:IMPALA.LOG
$ LOGOUT/BRIEF
The new job starts the command file.
The IMPALA.EXE
DIT$NFOPP and passes the following parameters:
NLN
objectid
task name

program

calls

DIT$K PAS FIREUP
0-IMPALA

This creates a passive task (IMPALA) to receive the connect request.
The operating system sends the connect request to IMPALA. IMPALA then
calls the DIT$NFACC routine to accept the connect request and
establish a logical link. When it finishes ·processing the request,
IMPALA closes the link with the DIT$NFCLS routine and exits. The job
then logs out, deleting all but the latest six copies of its log file
(as specified in the command file).

D-4

APPENDIX E
OIL STATUS CODES

ALL POSSIBLE STATUS CODES
FOR DECsystem-l0 and DECSYSTEM-20
LISTED BY DECIMAL VALUE
ALL POSSIBLE
RETURN CODES
1
60948488

60948489
60948490
60948491
60948492

60948496

60948497
60948498
60948499
60948500

60948504

60948505
60948506
60948507
60948508

60948512

60948513
60948514
60948515
60948516
60948520

60948521
60948522
60948523
60948524

60948528

60948529
60948530
60948531
60948532

r
r
r
r
r
r

DIL NAME

DESCRIPTION

SS-NORMAL

Success

DIX-ROUNDED

Result is rounded

DIX-TOOBIG

Converted source field too
large for destination field

DIX-INVDATTYP

Invalid data type code

DIX-UNKARGTYP

Argument passed by descriptor
is unknown type

DIX-UNKSYS

Unknown system of origin
specified

DIX-INVLNG

Length invalid or unspecified

E-l

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES

DIL NAME

DESCRIPTION

60948536 ~
60948537
60948538
60948539
60948540

DIX-INVSCAL

Scale factor invalid or
unspecified

60948544 ~
60948545
60948546
60948547
60948548

DIX-GRAPHIC

Graphic character changed in
conversion

60948552 ~
60948553
60948554
60948555
60948556

DIX-FMTLOST

Format effector gained or lost
in conversion

60948560 ~
60948561
60948562
60948563
60948564

DIX-NONPRINT

Non-printing character gained
or lost in conversion

60948568
60948569 ~
60948570
60948571
60948572

DIX-TRUNC

String too long for
destination -- truncated

60948576 ~
60948577
60948578
60948579
60948580

DIX-UNIMP

Unimplemented conversion

60948584 ~
60948585
60948586
60948587
60948588

DIX-INVALCHAR

Invalid character in source
field or conversion table

DIX-ALIGN

Invalid alignment for data
type

DIX-UNNORM

Floating point number
improperly normalized

60948592
60948593
60948594
60948595
60948596

60948600 ~
60948601
60948602
,
60948603
60948604

E-2

OIL STATUS CODES

r
r
r
r
r
r
r
r
r

ALL POSSIBLE
RETURN CODES

60948608
60948609
60948610
60948611
60948612
60948616
60948617
60948618
60948619
60948620
60948624
60948625
60948626
60948627
60948628
60948632
60948633
60948634
60948635
60948636
60948640
60948641
60948642
60948643
60948644
60948648
60948649
60948650
60948651
60948652
60948656
60948657
60948658
60948659
60948660
61210632
61210633
61210634
61210635
61210636
61210640
61210641
61210642
61210643
61210644

DIL NAME

DESCRIPTION

DIX-IMPOSSIBLE

Severe internal problems

DIX-UNSIGNED

Negative value moved to
unsigned field

DIX-INVBYTSIZ

Invalid byte size specified

DIX-INVDNUMCHR

Invalid display numeric
character in source
field.

DIX-INVDNUMSGN

Invalid display numeric sign
character in source field.

DIX-INVPDDGT

Invalid packed decimal digit
in source field.

DIX-INVPDSGN

. Invalid packed decimal sign
in source field.

DIT-HORRIBLE

Internal or system error

DIT-TOOMANY

Attempt to open too many files
or links

E-3

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES
61210648
61210649
61210650
61210651
61210652
61210656
61210657
61210658
61210659
61210660
61210664
61210665
61210666
61210667
61210668
61210672
61210673
61210674
61210675
61210676
61210680
61210681
61210682
61210683
61210684
61210688
61210689
61210690
61210691
61210692
61210696
61210697
61210698
61210699
61210700
61210704
61210705
61210706
61210707
61210708
61210712
61210713
61210714
61210715
61210716

>>>>>>>>>-

DIL NAME

DESCRIPTION

DIT-INVARG

Invalid argument

DIT-NETOPRFAIL

Network operation failed

DIT-CHECKSUM

Network checksum error

DIT-UNSFILETYPE

Unsupported file type

DIT-FILEINUSE

File activity precludes
operation

DIT-NOFILE

File not found

DIT-EOF

End of file

DIT-OVERRUN

Data overrun

DIT-NOMOREFILES

No more files

E-4

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES
61211432
61211433
61211434
61211435
61211436
61211440
61211441
61211442
61211443
61211444
61211448
61211449
61211450
61211451
61211452
61211456
61211457
61211458
61211459
61211460
61211464
61211465
61211466
61211467
61211468
61211832
61211833
61211834
61211835
61211836
61211840
61211841
61211842
61211843
61211844
61211848
61211849
61211850
61211851
61211852
61211856
61211857
61211858
61211859
61211860

~
~
~
~
~
~
~
~
~

DIL NAME

DESCRIPTION

DIT-CONNECTEVENT

Connect event

DIT-ABREJEVENT

Abort/reject event

DIT-INTDATAEVENT

Interrupt data event

DIT-DATAEVENT

Data event

DIT-DISCONNECTEVENT Disconnect event

DIT-ABORTREJECT

Abort/reject

DIT-INTERRUPT

Interrupt

DIT-NOTENOUGH

Not enough data available

DIT-NODATAAVAILABLE No data available

E-5

DIL STATUS CODES

ALL POSSIBLE
RETURN CODES

61211864
61211865
61211866
61211867
61211868

61211872
61211873
61211874
61211875
61211876

DIL NAME

DESCRIPTION

DIT-INFONOTAVAIL

Information not available

DIT-INFOOUTOFRANGE

Information out of range

ALL POSSIBLE STATUS CODES
FOR VMS SYSTEMS
LISTED BY DECIMAL VALUE
ALL POSSIBLE
RETURN CODES
1
15237128
15237129
15237130
15237131
15237132
15237136
15237137
15237138
15237139
15237140
15237144
15237145
15237146
15237147
15237148
15237152
15237153
15237154
15237155
15237156
15237160
15237161
15237162
15237163
15237164

r
r
r
r
r

DIL NAME

DESCRIPTION

SS-NORMAL

Success

DIX-ROUNDED

Result is rounded

DIX-TOOBIG

Converted source field too
large for destination field

DIX-INVDATTYP

Invalid data type code

DIX-UNKARGTYP

Argument passed by
descriptor is unknown
type

DIX-UNKSYS

Unknown system of origin
specified

E-6

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES

DIL NAME

DESCRIPTION

15237168 ~
15237169
15237170
15237171
15237172

DIX-INVLNG

Length invalid or unspecified

15237176 ~
15237177
15237178
15237179
15237180

DIX-INVSCAL

Scale factor invalid or
unspecified

DIX-GRAPHIC

Graphic character changed in
converstion

DIX-FMTLOST

Format effector gained or
lost in conversion

DIX-NONPRINT

Non-printing character
gained or lost
in conversion

DIX-TRUNC

String too long for
destination -- truncated

DIX-UNIMP

Unimplemented conversion

DIX-INVALCHAR

Invalid character in
source field or
conversion table

DIX-ALIGN

Invalid alignment for data
type

15237184
15237185
15237186
15237187
15237188
15237192
15237193
15237194
15237195
15237196
15237200
15237201
15237202
15237203
15237204
15237208
15237209
15237210
15237211
15237212
15237216
15237217
15237218
15237219
15237220
15237224
15237225
15237226
15237227
15237228

15237232 ~
15237233
15237234
15237235
15237236

E-7

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES

DIL NAME

DESCRIPTION

DIX-UNNORM

Floating point number
improperly normalized

DIX-IMPOSSIBLE

Severe internal problems

DIX-UNSIGNED

Negative value moved to
unsigned field

15237264 ~
15237265
15237266
15237267
15237268

DIX-INVBYTSIZ

Invalid byte size
specified

15237272 ~
15237273
15237274
15237275
15237276

DIX-INVDNUMCHR

Invalid display numeric
character in source field

15237280 ~
15237281
15237282
15237283
15237284

DIX-INVDNUMSGN

Invalid display numeric sign
character in source field

DIX-INVPDDGT

Invalid packed decimal digit
in source field

DIX-INVPDSGN

Invalid packed decimal sign
in source field

DIT-HORRIBLE

Internal or system error

15237240
15237241
15237242
15237243
15237244
15237248
15237249
15237250
15237251
15237252
15237256
15237257
15237258
15237259
15237260

15237288
15237289
15237290
15237291
15237292
15237296
15237297
15237298
15237299
15237300
15302664
15302665
15302666
15302667
15302668

E-8

OIL STATUS CODES
ALL POSSIBLE
RETURN CODES
15302672
15302673
15302674
15302675
15302676
15302680
15302681
15302682
15302683
15302684
15302688
15302689
15302690
15302691
15302692
15302696
15302697
15302698
15302699
15302700
15302704
15302705
15302706
15302707
15302708
15302712
15302713
15302714
15302715
15302716
15302720
15302721
15302722
15302723
15302724
15302728
15302729
15302730
15302731
15302732
15302736
15302737
15302738
15302739
15302740

~
~
~
~
~
~
~
~

DIL NAME

DESCRIPTION

DIT-TOOMANY

Attempt to open too many
files or links

DIT-INVARG

Invalid argument

DIT-NETOPRFAIL

Network operation failed

DIT-CHECKSUM

Network checksum error

DIT-UNSFILETYPE

Unsupported file type

DIT-FILEINUSE

File activity precludes
operation

DIT-NOFILE

File not found

DIT-EOF

End of file

DIT-OVERRUN

Data overrun

E-9

OIL STATUS CODES
ALL POSSIBLE
RETURN CODES
15302744
15302745
15302716
15302747
15302748
15303464
15303465
15303466
15303467
15303468
15303472
15303473
15303474
15303475
15303476
15303480
15303481
15303482
15303483
15303484
15303488
15303489
15303490
15303491
15303492
15303496
15303497
15303498
15303499
15303500
15303864
15303865
15303866
15303867
15303868
15303872
15303873
15303874
15303875
15303876
15303880
15303881
15303882
15303883
15303884

>->->--

>--

DIL NAME

DESCRIPTION

DIT-NOl10REFI LES

No more files

DIT-CONNECTEVENT

Connect event

DIT-ABREJEVENT

Abort/reject event

DIT-INTDATAEVENT

Interrupt data event

DIT-DATAEVENT

Data event

DIT-DISCONNECTEVENT Disconnect event

DIT-ABORTREJECT

Abort/reject

DIT-INTERRUPT

Interrupt

DIT-NOTENOUGH

Not enough data available

E-I0

DIL STATUS CODES
ALL POSSIBLE
RETURN CODES

DIL NAME

DESCRIPTION

15303888 ~
15303889
15303890
15303891
15303892

DIT-NOTDATAAVAILABLE No data available

15303896 ~
15303897
15303898
15303899
15303900

DIT-INFONOTAVAIL

Information not
available

15303904 ~
15303905
15303906
15303907
15303908

DIT-INFOOUTOFRANGE

Information out of
range

E-ll

APPENDIX F
BIT TRANSPORT

This appendix describes how the DIL routines actually move the user
data.
You do not need this information if you plan to transfer ASCII
data or binary fields of common data types.
ASCII data appears as
ASCII data on any homogeneous or heterogeneous system. Common binary
data arrives at the receiving heterogeneous system in a format that
can be used by the Data Conversion Routines.
The information supplied by this appendix will be useful if your data
consists of bit maps, masks, or other special-purpose or user-defined
data types.
This type of data is beyond the scope of the Data
Conversion Routines.

F.l

NFOPB LINKS

Data from a 36-bit system is shipped across the network link as a
string of 8-bit bytes. They are sent in order, from right to left.
The four high-order bits of the first word are combined to form a byte
with the four low-order bits of the next word.
The following example shows two 36-bit words that contain ASCII data.

No. of bits

These words actually travel
format:

through

the

network

IEEEEEEEXI

ICDDDDDDDI

IBBCCccccl

IAAABBBBBJ

F-l

the

following

BIT TRANSPORT

JJJYAAAA

IIIIJJJJ

HHHHHIII

I GGGGGGHH

I FFFFFFFG I
If the receiving system is also a 36-bit system, it stores the bytes
in the same order as they were stored on the original system.
If the
receiving system is a 32-qit system, it stores the bytes in the order
they were sent. The data can then be meaningfully accessed with the
Data Conversion Routines.
The sys'tem sends VMS data through the network as 8-bi t bytes.
following nine bytes exist on a VAX:
11111111

22222222

33333333

44444444

55555555
H

66666666

F-2

the

BIT TRANSPORT

77777777

88888888

99999999
They are sent through the network in this order. They also arrive at
a 32-bit system in the same order. The bytes will arrive at a 36-bit
system as the following two words:

I 555544444444333333332222222211111111 )
L

I 999999998888888877777777666666665555 I
H

Byte 5 is split between 2 words:
low-order bits in the first word and
high-order bits in the second word. These 36-bit words are suitable
for input to the Data Conversion Routines.
If you send data between homogeneous systems, the data arrives at the
recelvlng system formatted in the same way as it appeared on the
sending system.
You do not,
therefore, need to call the Data
Conversion Routines to translate this data.

F.2

REMOTE FILE ACCESS IN ASCII MODE AND NFOPA LINKS

ASCII data, stored as 7-bit bytes on 36-bit systems or as 8-bit bytes
on 32-bit systems, becomes a special case when sent in ASCII mode.
It
is always sent as 8-bit ASCII characters and stored in the format of
the receiving system.
This means that the following 36-bit word of
ASCII data:

No. of bits:

I0 I

F-3

BIT TRANSPORT

Is sent through the network, and arrives at a
following format:

32-bit

system

the

a
a
a
a
This data can then be used without calling the Data Conversion
Routines, even if it was transported between heterogeneous systems.

F.3

NFOP8 LINKS

Task-to-Task communication using NFOpa links should only be used if
you plan to move a-bit bytes of non-textual data. The host system
stores and accesses the bytes as it would normally store 8-bit bytes.
Unused bits are not considered significant and are not sent over the
network. The data will not necessarily be in a format appropriate for
input to the Data Conversion Routines.
For example, the 36-bit word:

No. of bits:

F-4

BIT TRANSPORT

would be sent through the network and received on a VAX as:

1111111111
8
1222222221

1333333331
8

I 444444441
8

F-5

APPENDIX G
TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES

This appendix explains error messages and
Task-to-Task and Remote-File-Access routine.

G.l

their

causes

for

each

REMOTE-FILE-ACCESS ERROR CODES AND THEIR MEANINGS:

G.l.l

ROPEN/DIT$ROPEN Routine:

DIT-INVARG:
1.

Filename is a string but
is not ASCII-7
(DECsystem-lO/20
only).
If you are using the routine from a COBOL program,
make sure that the filename's USAGE is DISPLAY-7.

Userid is a string but is not ASCII-7 (DECsystem-lO/20 only).
If you are using the routine from a COBOL program, make sure
that the userid's USAGE is DISPLAY-7.

Password is a string but is not ASCII-7
(DECsystem-lO/20
only).
If you are using the routine from a COBOL program,
make sure that the password's USAGE is DISPLAY-7 ..

Account is a string but is not ASCII-7
(DECsystem-lO/20
only).
If you are using the routine from a COBOL program,
make sure that the account's USAGE is DISPLAY-7.

File open mode does not have a valid value. The file must be
opened for MODE-READ, MODE-WRITE, or MODE-APPEND.

File data type does not have a valid value.
must be TYPE-ASCII.

File record format does not have a valid value. Valid record
formats are RFM-UNDEFINED, RFM-FIXED, RFM-VARIABLE, RFM-VFC,
or RFM-STREAM.

Record attributes does not have a valid value. Valid record
attributes are RAT-UNSPECIFIED, RAT-ENVELOPE, RAT-PRINT, or
RAT-FORTRAN.

File name has improper syntax.

G-l

The

data

type

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
10.

Error in directory name (VMS only).

11.

Device full (VMS only).

12.

Logical name error (VMS only).

13.

Node name error (VMS
syntax.

14.

Error in quoted string (VMS only). There is no need for you
to specify access information in a quoted string.
If you
receive this error without doing so, it is an internal error.

15.

Error in file type (VMS only).

16.

Error in file version

only).

nu~ber

The

node

name

has

improper

(VMS only).

SS-NORMAL:
1.

Normal successful completion.

DIT-FILEINUSE:
1.

File activity precludes this operation (VMS only).

DIT-TOOMANY:
1.

Attempt to open more than 20 files.
You are
files open at once for version 2 of the OIL.

limited

DIT-NOFILE:
1.

File to be created already exists.

File not found.

File not available because it is locked.

File protection violation.

Error in access control string (probable internal error,
only).

Directory not found (VMS only).

File expiration date not yet reached (VMS only). You
overwrite this file because it has not expired yet.

cannot

DIT-CHECKSUM:
1.

Network checksum error (probable monitor error, VMS only).

G-2

VMS

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-NETOPRFAIL:
1.

Cannot connect to the FAL. This may be because the monitor
has used up the resources it needs to make the connection,
the network node you want is down or does not exist, the node
is not currently running a FAL, the FAL on the node you need
has aborted, there are already too many connections to the
node you need, there are too many connections already to the
FAL, you passed invalid accounting information (userid,
password, and account) for the remote file, or because there
is no network path to the node you need.

DAP protocol error (internal error).

Network link broken.

Operation not supported by remote system.

File-transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.l.2

RREAD/DIT$RREAD:

DIT-INVARG:
1.

File number not in valid range or refers to a file
not open.

which

SS-NORMAL
1.

Normal successful completion.

DIT-EOF:
1.

End of file.

DIT-OVERRUN:
1.

Data overrun. For files on a DECsystem-lO or DECSYSTEM-20,
you must add 2 to the length of a written record to determine
the actual record size in the file. This is because files on
the DECsystem-lO or DECSYSTEM-20 are always actually written
in stream format with <CR><LF>s, and you must allow room in
your buffer when reading such a file to accommodate the
<CR><LF> as well as your data.

G-3

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-NETOPRFAIL:
1.

Cannot connect to FAL. This may be because the monitor has
used up the resources it needs to make the connection, the
network node you want is down or does not exist, the node is
not currently running a FAL, the FAL on the node you need has
aborted, there are already too many connections to the node
you need, there are too many connections already to the FAL,
you passed invalid accounting information (userid, password,
and account)
for the remote file, or because there is no
network path to the node you need.

DAP protocol error (internal error).

Network link broken.

Operation not supported by remote system.

File-transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-CHECKSUM:
1.

Network checksum error (probable monitor error, VMS only).

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.l.3

RWRITE/DIT$RWRITE:

DIT-INVARG:
1.

File number is out of range or refers to a file which is
open.

not

S5-NORMAL:
1.

Normal successful completion.

DIT-NOFILE:
1.

Privilege violation.

DIT-NETOPRFAIL:
1.

G-4

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
2.

DAP protocol error (internal error).

Network link broken.

Operation not supported by remote system.

File transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-HORRIBLE:
1.

In version 2 of the DIL, it is possible to get this error on
a DECsystem-lO or DECSYSTEM-20 if you attempt to write a
fixed-length file on a VMS system and the length of the
record being written does not agree with the record size of
the file.

Internal error.

Monitor error.

Hardware error.

G.l.4

RCLOSE/DIT$RCLOSE:

DIT-INVARG:
1.

Invalid close option. Valid close options
OPT-PRINT, OPT-SUBMIT, or OPT-DELETE.

File number out of range or refers to a
open.

are

file

OPT-NOTHING,
which

not

DIT-NETOPRFAIL:
1.

Cannot connect to FAL. This may be because the monitor has
used up the resources it needs to make the connection, the
network node you want is down or does not exist, the node is
not currently running a FAL, the FAL on the node you need has
aborted, there are already too many connections to the node
you need, there are too many connections already to the FAL,
you passed invalid accounting information (userid, password,
and account) for the remote file, or because there is no
network path to the node you need.

DAP protocol error (internal error).

Network link broken.

Operation not supported by remote system.

File transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

G-5

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-HORRIBLE:
1.

In version 2 of the OIL, it is possible to get this error on
a DECsystem-l0 or DECSYSTEM-20 if you attempt to write a
fixed-length file on a VMS system and the length of the
record being written does not agree with the record size of
the file.

Internal error.

Monitor error.

Hardware error.

G.l.S

RDEL/DIT$RDEL:

DIT-INVRG:
1.

File name is a string but is not ASCII-7
(DECSYSTEM-I0/20
only).
If you are using this routine from a COBOL program,
the filename's USAGE must be DISPLAY-7.

Userid is a string but is not ASCII-7
(DECsystem-l0 or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the userid's USAGE must be DISPLAY-7.

Password is a string but is not ASCII-7
(DECsystem-l0 or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the password's USAGE must be DISPLAY-7.

Account is a string but is not ASCII-7
(DECsystem-l0 or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the account's USAGE must be DISPLAY-7.

Filename has invalid syntax.

SS-NORMAL:
1.

Normal successful completion.

DIT-NOFILE:
1.

Invalid simultaneous access.
this file.

File not found.

File protection violation.

Error in access control string (VMS only).

Directory not found (VMS only).

G-6

Another user is

already

using

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-NETOPRFAIL:
1.

Cannot connect to FAL. This may be because the monitor has
used up the resources it needs to make the connection, the
network node you want is down or does not exist, the node is
not currently running a FAL, the FAL on the node you need has
aborted, there are already too many connections to the node
you need, there are too many connections already to the FAL,
you passed invalid accounting information (userid,
password,
and account)
for the remote file, or because there is no
network path to the node you need.

DAP protocol error (internal error).

Network link broken.

Operation not supported on remote system.

File transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.l.6

RSUB/DIT$RUB:

DIT-INVARG:
1.

File name is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the filename's USAGE must be DISPLAY-7.

Userid is a string but
is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the userid's USAGE must be DISPLAY-7.

Password is a string but
is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the password's USAGE must be DISPLAY-7.

Account is a string but
is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the account's USAGE must be DISPLAY-7.

Filename has invalid syntax.

Error in directory name (VMS only).

Logical name error (VMS only).

Node name error (VMS only).

G-7

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
9.

Error in quoted string (VMS only).

10.

Error in file type (VMS only).

11.

Error in version number (VMS only).

DIT-NOFILE:
1.

File not found.

File protection violation.

Error in access control string (VMS only).

Directory not found (VMS only).

File locked (VMS only).

SS-NORMAL:
1.

Normal successful completion.

DIT-NETOPRFAIL:
1.

Cannot connect to FAL. This may be because the monitor has
used up the resources it needs to make the connection, the
network node you want is down or does not exist, the node is
not currently running a FAL, the FAL on the node you need has
aborted, there are already too many connections to the node
you need, there are too many connections already to the FAL,
you passed invalid accounting information (userid, password,
and account) for the remote file, or because there is no
network path to the node you need.

DAP protocol error (internal error).

Network link broken.

Operation not supported on remote system.

File transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.l.7

RPRINT/DIT$RPRINT:

DIT-INVARG:
1.

Filename is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, filename's USAGE must be DISPLAY-7.

G-8

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
2.

Userid is a

string but is not ASCII-7
(DECsystem-lO or
only).
If you are using this routine from a
COBOL program, userid's USAGE must be DISPLAY-7.
DECSYSTEM~20

Password is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, password's USAGE must be DISPLAY-7.

Account is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, account's USAGE must be DISPLAY-7.

Filename has invalid syntax.

Error in directory name (VMS only) •

Logical name error (VMS only) •

Node name error (VMS only) •

Error in quoted string (VMS only) .

10.

Error in file type (VMS only) •

11.

Error in version number (VMS only) •

SS-NORMAL:
1.

Normal successful completion.

DIT-NOFILE:
1.

File locked.

File not found.

File protection violation.

Error in access control string (VMS only).

Directory not found (VMS only).

File locked (VMS only).

DIT-NETOPRFAIL:
1.

Cannot connect to FAL. This may be because the monitor has
used up the resources it needs to make the connection, the
network node you want is down or does not exist, the node
is
not currently running a FAL, the FAL on the node you need has
aborted, there are already too many connections to the node
you need, there are too many connections already to the FAL,
you passed invalid accounting information (userid,
password,
and account)
for the remote file, or because there is no
network path to the node you need.

DAP protocol error (internal error).

Network link broken.

G-9

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
4.

Operation not supported by remote system.

File transfer mode precludes operation (VMS only).

Network operation failed (VMS only).

DIT-HORRIBLE:

G.2

Internal error.

Monitor error.

Hardware error.

TASK-TO-TASK ERRORS AND THEIR MEANINGS:

G.2.1

NFOPA, NFOPB,
DIT$NFOPP:

NFOP8,

NFOPP/DIT$NFOPA,

DIT$NFOPB,

DIT$NFOP8,

DIT-INVRG:
1.

Network Logical Name is not an integer.

Network Logical Name has an invalid value (for DIT$NFOPP, VMS
only).
It must have the initial value of either PAS-FIREUP
or PAS-NFIREUP on entry to this routine on a VMS system.

Hostname is a string but is not ASCTI-7
(DECSYSTEM-IO/20
only).
If this routine is called from a COBOL program,
hostname's USAGE must be DISPLAY-7.

Objectid is a string but is not ASCII-7
(DECSYSTEM-IO/20
only).
If this routine is called from a COBOL program,
objectid's USAGE must be DISPLAY-7.

Descriptor is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If this routine is called from a COBOL
program, descriptor's USAGE must be DISPLAY-7.

Taskname is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If this routine is called from a COBOL
program, taskname's USAGE must be DISPLAY-7.

Password is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If this routine is called from a COBOL
program, password's USAGE must be DISPLAY-7.

Account is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If this routine is called from a COBOL
program, account's USAGE must be DISPLAY-7.

User data is a string but is not ASCII-7
(DECsystem-lO or
DECSYSTEM-20 only).
If this routine is called from a COBOL
program, the user data must have USAGE DISPLAY-7.

G-IO

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
10.

Wait code is not an integer.
or WAIT-NO.

It must have the value WAIT-YES

11.

Unknown or unreachable network node name.

12.

Invalid object. You may have specified a nonexistent object
name (one that is not defined for your system), or used an
object number which is out of range or which you do not have
the privilege to use for a passive task. See the DECnet
manual for your system.

13.

Invalid taskname.

14.

Object is already defined.

15.

Optional data exceeds 16 bytes.

The taskname you gave may not be unique.

SS-NORMAL
1.

Normal successful completion.

DIT-TOOMANY:
1.

Attempt to open more than 20 links at once. You are
to 20 links at anyone time in DIL version 2.

limited

The monitor will not allow you to open any more links. On a
DECsystem-lO or DECSYSTEM-20, a nonprivileged job has a limit
of four open links. The monitor itself may have run out of
links.

No privileges to open links (VMS only).

Insufficient memory to open links (VMS only).

DIT-ABORTREJECT:
1.

Waiting link open got an abort or reject.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.2

NFGND/DIT$NFGND:

DIT-INVARG:
1.

Network Logical Name is not an integer, is out of
refers to an unused link.

Wait code is not an integer or has an invalid value.
have the value WAIT-YES or WAIT-NO.

G-ll

range,

It must

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
SS-NORMAL:
1.

Wait code was WAIT-NO and nothing new has happened.

DIT-CONNECTEVENT:
1.

Connect event occurred (connect request if link
connect accept if link is active).

passive:

DIT-ABREJEVENT:
1.

Abort or reject event occurred.

DIT-DISCONNECTEVENT:
1.

Disconnect event occurred.

DIT-INTDATAEVENT:
1.

Interrupt data available.

DIT-DATAEVENT:
1.

Data available.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.3

NFACC/DIT$NFACC:

DIT-INVARG:

Network Logical Name is not an integer, is out of
refers to an unused link.

Link type is not an integer or has an invalid value.
Valid
link types are LTYPE-ASCII, LTYPE-BINARY, or LTYPE-8BIT.

Count of optional data is not an integer or has an invalid
value.
You may have 0 to 16 optional data characters.

Optional data is a string but is not ASCII-7 (DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the optional data must have USAGE DISPLAY-7.

SS-NORMAL:

Normal successful completion.

DIT-ABORTREJECT:

Link aborted.

G-12

range,

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.4

NFRCV/DIT$NFRCV:

DIT-INVARG:
1.

Network Logical Name is not an integer, is out of
refers to an unused link.

range,

Data unit size is not an integer.

Count of data is not an integer.

Message-mode flag is not an integer or has an invalid
It must have the value MSG-STM or MSG-MSG.

value.

Wait code is not an integer or has an invalid value.
have the value WAIT-YES or WAIT-NO.

It must

SS-NORMAL:
1.

Normal successful completion.

DIT-INTERRUPT:
1.

Interrupt data message must be read first.

DIT-NOTENOUGH:
1.

Not enough data available to satisfy nonwaiting
request (DECSYSTEM-20 only).

No data available now for non-waiting read.

stream

mode

DIT-ABORTREJECT:
1.

Link aborted or disconnected.

DIT-OVERRUN:
1.

Data will not fit into user buffer. For a DECSYSTEM-20 only,
no data is lost. Another NFRCV call with a larger buffer may
retrieve the data. On other systems, the data message has
been truncated to fit in the user's buffer.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G-13

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
G.2.S

NFSND/DIT$NFSND:

DIT-INVARG:
1.

Network Logical Name not an integer, is out of range, or
an invalid value.

Record unit size is not an integer.

Data count is not an integer.

Message-mode flag not an integer or has an invalid value.
must have the value MSG-MSG or MSG-STM.

has

SS-NORMAL:
1.

Normal successful completion.

DIT-ABORTREJECT:
1.

Link aborted.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.6

NFREJ/DIT$NFREJ:

DIT-INVARG:
1.

Network Logical Name not an integer,
refers to an unused link.

Reject code is not an integer.

Count of optional data is not an integer or
value.
It must be from 0 to 16.

Optional data is a string but is not ASCII-7 (DECsystem-l0 or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the optional data must have USAGE DISPLAY-7.

DIT-ABORTREJECT:
1.

Link aborted.

SS-NORMAL:
1.

Normal successful completion.

G-14

,is

out

has

range,

invalid

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.7

NFINT/DIT$NFINT:

DIT-INVARG:
1.

Network Logical Name not an integer,
refers to an unused link.

out

range,

Count of interrupt data not an integer or has
value.
It must have a value between 0 and 16.

Interrupt data is a string but is not ASCII-7
(DECsystem-lO
or DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the interrupt data must have USAGE DISPLAY-7.

invalid

SS-NORMAL:
1.

Normal successful completion.

DIT-ABORTREJECT:
1.

Link aborted.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

DIT-INTERRUPT:
1.

G.2.8

There is an outstanding interrupt message.

NFRCI/DIT$NFRCI

DIT-INVARG:
1.

Network Logical Name not an integer,
refers to an unused link.

Count of interrupt data characters is not an integer.

Interrupt data is a string but is not ASCII-7
(DECsystem-lO
or DECSYSTEM-20 only).
If you are using this routine in a
COBOL program, the data must have USAGE DISPLAY-7.

G-15

out

range,

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
SS-NORMAL:
1.

Normal successful completion.

DIT-ABORTREJECT:
1.

Link aborted.

DIT-NODATAAVAILABLE:
1.

No interrupt data available now.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G.2.9

NFCLS/DIT$NFCLS:

DIT-INVARG:
1.

Network Logical Name not an integer,
refers to an unused link.

range,

Type of link close is not an integer.

Count of optional close data is not an integer or is out
range. The count of optional data must be from 0 to 16.

Optional data is a string but is not ASCII-7 (DECsystem-lO or
DECSYSTEM-20 only).
If you are using this routine from a
COBOL program, the optional data must -have USAGE DISPLAY-7.

SS-NORMAL:
1.

Normal successful completion.

DIT-ABORTREJECT:
1.

Link aborted.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G-16

out

TASK-TO-TASK AND REMOTE-FILE-ACCESS ERROR MESSAGES
G.2.10

NFINF/DIT$NFINF:

DIT-INVARG:
1.

Network Logical Name is not an integer, is out of
refers to an unused link.

range,

Type of information wanted is not an integer.

Count of information returned is not an integer.

Area for returned information is a string but is not ASCII-7
(DECsystem-lO or DECSYSTEM-20 only).
If you are using this
routine in a COBOL program, the data area must have USAGE
DISPLAY-7.

SS-NORMAL
1.

Normal successful completion.

DIT-ABORTREJECT:
1.

The link aborted or was rejected.

DIT-INFOOUTOFRANGE:
1.

Information requested is not in the range of valid values.
Valid
information
to request is INF-NODE,
INF-OBJECT,
INF-DESCF,
INF-DESC,
INF-USERID,
INF-PASSWD,
INF-ACCT,
INF-OPT, INF-SEG, or INF-ABTCODE.

DIT-INFONOTAVAILABLE:
1.

Information requested is not available. You cannot get it
because this operating system does not supply it, you do not
have the necessary privileges, or the information is not
available for this type of link.

DIT-HORRIBLE:
1.

Internal error.

Monitor error.

Hardware error.

G-17

INDEX

. NOTE
To minimize the length of entries,
several abbreviations have been
used throughout this index.
The following
list explains these
abbreviations:
Abbreviation
DIL
DCR
TTT
RFA
FFD
NLN
(T)

(TC)
(TF)
(V)

(VC)
(VF)

Meaning
Data Interchange Library
Data Conversion Routines
Task-to-Task Routines
Remote File Access Routines
Foreign Field Descriptor
Network Logical Name
TOPS-IO/TOPS-20
TOPS-IO/TOPS-20 COBOL
TOPS-IO/TOPS-20 FORTRAN
VMS
VMS COBOL
VMS FORTRAN

The example shown below tells where to find information about
a foreign field descriptor from TOPS-IO/TOPS-20 COBOL:
FFD,
storing (Te)

storing

INDEX

-AAccess, remote File
see RFA
-BBit Transport, F-1
Byte Offset
Introduction, 2-4
TOPS-10/20, 2-4
VMS, 2-4

-cCHARACTER datatype for TOPS-10/20
FORTRAN, 6-5, 7-4
CHARACTER datatype for VMS
FORTRAN, 10-6, 11-6
COBOL
DCR (T), 5-1
DCR (V), 9-1
RFA (TC), 7-1
RFA (V), 11-1
TTT (T), 6-1
TTT (V), 10-1
Code
condition, 1-5
facility, 1-5
message, 1-5
severity, 1-5
Condition value, 1-4
Condition value, VMS, 1-4
Control Bits, 1-5
CVGEN Routine, 5-30

DCR (Cont.)
Foreign Field Descriptors, 2-2
Record Layout for, 2-4
Single-function Routines, 2-2
Supported Conversions, 2-1
DIL
Data Formats, B-1
DIL names, A-1
Introduction, 1-1
sample application, C-1
DIL Names
values for, A-1
DILINI Routine, 5-3, 5-7
DIT$NFACC Routine, 10-23
DIT$NFCLS Routine, 10-32
DIT$NFGND Routine, 10-7
DIT$NFOP8 Routine, 10-18
DIT$NFOPA Routine, 10-12
DIT$NFOPB Routine, 10-15
DIT$NFOPP Routine, 10-21
DIT$NFRCV Routine, 10-26
DIT$NFSND Routine, 10-28
DIT$RCLOSE Routine, 11-12
DIT$RDEL Routine, 11-13
DIT$ROPEN Routine, 11-7
DIT$RPRINT Ro~tine, 11-17
DIT$RREAD Routine, 11-10
DIT$SUB Routine, 11-15
DIT$WRITE Routine, 11-11
DIX$BY DET Routine, 9-11
DIX$BY-DIX DES Routine, 9-9
DIX$MAK DES DET
passing to (VC), 9-3
Routine, 9-7

-F-DData Conversion Routines
see DCR
Data Formats, B-1
fixed-point, B-3
floating-point, B-7
string, B-1
Data Interchange Library
see DIL
Data Names
for COBOL (T), A-6
for COBOL (V), A-9
for FORTRAN (T), A-8
for FORTRAN (V), A-11
DCR, 1-1
Byte Offset for, 2-4
Concepts, 2-1
Detailed Description, 2-4
for TOPS-10/20 COBOL, 5-1
for TOPS-10/20 FORTRAN, 5-4
for VMS COBOL, 9-1
for VMS FORTRAN, 9-4

FAL, 4-2
FFD, 2-2
storing (TC), 5-2
storing (TF), 5-4
storing (VC), 9-3
storing (VF), 9-5
File Access Listener, 4-2
File name
format, 4-2
Foreign Field Descriptor
see FFD
FORTRAN
DCR (T), 5-4
DCR (V), 9-4
RFA (TF), 7-4
RFA (V), 11-4
TTT (T), 6-4
TTT (V), 10-4
-HHeterogeneous Network, 1-1

Index-1

Homogeneous Network, 1-1
-1-

Instructions, overlay
TOPS-I0/20, 8-1
Interface Files
compatible, 1-6
for DCR (TC), S-l
for DCR (TF), S-4
for DCR (VC), 9-1
for DCR (VF), 9-4
for RFA (TC), 7-1
for RFA (TF), 7-4
for RFA (VC), 11-1
for RFA (VF), 11-4
for TTT (TC), 6-1
for TTT (TF), 6-4
for TTT (VC), 10-1
General, 1-6
Introduction, 1-6
native, 1-6
specific, 1-6
TTT (VF), 10-4
-LLayout, record
Introduction, 2-4
TOPS-I0/20, 2-4
VMS, 2-4
Like-to-like translation, 2-1
Linkage Instructions
TOPS-I0, 8-1
TOPS-20, 8-1
VMS, 12-1
Logical Link, 3-1

-NNetwork Connection, 3-1
Network Logical Name
see NLN
Network, heterogeneous, 1-1
Network, homogeneous, 1-1
NFACC Routine, 6-22
NFCLS Routine, 6-32
NFGND Routine, 6-6
NFOP8 Routine, 6-17
NFOPA Routine, 6-11
NFOPB Routine, 6-14
NFOPP Routine, 6-20
NFRCV Routine, 6-2S
NFSND Routine, 6-28
NLN, 3-2
for TOPS-I0 FORTRAN, 6-4
for TOPS-20 COBOL, 6-2
for TOPS-20 FORTRAN, 6-4
for VMS COBOL, 10-3
for VMS FORTRAN, 10-S

-0Open Link
AS C I I ( T ), 6 - 11
AS C I I ( V), 1 0 -1 2
Binary (T), 6-14
binary (V), 10-lS
8-bit (T), 6-17
8-bit (V), 10-18
Passive task (Tt, 6-20
Passive Task (V), 10-21
Overlay Instructions
TOPS-I0/20, 8-1

-PPSI, status
for TOPS-I0, 6-3, 6-S, 7-3, 7-S
-RRCLOSE Routine, 7-11
RDEL Routine, 7-13
Record Layout
Introduction, 2-4
TOPS-I0/20, 2-4
VMS, 2-4
Remote File Access
see RFA
RF A , 1- 3, 7 - 1
Concepts, 4-1
f i 1 e name, 4 - 2
for TOPS-I0 COBOL, 7-1
for TOPS-I0 FORTRAN, 7-4
for TOPS-20 COBOL, 7-1
for TOPS-20 FORTRAN, 7-4
for VMS COBOL, 11-1
for VMS FORTRAN, 11-4
Storing fields (TC), 7-2
Storing fields (TF), 7-4
storing fields (VC), 11-3
storing fields (VF), 11-6
ROPEN Routine, 7-6
Routines
CVGEN, S-30
DILINI, S-3, S-7
DIT$NFACC, 10-23
DIT$NFCLS, 10-32
DIT$NFGND, 10-7
DIT$NFOP8, 10-18
DIT$NFOPA, 10-12
DIT$NFOPB, 10-lS
DIT$NFOPP, 10-21
DIT$NFRCV, 10-26
DIT$NFSND, 10-28
DIT$RCLOSE, 11-12
DIT$RDEL, 11-13
DIT$ROPEN, 11-7
DIT$RPRINT, 11-17
DIT$RREAD, 11-10
DIT$SUB, II-IS
DIT$WRITE, 11-11
DIX$BY_DET, 9-+1

Index-2

Routines (Cont.)
OIX$BY OIX OES, 9-9
OIX$MAK OES OET, 9-7
NFACC, 6-22NFCLS, 6-32
NFGNO, 6-6
NFOP8, 6-17
NFOPA, 6-11
NFOPB, 6-14
NFOPP, 6-20
NFRCV, 6-25
NFSNO, 6-28
RCLOSE, 7-11
ROEL, 7-13
ROPEN, 7-6
RPRINT, 7-17
RREAO, 7-9
RSUB, 7-15
RWRITE, 7-10
XCGEN, 5-10
XCVFB, 5-13
XCVFP, 5-14
XCVST, 5-12
XOESCR, 5-2, 5-8
RPRINT Routine, 7-17
RREAO Routine, 7-9
RSUB Routine, 7-15
RWRITE Routine, 7-10

-S-

Sample application, C-1
Status Code
by decimal (T), E-1
by decimal (V), E-1
Condition code, 1-5
Control Bits, 1-5
Facility Code, 1-5
for OCR (TC), 5-3
for OCR (TF), 5-6
for OCR (VC), 9-3
for OCR (VF), 9-6
for RFA (TC), 7-3
for RFA (TF), 7-5
for RFA (VC), 11-3
for RFA (VF), 11-6
for TTT (TC), 6-3
for TTT (TF), 6-5
for TTT (VC), 10-3
for TTT (VF), 10-6
Introduction, 1-4
LIB$MATCH CONO, 1-6
Message Code, 1-5
Severity Code, 1-5
TOPS-10/20, 1-5
VMS, 1-4

Status PSI
for TOPS-10, 6-3, 6-5, 7-3, 7-5
-TTask
active, 3-1
fired-up (V), 0-3
identification, 0-1
not fired-up (V), 0-3
not fired-up example, 0-3, 0-4
Passive, 0-2
passive, 3-1
Task-to-Task Routines
see TTT
TOPS-10/20
Record Layout, 2-4
TTT, 1-2
ASCII data (T), 6-11
ASCII data (V), 10-12
Binary data (T), 6-14
binary data (V), 10-15
8-bit data (T), 6-17
8-bit data (V), 10-18
Concepts, 3-1
for TOPS-10 COBOL, 6-1
for TOPS-10 FORTRAN, 6-4
for TOPS-20 COBOL, 6-1
for TOPS-20 FORTRAN, 6-4
for VMS COBOL, 10-1
for VMS FORTRAN, 10-4
Logical Link, 3-1
Network Logical Name, 3-2
Open Passive Task (T), 6-20
Opening a link, 3-2
Passive Task (V), 10-21
Passive Tasks
(V), 0-2
storing fields (TC), 6-2
storing fields (TF), 6-4
storing fields (VC), 10-3
storing fields (VF), 10-6

-vValue, condition, 1-4
Value, VMS condition, 1-4
VMS condition value, 1-4

-xXCGEN Routine, 5-10
XCVFB Routine, 5-13
XCVFP Routine, 5-14
XCVST Routine, 5-12
XOESCR Routine, 5-8
Passing to (TC), 5-2
Passing to (TF), 5-5

Index-3

DIL User Reference Manual
AA-M581 B-TK
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.

D Assembly language programmer
D Higher-level language programmer

D Occasional programmer (experienced)
D User with little programming experience
D Student programmer

D Other (please specijy)~~~~~~~~~~~~~~~~~~~~~

Name~~~~-----~~~~~~~~-----~~----

Date __~~~_____~~~~~__

Organization

Telephone ~~~~~~~~_

Street __~~~~~~~~~~~~~----------~--~~~--------------------------_______
City __________________________~ State _______ Zip Code _ _ __
or Country

--~.--0 ;oTear~~.d"aere and Tape ----------------------ffl-Ill--------~~;;;~~ -__

I
I
I
I
I
I
I

W II~

if 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

-- - - -

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -