Digital PDFs

AA-J201A-TK

May 1981

282 pages

Original

9.0MB

Document:	XPORT Programmers Guide Apr81
Order Number:	AA-J201A-TK
Revision:	0
Pages:	282
Original Filename:	AA-J201A-TK_XPORT_Programmers_Guide_Apr81.pdf

OCR Text

April 1981

XPORT
Programmer's Guide
A Tutorial and Reference Manual
Order No. AA-J201 A-TK

SUPERSESSION/UPDATE INFORMATION:

This is a new document for this release.

OPERATING SYSTEM AND VERSION:

VAX/VMS V2.2
TOPS-10 V7.01
TOPS-20 V4.0

SOFTWARE VERSION:

XPORT V1.0

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, April 1981
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 be used or copied only 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.

CD 1981 by Digital Equipment Corporation.
All Rights Reserved.

Printed in U.S.A.

this
The postage-paid READER'S COMMENTS form on the
last page of
document requests
the
user's critical
evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DEC
DECUS
DIGITAL
PDP
UNIBUS
VAX
DECnet

DECsystem-lO
DECSYSTEM-20
DECwriter
DIBOL
Edusystem
lAS
MASSBUS

PDT
RSTS
RSX
VMS
VT

~D~DDmD

CONTENTS

CHAPTER 1

1.1
1.2
1.3
1.4
1.5
1.6
CHAPTER 2

2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.2
2.2. 1
2.2.2
2.2.3
2.2.4
2.2.5
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.4
2.4.1
2.4.2
2.4.3
2.5
CHAPTER 3

3.1
3.1.1
3.1.2
3.2
3.2.1
3.2.2
3.2.3
3.3
3.3.1
3.3.2

INTRODUC '1'1 ON
APPLICABILITY OF XPORT FACILITIES
• •
PROGRAM TRANSPORTABILITY •
•
FILE TRANSPORTABILITY . • •
·
SYMBOL NAMING CONVENTIONS
• • . • . .
COMPILATION ERROR MESSAGES .
SMALL SAMPLE PROGRAM • • • •

•

• 1- i

•

• • • .
• • •.
•.
· • •
• •

• • 1-2
1-3
• • 1-3
• • 1-4
• • 1-5

TRANSPORTABLE DATA STRUCTURES
IN'I'RODUC'I'ION •
•
The Problem
The Solution •
Simple Example
Terminology
$FIELD DECLARATION AND $FIELD_SET_SIZE •
$FIELD Declaration • • • • • •
•
Transportable .Field-Types
•••..
Nontransportable Field-Types • • • . •
Guidelines for Individual Field-Types
$FIELD SET SIZE Usage
SUPPLEMENTARY FEATURES • • • • • • • •
Field-Positioning Features •
Literal-Defining Eeatures
Value-Display Feature
Subfield Referencing Feature
TRANSPORTABILITY CONCERNS
• • • •
Field Size • • • • • . • • •
Integer Value Range
•.••
Use of $BYTES for Character Strings
EFFICIENCY CONCERNS
••••••••. •

• • • • • 2-1
· 2-1
2-2
• 2-3
· • 2-5
• 2-5
• • • • • 2-5
• 2-6
• • • • • 2-8
• • • • • 2-8

2-12
2-12
2-12
2-14
2-15
2-16
•

• ••

2-20

• • ••

2-20
2-21
2-21
2-22

INPUT/OUTPUT FACILITIES
INTRODUCTION • • • . • • •
• •
General Characteristics
•.•••••
Specific Functions • • • • • • • •
CAPABILITIES • • • • • • •
• • •
File Level Capabilities
• •
Input/Output Capabilities
••
•
File Specification Resolution
I/O RE LA'I'ED MACROS • . . • • • • •
General Format and Common Parameters .
File-Level Macros
•••• • • . • . .

iii

• • • •
•
•
.
• • • •
• • • •
·
·

• •.

•
•
•
•
•
•
•
·

3-1
3-2
3-3
3-3
3- 3
3- 5
3-8
3-9
3-10
3-11

3.3. 3
3.4
3.4.1
3.4.2
3.5
3.6
3.6.1
3.6. 2
3.7
3.8
CHAPTER 4
4. 1
4.2
4.3
4.3.1
4.3.2
4.3.3
4.4
4.5
CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.3
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.3
6.3. 1
6.3.2
6.4
6.5
6.5.1
6.5. 2
6.5. 3

Input/Output Macros
. . . • •
INPUT/OUTPUT CONTROL BLOCKS
Creating and Initializing lOBs
Using lOB Fields and Values
•••••.•.•
STANDARD I/O DEVICES • • • • • • .
•••••
FILE SPECIF'ICATION PROCESSING
••••
File Specification Resolution
File Specification Parsing
I/O COMPLETION CODES •
I/O ACTION ROUTINES
• • • •

· . .'

3-15
3-18
3-18
3-19
3-22
3-23
3-23
3-26
3-27
3-28

MEMORY MANAGEMENT FACILITIES
INTRODUCTION • . • • • • • .
• •
•
CAPABILITIES . • • • • • •
MEMORY MANAGEMENT MACROS •
•••.
$XPO GET MEM - Allocating Dynamic Memory
$XPO-FREE MEM - Releasing Dynamic Memory
Dynamic Memory Elements
. • • •
•
COMPLETION CODES •
ACTION ROUTINES
• • • • . •
• •

• • • • 4-1
• • • . 4-1
• 4-2
• 4-2
•
• 4-3
• • 4-4
• • • • 4- 4
• • • • 4- 4

OTHER SYSTEM SERVICES
INTRODUC'I'ION
$XPO PUT MSG • • • •
Completion Codes •
Act ion Ro uti nes
$XPO TERMINATE

• • 5-1
• • • • 5-1
5-3
• 5-3
• • 5-3

STRING HANDLING FACILITIES
STRING DESCRIPTORS •
• • • • • • • • • • • • 6-1
$STR DESCRIPTOR -- Creating a String Descriptor 6-2
$S'I'R-DESCRIPTOR -- Compile-Time Descriptor
InitIalization . • • • • . • . • • . • . • • • • 6-2
$STR DESC INIT -- Run-Time String Descriptor
InitTalization • • • • • • • • •
• 6-3
6-4
String Descriptor formats
String Descriptor Usage Rules
• 6-6
Descriptor Data Types
••••
• 6-8
STRING DESCRIPTOR STRUCTURE REFERENCES • • • • . • 6-9
6-9
STRING MODIFICATION
• • • .
. ••.
$STR COPY Operation
. . • • .
6-10
6-11
$STR=APPEND Operation
.••.
STRING COMPARISON
• • ••
.•••
6-12
6-14
STRING SCANNING • • • •
6-14
$STR SCAN Overview • • .
$STR-SCAN FIND - Find a Character Sequence
6-15
$STR-SCAN SPAN - Match a Set of Characters
6-16
iv

6.S.4
6.S.S
6.S.6
6.6
6.6.1
6.6.2
6.6.3
6.6.4

CHAPTER 7
7.1
7.2
7.2. 1
7.2.2
7.2.3
7.2.4
APPENDIX A
A.l
A. 1. 1

A.l.2
A.2
A.2.1
A.2.2
A.2.3
A.2.4
A.2.S
A.3
A.3.1
A.3.2
A.3.3
A.3.4
A.4
A.4.1
A.4.2
A.4.3
A.4.4
A.4.S
A.S
A.S.l
A.S.2

$STR SCAN STOP - Search for a Set of Characters
$STR SCAN - Returning a Substring
$STR-SCAN - "Scanning Through" a BOUNDED Str ing
STRING-CONVERSION
$STR CONCAT and $STR FORMAT - ASCII to ASCII
String Conversions
$STR ASCII - Binary-Data to ASCII String
Conver sion
Nesting $STR ASCII, $STR _CONCA'l', $STR- FORMAT
Pseudo-FunctTons
$STR BINARY - ASCII Str i ng to Binary-Data
Conversion

·········.···..

········
...·········
······· ··
. . . · · · · · · · · ·

··
··
·· ·
· · ·

6-16
6-17
6-17
6-18
6-18
6-19
6-21
6-22

BINARY DA'lA DESCRIPTORS
INTRODUCTION • • • • • . • • . • • • • • • • • • •
BINARY DATA DESCRIP'l'OR CREATION AND INITIALIZA'l'ION
$XPO DESCRIPTOR -- Creating a Binary Data
Desc~iptor • • • • • . • • • • • • • • • •
•
$XPO DESCRIPTOR -- Compile-Time Descriptor
InitTalization • • • • • • • • • • • • • •
$XPO DESC INIT -- Run-Time Data Descriptor
InitTaliz~tion • • • • • • • • ~ . • • • • • • .
Classes Of Descriptors
.•••••.•
•

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

MACRO DESCRIPTIONS
DESCRIPTIVE NOTATION AND CONVENTIONS • • • • • • • A-I
Syntax Notation
• • • • . • . • • . • • • • A-I
• • A-2
Character-String and Binary-Data Parameters
A-4
$STR APPEND - Append a String
Sy~tax • • • • • • •
• A-4
Restrictions • . • • •
• A-4
. • A-4
Parameter Semantics
Operational Semantics
A-S
Completion Codes • • • .
• A-6
$STR ASCII - Binary-to-ASCII Conversion
Pseudo-Function
. • ••
..•.
A-7
Syntax • • • • • • • •
A-7
Restrictions. • • • •
. • • • • . • • • . A-7
Parameter Semantics
• • • • • • • • . . • A-7
Usage Guidelines..
. • • • • • • • • . . • A-8
$STR BINARY - Convert ASCII to Binary
. . A-9
Sy~tax . • • • • • •
. A-9
Restrictions. • • •
• • • • A-9
Parameter Semantics
• • • •
A-I0
Usage Guidel ines • •
A-I0
Completion Codes • • • • • • •
••••
A-II
$STR COMPARE - String Comparison
A-12
Sy~tax • • • •
••••
A-12
Restrictions. • . • • . • • • • . . • • •
A-12
v

A.5.3
A.5.4
A.5.5
A.6
A.6.1
A.6.2
A.6.3
A.6.4
A.7
A.7.1
A.7.2
A.7.3
A.7.4
A.7.5
A.8
A.8.1
A.8.2
A.8.3
A.9
A.9.1
A.9.2
A.9.3
A.9.4
A.IO
A. 10. 1
A. 10. 2
A. 10. 3
A. 10. 4
A. 10. 5
A.ll
A.ll.l
A.II.2
A.ll.3
A.ll.4
A.12
A.12.1
A.12.2
A.12.3
A.12.4
A.12.5
A.13
A.13.1
A.13.2
A.13.3
A.13.4
A.13.5
A.14
A. 14.1
A. 14. 2
A. 14. 3
A. 14. 4

· · · · · · · · · · · · · A-12
· · · · · · · · · A-13
·
· · · · · A-13
· · · · · · · · · · · A-14
A-14
· · ··
····
A-14
· · · · · · · · · · · · ·· · · ·· ·· A-14
··· ··
· · · · · · · A-15
A-16
· · · ·
A-16
····· ····
· · · · ·· · ·· · · ·
· · · · · A-16
A-16
· ·
· · · · · · A-17
A-18
· · ··
··· ·
A-19
A-19
· · · · · · · ·
A-19
· · · · · · · · · · · · · · · · · A-19
· · · · · · · · · · · · · A-21
· · · · ·
· · · · A-2I
A-21
· ··· ·
· · · · · · · · ·· A-21
· · · A-22
· · · · A-23
····
A-23
· · · · · · ·· · ·
· · · · · A-23
······
A-23
A-24
···
·
A-25
·
· · · · · · · · · · · · A-26
· · · · A-26
··· ·····
A-26
···
··· ·
A-27
·····
··
· · · · · A-27
A-29
· · · · · ·· · · · · ·
· · · · A-29
········
A-29
· · · · ·
· · · · · A-29
A-30
····
A-3I
· · · · · · · · · · · · · · · A-32
· · · · · · · · · · · · · · · · · A-32
A-32
······· ···
·· · · · · A-32
· · · · · · · · · A-33
· ·· ·
· · · · · A-34
· ·· ·
· · · · · A-35
· · · · · · · · · · · · · · · · · · · · A-35
A-35
· ·· · ·
·
·
·
·
·
· ·· ·
· · · · A-35
· · · · · · · · · A-36

Parameter Semantics
Operational Semantics
Completion <;:odes
$STR CONCAT - String Concatenation
Pseudo-Function
Syntax • . •
Restrictions
Parameter Semantics
Usage Guidelines
$STR COPY - Copy a String
Syntax
Restrictions
Parameter Semantics
Operational Semantics
Completion Codes
$STR DESCRIPTOR - Declare a String Descriptor
Syntax . • •
Restrictions
Parameter Seman tic s
$STR DESC INIT - Initialize a String Descriptor
Syntax • • •
Restrictions
Parameter Semantics
Completion Code
$STR EQL - String Equality Compar ison
Syntax • • •
Restrictions
Parameter Semantics
Operational Semantics
Completion Codes
$STR FORMAT - Str ing Fo rmat ti ng Pseudo-Function
Syntax
Restrictions
Parameter Semantics
Usage Guidelines
$STR GEQ - String Greater-Than-or-Equal
Comparison
Syntax
Restrictions
Parameter Semantics
Operational Semantics
Completion Codes
$STR GTR - String Greater-Than Compar ison
Syntax • . .
Restrictions
Parameter Semantics
Operational Semantics
Completion Codes
$STR LEQ - String Less-Than-or-Equal Comparison
Syntax
Restrictions
Parameter Semantics
Operational Semantics

A.14.5
A.15
A. 15.1
A. 15. 2
A.15.3
A.15.4
A. 15. 5
A.16
A.16.1
A.16.2
A. 16. 3
A. 16.4
A. 16.5
A.17
A.17.1
A.17.2
A.17.3
A.17.4
A.17.5
A.18
A.18.1
A.18.2
A.18.3
A.18.4
A.18.5
A.19
A.19.1
A.19.2
A.19.3
A.19.4
A.20
A. 20. 1
A. 20.2
A. 20 . 3
A.21
A. 21. 1
A. 21. 2
A. 21. 3
A.22
A. 22. 1
A.22.2
A.22.3
A.23
A.23.1
A.23.2
A.23.3
A.23.4
A.24
A. 24 • 1
A.24.2
A. 24. 3
A. 24 • 4
A.25

Completion Codes i • • • • • • • • • • • • • •
$STR_LSS - String Less-Than Comparison
Syntax • • • • • • • • • • • • • • • • • • • •
Restrictions • • • • • • • • • .
• •..•
Parameter Semantics
.•••
Operational Semantics
Completion Codes • • • • • • • • •
$STR_NEQ - Str-ing Inequality Comparison
••••
Syntax • • • • • • • • •
Restrictions • • • • . • • • • •
Parameter Semantics
Operational Semantics
.•.•• •
Completion Codes
•
$STR_SCAN - String Scanning
Syntax • • • • • • •
Restrictions • • • • • • • • • • •
Parameter Semantics
Operational Semantics
Completion Codes • • • • • • • • • • • • • • •
$XPO BACKUP - Preserve an Input File
Syntax • • • • • • •
Parameter Semantics
Usag e Gu idel ines
Completion Codes
Example
•• • • • •
$XPO CLOSE - Close a File
Syntax . •
Parameter Semantics
Usage Guidelines.
Completion Codes • • • •
$XPO DELETE - Delete a File
Sy~tax • • • • • • •
Parameter Semantics
Completion Codes . .
• • • • • • • • • •
$XPO_DESCRIPTOR - Declare a Data Descriptor
Syntax • • • . • • • • • • •
. • • . . •
Restrictions • • • • • • • • • • . • • • •
Parameter Semantics • • . • • • • . • • • • •
$XPO DESC INIT - Initialize a Data Descriptor
Syntax -: • • • • • • • • . • • • • • • • •
Parameter Semantics • • • • • . • • • . . • •
Completion Code
•••••••.•••••••
$XPO FREE MEM - Release a Memory Element .
Sy~tax -: • . . • • •
. . • • . . • •
Restrictions . • • •
Parameter Semantics
Completion Codes •
$XPO_GET - Read From a Eile
Syntax • • • • . . •
Parameter Semantics
Usage Guidelines . • •
Completion Codes • • . • . .
$XPO_GET_MEM - Allocate Dynamic Memory Element

. . . . . . .

vii

A-37
A-38
A-38
A-38
A-38
A-39
A-40
A-41
A-41
A-41
A-41
A-42
A-43
A-44
A-44
A-44
A-45
A-46
A-47
A-48
A-48
A-48
A-49
A-49
A-50
A-51
A-51
A-51
A-52
A-52
A-54
A-54
A-54
A-55
A-57
A-57
A-57
A-57
A-59
A-59
A-59
A-60
A-61
A-61
A-61
A-61
A-62
A-63
A-63
A-63
A-64
A-65
A-67

A.25.1
A. 25. 2
A. 25. 3
A. 25. 4
A.26
A. 26. 1
A. 26. 2
A. 26. 3
A.27
A. 27 • 1
A. 27 . 2
A. 27 . 3
A. 27 • 4
A.28
A. 28. 1
A. 28. 2
A. 28.3
A.29
A.29.1
A.29.2
A.29.3
A.30
A. 30 . 1
A.30.2
A.30.3
A. 30. 4
A.30.5
A.31
A.31.1
A. 31 . 2
A. 31. 3
A.32
A.32.1
A.32.2
A.32.3
A.33
A. 33. 1

A.33.2
A.34
A. 34. 1
A. 34. 2
A.34.3
APPENDIX B
B.l
B.2
B.3
B.4

Syntax • • . • • • . •
Restrictions • • . • •
Parameter Semantics
Completion Codes • • •
$XPO lOB - Declare an lOB
Syntax • . • • • • • • . •
• • • •
Parameter Semantics
.•••
Exampl~es • • • • • • • • •
• •••
$XPO lOB INIT - Initialize an lOB
•••.
Syntax- • • • • • • • • • • • • • • • • • •
Restrictions. . • • •
• •••••
Parameter Semantics • • • •
Completion Code
••••
$XPO_OPEN - Open a File
•••.
Syntax • • • • • . • .
• • • •
Parameter Semantics
• • • .
Completion Codes • • •
• • • •
$XPO PARSE SPEC - Parse a File Specification
Syntax .-. • • • . • • • • • .
. •••
Parameter Semantics • . • •
• • • .
Completion Codes • • • • • .
• • • •
$XPO PUT - Write to a File •
. •••
Syntax . • • • • • •
• • ••
••••
Restrictions • • • • • • • • • •
Parameter Semantics
Usage Guidelines • . .
Completion Codes • . •
$XPO PUT MSG - Send a Message
Syntax-. • • • • • . •
Parameter Semantics
Completion Codes • • • . • •
$XPO RENAME - Rename a File
Syntax • • • • • • •
Parameter Semantics
Completion Codes • •
$XPO SPEC BLOCK - Declare a File Specification
Block
••••
Syntax • . • • • • • • •
• • • . • .
Examples • • • • • . . •
• • • • • •
$XPO TERMINATE - Terminate Program Execution
Syntax . • • •
Parameter Semantics
Routine Value

A-67
A-67
A-67
A-68
A-70
A-70
A-70
A-70
A-71
A-71
A-71
A-71
A-72
A-73
A-73
A-74
A-77
A-79
A-79
A-79
A-80
A-81
A-81
A-81
A-82
A-82
A-82
A-84
A-84
A-84
A-85
A-86
A-86
A-87
A-89
A-90
A-90
A-90
A-91
A-91
A-91
A-91

CONTROL BLOCKS
INPUT/OUTPUT BLOCK (lOB)
STRING DESCRIPTORS
BINARY DATA DESCRIPTORS
FILE SPECIFICATION PARSE BLOCK .

viii

• • B-2
• B-4
• • B-5
B-6

APPENDIX C

COMPLETION CODES

APPENDIX D

SAMPLE PROGRAM

APPENDIX E

AC'l'ION ROUTINES

E.l
E.l.l
E.l.2
E.2
E.3
APPENDIX F
F.l
F.2
F.3
APPENDIX G
G.l
G.l.l
G.l.2
G.l.3
G • 1. 4
G.2
G.2.1
G.2.2
APPENDIX Z
Z.l
Z.2
Z.3
Z. 3. 1

Z.3.2
Z.3.3
Z.3.4
Z.3.5
Z.3.6
Z.4
Z .4. 1
Z • 4. 2

Z. 4. 3

Z.4.4
Z.4.5

ACTION-ROUTINE CALLS AND RETURNS •
Action Routine Calls • • • • • • .
Action Routine Return Values • • • • • .
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING •
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING •

·
·

•
.
•
.

E-l
E-l
E-3
E-4
E-15

COMPILING AND LINKING
DEFINING A TRANSPORTABLE LOGICAL DEVICE
COMPILING
. . • • •
LINKING
•• • • • • • • . • • • • • . .

· • F-l
· • F-2
• • • . F-3

XDUMP UTILITY PROGRAM
XDUMP - XPORT DATA STRUCTURE DISPLAY UTILITY
·
Running the XDUMP Utility • • • . .
· .
Compiling a Structure Display Module • • • • · •
Linking a Structure Display Module •
•
Displaying a User Declared Structure While
Debugging
• • • • • . • ••
. ••
XDESC, XIOB, and XSPEC - XPORT STRUCTURE DISPLAY
MODULES
• • • • • • . . • • . • • . . • • • •
Linking an XPORT Structure Display Module
•
Displaying an XPORT Structure While Debugging
•
EASY-TO-USE I/O PACKAGE

G-3
G-3
G-3
G-4

(EZIO)

OVERVIEW . • • . • . .
• • • •
. •
LIMITATIONS
• • • • • • .
• • • • ••
•
FUNCTIONAL DESCRIPTION .
• • • • • • • • •
The FILOPN Routine
• • • • ••
.•
The FILIN Routine
• • • • • •
The FILOUT Routine
• • • •
• •
The FILC LS Ro ut i ne • .
• • • • • • • • •
Restrictions • • •
• • • • • • • • • •
• • •
Example
•••••
• • • • •
LOADING EZIO WITH USER PROGRAM • .
EZIOFC - File Services 11 (RSX-IIM)
EZIORT - RT-ll •
. ••...•••••
EZIOIO - TOPS-IO
.•••.•••••.
EZI020 - TOPS-20
.•••....•••.
EZIOVX - VAX/VMS. • • .
• •••
ix

G-l
G-l
G-2
G-3

Z-l
Z-1
Z- 2

Z-2
Z-4
Z-4
Z- 5
Z- 5

Z-6
Z-7
Z-7

Z-8
Z-8
Z-8
Z-8

Z.5

Z-8

PACKAGING

CHAPTER 1
1.1
1.2
1.3
1.4
1.5
1.6

INTRODUCTION
APPLICABILITY OF XPORT FACILITIES
. • . .
PROGRAM TRANSPORTABILITY •
• . • •
.
FILE TRANSPORTABILITY
. • • • • . . . . . .
SYMBOL NAMING CONVENTIONS
. • . .
.
COMPILATION ERROR MESSAGES • • • • .
.
SMALL SAMPLE PROGRAM . • • •
. • . • • •

•
•
•
•
.
•

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

CHAPTER 1
INTRODUCTION

This manual describes a
collection of transportable,
source-level
programming
tools for
use with the BLISS language.
These tools
provide extensive input/output facilities,
a
uniform
interface for
obtaining operating-system services - such as dynamic memory, and aids
for data structuring and string handling.
Stand-alone BLISS utility programs, such as PRETTY or BLSCRF, are
described in this manual.

not

The Transportable Programming Tools package is informally referred
to
as
XPORT - for "transportable" - which indicates the design emphasis
on source-level transportability across all BLISS target systems, as
well
as on ease-of-Iearning
and ease-of-use.
(Transportability is
discussed in further detail below.)

1.1

APPLICABILITY OF XPORT FACILITIES

Except for the data-structure definition aids described in Chapter 2,
the
facilities described
in this manual
are
intended for use in
development of 'application' programs, that is, programs that can make
use of operating-system services, as opposed to the programs that make
up the operating system itself.
(The BLISS language,
of course,
is
intended for implementation of programs in both categories.)
In the system-software context, an 'application' might be a
compiler,
linker, or utility program.
The use of XPORT for such implementations
offers programming convenience, maintainability, and
transportability
in
the system-services area,
combined with the efficiency and
reliability obtainable through the use of BLISS.

1-1

Introduction
APPLICABILITY OF XPORT FACILITIES
The data-structuring facilities do not involve calls on underlying
target-system services
(as do the other XPORT facilities), and thus
can be used in any type of program development.

1.2

PROGRAM TRANSPORTABILITY

With a very few exceptions, the XPORT programming
tools are fully
transportable.
This
means that,
used
in accordance with the
guidelines given in this manual,
the same XPORT source code will
produce identical or equivalent results on each BLISS target system.
XPORT provides a
small number of system-specific
features deemed
mandatory for some programs on a particular target system.
An example
of this type of feature is a field type, $SIXBIT, that relates to
the
SIXBIT string encoding.
Some programs for the TOPS-IO environment may
require its use.
XPORT also provides a few discretionary features
that allow you to
take advantage of the storage characteristics of a particular system,
e.g., to possibly eke out a bit more storage efficiency in certain
situations.
Use of the discretionary type of non-transportable feature is strongly
discouraged except in very unusual situations.
In the majority of
cases only a very little storage will be saved at the cost of
transportability, which may turn out to be a very serious cost at some
point in the product's lifecycle.
Also, compaction of storage beyond
that provided by default may incur a significant execution-speed
penalty.
Obviously the use of XPORT will
not make an
otherwise
nontransportable BLISS program into a transportable one.
And as in the
case of Common BLISS constructs,
features of XPORT that are
in
themselves
transportable can be used in completely non-transportable
ways.
This is due to the very significant architectural differences
that exist among the several target-system families.
In order to use either Common BLISS constructs or XPORT features in a
transportable fashion, these crucial differences must be recognized at
the outset and kept constantly in mind.
(One such difference
is
in
the
range of integer values possible on the 16-bit systems versus the
32- or 36-bit systems.)
Just as with BLISS itself,
transportable
programming using XPORT is primarily a matter of design rather than of
coding.

1-2

Introduction
PROGRAM TRANSPORTABILITY
Throughout this manual we have tried
to
provide transportability
guidelines and warnings concerning all
"problematic"
features of
XPORT.
Transportable BLISS programming in general is discussed in the
"Transportability Guidelines"
chapter of the several BLISS User's
Guides.

1.3

FILE TRANSPORTABILITY

There are two aspects of XPORT file transportability.
The
first
concerns
the transportability of I/O operations at the source-program
level. With very few exceptions
(clearly noted),
the XPORT I/O
functions behave the same in all environments.
The second aspect of file transportability concerns the ability to
move XPORT-created
files themselves from one environment to another.
It
is not a goal of XPORT to
provide
this·
kind
of
file
transportability.
Instead,
standard
file-interchange
utilities
provided as a part of each target system - must be used to move files
from system to system.

1.4

SYMBOL NAMING CONVENTIONS

The names used in the XPORT package are formed
in accordance with
VAX/VMS
operating-system conventions.
The names so
formed
are
somewhat unwieldy in a few cases, but they all have the virtues of
consistency and clarity.
After you have learned
the few simple
patterns involved, you can easily identify the kind of entity
(macro,
completion code,
control-block field, etc.) represented by any given
name.
VAX/VMS-compatible names are formed of facility codes, dollar signs,
underscores, and alphanumeric strings.
The facility codes assigned to
the XPORT package are the following (more may be added in future):
o

XPO - I/O, memory, and host-system service facilities

lOB - I/O control block definitions

STR - String-handling facilities.

Names formed according
to
the convention begin with one of the
facility codes listed
above.
Arbitrarily, we will use the facility
code XPO in the name formats and most of the examples given below.

1-3

Introduction
SYMBOL NAMING CONVENTIONS
The name formats used in XPORT are as follows:
o

$XPO xxxx

Macro name
Example:
$XPO PUT

XPO$xxxx

Global symbol, usually a routine name
Example:
XPO$FAILURE

XPO$ xxxx

Completion code (special case of a literal name)
Example:
XPO$_NORMAL

XPO$c xxxx Variable or field name
where c is a data-type code, as follows:
c

= A
B
G
H
K

T
V

Address/pointer value
Byte value (9-bit field on -10/20 systems)
General value (fullword integ er)
Short value (two bytes)
Literal (Ilkonstant ll )
Text string (STR descriptor)
Arbitrary field (usually one or more bits)
Other
Examples:
IOB$T STRING

a string descriptor sub-block,
which includes the fields:

IOB$H STRING -- a two-byte count value
IOB$A-STRING
a character-string pointer
Two other farms are used for internal names, some
encounter in listings and compiler diagnostics:
$XPO$xxxx

and

which

you

may

$XPO$$xxxx

In Chapter 2, the macros associated with the data-structuring facility
have simple names of the form
II$XXXXIl, such as $FIELD, $INTEGER,
$TINY INTEGER, $DESCRIPTOR, and $OVERLAY.
This
is so because
the
data-structuring
facility has no facility code assigned to it;
the
names otherwise adhere to the naming convention.

1.5

COMPILATION ERROR MESSAGES

The use of XPORT facilities usually implies the expansion of many
macros during compilation.
Macro expansion following the occurence of
a source-language error can result in the generation of spurious error
messag es.

1-4

Introduction
COMPILATION ERROR MESSAGES
Once an error-level diagnostic (prefixed %ERR) has been generated, the
compilers stop performing most expression evaluations.
This causes
the object file to be discarded and, assuming there are macros in the
source program,
sometimes results in erroneous macro expansions and
the consequent generation of spurious error messages.
If the cause of a compiler diagnostic
is not immediately evident
(especially one referring
to a macro expansion) and an error-level
diagnostic has already been issued, ignore the diagnostic in question,
correct all
known source errors, and recompile.
Any spurious error
messages will
"go away"
when the preceding
actual
errors
are
eliminated.

1.6

SMALL SAMPLE PROGRAM

As an initial "taste" of XPORT coding, we present below a minimal
sample program consisting almost entirely of XPORT macro calls.
This
program is a simple file-copy utility, called LISTER.
Appendix D contains a much more extensive programming
example which
illustrates the use of many XPORT features in a completely realistic
context.
SAMPLE PROGRAM
MODULE LISTER ( MAIN

LISTER ) =

BEGIN
1+
1 This program asks for a file name, opens the named file,
1 and copies the file to the terminal.
1-

LIBRARY 'BLI:XPORT'i

XPORT definitions

OWN
terminal iob:
$XPO IOB(),
file iob-:
$XPO_IOB()i
ROUTINE LISTER
BEGIN
Open the user's terminal and ask for a file name.
$XPO_OPEN( IOB=terminal iob, FILE_SPEC=$XPO_INPUT

$XPO_GET( IOB=terminal iob,
PROMPT= 'Enter name of file to be listed:

1-5

);

Introduction
SMALL SAMPLE PROGRAM
Open the files
$XPO_OPEN( IOB=file iob, FILE_SPEC=terminal iob[IOB$T_STRING]

);

Process each line.
WHILE $XPO GET( IOB=file iob ) DO
$XPO_PUT( IOB=terminal_iob, STRING=file iob[IOB$T_STRING]

);

$XPO_CLOSE( IOB=file iob );
$XPO_PUT( IOB=terminal_iob, STRING=

'*** End of file ***' );

$XPO_CLOSE( IOB=terminal iob
END;
END
ELUDOM
Note:
$XPO INPUT is the transportable name for
the standard
input
device.
It-is, for example, equivalent to "TTY:" on some systems.

1-6

CHAPTER 2
2.1

TRANSPORTABLE DATA STRUCTURES

INTRODUCTION • •
• • • . . • ••
• 2-1
The Problem
. • • • . • • • • •
• 2-1
The Solution • • .
• • • •
• • 2-2
2.1.3
Simple Example
• • • . • • • . • • • • 2-3
2.1.4
Terminology • .
• • • •
• • • • • 2-5
2.2
$FIELD DECLARATION AND $FIELD_SET_SIZE • . • . . . 2-5
2.2.1
$FIELD Declaration • • • • • . . • •
• 2-5
2.2.2
Transportable Field-Types • . • • •
. 2-6
2.2.3
Nontransportable Field-Types • • • • • .
. 2-8
2.2.4
Guidelines for Individual Field-Types
• • • 2-8
$ADDRESS vs. $POINTER Usage • • • • • • • • . 2-8
2.2.4.1
2.2.4.2
Coding the $SUB BLOCK Field-Type • .
. • 2-9
Cod ing the $DESCRIPTOR Fi eld-rrype
2-10
2.2.4.3
Coding the $REF DESCRIPTOR Field-type
2-11
2.2.4.4
Coding the $STRING Field-Type
2-11
2.2.4.5
2.2.5
$FIELD SET SIZE Usage
2-12
2.3
SUPPLEMENTARY FEATURES • • • • • • • •
2-12
2.3.1
Field-Positioning Features.
2-12
$ALIGN Usage • • • • • •
• • •.
2-13
2.3.1.1
$OVERLAY and $CONTINUE Usage
2-14
2.3.1.2
Literal-Defining Features
. . • .
2-14
2.3.2
$LITERAL and $DISTINCT Usage • •
...•
2-15
2.3.2.1
Value-Display Feature
••••••••••••
2-15
2.3.3
$SHOW Usage •• • • • • •
•••.
2-15
2.3.3.1
Subfield Referencing Feature
. . . . • . • 2-16
2.3.4
Subfield Referencing Using a BIND Declaration 2-17
2.3.4.1
Subfield References Using General Structure
2.3.4.2
2-18
References • • • • • • • • • • • • • • •
2-19
Subfield References Using $SUB FIELD .
2.3.4.3
Using $SUB FIELD with $OVERLAY-. . • • .
2-19
2.3.4.4
2.4
TRANSPORTABILITY CONCERNS
• • • • 2-20
2-20
2.4. 1
Field Size. • • • . • . . . . ••
. •.•
2-21
2.4.2
Integer Value Range • . • • • • • • . . • . •
2-21
2.4.3
Use of $BYTES for Character Strings . . • • .
2.5
2-22
EFFICIENCY CONCERNS • . . • • . • • • • • • • •
2. 1. 1
2. 1. 2

CHAPTER 2
TRANSPORTABLE DATA STRUCTURES

2.1

INTRODUCTION

This chapter describes a high-level aid for defining
structures in a convenient and transportable manner.

2.1.1

BLOCK-type

data

The Problem

The specification of reasonably compact, non-uniform data structures
-- typically control blocks -- for use across target systems poses a
difficult transportability problem.
The difficulty is caused by the
basic architectural differences found among the BLiSS target systems,
as discussed in Chapters I and III of the BLISS Language Guide.
Briefly,
the differences
characteristics:

are

found

following

the

The size of the fullword

(or BLISS value) :

The size of the addressable unit:

The ability to access fields that cross
VAX-II only

system

16, 32, or 36 bits

8 bits vs. 36 bits
fullword

boundaries:

These differences affect the transportable design of all types of data
segments, scalar or structured, to some extent.
But in particular,
the difficulty of defining
BLOCK
and
BLOCKVECTOR
structures
transportably,
using
standard BLISS declarations, is such that the
programmer often ducks the issue altogether and
resorts to
separate
sets of FIELD and data declarations for each target system.

2-1

Transportable Data Structures
INTRODUCTION
The numeric notation ordinarily used in the standard FIELD declaration
e.g.,
[1,0,16,1]
while powerful, is inconvenient to code and
modify
and
is
quite
error-prone,
in
addition
to
being
nontransportable.

2.1.2

The Solution

The XPORT structure-definition facility is a collection of macros that
provides a solution to
these problems.
It allows you to define
efficient BLOCK structures in a way that is both convenient and,
for
the most part, system independent.
The facility consists principally
of a replacement for the standard BLISS FIELD declaration,
using
the
keyword $FIELD.
The facility also includes
namely:
$<field-types>
}
$FIELD_SET_SIZE}
$ALIGN
$OVERLAY
$CONTINUE

}
}
}

$LITERAL
$DISTINCT

}
}

several

groups

supporting

features,

Block-defining features
Field-positioning features

Literal-defining features

$SHOW

Value-display feature

$SUB FIELD

Subfield-referencing feature

The overall strategy of the structure-definition facility is to allow
you to name the kind of field required for each block component, as
opposed to specifying its (necessarily machine dependent) position and
size, and
to have the compiler calculate the appropriate structurereference values and the aggregate block size for each target system.
A "kind of field"
or
field-type
(e.g., $SHORT INTEGER) generally
implies not only the size but also the alignment and
sign-extension
mode required.
In addition to transportability, this facility offers a degree of
coding
convenience
(and consequent ease of modification) that alone
justifies its use.

2-2

Transportable Data Structures
INTRODUC TI ON
CAVEAT
The XPORT structure-definition facility
cannot
solve
all
transportability
problems.
Particularly,
it cannot of
itself
solve
the
kind
of
transportability problem that is often
encountered when transporting a program
between a 32- or 36-bit system on one
hand and a 16-bit system on the other,
caused by the large discrepancy
in
BLISS-value
size
between those two
system groups.
Section 2.4 discusses
such transportability problem areas in
some detail.

2.1.3

Simple Example

The following example of a fairly simple block structure called XCB
(for
Xample Control Block), gives the general flavor of the XPORT
structure-definition facility:
$FIELD
XCB FIELDS
SET
[$ADDRESS] ,
XCB 1
XCB-2
[$TINY INTEGER],
XCB-3
[$B YTE],
XCB-4
[$SHORT INTEGER],
XCB-S
[$POINTER]
TES
LITERAL
$FIELD- SET - SIZE
XCB SIZE

OWN
XCB ALPHA

BLOCK[XCB_SIZE] FIELD (XCB_FIELDS)

If the XPORT data-structure macros were not used, the following
sets
of equivalent, system-specific declarations would be required for each
BLISS dialect:

2-3

Transportable Data Structures
INTRODUCTION

FOR BLISS-16 =)
FIELD
XCB FIELDS

SET
XCB 1
XCB-2
XCB-3
XCB-4
XCB-S

[0,0,16,0],
[1,0,8,1],
[1,8,8,0],
[2,0,16,1],
[3,0,16,0]

TES ;
OWN
XCB ALPHA
FOR BLISS-32

BLOCK[4] FIELD(XCB_FIELDS)

FIELD
XCB FIELDS
SET
XCB 1
XCB 2
XCB - 3
XCB 4
XCB S
TES ;

[0,0,32,0],
[1,0,8,1],
[1,8,8,0],
[1,16,16,1],
[2,0,32,0]

OWN
XCB ALPHA
FOR BLISS-36

BLOCK[3] FIELD(XCB_FIELDS)

FIELD
XCB FIELDS
SET
XCB 1
XCB 2
XCB 3
XCB - 4
XCB S
TES ;

[0,0,18,0],
[0,18,9,1],
[0,27,9,0],
[1,0,18,1],
[2,0,36,0]

OWN
XCB ALPHA

BLOCK[3] FIELD(XCB_FIELDS)

2-4

Transportable Data Structures
INTRODUC TI ON
2.1.4

Terminology

The coined term "fullword"
stands for
"word"
on the PDP-II,
for
"longword" on the VAX-II, and for "word" on the DEC-IO/20 systems, and
corresponds to the size of a BLISS value on all target systems~
The BLISS predefined literal name %BPVAL is used
in subsequent
descriptions to denote the number of bits in a fullword (i.e., ~its
per BLISS value) for any target system.
That is, %BPVAL implies the
value 16, 32, or 36 for BLISS-16, BLISS-32, or BLISS-36 respectively.
The BLISS predefined literal name %UPVAL is used
in subsequent
descriptions to denote the number of addressable units in a fullword
(i.e., units per BLISS value) for any target system.
That is,
%UPVAL
implies the -value
2,---4,
or 1 for BLISS-16, BLISS-32, or BLISS-36
respectively.
Also, the abbreviation "DEC-IO/20" is used to stand for
"DECsystem-lO
or DECSYSTEM-20".
It denotes the entire 36-bit family of target
systems.

2.2

$FIELD DECLARATION AND $FIELD SET SIZE

The XPORT $FIELD declaration is used
in place of the BLISS FIELD
declaration to define the structure-reference actuals for fields of a
BLOCK structure.
The $FIELD SET SIZE feature is used to calculate the
size of a block defined via $FIELD.

2.2.1

$FIELD Declaration

The general form of a $FIELD declaration is:
$FIELD

field-set-name

SET
field-name-l
field-name-2

field-name-n
TES;

[field-type] ,
[field-type] ,

[field-type]

2-5

Transportable Data Structures
$FIELD DECLARATION AND $FIELD SET SIZE
where field-set-name and field-name-i are user-chosen names, as
FIELD declaration
field-type is one of the (macro)
two subsections.

names defined in the

following

The XPORT $FIELD declaration is used in much the
same way as
the
standard
FIELD declaration.
The major differences are summarized
below.

2.2.2

A field-type name must be used instead of the conventional
list
of numeric values
in each field-definition.
The
field-type
names are actually macro calls
(as
is
the
, k e yw 0 r d' $ FIE LD its elf) •

The $FIELD keyword
indicates the beginning
of
a
new
block-structure
description
(the
macro call generates
counter-initializing code as well as a "FIELD" lexeme).
This
implies that,
in normal usage, each $FIELD declaration will
contain exactly one field-set-definition.

The ordering of the individual field-definitions within the
declaration
is significant.
That is, the order in which the
fields are specified determines the physical ordering of the
corresponding block components.
Fields are packed as densely
as possible, and thus several fields may be allocated within
one fullword.

The $ALIGN feature can be used preceding
a
field-definition
to
force
a
non-default boundary alignment for that field.
The use of $ALIGN is described in Section 2.3.1.

The $OVERLAY and $CONTINUE features can be used
within the
declaration to create overlapping field-definitions;
the use
of these features is described in Section 2.3.1.

Transportable Field-Types

The following field-types can be used with any BLISS compiler:
Field Type

Definition

$BIT

Single bit field

$BITS(n)

Specified number of bits - transportability
limited if n>16 (see Section 2.4.1)

2-6

Transportable Data Structures
$FIELD DECLARATION AND $FIELD SET SIZE
$BYTE

Unsigned field:
eight bits on a PDP-ll or
VAX-ll;
nine bits on a DEC-10/20

$BYTES(n)

Unsigned field:
specified number of bytes transportability limited if n>2 (see Section
2.4.1).
Not to be used for character strings;
see Section 2.4.3.

$INTEGER

Signed fullword integer (iwo bytes on a PDP-ll,
four bytes on a VAX-ll or a DEC-10/20)

$TINY INTEGER

Signed one-byte integer

$SHORT INTEGER

Signed two-byte integer

$LONG INTEGER

Signed four-byte integer - transportability
limited for PDP-ll (see Section 2.4.1)

$ADDRESS

Address of a memory location (fullword on a
PDP-ll or VAX-ll, two bytes on a DEC-10/20)

$POINTER

Pointer to a character position in memory (a
fullword on all target systems;
to be used with
CH$PTR)

$SUB_BLOCK(len)

Fullword-aligned beginning of a substructure
within the current structure, where the length
len is specified in fullwords.
(The resulting
field description may have a zero length.) See
Section 2.2.4.2 for usage guidelines.

$DESCRIPTOR(class)
Fullword aligned, standard character-string or
binary-data descriptor sub-block, the length of
which varies according to the class of
descriptor requested.
The class may be FIXED,
BOUNDED, DYNAMIC, DYNAMIC BOUNDED, or UNDEFINED.
See Section 2.2.4.3 for usage guidelines.
Descriptors in general are discussed in Chapter

6.
$REF_DESCRIPTOR

Address of a character-string or binary-data
descriptor (see Section 2.2.4.4)

$STRING(n)

Specified number of ASCII character positions,
i.e., a character-position sequence (eight bits
per character for PDP-ll or VAX-ll, seven bits
per character for DEC-10/20), addressable-unit
aligned.
See Section 2.2.4.5 for usage
guidelines.

2-7

Transportable Data Structures
$FIELD DECLARATION AND $FIELD SET SIZE
2.2.3

Nontransportable Field-Types

An additional nontransportable field-type, BLISS-36 only, is
for the sake of completeness:
Field Type
$SIXBIT(n)

2.2.4

provided

Definition
Specified number of 6-bit characters, where n
must be a multiple of three (DEC-lO/20 only)

Guidelines for Individual Field-Types

The use of the bit, byte, and integer
form of XPORT field-type
is
straightforward and does not require further discussion, except under
the heading of "Transportability Concerns" (Section 2.4).
The proper
use
of $ADDRESS, $POINTER, $SUB BLOCK, $DESCRIPTOR, $REF DESCRIPTOR,
and $STRING,
however, may not- be
completely
obvious.
These
field-types are discussed individually below.

2.2.4.1

$ADDRESS vs. $POINTER Usage

On the PDP-II and VAX-II,
the $ADDRESS and $POINTER field-types
produce the same size
field,
a
fullword
in each case.
In the
DEC-IO/20 environment (without extended addressing),
however,
these
two field-types produce quite different-sized fields:
18 bits vs.
36
bits respectively.
It is
important to
understand
the distinction
between these two related types of field, and their intended usage.
An address is simply the storage address of a binary data
item or
structure.
A pointer
is a
'character address' that designates a
position in a BLISS character-position sequence, as interpreted by the
BLISS character-handling (CH$xxxx) functions.
For example, a pointer
to the nth character of a
character string beginning
at a
known
address can be calculated
using
the BLISS CH$PTR function.
Thus,
"pointer" denotes a specialized, transportable kind of address value
for string data.
In a 36-bit environment without extended addressing, an address can be
represented by only 18 bits (half a BLISS fullword), but a pointer
requires 36 bits (an entire BLISS fullword).
In a
16-bit or
32-bit
environment,
an address and
a
pointer have the same internal
representation, each requiring an entire BLISS fullword.

2-8

Transportable Data structures
$FIELD DECLARATION AND $FIELD SET SIZE
2.2.4.2

Coding the $SUB_BLOCK Field-Type

The intended purpose of the $SUB BLOCK field-type is
to
signify the
beginning of a related group of fields within a block structure.
This
field-type can be used in one of two ways:
1.

As a
"placeholder"
only.
In
the
form $SUB BLOCK()
or
$SUB_BLOCK(O),
it identifies a specific point in-a block but
reserves no space.
When
used
in this
form,
the next
field-definition defines a field beginning at the same point
as that identified by the "name = [$SUB BLOCK()]" definition.
(Fullword
alignment
is
implicit for-this field-type.) For
example, consider the following $FIELD-declaration fragment:
SET
STATUS CELLS
COMP CODE
RETRY STATUS
UPDATE STATUS

[ $ S UB BLOC K 0 ] ,
[$B YTE] ,
[$BITS (3)],
[$BIT] ,

TES;
In the block structure defined by this declaration, the field
COMPL CODE begins at the
fullword
also identified by the
field=name STATUS CELLS.
The implicit fullword alignment for
field-name
STATUS CELLS ensures that that
the
positions
identified by these two names will in fact coincide,
on any
system and no matter what definitions precede the ones shown.
A field description generated by $SUB BLOCKO
always has a
size-value of
zero,
and thus can only be used in a context
that does not specify or imply indirection,
that
is,
in a
non-fetch/non-store context.
2.

As a "spaceholder".
In the form $SUB BLOCK(len) ,
where len
is
the length of the sub-block Tn addressable units,-rt
identifies a
specific
point in a
block and
reserves a
specified
amount of space. When used in this-iorm, the next
field-definition defines a
field
that begins
immediately
following
the
sub-block
being defined.
Consider
the
following coding fragment:

2-9

Transportable Data Structures
$FIELD DECLARATION AND $FIELD SET SIZE
SET
INPUT lOB
[$SUB BLOCK(IOB$K LENGTH)],
OUTPUT lOB
[$SUB-BLOCK(IOB$K-LENGTH)],
TEMP lOB
[$SUB-BLOCK (IOB$K-LENGTH)] ,
SERVICE CODE = [$BYTE],
TES;
In
this
example
three
separate
sub-blocks,
each
'IOB$K LENGTH'
units long, are defined
in sequence.
The
SERVICE CODE field follows the sub-block TEMP lOB.
A field description generated by $SUB BLOCK(n)
where n
is
either 0 or greater than %UPVAL has a size-value of zero, and
can only be used in an address (i.e.,
non-fetch, non-store)
context.
The field-positioning features $OVERLAY and $CONTINUE are
often used
in combination with this field-type, to define
individual fields within the sub-block.
The use of these
features is shown in a later example (Section 2.3.1.2).

2.2.4.3

Coding the $DESCRIPTOR Field-Type

The purpose of the specialized $DESCRIPTOR(class)
field-type
is to
define the beginning and extent of a standard XPORT sub-block, called
a descriptor, within a larger block structure.
The size of this subblock varies according
to
the class of descriptor specified;
the
class keywords are FIXED,
BOUNDED,
DYNAMIC,
DYNAMIC BOUNDED,
and
UNDEFINED.
Section 6.1 of this manual describes the properties of the
different classes, as well as descriptor usage in general.
The $DESCRIPTOR field-type is actually equivalent to the "spaceholder"
form of $SUB BLOCK, that is, to $SUB BLOCK(len) where the value of len
is implied by a class keyword.
As for $SUB BLOCK, fullword
alignment
is
implicit.
Also,
the field descripti~n generated by $DESCRIPTOR
always has a size-value of zero, and can only be used
in an address
context.
The default class
is FIXED for a field definition of the
form $DESCRIPTOR().
The field-positioning features $OVERLAY and $CONTINUE can be used
in
combination with this field-type, to define individual fields within
the descriptor.
The use of these positioning features is shown in a
later example (Section 2.3.1.2).

2-10

Transportable Data Structures
$FIELD DECLARATION AND $FIELD_SET_SIZE
The various string and binary-data descriptors
included within the
XPORT
I/O control block (lOB), described in Section 3.4 and Appendix
B, provide an actual instance of descriptors used
as sub-structures
(as opposed to independent block structures) •

2.2.4.4

Coding the $REF_DESCRIPTOR Field-type

The purpose of the specialized $REF DESCRIPTOR field-type is to define
a
field
that is the address of eTther a character-string or binarydata descriptor.
(See Chapters 6 and 7 for general
information on
descriptors.)
For
the
purposes
of
field
declaration,
the
$REF DESCRIPTOR field-type is equivalent to $ADDRESS.
Use of the $REF_DESCRIPTOR field-type has two benefits, however:
(1)
the
field declaration in which it is used is more self-documenting,
and (2) the XDUMP utility can provide a more symbolic
field
display
during
program debugging.
(See Appendix G for
a description of
XDUMP.)

2.2.4.5

Coding the $STRING Field-Type

The
$STRING(n)
field-type
reserves
space
for
an
ASCII
character-position sequence of length n.
Each character position
occupies eight bits on the PDP-ll or seven-bits on the DEC-IO/20.
The
BLISS character-handling (CH$xxxx) functions, described in Chapter 20
of the BLISS Language Guide, are specifically designed to access and
manipulate such sequences in a completely transportable fashion.
For
example, a pointer to the beginning (first character position of)
a
transportable string field defined as, e.g.,
STRING BUFFER

= [$STRING(80)]

should be constructed with the function CH$PTR(address) , for
CH$PTR( IOBLOCK[STRING_BUFFER] ).

example,

The field description generated by a $STRING(n) definition has a
zero
size value
if n specifies a character-position sequence whose length
exceeds %BPVAL bTts (or if n is 0).
In usual practice, however,
this
is of no consequence because the field-name is only used to generate a
character-position pointer as described above.
A $STRING field
is
aligned
to
the nearest (higher order) addressable-unit boundary:
A
byte boundary for the PDP-ll or VAX-ll, or a
word
boundary for
the
DEC-IO/20.
(This ensures that the
field-reference implied by the
field name is usable as a primary expression,
i.e.,
as an address
val ue .)

2-11

Transportable Data Structures
$FIELD DECLARATION AND $FIELD_SET_SIZE

The $FIELD SET SIZE feature calculates the length, in fullwords, of a
block defTned- with the $FIELD declaration.
You would ordinarily use
this feature in a LITERAL declaration following a $FIELD declaration,
to obtain the number of fullwords needed to accomodate the fields
defined in that declaration.
(The
usual
placement is
immediately
following
the $FIELD declaration,
since $FIELD SET SIZE implicitly
refers to the last such declaration.) For example:$FIELD
field-set-name
SET

TES;
LITERAL literal-name

= $FIELD_SET_SIZE;

The example given at the beginning of this chapter amply illustrates
the
use of this feature
and
its transportability aspects.
As
demonstrated by that example,
$FIELD_SET_SIZE produces the exact
number of fullwords needed to allocate a BLOCK structure.

2.3

SUPPLEMENTARY FEATURES

The supplementary features of the XPORT structure-definition facility
are described below under several different functional categories.
Like the rest of the structure-definition facilities,
these
features
are implemented as macro calls.

2.3.1

Field-Positioning Features

The field-positioning features
$ALIGN, $OVERLAY, and $CONTINUE
are
used within the $FIELD declaration and allow you to alter the
default positioning of a field within a structure.
By default, the only boundary alignment performed by the $FIELD
declaration
is the minimum required by the respective machine
architectures.
For example, the PDP-II and DEC-IO/20 systems cannot
fetch from or store into a
field that spans a fullword boundary.
Therefore, for those systems $FIELD provides fullword
alignment for
such fields that would otherwise cross that boundary.
On the VAX-II,
however, no such restriction exists and no boundary alignment is
performed
for a fetchable field (i.e., any field of up to %BPVAL bits
in length).
2-12

Transportable Data Structures
SUPPLEMENTARY FEATURES
2.3.1.1

$ALIGN Usage

The $ALIGN(mode) feature forces a specified mode of alignment for
the
immediately following field-definition.
The alignment modes are BYTE,
WORD, UNIT, and FULLWORD.
$ALIGN(xxx) causes the subsequently defined
field to begin at the next xxx-type boundary point assuming that it is
not already at such a boundary by default.
The precise meaning of the
mode keywords are as follows:
o

BYTE indicates alignment to the next (8-bit) byte boundary for
a
PDP-II
or VAX-II;
or to the next 9-bit byte position on a
DEC-IO/20 system, that is, to the next bit that is a multiple
of 9.

WORD indicates alignment to
the next even-numbered byte
boundary for
a PDP-II or VAX-II;
or to the next fullword or
halfword boundary for
a
DEC-IO/20 system, whichever
is
encountered first.

UNIT indicates alignment to the next addressable-unit:
to a
byte boundary on a PDP-II or VAX-II, or to a word boundary on
a DEC-IO/20.

FULLWORD indicates alignment to the next fullword boundary
any system.

For example:
$FIELD
FIELDSET A
SET
FIELD Al = [$SHORT_INTEGER],
FIELD-A2 = [$BYTE],
$ALIGN(FULLWORD)
FIELD A3 = [$ADDRESS],
TES;
The use of $ALIGN here ensures that field
FIELD A3 will
fallon
a
fullword
boundary on any system.
It also ensures that this alignment
is insensitive to any changes that may be made to
preceding
field
definitions.
(See Section 2.4 on efficiency considerations.)

2-13

Transportable Data Structures
SUPPLEMENTARY FEATURES
2.3.1.2

$OVERLAY and $CONTINUE Usage

The $OVERLAY(field) feature causes the next field to begin at the same
point
in the structure as
the named
field, which itself must be
defined by a preceding field-definition.
Essentially it allows you to
create alternate definitinns for a portion of a structure.
The $CONTINUE feature is used
after a
$OVERLAY and,
as
its name
implies,
allows
you to end a sequence of overlapping definitions and
continue defining fields at the "end" of the structure.
That
is,
it
causes
the
field defined
subsequent to
it to
start at a point
following
the highest-order
position already
occupied
by
any
previously defined field.
Consider the following coding fragment:

STATUS
[$B ITS (16)] ,
$OVERLA Y (STATUS)
INITIAL
[$BIT],
OPEN
[$BIT],
ERROR
= [$BIT],
EOF
= [$BIT],
$CONTINUE
NEXTFIELD = [$INTEGER],
In this example, the
overlap the
16-bit
the STATUS field, or
The STATUS field has
for future use.

2.3.2

INITIAL, OPEN, ERROR,
and
EOF bit fields all
field named STATUS, while NEXTFIELD starts beyond
indeed beyond the furthermost field yet defined.
12 high-order bits that, presumably, are reserved

Literal-Defining Features

The literal-defining features $LITERAL and $DISTINCT are
used
in
con j un c t ion wit h
( but 0 u t sid e 0 f) a $ FIE LD dec 1 a rat ion.
Th e y allow
you to define a sequence of literal values in a convenient and
easily
maintainable fashion.

2-14

Transportable Data Structures
SUPPLEMENTARY FEATURES
2.3.2.1

$LITERAL and $DISTINCT Usage

These two features are used
together to generate members of the
integer
set 1,2,3,4, •.• and assign them in ascending order to literal
names.
This is useful, for example, for defining an arbitrary but
dense set of status-code values and assigning names to those values.
The $LITERAL 'keyword' essentially provides a modified
form of the
BLISS LITERAL declaration, in which the $DISTINCT feature may be used.
The general form of this declaration is:
$LITERAL
literal-name-l
literal-name-2
literal-name-3
literal-name-4

$DISTINCT,
$DISTINCT,
$DISTINCT,
$DISTINCT,

literal-name-n = $DISTINCT;
$LITERAL initializes an internal
"value counter"
to 0;
$DISTINCT
bumps
that counter by 1.
Thus the literal names are given the values
1 through n in the order of their declaration.
Although this feature has no specific transportability aspect, it is a
coding convenience that particularly facilitates the modification or
maintenance task when such a set of literals needs to be altered.

2.3.3

Value-Display Feature

The $SHOW feature allows the numeric values generated by the XPORT
$<field-type>,
$FIELD_SET_SIZE,
and $DISTINCT macros to be displayed
in the program immediately following each macro call.
It also allows
the supression of any informational-level messages (prefixed %INFORM)
concerning $FIELD usage.

2.3.3.1

$SHOW Usage

$SHOW is used anywhere in a module to enable or disable the display of
subsequent XPORT-generated field definitions,
literal values, and
informational messages related to $FIELD usage.
The general
form of
the $SHOW macro is
$SHOW ( display-keyword , ••. )

2-15

Transportable Data Structures
SUPPLEMENTARY FEATURES
where the display-keywords are:
FIELDS or NOFIELDS
LITERALS or NOLITERALS
INFO or NOINFO
ALL
NONE
The initial (default)
INFO.

$SHOW

- Display/don't display field
definitions
- Display/don't display literal values
- Give/suppress informational messages
concerning field definitions
- Display both definitions and values,
and give informational messages
- Don't display any definitions, and
suppress informational messages.
options

are

NOFIELDS,

NOLITERALS,

and

An example of the $SHOW macro is
$SHOW( FIELDS, NOLITERALS )
which would cause the actual field-definition values generated by any
subsequent $FIELD declaration to appear in the source listing.
The
values are displayed immediately following the source line to which
they correspond.
(Any $FIELD-related informational messages would be
reported by default, assuming no prior setting of NOINFO.)

2.3.4

Subfield Referencing Feature

(Note to readers:
If this manual were organized according
to
levels
of difficulty,
the following material would be presented under
"Advanced Features".
Therefore, if the material in this section seems
obscure to you,
it
is likely that you have not yet experienced the
need for a subfield-referencing capability.)
The $SUB FIELD feature
provides a convenient and clear means of
referring to a subfield;
that is, to a field within a substructure.
This feature can be used instead of, or in addition to, methods of
subfield
referencing
involving BIND declarations or the use of
general-structure-references.
The need for a subfield-referencing mechanism arises when a data
structure
is defined in a composite fashion, using separate "building
blocks", as shown in the subsequent example.
The building blocks can
be either explicit $FIELD declarations or can be implicit (predefined)
XPORT descriptor structures;
see the $DESCRIPTOR field-type
and
Section 6.1.

2-16

Transportable Data Structures
SUPPLEMENTARY FEATURES
The following declarations provide a context for discussion and
examples of subfield referencing.
The XCB structure definition given
in Section 2.1.3 is referred to in the first declaration, and forms a
part of the context.
$FIELD
COMPOSITE BLOCK
SET
X CHAIN
X-CONTROL
X-NAME
X-BUFFER
TES;

[$ADDRESS] ,
[$SUB BLOCK(XCB SIZE)],
[$DESCRIPTOR(FIXED)] ,
[$DESCRIPTOR(BOUNDED)]

LITERAL COMP_BLK_SIZE

= $FIELD_SET_SIZE;

OWN
X PROCESS
GLOBAL
X REPORT

BLOCK[COMP BLK_SIZE] FIELD(COMPOSITE_BLOCK);
BLOCK [COMP_BLK_SIZE] FIELD(COMPOSITE_BLOCK);

The structure described by the COMPOSITE BLOCK field-set consists of a
single address field
and
three sub-blocks.
The format and size of
each of the sub-blocks are defined at some point prior
to
this code
fragment (see Section 2.1.3 and Appendix B.2).
Note carefully at this point that, given the
the ordinary-structure-references

preceding

declarations,

and

would be incorrect because the subfield names are not defined relative
to the origin of the entire block.

2.3.4.1

Subfield Referencing Using a BIND Declaration

To facilitate references to X CONTROL subfields within
block, for example, you could-write the declaration

the

X PROCESS

BIND
PROCESS CTL

X_PROCESS[XCONTROL]: BLOCK[] FIELD(XCB_FIELDS);

2-17

Transportable Data Stru~tures
SUPPLEMENTARY FEATURES
Then, within the scope of this declaration, you would be able
the following fetch expression:

use

(The subfields XCB 2, XCB_3, etc., could also be referred
same way, of cours~.)

the

Similar references to X CONTROL subfields of the X REPORT block would,
however,
require an additional BIND declaration,-as would references
to X NAME or X BUFFER subfields of either block.
For example,
ordinary-structure-references to X BUFFER subfields of the X REPORT
block would require a governing declaration of the form
BIND
REPORT_BUF

= X_REPORT[X_BUFFER]:

$STR_DESCRIPTOR();

where $STR DESCRIPTOR() is an XPORT macro, described
in Chapter 6,
that provIdes a structure-attribute and field-attribute for standard
XPORT string descriptors. Within the scope of this BIND declaration,
you would be able to use expressions such as

2.3.4.2

Subfield References Using General Structure References

Sub- field references equivalent to those shown above can be achieved
using
a general-structure-reference, as shown in the following
parallel examples of fetch expressions:
.BLOCK[X_PROCESS[X_CONTROL],XCB 1]
.BLOCK[X_REPORT[X_BUFFER],STR$H_LENGTH]
These expressions are more verbose than their equivalents
in the
preceding subsection, but have the advantage of not requiring the BIND
declarations when only one or two references to each substructure are
to be made.
The syntax of a general-structure-reference does,
however, leave something to be desired
in the way of clarity and
simplicity.

2-18

Transportable Data Structures
SUPPLEMENTARY FEATURES

2.3.4.3

Subfield References Using $SUB_FIELD

The $SUB FIELD feature offers the same advantage as the generalstructure-reference for subfield references, and in addition provides
clarity of intent and a simpler syntax.
The general
form of a
$SUB FIELD reference is
$SUB_FIELD( substructure-name, field-name)
where the definition of <field-name>
and
the
definition
<substructure-name> occur in different $FIELD declarations.

The following fetch expressions, using $SUB FIELD, are equivalent
the fetch expressions given in the preceding two subsections:

• X_PROCESS [$SUB_FIELD(X_CONTROL,XCB_l)]
• X_REPORT [$SUB_FIELD(X_BUFFER,STR$H_LENGTH)]

2.3.4.4

Using $SUB_FIELD with $OVERLAY

particular subfield of a structure will be referred
to
When a
frequently, it is common practice to provide an explicit definition of
that subfield within the overall structure definition.
The following
alternative definition of the COMPOSITE BLOCK structure demonstrates
the use of $SUB_FIELD with $OVERLAY in order to declare an "explicit
subfield":
$FIELD
COMPOSITE BLOCK
SET
X CHAIN
[$ADDRESS],
X-CONTROL
[$SUB BLOCK(XCB SIZE)],
X-NAME
[$DESCRIPTOR(FIXED)],
X-BUFFER
[$DESCRIPTOR(BOUNDED)],
$OVERLAY( $SUB FIELD(X BUFFER,STR$H_MAXLEN)
X MAX BUFF SIZE = [$BYTES(2)]
$CONTINUE
TESj
Thus the following two references to the subfield in question would be
equivalent:
. X_PROCESS [X_MAX_BUFF_SIZE]
. X_PROCESS [$SUB_FIELD(X_BUFFER,STR$H_MAXLEN)]

2-19

Transportable Data Structures
TRANSPORTABILITY CONCERNS
2.4

TRANSPORTABILITY CONCERNS

Two related problem areas cause most of the transportability concerns
that arise in connection with XPORT data structures:
field size, and
integer value
range.
Another,
lesser problem
is the
possible
confusion of $BYTES(n)
with $STRING(n) as a means of transportably
defining a character-string field.
These potential problem areas are
discussed individually below.

2.4.1

Field Size

Several of the XPORT field-types can cause a transportability problem
with
respect to field size (assuming that the field being defined is
to be fetched from or stored into).
The problem stems from
the
fact
that a fetchable/storable field cannot exceed a fullword (%BPVAL bits)
in length on any system.
The problematic field-types are:
1.

$LONG INTEGER.
This field-type is not fully transportable to
the
PDP-II,
since
no
more
than two bytes can be
fetched/stored on that system.
If compiled for that system,
it will
reserve four
bytes
in the data structure but the
corresponding field description will have a zero size value
and will be useful in an address context only.
(Note here
that the field-type $INTEGER will
produce the exact same
effect as $LONG INTEGER on the VAX-II and DEC-IO/20, and is
fully transportable to the PDP-II
albeit with a
radical
reduction in integer value range, as discussed below.)

$BITS (n).
If the value of n exceeds 16, this field
type
is
not fully transportable across all target systems, for the
reasons given under
item
(1)
above.
(This
field-type,
however, is often used as a "spaceholder" for a collection of
bits that is not typically fetched or stored as a whole.)

$BYTES (n).
If the value of n exceeds 2, this
field-type
is
not fully transportable aGross all target systems, for the
reasons given under item (1) above.

Observe that we have not included either $SUB BLOCK or $STRING in the
above
list,
on the assumption that fields defined with these
field-types are typically longer than a fullword and are 'pointed
to'
in
some fashion rather than accessed directly.
If, however, $STRING
were used (e.g.) to define a character-string field
that was
to be
fetched
directly,
anything over two character positions would not be
fully transportable.

2-20

Transportable Data Structures
TRANSPORTABILITY CONCERNS
In all cases, if a longer-than-fullword field is generated by a fieldtype other than $SUB BLOCK or $STRING, it is the user's responsibility
to align it to an addressable boundary
(with $ALIGN(UNIT))
if
its
address is to be used.

2.4.2

Integer Value Range

Transportation of programs between the two larger BLISS target-system
families
(i.e.,
VAX-II and DEC-lO/20)
does not usually present a
problem with regard to range of integer values, since each system
accomodates a fullword value of the same order of magnitude.
However,
unless considerable care is taken at the design stage,
the potential
problems involved in moving a program from a system with 32 or 36 bits
per value to a system with only 16 bits can be very troublesome
indeed.
The discrepancy between the maximum values that can be
hand.led is enormous.
For example, $INTEGER defines a
field on the
VAX-II
or
the DEC-lO/20 that can accomodate a value in excess of two
billion or 34 billion respectively.
On the
PDP-II,
however,
the
maximum (positive) value that a $INTEGER field can hold is 32,767.
Obviously, this problem can only be resolved by a design that ensures
that no calculated value need exceed the value limit of the smallest
system to which the program is to be transported.

2.4.3

Use of $BYTES for Character Strings

The $BYTES field-type is not intended for the transportable definition
of character-string fields.
Although it will serve the purpose on the
PDP-II and VAX-II, where each ASCII character position occupies an
8-bit byte, on the DEC-lO/20 it will define a sequence of 9-bit bytes
whereas a sequence of 7-bit character positions is required.
The BLISS transportable character-handling functions assume a 7-bit
character
size on the DEC-lO/20.
The $STRING field-type is intended
expressly for this purpose.
It provides the correct space allocation
in each case, and also provides automatic alignment of the field to an
addressable-unit boundary, which is required in order that the field's
address may be passed (or otherwise used as an address) .

2-21

Transportable Data Structures
EFFICIENCY CONCERNS
2.5

EFFICIENCY CONCERNS

On some systems, a certain amount of speed advantage can be gained
from having fields begin on a major addressable boundary.
The $ALIGN
feature allows you to
request this alignment.
By default XPORT
produces maximally packed
fields,
on the assumption that space
efficiency will more often be desired.
As a case in point, the VAX-ll system allow fetchable/storable
fields
to
cross fullword
boundaries,
and
therefore XPORT will begin most
fields (addresses, integers, byte sequences) at any point in a VAX
longword.
As an extreme example, an address field may begin at bit 31
of a given word and extend through bit 30 of the following
word.
A
considerable amount of efficiency would be gained
(assuming, of
course, that the address value is used with some frequency)
if
the
field began on a fullword boundary.
In general it can be said that,
on the byte-oriented architectures, a
field
that corresponds to a
standard allocation unit
(BYTE, WORD,
LONG)
should,
for maximum
efficiency, start on an address boundary that is
'natural'
for
its
size.
On a
PDP-II system this alignment of fields tends to occur
"automatically" in XPORT data structures as a
result of the PDP-Il
field-reference restrictions (discussed above).
On the VAX-Il however
this alignment is the user's responsibility.
Another potential candidate for alignment consideration is a two-byte
(lS-bit)
field on a DEC-IO/20, which can be very efficiently accessed
from either a word or half-word boundary. By default XPORT will align
such a field to a fullword boundary only if it would otherwise span a
fullword boundary.
JUdicious use of the BYTE option of $ALIGN can
achieve the desired positioning in this case.
On the whole, however, the real probability of significant speed gains
can only be determined by a study of the target-system architectures
in relation to the program's use of the fields in question.

2-22

CHAPTER 3

INPUT/OUTPUT FACILITIES

INTRODUCTION • . • • • •
. • • . . . . • . . • 3-1
General Characteristics • • • • . . . • •
. 3-2
Specific Functions • • • •
. . . . . • 3-3
3.2
CAPABILITIES . • • • • • . • . . . • •
. 3-3
3.2.1
File Level Capabilities
• • • •
3-3
3.2.1.1
OPEN • • •
••• •
3-4
3.2.1.2
CLOSE • • • • • • • •
3-4
3.2.1.3
BACKUP • • • • • • • • • • • • • • •
• • • 3-4
3.2.2
Input/Output Capabilities
• 3-5
3.2.2.1
Opening Concatenated Input Files
. 3-6
3.2.2.2
Output File Opening Options
. • • 3-7
3.2.2.3
Devices Openable for Both Input and Output . . 3-8
File Specification Resolution • • . •
. . . 3-8
3.2.3
3.3
I/O RELATED MACROS • • • • • . • • • •
• 3-9
3.3.1
General Format and Common Parameters • . • • •
3-10
3.3.2
File-Level Macros • • • • • • • .
.•.•
3-11
3.3. 3
Input/Output Macros • • • • • • • •
3-15
3.3.3.1
Use of Pointers Vs. Addresses in Macro Calls 3-17
3.4
INPUT/OUTPUT CONTROL BLOCKS
3-18
3.4. 1
Creating and Initializing IOBs •
3-18
3.4.2
Using IOB Fields and Values
3-19
3.5
STANDARD I/O DEVICES • • • • • •
3-22
FILE SPECIFICATION PROCESSING
• • ••
3-23
3.6
File Specification Resolution
3-23
3.6.1
Rules for File Specification Resolution
3-24
3.6.1.1
3.6.2
File Specification Parsing
3-26
3.7
I/O COMPLETION CODES • • • . • • • • • • • • • •
3-27
I/O ACTION ROUTINES • . • . •
. • ••
3-28
3.8
3.1

3. 1. 1
3. 1. 2

CHAPTER 3
INPUT/OUTPUT FACILITIES

This chapter describes the input/output-related portions of the XPORT
Programming Tools Facility.
The description given here is intended to
present concepts rather than give complete details
in all cases.
Appendix A contains complete, detailed descriptions of all XPORT macro
calls in a form designed for concise reference.

3.1

INTRODUCTION

The BLISS language does not provide built-in I/O capabilities.
Among
other services, the XPORT facility provides easy-to-use, transportable
input/output support, via macro calls, for application programs that
do not have particularly stringent or sophisticated I/O requirements.
XPORT I/O
is a
system-independent service package that supports
sequential
I/O operations in record,
character-stream, and binary
mode,
and
provides basic
file-level
functions.
The
file-level
functions
include, for example, file deletion and renaming as well as
opening and closing.
The
XPORT
I/O
facility
actually
consists
of
a
separate
source-and-object package for
each target operating system and file
system.
However,
the source-program
interface to each of these
packages
is
identical, and the results are equivalent.
Thus the I/O
support provided is fully transportable except where clearly noted.

3-1

Input/Output Facilities
INTRODUCTION
3.1.1

General Characteristics

The program interface is implemented as a set of BLISS keyword-macros,
of the form $XPO xxxx( ••. ).
For example, $XPO PUT is the name of the
write operation; -a typical call for writing
out the content of a
character-string buffer might look as follows:
$XPO PUT( lOB = output f i l e ,
STRING = ( :char count,

.line_pointer ) )

where the lowercase names are user-defined.
Central to the operation of the I/O macros is the I/O control block,
or
lOB.
The
lOB
is a standard BLISS block structure, for which an
extensive set of field names is defined.
As will be shown,
the
lOB
fields can be accessed either by standard structure-references or, in
many cases, by means of macro keywords.
The lOB field
names are of
the
form
IOB$x xxxx;
for
example,
IOB$T STRING names a
string
descriptor sub-block of the lOB.
(See Section 2.2.3 concerning
subblocks.)
The corresponding macro
keywords are similar to the xxxx
portion of the field names, e.g., STRING.
Each system-dependent implementation of XPORT consists essentially of
two parts:
a set of BLISS declarations (macro, literal, and field),
and a set of object-time service routines.
The source declarations,
many of which define routine calls, are obtained from the XPORT
library file for the target system, which must be named in a
LIBRARY
declaration in your source program.
An example of such a declaration
is
LIBRARY 'BLI:XPORT'
The relevant service routines are linked with your object program.
An
example of an appropriate command
to
perform such linking in the
VAX/VMS environment is
$ LINK

user-module-name, SYS$LISRARY:XPORT/LIBRARY

(Appendix F gives additional examples for other target systems.)
The names of the required source-and object-time files for each target
system are given
in Appendix
F,
along
with suggested methods of
referring to those files in a transportable manner.

3-2

Input/Output Facilities
INTRODUC TI ON
3.1.2

Specific Functions

XPORT I/O comprises the following I/O and file-manipulation functions:
OPEN

prepa res an existing
file
new or
pre pa res either a
(output) •

for
reading
(input),
or
existing
file
for writing

terminates the processing of an input
flushing any I/O buffers as necessary.

GET

returns the address and length of character or binary
data
read
from
an
opened
input file.
Logical
concatenation of several input files can be automatically
performed when an intermediate end-of-file is reached.

PUT

writes character or binary data to an opened output file.

DELETE

deletes an existing file.

RENAME

changes the name of an existing file.

BACKUP

provides a mechanism for preserving a copy of an
input
file when a
program creates a new version of that file
(typically used by editor-type applications).

PARSE

parses a file specification into its component parts.

Each of these functions is represented by a macro name;
$XPO RENAME.
There are also
several other related
creating and initializing various XPORT control blocks.

3.2

output

file,

for
example
macros,
for

CAPABILITIES

XPORT I/O provides sequential
input and output for
standard
I/O
devices on the
user's target system.
In addition,
a number of
file-level operations are available for
named
files.
The specific
capabilities are discussed below.

3.2.1

File Level Capabilities

XPORT allows the user to delete, rename, and 'backup' named files,
as
well as to open and close files (and devices) for input/output. While
the general result of a file delete or
rename operation should be
reasonably familiar and not in need of further elaboration, the XPORT
open, close, and backup operations require some further discussion.

3-3

Input/Output Facilities
CAPABILITIES
3.2.1.1

OPEN

The open operation incorporates a
feature
called
file-specification
resolution
which
IS
somewhat unusual
in a
high-level
language
facility.
This feature is essentially a file-specification defaulting
mechanism.
It allows the end user, for example, to give an incomplete
file specification which, at open time, is automatically combined with
program- and system-supplied default components to make up a full file
specification.
File-specification resolution is discussed
in detail
in Section 3.6.1.
(DELETE and RENAME also perform file-specification
resolution when necessary.)

3 • 2. 1 • 2

C LO S E

The close operation provides a
REMEMBER option that preserves the
file-attribute
information .in the corresponding lOB for subsequent
operations:
reopening,
deletion,
renaming,
or
backup.
When the
REMEMBER option is used,
any subsequent operations which would
ordinarily perform file-specification resolution do not do
so,
but
take
the already resolved (and 'remembered') file specification from
the lOB.
When a file is closed without the REMEMBER option,
all
fields of the corresponding lOB are reinitialized.

3.2.1.3

BACKUP

The backup operation is intended
for
applications that produce an
output file that is, in some sense, an "upgraded" version of the input
file;
typically an editor-type application.
The
presumption
upon
which
the operation is based is that the output, or new, file is to
take the name of the input, or old, file, but also that the new file
is
to be "backed
up"
by the old file for safety's sake (e.g., for
recovery purposes).
For example,
the BLISS
Language Formatter,
PRETTY, produces a reformatted version of the input source file as its
output file, and the output file name defaults to the input file name.
On each host system, the new file is renamed by the backup operation
with the old file name.
The old file is "backed up," or preserved, in
either of two ways depending upon the file-system capabilities of -the
host
system.
On host systems such as VAX/VMS which support multiple
file-version numbers, the new file is simply given the old-file name
with
the next higher version number and the old file is not renamed.
On systems that do not support multiple version numbers, however, such
as TOPS-IO,
the new file takes the old-file name and the old file is
given a different file type (or extension).
The default file type for
backup operations is ".BAK".

3-4

Input/Output Facilities
CAPABILITIES
Note that the new output file
involved
in
typically an XPORT temporary file
prior
$XPO TEMPORARY in Section 3.5.

a
to

backup operation is
its renaming;
see

The backup operation requires that, prior to its invocation,
both of
the files involved have been opened, and then closed with the REMEMBER
option (see above).
(Presumably the
input and output files
are
processed to completion in the interval.)

3.2.2

Input/Output Capabilities

XPORT provides a get and a put operation,
which perform sequential
input and output respectively.
The get operation works in "locate" -as opposed to "move" -- mode;
that is, it reports the location
(and
length)
of the data
read
in,
rather than reading the data into a
user-specified location.
(The put operation takes
its output data
from a user-specified location, per usual practice.)
The data read or written by these operations can be in
basic forms:

one

three

A logical record, consisting of a variable
(or sometimes
fixed) amount of character-string data (RECORD mode) •

A stream of characters of user-specified
length
(STREAM
mode) •
The character stream is not differentiated by XPORT
as to control characters vs.
non-control characters.

A user-specified number of of binary values
(BINARY mode).
The number of binary values to be read or written can be
specified in terms of either BLISS values
(FULLWORDS)
or
addressable units
(UNITS),
although specification of the
latter normally limits program transportability.

The mode keywords RECORD, STREAM, and BINARY are file-level attributes
that must be specified when opening
a given file.
Another such
keyword, SEQUENCED, implies RECORD and
further
specifies that an
output file is to be sequence numbered;
i.e., that a sequence number
is to be associated with each logical record written.
This
type of
file
is produced by the SOS text editors,
for example.
(For a
sequenced input file, the SEQUENCED indicator in the lOB is set by the
open operation if the file is opened in RECORD mode.)

3-5

Input/Output Facilities
CAPABILITIES
For character-encoded (e.g., ASCII) files,
RECORD mode
is normally
used.
In this mode, terminal-control-character (TCC) sequences are
not passed to the program on input, and are automatically supplied by
XPORT on output as appropriate for the host system involved.
Note,
also, that the program does not specify the number of characters to be
read
in this mode;
the size of an input record is determined from
information contained in the file.
Character-string files can also be processed in STREAM mode, in which
all of the data read (plus, in some cases, the TCC sequences implied
by the file format) is passed to the program as an undifferentiated
stream of characters, and on output, no TCC sequences are supplied by
XPORT.
In other words, the user is "in full control"
in this mode,
and must have a detailed knowledge of the file formats and conventions
of each host system for which the program is intended.
The amount of
data
to be read,
as well
as the amount to be written, must be
specified in each I/O call.
STREAM mode is provided on a caveat
programmator basis for
the
relatively few kinds of applications
needing this capability.
BINARY mode is used to read and write files of binary data.
The
amount of data to be read, as well as the amount to be written, must
be speci~ied in each I/O call.
The specification of an input or
output datum size
in terms of FULLWORDS allows source program
transportability, assuming that CPU word
size
is not a
limiting
factor.
The use of UNITS, on the other hand, allows transportability
between the 16-bit and 32-bit environments with identical results, but
drastically reduces the likelihood of transportability between the
16/32-bit environments and the 36-environment.

3.2.2.1

Opening Concatenated Input Files

A sequence of input files can be treated as a single file through use
of the XPORT "concatenated input" feature.
Concatenation is indicated
to XPORT by giving a file specification of the form
file-spec-l + file-spec-2 + ••• + file-spec-n
in an OPEN call.
This requests that when the end of each file
is
reached,
the next file in the specified sequence of input files is to
be opened and read (in a way that is completely transparent to
the
reading program).

3-6

Input/Output Facilities
CAPABILITIES
The only file in the sequence that is explicitly opened by the program
is
the
first one.
All GET operations on the entire sequence are
requested by reference to the same lOB.
The file attributes and other
parameters specified in the OPEN call are assumed for all of the files
in the sequence.
Actually, when a
concatenated
file needs
to
be
opened, the following actions take place:
o

Th e cur r en t 1 Y 0 pe n ed f i 1 e (e. g ., the i nit i a 1 f i 1 e)

i scI 0 sed ,

The file-specification
information for
the next file
is
resolved, using default and related-file information, if any,
from the lOB, and

The new resultant file specification is placed
in the
lOB,
replacing
the previous one.
(File specification resolution
is described in detail in Section 3.6.1.)

The concatenated file is then opened
and
read.
Thus
the
associated GET call
refers to the same lOB throughout the
processing of an entire input-file sequence.

Note that the concatenated input-file capability can be completely
automatic
and
transparent to the user program.
That is to say, the
logic and structure of a program need not be affected by the fact that
multiple
input files may be processed.
Detailed $XPO GET completion
codes do, however, allow the program to monitor concatenated-input
processing (see Section A.8.3).

3.2.2.2

Output File Opening Options

In addition to the OUTPUT file-processing option itself,
applicable to output files are APPEND and OVERWRITE.

the

options

APPEND means that, if the specified file already exists,
the
initial
write
operation is to begin at the current end-of-file, that is, the
file is to be extended.
OVERWRITE means that, if the specified
file
already exists, the initial write operation is to begin at the current
beginning-of-file, overwriting the existing file content.
(Neither of
these
options have significance
if the named file does not already
exist.) Both of these options imply the OUTPUT option.
If the OUTPUT option alone is specified, XPORT will attempt to
create
the file even if the indicated file already exists.
If this cannot be
done (i.e., the host system doesn't support file versions,
the
user
has
specified
a verSlon number matching that of the existing file,
etc.), the open operation will fail.
In all cases, if
the
indicated
file does not already exist, it will be created if possible.

3-7

Input/Output Facilities
.
CAPABILITIES
In RECORD mode, a "RECORD SIZE = n" parameter may be specified
for a
file that is to contain flxed-length records.
Records 'put' to such a
file that are shorter or longer that n are padded (with ASCII spaces)
or
truncated
respectively.
An error indication is returned in the
truncation case.
RECORD SIZE = VARIABLE is the default.
A fixed physical-block size may also be specified
for
appropriate
devices, such as magnetic
tape, or for file formats to which it is
applicable.
(For RMS ISAM files,
for
example,
this parameter
is
converted into an RMS "bucket size".)
If no file-processing option is specified for a file by file-opening
time,
INPUT is assumed.
The INPUT and OUTPUT (as well as APPEND and
OVERWRITE)
options are mutually exclusive except for
non-filestructured devices;
see the following subsection.

3.2.2.3

Devices Openable for Both Input and Output

A communications (as opposed to file-storage) device that can be both
read and written is opened for input and output by default.
(The user
can specify that the device be opened either for
input or output
only.)
Such devices include all standard interactive-user terminals
and DECnet communication links.
Note that all devices,
including
interactive terminals, must be expLicitly opened in order to be used.

3.2.3

File Specification Resolution

XPORT file-specification resolution, which is performed by the open,
delete, and
rename operations, provides a general-purpose mechanism
for
defaulting various
components
of
a
file
specification.
Specifically,
it is the process of augmenting
a partial
file
specification (possibly only a
filename)
with default information
provided by both the program and the host file system, in order to
arrive at a complete file specification for the system in question.
For an input file, the program typically provides a default file type,
and
the host file system provides a default file-version number, if
any.
For an output file, the program may provide both a default file
name and
file type, with the system providing the version number if
any.
For both input and output files, the host file system
(through
XPORT)
provides a default for the network-node, logical- or physicaldevice, and directory (or
PPN)
components, as applicable for
the
system in question.

3-8

Input/Output Facilities
CAPABILITIES
The "initial" file specification with which the
process begins
is
typically one given by the end user (e.g., through direct interaction
with the program), and is called the primary file specification.
The
program can also specify a
o
o

Default file specification, usually only a
for both input and output files, and a

file

type,

used

Re 1 at ed f i 1 e s pe c if i cat ion (a 'r e 1 at ed' in pu t - f i 1 e s pe c ,
used only for output files.

for

example)~rmally

There is a
descriptor
sub-block
in the
lOB
for
each of
these
specifications,
and each has a corresponding keyword parameter (e.g.,
FILE SPEC, DEFAULT) in the appropriate macro calls.
The result of the
resolution
process
is called
the resultant file specification, for
which there is also a descriptor in the lOB (IOB$T_RESULTANT).
The order of application,
components is as follows:

precedence,

The primary file specification

The default file specification

The related file specification

System-prov ided defaults.

file-specification

In addition, for output files there is a special convention concerning
the
related
file
specification (involving the use of an asterisk in
either the primary or default specification)
which "forces"
filespecification
components
to
be copied
from
the
related
file
specification.
The actual coding details and precise rules for
using
file-specification
resolution are given in Section 3.6.
That section
also contains a discussion of the
'parse'
operation and
its macro
call, $XPO_PARSE_SPEC.

3.3

I/O RELATED MACROS

This section discusses the file-level and I/O macro calls, mostly by
way of
typical
usage examples.
Other macros are discussed in later
sections and chapters:
lOB creation and
initialization macros are
covered
in
Section
3.4.1;
the macros concerned
with
filespecification parsing in Section 3.6.2.
Stringand data-descriptor
creation macros are described in Chapter 6.

3-9

Input/Output Facilities
I/O RELATED MACROS
Four parameters are common to most· of the macros calls;
we will
describe
these
first,
along with the general macro format, to avoid
subsequent repetition.

3.3.1

General Format and Common Parameters

The general format of an XPORT I/O macro call
is given in the
following
syntax diagram.
(The notational conventions of the BLISS
Language Guide apply here as well:
lowercase
indicates syntactic
variables, uppercase indicates syntactic literals, and so on.)

+--------------------------------------------------------------------+
\

\ i/o-macro-call

\ $XPO function ( parameter , .•. )

+--------------------------------------------------------------------+
\

\ function
\

\
\

\ parameter
\
\

\ {keyword
\ {keyword
\ { k e yw 0 r d

BACKUP \ CLOSE \ DELETE
GET \ OPEN \ PUT \ RENAME

\
\
\

+--------------------------------------------------------------------+
\
\ {keyword
user-defined-string-or-value
}\
(user-defined-string-or-value, .•• ) } \
secondary-keyword
}\
( s e con dar y - k e yw 0 r d ,... )
}\

+-------------------------------------~------------------------------+

Examples of parameter keywords are FILE SPEC,
STRING,
PROMPT,
and
OPTIONS.
Examples of secondary keywords are INPUT, APPEND, RECORD,
and SEQUENCED.
The four commonly occuring parameters are the following:
o

lOB = address of iob
This required parameter specifies the address of the lOB
upon which or
through which the operation is to be
performed.
(Note:
BACKUP requires two lOB addresses.)

FAILURE = address of a failure-action routine
This optional
parameter specifies the address of a
routine to which XPORT is to pass control in the event
of a failure condition (i.e., an exception or error).
If
this
parameter
is
not specified,
a default
failure-action
routine
is supplied
by
XPORT,
as
discussed in Section 3.8.

3-10

Input/Output Facilities
I/O RELATED MACROS
o

SUCCESS = address of a success-action routine
This optional
parameter specifies the address of a
routine to which XPORT is to pass control following
successful completion of the requested operation.
If
this parameter is not specified, no success-action
routine is called, and control returns directly to
the
call site.
(This parameter is rarely used.)

USER = user-defined fullword value
This optional parameter specifies a value to be placed
in the IOB$Z USER field of the lOB involved.
This value
is not interpreted or used by XPORT in any way;
the
parameter is provided simply for the user's convenience.
It might be used, for example, to maintain a count of a
given operation, or to hold an address or value to be
passed to the user's failure-action routine.

The next two subsections discuss specific examples of
and I/O macro calls.

3.3.2

the

file-level

File-Level Macros

Typical examples of the $XPO OPEN macro call
follow.
In these
examples,
user-defined names are shown in lower case for the sake of
clarity.
(Case is irrelevant, of course, outside of quoted strings.)
$XPO OPEN

lOB = user terminal ,
FILE SPEC ~ $XPO INPUT
-

This call opens an interactive end-user's terminal for both input and
output
(by default),
through an lOB named "user terminal" with the
symbolic file specification "$XPO INPUT".
This symbolic specification
(actually a macro call) indicates-the standard -- or system default -input device;
see Section 3.5.
(For a batch job, of course, this
is
simply the job's input stream, which would be opened for input only.)
A second example of the OPEN call,
$XPO OPEN

lOB = change file ,
FILE SPEC = user terminal [IOB$T_STRING]
DEFAULT = '.UPD'-)

opens an input file through the lOB named "change file".
(Recall that
OPTIONS=INPUT is the default for files.) The file specification is
given indirectly, via the IOB$T STRING descriptor in the user-terminal
lOB.
This string descriptor- describes the most recent record read
from the user's terminal, presumably a file specification.
A default
file specification consisting of the file type ".UPD" is specified.

3-11

Input/Output Facilities
I/O RELATED MACROS
This will be combined with the primary file specification if it
a file type.

lacks

A further OPEN example:
$XPO OPEN

lOB = output file ,
FILE SPEC = user terminal [IOB$T_STRING] ,
DEFAULT = '*.MAS' ,
RELATED = change file[IOB$T RESULTANT] ,
OPTION = APPEND ~
ATTRIBUTE = SEQUENCED) ;

In this case, the file is opened for output and is to be extended
if
it already exists
(APPEND).
Like the input file, the primary file
specification is to be read from the user-terminal
lOB,
but
if the
terminal
response
is null
(or contains one or more asterlsks), the
missing components are obtained from the related
file specification,
which is the resultant file specification for the input (change) file.
Prior
to application
of
components
from
the
related
file
specification, however,
the default file type ".MAS" is applied if
needed, since a default file specification has precedence over a
related
file specification.
Finally, each logical record written to
this file is to have a record sequence number.
(This number must be
provided by the user as we will see in a subsequent PUT example).
Note that, because the file is being opened for APPENDing, if the file
already exists and is not sequence numbered, the SEQUENCED option is
ignored.
Several examples of the $XPO CLOSE macro call follow.
$XPO CLOSE

( lOB

= user

terminal)

;

This example is self-explanatory;
the user's terminal is
all fields in the associated lOB are reinitialized.

closed

and

A further example:
$XPO CLOSE

lOB = change_file ,
OPTIONS = REMEMBER )

In this case, the input file controlled by the change file
lOB
is
closed with the REMEMBER option, possibly because it is going to be
renamed or deleted, or
is to be reopened
for
reprocessing.
The
REMEMBER option causes all file-Iattribute information in the lOB to
be retained.
All file-processing options, on the other hand,
are
'forgotten' in any case, including the REMEMBER option.

3-12

Input/Output Facilities
I/O RELATED MACROS
An example of the DELETE call:
$XPO _DE LET E

lOB = arbitrary file ,
FILE SPEC = terminal input [IOB$T_STRING]

) ;

Here we assume that the file has never been opened (or has been closed
without
the REMEMBER option);
i.e'.,
that the resultant filespecification field of the lOB is empty.
The call relies on end-user
input to
supply a complete file specification (except for system
supplied defaults), since no default or related-file
parameters are
specified.
In contrast, the call
$XPO_DELETE ( lOB

= change_file

relies on the fact that a
resultant file specification has been
retained
in the
lOB for a file previously closed with the REMEMBER
option.
Thus no file-specification information is required.
An example of the RENAME call
(which assumes
that
preceding DELETE example has not been executed):
$XPO RENAME

the

immediately

rOB = change file ,
NEW_SPEC = (- .spec_length , .spec_ptr ) )

Here the call relies, as before, on the fact that a
resultant file
specification is still in the lOB (identifying the "current" name of
the closed file);
thus no FILE SPEC parameter is given.
For the new
name,
the call supplies a length value and pointer to a characterposition sequence, which presumably contains a
file specification
determined by the program.
As the basis for another example of RENAME, assume that the program
elicits
from
the
end-user's
terminal
(1)
a
'current'
file
specification and (2) a 'new' file specification. When response
(1)
is
read,
the program moves the string to an area pointed to by, say,
.old name ptr, then reads response
(2)
and
executes the following
call:
$XPO RENAME

lOB = arbitrary file ,
FILE SPEC = ( .oldname length, .oldname_ptr
DE FAULT = '. DA T ' ,
NEW SPEC = terminal input[IOB$T STRING] ,
NEW-DEFAULT = '*. NEW' )
-

Here the default file type
is ".DAT"
for
the
current
file
specification and "*.NEW"
for
the new file specification.
Also,
because no NEW RELATED parameter is given, XPORT assumes the current
file
specification (described in IOB$T RESULTANT) as the value of the
new-related file specification.
-

3-13

Input/Output Facilities
I/O RELATED MACROS
is null
Thus if the new-file-spec response from the user's terminal
for
any reason,
the
rename operation will
use the current file
specification but with the default type ".NEW".
Note that the program cannot specify a NEW RELATED parameter that has
the
same effect as the default assumption made by XPORT.
That is, a
RENAME parameter of the form
NEW RELATED = the-same-iob[IOB$T_RESULTANT]
will cause execution errors, since the description of the new-related
file
specification is determined before the
'old' resultant file
specification is actually created.
The following example of a BACKUP call is shown in-context,
in order
to
illustrate the proper usage of this operation.
For this example,
assume that the content of the input file
is modified
in some way
(processing not shown) to produce the output file.
$XPO OPEN
$XPO OPEN

lOB = input file ,
FILE SPEC =-input-spec-descriptor
lOB ~ output file ,
FILE_SPEC = $XPO_TEMPORARY , ••• )

, ...

The input and output files are
now processed to completion.
$XPO CLOSE
$XPO-CLOSE

lOB
lOB

$XPO_BACKUP

( OLD_lOB = input_file , NEW_lOB = output_file

input file , OPTIONS = REMEMBER ) ;
output_file , OPTIONS = REMEMBER) ;

Note that both files are closed with the REMEMBER option.
The purpose
of
this
is to preserve the
resultant file specifications in the
respective lOBs.
(Recall
that BACKUP does not
perform
filespecification resolution.)
Following the backup operation, if the host file system supports file
version numbers,
the new file has the same file specification as the
old file but with a higher version number.
If the host file system does not support multiple file versions,
the
new file will have the old file specification and the old file will be
renamed with the file type ".BAK" (by default).
Some other file type
may be specified;
the macro keyword is, naturally enough, FILE TYPE.
In either case, all fields of the two lOBs involved in the operation
are
reinitialized -- set to zeros or other initial value -- following
the backup procedure.

3-14

Input/Output Facilities
I/O RELATED MACROS
In order to do any further processing through these lOBs, they must be
reopened
as
if they had
just been initialized (see $XPO_IOB_INIT,
Section 3.4.1).

3.3.3

Input/Output Macros

Examples of the $XPO GET and $XPO PUT macro calls follow.
Note that
the
particular lOB names used have no special significance other than
to suggest or reflect some contextual
aspect of the example.
A
typical
call
for
input from an
interactive terminal, including a
prompt message, would look like:
$XPO GET

lOB = user terminal ,
PROMPT = 'INPUT FILE NAME:

) ;

Th i s call res u 1 ts i n a
' pr om pt ed
rea d '
0 pe rat ion;
t hat
is,
the
specified
prompt string is written to the terminal opened through the
lOB named user terminal, and then the terminal
is placed
in input
status
(without intervening carriage/cursor movement).
The same call
without the prompt parameter results in a simple read operation.
The
length and location of the input string read from the terminal are
available
in the
IOB$T STRING sub-block of the
lOB,
the
input
character-string descriptor, described further in Section 3.4.2.
A call to read a logical record from a file opened
file-processing attribute is simply the following:
$XPO_GET

( lOB

= input_file )

with

the

RECORD

;

Again, the length and location of the record read from
the
file are
available
in the descriptor
IOB$T STRING.
The pertinent fields of
this
sub-block are
IOB$H STRING,
which contains the number
of
characters in the record (in binary), and IOB$A_STRING, which contains
a pointer to the record.
A call to read a stream of characters from a
file
STREAM attribute is not much more complicated:
$XPO GET

opened

with

the

lOB = stream file ,
CHARACTERS :-SO )

The result of this call is to read the next SO characters of data,
including
any terminal-control-character
(TCC)
sequences, from the
indicated file (assuming that many characters are left in the
file).
The number-of-characters value can, of course, be any BLISS primary
expression, as well as a numeric literal as shown.
As before,
the
string that is read in is described by the IOB$T STRING descriptor.

3-15

Input/Output Facilities
I/O RELATED MACROS
A call to read a given number of ful~words of data from a file
with the BINARY attribute is as follows:
$XPO GET

opened

IOB = binary file ,
FULLWORDS = :how much

This call results in reading the requested number of fullwords,
i.e.,
BLISS values, from the indicated file.
The data is read into an XPORT
internal buffer;
the size and location of the data read are available
in
the
IOB descriptor IOB$T DATA, the pertinent fields of which are
IOB$H UNITS (size in addressable-units)
and
IOB$A DATA
(address of
first- data element).
The field immediately following the IOB$T DATA
descriptor, and closely associated with it, is IOB$H FULLWORDS, which
contains the datum size in fullwords.
A PUT call to write a character string to a terminal is as follows:
$XPO PUT

IOB
user terminal ,
STRING = 'Beginnin~ 3rd-phase processing.'

)

Note that,
if
the user terminal
IOB were opened with no
fileprocessing
attribute
(presumed
to be the case here), RECORD mode is
assumed.
XPORT automatically provides carriage/cursor control,
i.e.,
appropriate TCC sequences, for RECORD-mode operations.
Effectively,
XPORT appends a carriage-return/line-feed sequence to each string
(logical
record)
written.
Thus the user need not supply control
characters for anything
other than special cases
(e.g., multiple
spacing and formfeeds).
A call to write a logical record or stream of characters to a file (in
RECORD or STREAM mode respectively) might look like this:
$XPO PUT

IOB = output file ,
STRING = ( .out rec size, .out_rec_ptr

$XPO PUT

IOB = output file ,
STRING = out-rec descr

The first version directly specifies a string-length and
stringpointer value, which together identify the data to be written.
The
second version specifies the address of an XPORT string descriptor
(discussed in Chapter 6), which in turn contains the needed length and
pointer values, as well as other information.

3-16

Input/Output Facilities
I/O RELATED MACROS
A call to write a logical record to a sequenced (SOS format)
as follows:
$XPO PUT

file

lOB = sequenced file ,
STRING = out rec descr ,
SEQUENCE_NUMBER -;; .current_line)

An alternative version of the sequence-number parameter is
SEQUENCE NUMBER

= .sequenced_file[IOB$G_SEQ_NUMB] + 1

A simple method of making output sequence numbering conditional
upon
whether
the related input file is sequenced numbered, e.g., for file
copying purposes, is shown in a later section.
A call to write, say, twenty fullwords of data to a file
the BINARY attribute is as follows:
$XPO PUT
-

opened

with

( lOB = binary file ,
BINARY_DATA -;; ( 20, outbuffer, FULLWORDS ) ) ;

Observe here that an address value, rather than a pointer, is used
to
give the location of binary data, as suggested by the name "outbuffer"
used without a
fetch operator.
Also,
the
keyword
FULLWORDS
(alternative to UNITS) is shown for the sake of completeness, although
it is the default.
An alternative form of the binary-data parameter
is
BINARY DATA

= out buf descr

which specifies the address o.f an XPORT data descriptor containing the
data size and address information.

3.3.3.1

Use of Pointers vs. Addresses in Macro Calls

In all of the foregoing
examples of character-oriented operations
(those
implying
the RECORD or STREAM attribute), a data-location
subparameter is shown as a fetched value, e.g., ".out rec ptr".
This
is meant to indicate that a character-position pointer, rather than an
address, is required to identify the initial position of a character
string.
Such a
pointer
is created by the CH$PTR function, and is
manipulated by other function of the BLISS character-handling package.
String-location information returned by XPORT,
such as
in the
field
IOB$A STRING for a GET operation, is also a pointer value.
the discussion of pointers and addresses
in Section 2.2.3.1
transportability considerations.

3-1 7

lOB
See
for

Input/Output Facilities
I/O RELATED MACROS
As indicated in the final PUT example, the location of binary data
given (and returned) simply as an address value.

3.4

INPUT/OUTPUT CONTROL BLOCKS

Each file or concatenated file sequence processed by XPORT must be
described by an XPORT input/output block (lOB).
This control block,
created by means of the $XPO lOB macro,
contains the following
information by the time the file-is opened:
o

The file specifications associated with the file
the
primary file specification, a default file specification, if
any, possibly a related file specification, and the resolved
(i.e., resultant) file specification.

File attributes, such as the physical block size.

Record attributes, such as the record format (e.g.,
sequence
numbered),
the maximum record length, and -- after an I/O
operation -- the current record length and address and
the
sequence number, if any, of the current record.

File status information that indicates whether the file
open or closed, whether it has ever been opened, etc.

Internal information such as the current function code,
the
completion code of the last operation, and length of the lOB.

It is important to understand that the information in an lOB reflects
the current state of processing of a file rather than the state of the
file itself. This distinction is significant when two open lOBs refer
to
the same file.
For example, if the same file is opened for input
using
two
lOBs,
input operations
on
the
two
lOBs
proceed
independently, just as if two different files were being read.

3.4.1

Creating and Initializing lOBs

An lOB is created by use of the $XPO lOB macro as an attribute in a
data declaration, e.g., in an OWN or-LOCAL declaration.
If created in
permanent storage, the lOB is automatically initialized.
For example:
grundoon:

$XPO_IOB()

;

(Currently the $XPO lOB macro does not take any parameters.)
The
effect of this de~laration is to declare the data segment "grundoon"
as a block structure of appropriate size, and to associate a set of
field names with that structure.

3-18

Input/Output Facilities
INPUT/OUTPUT CONTROL BLOCKS
The effect is just as if an appropriate structure- and field-attribute
had
been used
in the data declaration.
The field names associated
with the lOB, of the form IOB$x abc, identify the various sub-blocks
and individual fields of the structure.
In this example
(permanent-storage allocation),
the
lOB
is also
initialized by the $XPO lOB macro to a "new lOB" state.
That is, the
many fields of the OWN data segment allocated for the lOB are
preset,
mostly
to
zero values.
This automatic
initialization is also
performed for lOBs allocated in GLOBAL storage.
If an lOB is created in either temporary
(e.g.,
LOCAL)
storage or
dynamically-acquired
storage,
however,
it
must be explicitly
initialized by means of the $XPO_IOB_INIT macro before it is used,
This macro results in
that is,
before any other reference to it.
lOB.
executable code that dynamically initializes all fields of the
For example:
LOCAL
temp_iob
$XPO lOB INIT ( lOB = temp iob )
$XPO-OPEN (lOB
temp_iob- FILE SPEC

. .. ,... )

This macro also accepts most OPEN, GET, PUT, CLOSE, DELETE, and RENAME
parameters, for optional 'presetting' of lOBs as described above for
the $XPO lOB macro.

3.4.2

Using lOB Fields and Values

An lOB is used (1) to pass information from the user program to an
XPORT
I/O routine and (2) to return information to the program upon
completion of the I/O operation.
As previously stated, when an lOB is allocated
a set of predefined
BLISS field-names
is
implicitly associated with
it.
Appendix B
describes the format of the lOB and each of the lOB fields, plus some
related literal values that may be of interest.
You have already seen
several lOB field names, however, in preceding macro examples.
These
field
names can, of course,
be
used
in ordinary BLISS structure
references.
(Similarly, the lOB-related literal names can be used
in
other types of BLISS expressions.)

3-19

Input/Output Facilities
INPUT/OUTPUT CONTROL BLOCKS
For example, consider the use of the field name IOB$H STRING
in the
following
program fragment.
The
IOB$H_STRING field
contains the
length of the character string last read by a GET operation:
OWN
g rundoon:
$XPO lOB () ,
pogo:
$XPO_IOB();

$XPO_GET( lOB

= grundoon );

Test for a non-null input string.
IF .grundoon[IOB$H STRING] NEQ 0
THEN
BEGIN
(filled in below)
END;
The I/O macros provide keyword parameters that set up appropriate
lOB
fields before calling
the
I/O function.
One related group of such
fields is the output-string descriptor IOB$T OUTPUT.
This descriptor
contains the fields IOB$H OUTPUT (length) and IOB$A OUTPUT (pointer),
which are set up by the STRING parameter of $XPO_PUT~
As shown in previous examples,
the STRING parameter takes several
forms of string description,
one being
simply the address of a
descriptor.
Thus one descriptor, i.e., set of fields, can be set up
by means of the contents of another.
IOB$T STRING is another such
descriptor, comprising
the subfields
IOB$H STRING
(length)
and
IOB$A STRING
(pointer),
among
others.
This is the
input-string
descrTptor set by $XPO GET.
Different forms of reference to these two
sets of fields are shown and discussed below.
(Standard string and data descriptors can also be created by the user;
see $STR_DESCRIPTOR and $STR_DESC_INIT in Chapter 6.)
In the following sample code, the data read from the "grundoon"
input
file
(see above)
is written twice to the "pogo" output file, first
using explicit BLISS expressions to set up the pertinent
lOB fields,
then using
keyword
parameters in the $XPO PUT macro call to do the
same thing.
(The second setup of the
lOB 1S actually unnecessary
since
the
relevant
lOB
fields are not modified by the first write
ope rat ion. )

3-20

Input/Output Facilities
INPUT/OUTPUT CONTROL BLOCKS
BEGIN
pogo[IOB$A OUTPUT] = .grundoon[IOB$A STRING] ;
pogo[IOB$H-OUTPUT] = .grundoon[IOB$H-STRING] ;
pogo[IOB$H-PAGE NUMB] = .grundoon[IOB$H PAGE NUMB]
pogo[IOB$G-SEQ NUMB]
.grundoon[IOB$G SEQ NUMB]
$XPO_PUT( lOB ~ pogo) ;
$XPO_PUT{ lOB = pogo,
STRING = grundoon[IOB$T STRING] ,
PAGE NUMBER = .grundoonTIOB$H PAGE NUMB] ,
SEQUENCE_NUMBER
.grundoon[IOB$G_SEQ_NUMB]
END ;
Note that when used as a STRING parameter value
(second
PUT call),
just the address of the input-string descriptor is sufficient to set
up the subfields of the output descriptor in the "pogo"
lOB.
When
direct structure references are used, however, the individual subfield
values themselves must be fetched
and stored.
(The expression
.grundoon[IOB$T STRING] is not valid, since this field name represents
only the beginning of a multifield sub-block of the lOB;
see Section
2.2.3, under $SUB_BLOCK.)
Clearly, implicit referencing of lOB fields via keyword parameters is
the more economical method, when information is to be stored in the
lOB.
When information has to be retrieved, however
(an input-string
description,
for
instance), explicit structure references must be
used.
As a final example of much that has been discussed up to
this point,
consider
the following
simple but realistic file-copy loop.
This
example includes a "preview" of the use of completion codes, discussed
further
in Section 3.7.
The details of file-specification handling
are omitted, since these are quite application dependent.
OWN
input file : $XPO lOB () ,
output_file: $XPO IOB() ;
$XPO lOB INIT (lOB
$XPO=IOB=INIT( lOB

input file)

= output_file)

;
;

$XPO_OPEN( lOB = input file,
F I LE_ S PE C =- • •• ) ;
Make output file SEQUENCED only if the input file is.
output_file[IOB$V_SEQUENCED]

• input_file [IOB$V_SEQUENCED]

3-21

Input/Output Facilities
INPUT/OUTPUT CONTROL BLOCKS
$XPO_OPEN( lOB = output file,
FILE SPEC = : •• ,
OPTIONS = OUT PUT ) ;
WHILE $XPO GET( lOB = input file) DO
$XPO_PUT( lOB = output f i l e ,
STRING = input file(IOB$T STRING] ,
PAGE NUMBER = :input file[IOB$H PAGE NUMB] ,
SEQUENCE_NUMBER = • input_file (IOB$G_SEQ_NUMB]
$XPO CLOSE ( lOB
$XPO=CLOSE ( lOB

in pu t f i 1 e ) ;
output_file) ;

Since one cannot conditionalize the SEQUENCED attribute keyword within
the OPEN call, the relevant lOB field, IOB$V SEQUENCED, is set outside
the call with the value of the same field in-the input lOB, after the
latter has been opened.
This makes output-file record sequencing
conditional upon the
input file
format,
in a handy,
'automatic'
fashion.
The DO loop controlling the GET and PUT operations depends upon the
fact
that all XPORT routines return a completion code that can be
tested for 'true', successful completion, or
for
'false',
failure,
with a standard low-bit test.
Input end-of-file is considered a
failure, but not an error,
condition.
(This distinction becomes
important when default failure-action
routines are described
in
Section 3.8.)

3.5

STANDARD I/O DEVICES

All operating systems support the concept of default, or standard,
input and output devices (e.g., the user's terminal, the system-output
line printer).
However, the way in which these standard devices are
named varies from system to system (e.g., TTY:, TI:, SYS$INPUT).
The
XPORT I/O facility provides four macros which represent the names of
these standard devices.
$XPO INPUT - standard input device
$XPO-OUTPUT - standard output device
$XPO-ERROR - standard error message device
$XPO=TEMPORARY - a unique temporary work file
Note that using a standard XPORT device does not eliminate the need to
open the file;
i.e., all files except concatenated input files must
be ex pI i cit 1 Y 0 pe n ed .

3-22

Input/Output Facilities
STANDARD I/O DEVICES
The use of $XPO TEMPORARY results in a uniquely named disk file having
a
file type Tor extension)
that
indicates it is temporary, e.g.,
".TMP".
(Some target file systems delete these
files at end of
session.)

3.6

FILE SPECIFICATION PROCESSING

File specification processing
services provided by XPORT:

commonly

includes

the

use

two

File-specification resolution, performed during open, delete,
and rename operations, and

File-specification parsing, provided via the
macro.

$XPO_PARSE_SPEC

This section discusses the reasons for, and use of, these services.

3.6.1

File Specification Resolution

Applications that process files are usually written so
that the end
user
can in some way specify the names of the files to be read,
written, renamed, etc.
In order to make such an application easier to
use by allowing
the user to give partial (or null) specifications,
defaults
for
certain file-specification components are generally
provided.
XPORT supports a defaulting technique that provides the
most frequently required capabilities.
A complete file specification consists of a
network node name,
a
device
name,
a directory name or project/programmer number, a file
name, a file type
(or extension),
and
sometimes a
file version.
During
file opening,
renaming, or deletion,
the XPORT facility,
working in conjunction with the host file
system,
automatically
constructs a complete file specification, using information contained
in the lOB and information provided by the host system.
It does this
by selecting the necessary components from the following sources:
1.

The primary file specification string,
usually provided by
the end
user;
described
in the
lOB.
This string might
consist only of a file name, or might even be null.

2•

A de f a u 1 t
f i 1 e s p e c i f i c at ion
( t yp i c all y a
f i 1e
provided by the program;
described in the lOB.

3-23

type) ,

Input/Output Facilities
FILE SPECIFICATION PROCESSING
3.

A related file specification (normally used only for
output
files), provided by the program;
described in the lOB.

System and user defaults (node, device, directory,
version) supplied by the host file system.

and

file

Generally speaking, default components are taken from these sources in
the order listed,
although the
rules for
selection of certain
components from
the
related
file specification are a bit more
complicated (see below) •
Input file specifications
are
typically
constructed
from
a
user-specified
file name,
a default file type, and system defaults.
Likewise, output file specifications are frequently constructed from a
related
file name (taken from the resultant file specification of an
associated input file), a default file type, and system defaults.
The program controls the resolution process essentially by using
the
primary,
default,
and
related
file-specification parameters of the
file-level macros in a way that, according with the selection rules
given below, achieves the desired effect.

3.6.1.1

Rules for File Specification Resolution

Although there are minor differences from system to system, all
current target systems support a subset or variant of the following
file-specification format:
node::device:<directory>filename.filetype.version
When a file is to be opened, renamed, or deleted,
a
resultant file
specification is constructed by selecting
tokens from
the file
specification(s) described
in the
lOB and
from
system defaults,
according
to the rules summarized in Table 3.1.
If a token exists in
more than one source for a given
file~specification
component,
the
first occurring
token is used.
"First occurrence" is determined by
traversing the decision table from top to bottom
in accordance with
the selection rules.

3-24

Input/Output Facilities
FILE SPECIFICATION PROCESSING
Table 3.1
File-Specification Resolution Semantics
+--------------------------------------------------------------------+

I
I
I

DECISION TABLE

I
I
I

+--------------------------------------------------------------------+
I
I
I node device I directoryl fil e I fil e I file
So urce
name
I
I name
I spec
I namel type lversion I
+--------------------- ------ ----------------------- ---------------+
X
X
X
X
X
X
I Primary file-spec
I
(X)
(X)
(X)
(X)
X
X
I Default file-spec
I
I Related file-spec
I
Open for input
X
X
X
X
X
I
I
Open for output
U
U
U
I
I
Delete
X
X
X
X
X
I
I
Rename - old name
X
X
X
X
X
I
I
Rename - new name
U
U
I
I
u'
I System/user defaults
I
Open for input
A
A
A
H
I
I
Open for output
A
A
A
I
I H+l
H
Rename
A
A
A
I
I
H
Delete
A
A
A
I
I
+--------------------------------------------------------------------+
TOKEN SELECTION RULES
A token can be an actual file-specification component or an
or an asterisk (*).
X
This token is always used if it exists.
(X)
This token is seldom specified but is used if it exists
U
This token is used if the corresponding primary or default,
token is an asterisk (*) or missing.
U'
This token is used only if the corresponding primary or
default token is an asterisk (*).
A
This token is always defined and is used if necessary.
H
Highest existing version is used.
H+l
Highest existing version plus 1 is used.
Not used.
+--------------------------------------------------------------------+

3-25

Input/Output Facilities
FILE SPECIFICATION PROCESSING
3.6.2

File Specification Parsing

XPORT provides file-specification parsing, i.e.,
the division of a
file specification into
its component parts together with a syntax
check,
v ia
the
$XPO _PARSE _S PEC
macro.
In
order
to
use
$XPO PARSE SPEC,
you must also use the macro $XPO SPEC BLOCK.
This
supporting-macro, used as an attribute of a data declaratTon, creates
a file specification block whose address
is a parameter of the
$XPO PARSE SPEC macro along with a file-spec-string description.
(The
format of a file specification block is given in Appendix B.)
A $XPO_PARSE_SPEC call might look as follows:
$XPO_PARSE_SPEC( FILE SPEC = input file[IOB$T RESULTANT]
SPEC-BLOCK = input_fs_block f ;

This example assumes that a file specification was previously resolved
in the input file lOB, and that the $XPO SPEC BLOCK macro was used to
allocate the data segment input_fs_block.
The $XPO PARSE SPEC macro essentially does two
things.
Firstly,
it
checks all non-null components of the indicated file-specification
string for valid syntax (for the host system) and, secondly, it places
those components
in the appropriate fields of the specified filespecification block, together with an indication of a
'wild card'
character
(*)
as one of the components.
(The asterisk is the only
character recognized by XPORT as a
'wild card'
character and must
appear by itself,
i.e., must represent an entire file-specification
component.) If one or more of the components is syntactically invalid,
the macro returns an error completion code that identifies the faulty
component (the first one encountered if more than one) •
The $XPO PARSE SPEC macro accepts resolved or
unresolved
file
specifications, and
recognizes null and
'wild card' components as
valid along with actual components.
The components described by the
file specification block include the attendant punctuation characters,
e.g., angle brackets or square brackets in the case of a directory,
UIC, or PPN component.
TRANSPORTABILITY WARNING
It must be observed here that, as with a
few other XPORT
features,
use of the file-specification parsing feature is
not likely to result in a fully transportable program unless
it
is
used with a considerable amount of care and
forethought.

3-26

Input/Output Facilities
FILE SPECIFICATION PROCESSING
This is so not only because of the system-dependent aspects
of the file-specification
format, e.g., the "punctuation"
characters, but also because of the substantive differences
that
exist
from
system to
system,
for
example the
conventional file type ".LST"
employed on some systems
versus ".LIS" on others, both used for the same purpose.
The file specification block contains, along with descriptors for each
of the components, a set of bits which indicate, individually:
directory-name

Whether a
specified,

Whether or not a 'wild card' occurred anywhere
specification, and

Which component(s)
any.

consist of a

PPN/UIC

'wild

card'

component
in

the

character,

was
file
if

PPN/UIC component values are contained within the file specification
block
(as binary integers);
all other components are described by
standard XPORT string descriptor
sub-blocks
within
the
file
specification block.

3.7

I/O COMPLETION CODES

The BLISS value of a macro that calls an XPORT I/O routine
is the
completion code returned by that routine.
Note that in most cases
there are several failure completion codes for a given routine and, in
some cases, more than one success completion code.
The completion code of an XPORT routine can simply be tested
for
success/failure status (i.e., standard BLISS low-bit test), or can be
compared with expected values for more detailed
testing.
XPORT
provides a complete,
transportable set of completion-code literals
(described with each macro call in App~ndix A)
expressly for
this
purpose.
Thus the programmer need
not be aware of the actual
(possibly system-dependent) numeric completion-code value in any case.
The
'unqualified
success'
completion code literal,
indicating
successful completion with no exception condition, is XPO$_NORMAL.
Note that a warning code, as is returned
for
input end-of-file,
is
considered
a
failure completion code, and as such invokes a failureaction routine.
The default failure-action routine, however, treats a
warning
code differently than failure codes having an error or fatal
severity.
In addition to a primary completion code being returned as the value
of the routine call, this completion code is also returned in the rOB
field IOB$G - COMP- CODE.
3-27

Input/Output Facilities
I/O COMPLETION CODES
Some completion codes
(e.g.,
XPO$ BAD lOB)
have
an
secondary
completion code which 1s returned
in the
10B$G 2ND CODE.
This secondary completion code field
is
XPORT-upon return from a call if it is not used.

3.8

associated
lOB field
zeroed by

I/O ACTION ROUTINES

Each macro that results in a call to an XPORT I/O routine allows
the
programmer to specify the address of another routine to be called upon
completion of the requested
function.
Separate routines can be
specified for successful and abnormal completion.
As seen previously,
the macro parameter keywords are SUCCESS and
FAILURE respectively.
These optional
user-provided
routines, called action routines, are
typically used to intercept and possibly correct error conditions.
An action routine must be declared in each XPORT routine call to which
it applies;
that is, action-routine addresses cannot be preset in the
lOB as can most other I/O parameters.
(No corresponding
lOB fields
exist,
in fact.)
Such presetting would in any case tend to obscure
control flow within the program.
A success or failure action routine, if any, is called by XPORT just
before returning
to
the caller of the I/O operation.
The action
routine is passed, as one of its calling parameters,
the address of
the
lOB specified
in the original call.
The action routine may
examine and/or change lOB fields and may perform any appropriate
I/O
operation using the passed lOB or another lOB.
For example, a failed
operation could be retried after possible lOB modification.
The
action routine may modify the completion code returned to the caller.
A listing of the default I/O failure-action routine provided by XPORT,
XPO$FAILURE,
appears in Appendix E.
This routine is the default for
the FAILURE parameter in I/O macro calls.
It issues a multiple-line
error message and
then terminates program execution for all I/O
failures except input end-of-file.
(The input-EOF condition has only
a 'warning' severity.)
An optional I/O failure-action routine, XPO$10 FAILURE, is provided to
allow standard XPORT error message processing without terminating
program execution.
Instead, control -- and
the
initial completion
code -- is returned to the caller.
(This routine is itself called by
XPO$FAILURE and is included in the same module;
see Appendix
E.)
There
is no default success-action routine;
such routines are rarely
used.
See Appendix E for information about writing action routines.

3-28

CHAPTER 4
4.1

4.2
4.3
4.3. 1

4.3.2
4.3.3
4.4
4.5

MEMORY MANAGEMENT FACILITIES
INTRODUCTION • • • • • • • • • • • • • • • • • ·
CAPABILITIES • • • • • • • • • • • • .
MEMORY MANAGEMENT MACROS • • • • . •
·
$XPO GET MEM - Allocating Dynamic Memory •
$XPO-FREE MEM - Releasing Dynamic Memory
Dynamic Memory Elements
•••. . •••
•
COMPLETION CODES • • • • • •
ACTION ROUTINES
• • • • •
•

• 4-1
4-1

. 4-2
· 4-2
·
•
•
•

4-3
4-4
4-4
4-4

CHAPTER 4
MEMORY MANAGEMENT FACILITIES

This chapter describes the memory-management portion of the XPORT
Programming Tools Facility.
The description given here is intended to
present concepts rather than give complete details
in all cases.
Appendix A contains complete, detailed descriptions of all XPORT macro
calls in a form designed for concise reference.

4.1

INTRODUCTION

The XPORT memory management facilities provide the ability to acquire
and
release memory space during program execution, as the program's
needs expand and contract, in a simple and fully transportable manner.
Dynamically acquired main-storage space, often referred to simply as
"dynamic memory", is typically used
for data buffers and control
blocks.
used
in
Dynamic and dynamic-bounded string/data descriptors may be
they are described
conjunction with the memory management facilities;
in Chapters 6 and 7.

4.2

CAPABILITIES

XPORT currently provides
management functions:

the

following

system-independent

Allocation of a specified amount of dynamic memory

Release of a dynamically-allocated memory element.

memory

The size of a dynamically allocated element of memory can be specified
in terms of characters, fullwords, or addressable units, though use of
the latter will probably limit program transportability.

4-1

Memory Management Facilities
MEMORY MANAGEMENT MACROS
4.3

MEMORY MANAGEMENT MACROS

Dynamic memory allocation and release is requested by means of the
$XPO GET MEM and $XPO FREE MEM macros respectively.
Both result in a
call-to an XPORT MEMORY function.

4.3.1

$XPO_GET_MEM - Allocating Dynamic Memory

The get-memory function stores a character-position pointer or address
value
into a
user-specified
location
(or descriptor field) if the
requested allocation is successful.
Typical usage examples are given
below.
The following code fragment illustrates the
character-string buffer:

acquisition

large

OWN
bigbuff ptr

$XPO_GET_MEM( CHARACTERS = 1028,
RESULT = bigbuff ptr,
FILL = %C' • ) ;Upon successful execution of the get-memory call,
a memory element
large enough to contain 1028 character positions is allocated, and a
pointer
to
the
first character position
is stored
in location
bigbuff ptr.
The optional
FILL parameter causes the element to be
initially blank-filled (any ASCII character code may be specified).
Note
that the standard BLISS character size is assumed for all target
systems, i.e., 8-bit characters in the 16/32-bit envirionments and
7-bit characters in the 36-bit envirionments.
Alternatively, a dynamic or dynamic-bounded descriptor can be used
in
conjunction with the $XPO GET MEM macro to achieve the same result, as
shown in the following code fragment:
LOCAL
bigbuff_desc

$STR DESCRIPTOR ( CLASS

$STR DESC INIT( DESCRIPTOR = bigbuff desc,
CLASS = DYNAMIC);
$XPO GET_MEM( CHARACTERS
DESCRIPTOR
FILL = %C'

1028,
bigbuff desc,
);
-

4-2

DYNAMIC );

Memory Management Facilities
MEMORY MANAGEMENT MACROS
In this case, on the successful completion of the get-memory function,
the
string descriptor
is updated
to describe the allocated memory
element (See Section 6.1 for a discussion of descriptor usage.)
To illustrate acquisition of dynamic memory in terms of fullwords,
assume that you want to get space in which to construct a 'dynamic'
lOB -- for reading
a REQUIRE-type
file,
for
example.
The XPORT
literal
IOB$K LENGTH defines the length
(in BLISS values)
of a
standard lOB structure.
The
following declaration and macro call
would be appropriate:
LOCAL
dynamic iob

REF $XPO IOB()

$XPO_GET_MEM( FULLWORDS = IOB$K LENGTH,
RESULT = dynamic_lob ) ;
Upon successful allocation, the location dynamic_iob will contain
address of the requested memory element.

the

the default
Note that for each of the macro calls shown above,
failure-action
routine XPO$FAILURE is assumed, in lieu of a FAILURE=
parameter.

4.3.2

$XPO_FREE_MEM - Releasing Dynamic Memory

In order to release the memory elements acquired
in the
first and
third examples above, the following $XPO FREE MEM calls would be used:
$XPO_FREE_MEM( STRING = ( 1028, .bigbuff_ptr ) ) ;
$XPO_FREE_MEM( BINARY_DATA = ( IOB$K_LENGTH,

.dynamic_iob ) )

For either
a string or
binary-data element,
if
the element is
described
by an XPORT descriptor at the time of its release, only the
descriptor address need be specified, as in the following example:
bigbuff_desc )
Optionally, a FILL parameter may be used in any form of $XPO FREE MEM
call
to
request memory clearing at release time.
Also, FAILURE-and
SUCCESS action-routine parameters may be specified
in either
the
$XPO_GET MEM or $XPO_FREE_MEM macros, as described in Section 4.5.

4-3

Memory Management Facilities
MEMORY MANAGEMENT MACROS
4.3.3

Dynamic Memory Elements

The $XPO GET MEM and $XPO FREE MEM macros result in alLocation or
release of space in multiples of fullwords, regardless of the terms in
which the element is described.
(Any necessary "rounding up" is done
by both functions, and thus can be ignored by the user.)
Dynamically acquired memory must be released in entire elements;
that
is, you may not release a portion of an allocated element.
The result
of
releasing
a
partial
element on any given target system
is
undefined.

4.4

COMPLETION CODES

The $XPO GET MEM and $XPO FREE MEM macros generate a call to an XPORT
memory management routine that returns a value via the standard BLISS
routine-value mechanism.
Like the XPORT I/O routines, the get-memory
and
free-memory routines return a success or failure completion code
as their routine value, as well as passing that code to any action
routine called by the operation.
(For the memory functions, however,
there is no analogue of the lOB in which the completion code can be
stored.)
As with all other XPORT completion codes,
the memory-management
completion codes can be tested for simple success or failure status
with a low-bit test (set for
success, cleared
for
failure).
The
specific failure completion codes are given, in terms of transportable
XPORT literals, in Appendix A as part of the description of the
respective macros.

4.5

ACTION ROUTINES

The XPORT memory-management macros allow the programmer to specify the
address of a routine to be called at the completion of the requested
function.
Separate routines can be specified
for
successful
and
abnormal
completion.
These optional user-provided routines, called
action routines, are typically used to intercept and possibly correct
error conditions.
A success or failure action routine, if any,
is called
just before
returning
to
the caller of the
requested operation.
The action
routine is passed an XPORT function code
in this case a code
identifying
the specific memory-management function (XPO$K GET MEM or
XPO$K FREE MEM), the completion code of the current operation, -and
a
functIon-specific
parameter:
the address of the XPORT descriptor
associated with the particular request.
4-4

Memory Management Facilities
ACTION ROUTINES
An understanding of the usage of these parameters is best gained
from
inspection of an actual
action
routine.
A listing of the default
XPORT failure action routine,
XPO$FAILURE,
appears
in Appendix
E.
(The memory-management specific
routines called by XPO$FAILURE are
XPO$GM FAILURE and XPO$FM FAILURE, which appear in the same module.)
This ~outine
is assumed-if no FAILURE parameter is specified in your
$XPO GET MEM or $XPO FREE MEM call.
This
routine
issues an error
message for all memory-management failures.
Program execution is then
terminated.
Optionally, the failure action
routine XPO$GM FAILURE
(for a getmemory failure)
or XPO$FM FAILURE (for a free=memory failure) can be
specified directly (in your-macro call) to allow standard XPORT error
reporting
without terminating program execution.
Instead, control is
returned to the caller.
See Appendix E for information about writing
action routines.

4-5

CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.3

OTHER SYSTEM SERVICES
INTRODUCTION .
$XPO PUT MSG

• • •
• • • •

Completion Codes •
Action Ro uti nes
$XPO TERMINATE

·
• •
•
•

•
•
•
•
•

5-1
5-1
5-2
5-3
5-3

CHAPTER 5
OTHER SYSTEM SERVICES

This chapter describes the "miscellaneous services"
portion of the
XPORT
Programming Tools Facility.
The description given here is
intended to present concepts rather than give complete details in all
cases.
Appendix A contains complete, detailed descriptions of all
XPORT macro calls in a form designed for concise reference.

5.1

INTRODUCTION

The services in the "miscellaneous" category perform commonly needed,
but not necessarily related, functions such as error/exception message
generation, and orderly program termination.
The services
are
provided
in a
simple and uniform manner across all target operating
systems.
It is expected that this collection of services will grow with time as
the need for additional transportable functions is perceived.

5.2

$XPO PUT MSG
-

The $XPO PUT MSG macro allows you to issue single-line or multipleline messages without naming or having opened an output device.
A
standard message text is automatically generated
for
any completion
codes specified in the call.
Required 'input' to the macro
is either a
completion code
(CODE
parameter),
e.g.,
one
returned by another XPORT operation, or a
message-string description
(STRING parameter).
Each
of
these
parameters represents a single "line" of the message, and either can
be given any number of times in one call, in any combination.
Thus,
"mixed"
multi-line messages can be produced.
Consider the following
example:

5-1

Other System Services
$XPO_PUT_MSG
$XPO PUT MSG(CODE = XPO$ END FILE,
STRING = 'No End-of-Data Sentinel Encountered'
The message that would be produced for this call
example, would look as follows:

under

);

TOPS-IO,

for

? end-of-file has been reached

No End-of-Data Sentinel Encountered
Another possible input to
the macro
is a severity-level
keyword
(SEVERITY parameter).
The
range of severity levels is SUCCESS,
WARNING, ERROR, and FATAL.
If nn SEVERITY parameter
is given,
the
severity level defaults to the severity associated with the condition
code specified, if the first parameter is CODE, Qr to
ERROR if
the
first parameter is STRING.
To illustrate, the severity level associated with the XPO$ END FILE
code
is only WARNING.
One might,
for example, want to raise the
severity level of the sample message given above, as follows:
$XPO PUT MSG(CODE = XPO$ END FILE,
SEVERITY = ERROR ,
STRING = 'No End-of-Data Sentinel Encountered'

);

The destination device(s) are automatically determined by the severity
level, assuming
that differing assignments for the standard output
devices ($XPO OUTPUT and $XPO ERROR) are in effect for a given program
application. - All messages -are sent to the standard output device
($XPO OUTPUT), whatever
their severity level.
Messages having a
sever Tty level other than SUCCESS are also sent to the standard errorlogging device ($XPO_ERROR).
Furthermore, issuance of a message sequence with an implied or
explicit FATAL severity level causes automatic program termination,
immediately following the message processing.
The standard XPORT messages are listed in Appendix C.

5-2

Other System Services
$XPO PUT MSG
5.2.1

Completion Codes

The put-message operation returns a completion code both directly
(i.e.,
by routine value)
and
to any action routine called by the
operation (see below).
Just as for I/O and message-management return
values,
the completion code can be tested for success/failure status
with a simple low-bit test, or can be compared with completion code
literals for more detailed
testing.
Specific completion codes are
given in Appendix A together with the macro description.
Depending upon the target system, an $XPO PUT MSG call may implicitly
invoke $XPO PUT to
perform message 170. - In this case, a failure
completion c~de returned by the latter
is "passed back"
as
the
completion code of $XPO PUT MSG.
Any detailed error testing must take
this into account.
--

5.2.2

Action Routines

Optionally, success and failure action routines may be specified for a
put-message operation,
just as for I/O and message-management macro
calls (see Chapter 3 or 4).
XPORT provides the default failure-action
routine XPO$FAILURE,
which issues a message (if possible) for any
message processing failure and terminates program execution.
Alternatively,
you
may
specify
the
failure-action
routine
XPO$PM FAILURE
(itself called by XPO$ FAILURE), which returns control
to
the call
site after
issuing
a- message unless the
failure
completion-code severity is FATAL.
See Appendix E for a listing of the default failure-action
and for information about writing action routines.

5.3

routines

$XPO TERMINATE

The $XPO TERMINATE macro causes program termination
immediately
following- the issuance of a termination message to the end user.
In
its simpler form, e.g.:
$XPO_TERMINATE()

;

the assumed program-termination code is XPO$ TERMINATE.
The message
text for this code is "program terminated du~ to program request".

5-3

Other System Services
$XPO TERMINATE
You can, however, specify a program-termination code with
the form:
$XPO_TERMINATE( CODE

call

= completion-code)

The standard XPORT message text for
the completion
instead of the standard termination message.

code

Completion codes
Appendix C.

are

listed

and

corresponding

5-4

message

texts

issued

CHAPTER 6
6.1

STRING HANDLING FACILITIES

STRING DESCRIPTORS •
• • • • • • • • • • • • 6-1
$STR DESCRIPTOR -- Creating a String Descriptor 6-2
6.1.2
$STR-DESCRIPTOR -- Compile-Time Descriptor
InitTalization
• • • • • • • • • • • • • • . 6-2
6.1.3
$STR DESC INIT -- Run-Time String Descriptor
Initraliz~tion • • • • • • • . .
• • • 6-3
6.1.4
String Descriptor Formats . • • • . • • • • • • 6-4
6.1.5
String Descriptor Usage Rules • . • • • • • • . 6-6
6.1.6
Descriptor Data Types
• • • . • • • • •
. 6-8
6.1.6.1
Character String Data Type (STR$K DTYPE T)
6-8
6.1.6.2
Binary Data Type (STR$K DTYPE Z):
•• 6-9
6.2
STRING DESCRIPTOR STRUCTURE-REFERENCES • • • • . • 6-9
6.3
STRING MODIFICATION
. • • • .
• 6-9
6.3. 1
$STR COPY Operation
. . • • • •
6-10
6.3.2
$STR-APPEND Operation
• • • • • • • •
6-11
6.4
STRING-COMPARISON
• • • • . • • • .
6-12
6.5
STRING SCANNING . • . • . • • • • • . . • • . • 6-14
6.5.1
$STR SCAN Overview • • . • • • • • • . . •
6-14
$STR-SCAN FIND - Find a Character Sequence
6-15
6.5.2
6.5.3
$STR-SCAN SPAN - Match a Set of Characters
6-16
$STR-SCAN STOP - Search for a Set of Characters 6-16
6.5.4
$STR-SCAN - Returning a Substring
6-17
6.5.5
$STR-SCAN - "Scanning Through" a BOUNDED String 6-17
6.5.6
STRING-CONVERSION • • • • • • • • • . . • • • •
6-18
6.6
$STR CONCAT and $STR FORMAT - ASCII to ASCII
6.6. 1
String Conversions .-. • • .
• • • • •.
6-18
6.6.1.1
$STR CONCAT • • • • . • • • • • • • . • ••
6-18
$STR-FORMAT • • • • • • • • • . • . • • • •
6-19
6.6.1.2
6.6.2
$STR ASCII - Binary-Data to ASCII String
Convirsion • • • • • • • • • • . • • . • • ••
6-19
6.6.3
Nesting $STR ASCII, $STR CONCAT, $STR FORMAT
Pseudo-Functions • • . • -. • • . • • • • •
6-21
6.6.4
$STR BINARY - ASCII String to Binary-Data
Convirsion • • • • • . . • . • • • . • • •
6-22
6. 1. 1

CHAPTER 6
STRING HANDLING FACILITIES

This chapter describes tools related to the manipulation of character
strings.
See also Appendix A for reference descriptions of the macros
discussed here.

6.1

STRING DESCRIPTORS

A string descriptor is a small control structure that facilitates
the
interchange of character data between two procedures (e.g., between
two BLISS routines).
The XPORT descriptors are closely modelled on
the
VAX/VMS descriptor convention.
The XPORT I/O and memorymanagement
facilities make extensive use
of
such
descriptors
internally,
and
fully support their
use by the
programmer -- a
descriptor address is always a valid form
of string
parameter,
for
example.
Two macros are
provided
for
string-descriptor
initialization:
$STR DESCRIPTOR and $STR DESC INIT.
concerning binary-data-descriptors.)
-

creation
and
(See Chapter 7

Terminology:
The term "length"
always means "number
character positions", in the transportable-BLISS sense.

ASCII

6-1

String Handling Facilities
STRING DESCRIPTORS
The descriptor classes are:
FIXED, BOUNDED, DYNAMIC, DYNAMIC_BOUNDED,
and
undefined.
The specific
usage conventions implied by each of
these classes are described in Section 6.1.5.
It should be noted
here,
however,
that for
the purposes of reading
an item (i.e.,
fetching
via
the descriptor)
all classes of
descriptors
are
equivalent to FIXED.

6.1.1

$STR_DESCRIPTOR -- Creating a String Descriptor

A string descriptor can be created using the $STR DESCRIPTOR macro as
an attribute of a data declaration (of an OWN or LOCAL declaration,
for example).
The macro expands to an appropriate structure-attribute
and
field-attribute for the class of descriptor desired.
A class may
either be specified or may be defaulted to FIXED.
For example,
the
declaration
OWN
my_desc:
declares
a
declaration

FIXED

$STR_DESCRIPTOR();
descriptor,

LOCAL
output_string:

Al ternatively,

the

$STR_DESCRIPTOR ( CLASS = DYNAMIC);

declares a DYNAMIC string descriptor,
dynamically allocated storage.

6.1.2

default.

for

use

conjunction

with

$STR_DESCRIPTOR -- Compile-Time Descriptor Initialization

A descriptor must be initialized prior to its first use.
A descriptor
created
in permanent storage
(OWN or GLOBAL)
can be statically
initialized by means of parameters of the $STR DESCRIPTOR macro.
Several examples follow:
OWN
eo f tex t :

$STR _DESCR 1 PTOR ( S'I'R ING

composi te_string

= 'End-o f- f i 1 e reached' ),

$STR_DESCRIPTOR( CLASS = DYNAMIC,
STR ING = (0,0) );

Note that a DYNAMIC descriptor in permanent storage can be initialized
to point to 'no storage' (only) at compile time.

6-2

String Handling Facilities
STRING DESCRIPTORS
Further examples of static initialization:
OWN
message-buffer:
message:

VECTOR[ CH$ALLOCATION(132) ],

$STR DESCRIPTOR( CLASS = BOUNDED,
STRING = (132, CH$PTR(message_buffer))

NOTE:
A descriptor created in temporary (LOCAL)
or dynamic
must be dynamically initialized via the $STR DESC IN IT macro.

6.1.3

);

storage

$STR_DESC INIT -- Run-Time String Descriptor Initialization

The executable $STR DESC INIT macro dynamically initializes all fields
of a descriptor. -This-macro must be used for descriptors created in
temporary or dynamic storage.
Following are several examples of initializing
'declared' in the previous section:
$STR_DESC INIT( DESCRIPTOR

= my_desc

the

first

descriptor

);

The named descriptor is initialized as class FIXED by default, and the
string
length and
pointer fields are set to indicate a null string
value (i.e., a string of zero length).
A string value can be preset with a STRING parameter, as follows:
$STR_DESC INIT( DESCRIPTOR
my desc,
STRING = ( length-exp, pointer-exp ) );
Alternatively, a string literal may be given as the
val ue :
$STR_DESC_INIT( DESCRIPTOR = my desc,
STRING = 'Who struck John?'
The dynami6 descriptor 'declared'
initialized as follows:

in the

STRING

parameter

section

might

);

$STR DESC INIT( DESCRIPTOR = output string,
CLASS = DYNAMIC ); The named descriptor is initialized as
the descriptor of a
string
created
in dynamic memory during
a subsequent operation
(e.g.,
$XPO GET MEM, $STR COPY).
Without a STRING parameter, the length and
address fields are-set to indicate a null string value.
6-3

String Handling Facilities
STRING DESCRIPTORS
Note particularly that the class that is specified (or defaulted)
in
the $STR DESC INIT macro must match the class specified or defaulted
in the $STR DESCRIPTOR macrO:--(The CLASS= parameter may be omitted in
either
or -both macros only in the case of a FIXED descriptor.) Also,
the class of a descriptor cannot be changed "in mid-stream", that is,
without reinitialization.

6.1.4

String Descriptor Formats

All string descriptors contain the following common fields:
o

A length field, named STR$H_LENGTH,

A pointer field, named STR$A_POINTER,

A class field, named STR$B_CLASS, and

A data-type field, named STR$B_DTYPE.

In addition to these fields, BOUNDED and
also contain the following:

DYNAMIC BOUNDED

A prefix-length field, named STR$H_PFXLEN, and

A maximum-length field, named STR$H_MAXLEN.

descriptors

Figure 6.1 shows the format a FIXED or DYNAMIC descript~r;
figure 6.3
shows
the
format of a BOUNDED or DYNAMIC BOUNDED descriptor.
Note
that a
BOUNDED descriptor
is simply an- extension of a
FIXED
descriptor.
Figures 6.2 and 6.4 show the format of the strings described by
descriptors.
Figure 6.1
Format of a FIXED or DYNAMIC Descriptor

+------------------------------------------------------+
I
1
1

STR$B CLASS
-

1
1
1

STR$B DTYPE
-

I
1
1

STR$H LENGTH

1
I
1

1------------------------------------------------------I
1
1

STR$A POINTER

+------------------------------------------------------+
6-4

these

String Handling Facilities
STRING DESCRIPTORS
Figure 6.2
Format of a FIXED or DYNAMIC String
+-----------STR$A POINTER
1

+-------------------------------------------+
1

1 This is a sample FIXED or DYNAMIC string.

+-------------------------------------------+
1

1<--------------STR$H_LENGTH---------------> 1
Figure 6.3
Format of a BOUNDED or DYNAMIC_BOUNDED Descriptor
+------------------------------------------------------+
1
1
1
1
1 STR$B CLASS 1 STR$B DTYPE 1
STR$H_LENGTH
1
1
1
1
1
1------------------------------------------------------I
1

STR$A POINTER

1------------------------------------------------------I
1
1
1
1
STR$H MAXLEN
1
1
STR$H PFXLEN
1
1
1
+------------------------------------------------------+
Figure 6.4
Format of a BOUNDED or DYNAMIC_BOUNDED String
+-----------STR$A POINTER
1

+-----------------------------------------------------------+
1
1
1
1
1
1
1
1 This is a BOUNDED string.
1
1
1
1
+-----------------------------------------------------------+
1
1
1
1
I<---STR$H PFXLEN--->I<-------STR$H LENGTH------->1
1
1

1<----------------------STR$H_MAXLEN----------------------->1

6-5

String Handling Facilities
STRING DESCRIPTORS
6.1.5

String Descriptor Usage Rules

For each class of descriptor, the usage rules specify which fields may
be modified, and which fieLds may not, by a procedure that is not the
"owner" of the descriptor.
Such a procedure is typically a routine that is passed
a descriptor
address as one of its calling parameters.
Moreover, the rules only
apply where the descriptor is passed in order that the called
routine
can
either modify information already described by the descriptor or
can
return new information to
the caller via
the
descriptor.
(Obviously,
when a descriptor is used simply to pass information for
reading only, no descriptor fields need be modified by the
recipient.
All
descriptor classes are, in fact, equivalent to FIXED for purposes
of reading, i.e., fetching data via the descriptor.)
The UNDEFINED class -- which is actually sort of a 'non-class'
no rules associated with it and is for intra-program use only.

has

Table 6.1 gives the usage rules for each class of descriptor.
Table 6.1
String Descriptor Usage Rules

+----------------------------------------------------+
1
Can recipient modify descriptor field?
1
1
+---------------1-------------------------- ------------ -----------1

Descriptor
Class

Current
1 String
Prefix
Maximum
Length
1
Pointer
Length
Length
ISTR$H LENGTHISTR$A POINTER STR$H PFXLEN STR$H MAXLEN

---------------1-----=------1-----=------- ------------ -----------FIXED
1
NO
1
NO
(n.a.)
(n.a.)
---------------1------------1------------- ------------ -----------BOUNDED
YES
YES
YES
NO
---------------1------------1------------- ------------ -----------DYNAMIC
YES*
YES*
(n.a.)
(n.a.)
--------------- 1------------1------------- ------------ -----------1

DYNAM IC BOUNDED 1

YES

YES *

YES

YES *

-------=------- 1------------1------------------------ -----------UNDEFINED
1
1
NOTE:

It is always valid (with respect to these rules) to modify
content, that is, to change the data described by the descriptor, within the limits set by these rules.

+--------------------------------------------------------------------+
* Requires interaction with $XPO_FREE_MEM and $XPO_GE'I'_lVIEM.

6-6

String Handling Facilities
STRING DESCRIPTORS
The rules in Table 6.1 give
rise
to
the
following generalizations
about descriptor classes
(keep in mind that they do not necessarily
apply to the "owner" of the descriptor) :
o

A FIXED descriptor describes a
extent may not be changed.

string,

whose

location

and

This class of descriptor is typically used to pass a
string
to another
routine,
and
is seldom (almost never) used to
describe space.
o

A BOUNDED descriptor describes a
fixed-length buffer
that
contains a string of varying length.
The string may begin at
any point in the buffer and may extend
to
the end of the
buffer.
The buffer location and length may not be changed
(presumably it
is allocated
in OWN,
GLOBAL,
or
LOCAL
storage);
the
string,
however, may be moved, shortened
and/or lengthened within the limits of the
fixed-length
buffer.
This class of descriptor is typically used
to describe a
space in which to construct or update a string which, by its
nature, will not exceed a specific maximum length.
In addition to describing
a bounded string,
a
BOUNDED
descriptor
implicitly describes three additional strings the "container string", a "prefix string", and a
"remainder
string".
The container string is the entire buffer and thus
includes the bounded string.
The prefix string
is
the
portion of the container string (possibly null) that precedes
the bounded string.
The remainder string is the portion of
the container string (possibly null) that follows the bounded
string.

A DYNAMIC descriptor describes a moveable string whose length
may vary from 0 to 64K characters.
It is generally used for
a string to be returned by a called routine.
Note that this class implies the use of dynamic memory, since
the storage described
is always assumed to be releasable.
(See Chapter 4 concerning dynamic-memory facilities.)

A DYNAMIC BOUNDED descriptor describes a moveable buffer
containing
a string of varying length.
The string may begin
at any point in the buffer and may extend to the end of the
buffer.
As its name implies, this class is a generalization of both
the BOUNDED and DYNAMIC classes.
It can be used to avoid the
maximum-length restriction imposed by BOUNDED;
it can also
be used
for
a very volatile string, to avoid much of the
memory-management overhead implied by DYNAMIC (i.e.,
storage
need be reallocated only when the buffer becomes too small).

6-7

String Handling Facilities
STRING DESCRIPTORS
Note that this class also implies the use of dynamic memory,
since
the
storage described
is always assumed
to be
releasabl~.
(See Chapter
4
concerning
dynamic-memory
facilities.)
The term "moveable"
implies that the allocated
storage
(if any)
described
by a
passed descriptor can be released and newly-acquired
string storage be described in its place.
Following are
classes:

some

typical

uses

for

the

four

string

descriptor

FIXED -

To describe a standard message-text string.

BOUNDED -

To describe a LOCAL print-line buffer with a maximum
length of 132 characters;
or to describe a substring
of a FIXED or DYNAMIC string.

DYNAMIC -

To describe a dynamically-created character string.
For example,
XPORT I/O uses a DYNAMIC descriptor
(located in the lOB) to describe the
resultant file
specification, i.e., IOB$T_RESULTANT.

DYNAMIC BOUNDED To describe a character string whose length
is
continually changing,
e.g., an unlimited print-line
buffer.
XPORT I/O uses this class of descriptor
to
describe its input-string buffer, i.e., IOB$T_STRING.

6.1.6

Descriptor Data Types

The data type field in a descriptor
identifies the type of item
described
by the descriptor.
Although VAX/VMS defines a multitude of
possible data types, only two of these are relevant to
transportable
descriptor usage:
STR$K_DTYPE_T and STR$K_DTYPE_Z.

6.1.6.1

Character String Data 'I'ype

(STR$K_DTYPE_T)

This data type identifies XPORT-compatible ASCII character strings.
The
length field
(STR$H LENGTH)
of a
character string descriptor
specifies the number of characters in the string.
The pointer field
(STR$A POINTER) contains a BLISS character pointer which points to the
first character of the string.
A character string descriptor may be
used
in conjunction with all XPORT I/O, dynamic memory management and
string processing functions.

6-8

String Handling Facilities
STRING DESCRIPTORS
6.1.6.2

Binary Data Type

(Sr:£'R$K_DTYPE_Z)

This data type
identifies XPORT-compatible binary
described in Chapter 7, "Binary Data Descriptors".

6.2

data.

STRING DESCRIPTOR STRUCTURE REFERENCES

An XPORT string descriptor is actually a
transportable XPORT data
structure.
A reference description of this structure appears in the
Appendix section B.2.
The individual fields of a string descriptor may be referred to
using
conventional
BLISS
field
references.
As an example of such
first
references, consider the following routine which returns the
character of a string or a null (indicating a null string).
ROUTINE first_character( string) =
BEGIN
MAP string:
REF $STR_DESCRIPTOR();
IF .string[STR$H_LENGTH] EQL 0
THEN
RETURN %CHAR(O)
ELSE
RETURN CH$RCHAR( .string[STR$A_POINTER]
END;
This sample routine (which does not distinguish
string
and
a NUL first character)
will
work
character strings in all target environments.

6.3

between the null
for all classes of

STRING MODIFICATION

The $STR COPY and $STR APPEND functions permit convenient modification
of a strIng value regardless of the class of the string.
The $STR COPY function replaces a current string value with a
new
val ue. -The $STR APPEND function adds characters to the end of an
existing string. The following sample routine illustrates the use of
these string modifications functions.

6-9

String Handling Facilities
STRING MODIFICATION
ROUTINE echo
BEGIN
OWN
terminal
message

$XPO lOB () ,
$STR DESCRIPTOR ( CLASS = DYNAMIC BOUNDED,
STRING = (0,0) );

$XPO_OPEN( lOB = terminal, FILE SPEC

$XPO_INPUT );

WHILE $XPO_GET( lOB = terminal,
PROMPT = IEnter a string: I ) DO
BEGIN
$STR COPY ( STRING = IECHO: II I, TARGET
message) ;
terminal[IOB$T STRING],
$STR=APPEND( STRING
TARGET = message );
$STR APPEND( STRING = 1111, TARGET = message );
$XPO-PUT( lOB = terminal, STRING = message)
END END;
The actual processing performed by the $STR COPY and $STR APPEND
functions
depend on the class of the target string descriptor, as
described in the following two sections.

6.3.1

$STR_COPY Operation

The string copy operation
strings as follows:
o

acts

the

various

classes

target

FIXED target string:
The source string
is copied
to
the
target string, replacing any previous content.
If the source
string is shorter than the target string,
the target is
padded with trailing blanks.
If the source string is longer than the target string, it is
either truncated (if requested by the user) or the operation
fails.
Optional truncation is specified by the parameter
OPT I ON=TRUNCATE.

DYNAMIC target string:
If the source and target strings are
the same length,
the source string is copied to the target
string, replacing any previous content.
If the source string is either shorter or longer
than the
target string,
the dynamic memory occupied by the target
string is freed, a new dynamic-memory element is allocated,
and
the source string
is copied to it.
The target string
descriptor is updated to reflect the new length and storage
location.
6-10

String Handling Facilities
STRING MODIFICATION
o

BOUNDED target string:
If the source string will fit
within
the bounded-pIus-remainder portion of the target container
string, the source string is copied to the target string
and
and
the length field of the target string descriptor is
updated to reflect the new bounded-string length.
If
the source string
is
longer
than the bounded-plusremainder
portion of the target container
string, it is
either truncated (if requested by the user) or the operation
fails.
Optional
truncation
is specified by the parameter
OPTION=TRUNCATE.
The prefix portion, if any, of the target container string is
never modified by the copy operation.

DYNAMIC BOUNDED target string:
If the source string will fit
within the bounded-pIus-remainder portion of the target
container string, the source string is copied to
the
ta rg et
string
and
and
the length field of the
target str ing
descriptor is updated
to
reflect the new bounded-string
length.
If
the source string
is
longer
than the bounded-plusremainder
portion of the
target container string, a new
dynamic-memory element is allocated, the
prefix
portion of
the original
target string
plus
the new source string is
copied to it, and
the original dynamic-memory element
is
freed.
The target string descriptor is updated to reflect
the new bounded-string length, storage location, and maximum
(i.e., container string) length.
The prefix portion, if any, of the original target
string is never modified by the copy operation.

6.3.2

container

$STR_APPEND Operation

The string append operation acts on
strings as follows:

the

various

classes

target

FIXED target string:
An append operation is not permitted
since a FIXED string cannot be
for
a
FIXED target string
ex tended.

DYNAMIC
target string:
The source string
is logically
concatenated with the target string and the result is copied
into a newly allocated dynamic-memory element.
The dynamic
memory allocated
for the original target string (if any) is
then freed, and the target string descriptor
is updated
to
reflect the new length and storage location.

6-11

String Handling Facilities
STRING MODIFICATION
o

BOUNDED target string:
If the source string will fit within
the
remainder portion of the target container string, the
source string is added to the end of the target string
and
and
the length field of the target string descriptor is
updated to reflect the new bounded-string length.
If the source string is
the target container
requested by the user)
truncation is specified

longer than the remainder portion of
string,
it
is either truncated (if
or the operation fails.
Optional
by the parameter OPTION=TRUNCATE.

The prefix portion, if any, of the target container string is
never modified by the append operation.
o

DYNAMIC BOUNDED target string:
If the source string will fit
within the remainder portion of the target container string,
the source string is added to the end of the target string
and
and
the length field of the target string descriptor is
updated to reflect the new bounded-string length.
If the source string is longer than the remainder portion of
the target container string, a new dynamic-memory element is
allocated, the source string is logically concatenated with
the
prefix-pIus-bounded portion of the original
target
string, and the result is copied to the new memory element.
'rhe original dynamic-memory element is then freed.
'l'he
target string descriptor
is updated
to
reflect the new
bounded-string length,
storage location, and maximum (i.e.,
container string) length.
The prefix portion, if any, of the original target
string is never modified by the append operation.

6.4

container

STRING COMPARISON

The BLISS language provides a collection of built-in character
comparison functions
(CH$xxx)
which can be used
to compare two
character string values.
Each of these functions uses pairs of length
and
pointer values to describe the characters strings.
The XPORT
string comparison functions provide a similiar set of functions which
are based on implicit or explicit string descriptors.
The basic form of all of the XPORT string comparison functions
follows:
$STR relation( STRINGI
STRING2
{, FILL

string-info,
string-info
char-value-expression } )

6-12

String Handling Facilities
STRING COMPARISON
The "string-info" value can be the address of a string descriptor,
a
literal ASCII string, a string length/pointer pair, or an XPORT string
pseudo-function (see Section 6.6).
The "char-value-expression" can be
any expression that produces a value between a and 127 (decimal)
inclusive.
The following string comparison functions are provided:
Function

Meaning
String-l and string-2 are equal, i.e., both
strings are the same length and have the same
value.

$STR_NEQ

String-l and string-2 are not equal.

$STR LSS

The value of string-l is less than the value
of string-2.
The value of string-l is less than or equal
to the value of string-2.
The value of string-l is greater than or
equal to the value of string-2.

$STR GTR

The value of string-l is greater than the
value of string-2.

$STR COMPARE

Compare string-l for a less-than, equal-to,
or greater-than relationship to string-2.

With the exception of $STR COMPARE, these functions return a value of
1 if the comparison is- satisfied,
a value of a
(zero) if the
comparison is not satisfied, or an error completion code if either of
the string descriptors is invalid.
$STR COMPARE returns values of -1,
0, or +1 for less-than, equal-to, or greater-than, respectively.
In order to compare as equal, two strings must be equal in length as
well
as content.
If requested with the FILL= parameter, the shorter
of the two character strings is extended by adding
"fill characters"
to make the two strings the same length.
The relationship between two string values (e.g., less than)
depends
on the ordering of the characters within the two strings.
That
ordering is determined by the ASCII collating sequence.

6-13

String Handling Facilities
STRING COMPARISON
The following sample
routine,
which determines whether a
keyword
begins with a capital letter,
illustrates the use of the string
comparison functions.
ROUTINE keyword test( keyword_desc ) =
BEGIN
IF $STR LSS( STRINGI = .keyword desc, STRING2
$STR=GTR( STRINGI = .keyword-desc, STRING2
FILL = 'Z' )
THEN
RETURN a
ELSE
RETURN 1
END;

6.5

'A'

'z ' ,

) OR

STRING SCANNING

6.5.1

$STR SCAN Overview

The $STR SCAN
scanning:

function

performs

three

different

types

string

It can locate a specific sequence of characters within a
string (FIND mode) •

It can match a stream of specific characters (SPAN
mode) .

It can search for one of a set of specific characters
(STOP mode) .

Each of these scanning operations determines a unique substring of the
string being scanned.
There are several
operations:

possible

results

these

string

A completion code is returned which indicates whether
the operation was successful.

A substring descriptor (FIXED or BOUNDED only)
fill ed in.

A copy of the resulting substring can be returned.

6-14

can be

scanning

String Handling Facilities
STRING SCANNING
o

The character that terminated the search can be
ret urned •

For the purpose of presenting meaningful
string scanning examples
further
on,
imagine a simple application which reads and scans data
records which have the following syntax:
keyword {=value}

, •••

Following are sample data records which conform to this syntax:
BEGIN
COPIES=5
SUB TOTALS, TOTALS, GRAND TOTAL
ENDEach of the string-scanning code fragments
assumed to appear in the following routine:

presented

later

ROUTINE data scan( data line) =
BEGIN
BIND
line = .data line
$S'I'R _DESCR I PTOR () i
OWN
keyword:
$STR_DESCRIPTOR( STRING=(O,O) ),
keyword_copy:
$STR DESCRIPTOR ( CLASS = DYNAMIC,
STRING = (0,0) ),
$STR_DESC INIT( DESCRIPTOR = line, CLASS
STRING = .data line )i

6.5.2

BOUNDED,

$STR_SCAN FIND - Find a Character Sequence

The following code fragments illustrate the use of the $STR SCAN FIND
operation to locate a specific sequence of characters within a string,
and to modify a descriptor to isolate that sequence (if found).

6-15

String Handling Facilities
STRING SCANNING

, : =I
line, FIND
IF $STR SCAN( STRING
THEN
BEGIN
'Obsolete syntax in following line',
$XPO PUT MSG( STRING
line) ;
STRING
RETURN a
END;

6.5.3

$STR SCAN SPAN - Match a Set of Characters

The $STR SCAN SPAN operation determines the longest substring which
(1)
begIns
at the start of a string and (2) consists solely of a
specified set of characters.
A successful-sFAN operation may result
in a null substring, i.e., zero characters spanned.
The following code fragment illustrates the creation
descriptor for the first keyword of a data record.

substring

$STR_SCAN( STRING = line,
SPAN = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 '
SUBSTRING
keyword,
DELIMITER = keyword_delim );
This scan call will isolate any upper-case symbol occuring
at the
beginning of the data line, will modify the descriptor named "keyword"
to describe
that symbol,
and will
also
return
the
character
immediately
following
the
symbol
in
the data-segment named
"keyword delimIt.

6.5.4

$STR SCAN STOP - Search for a Set of Characters

The $STR SCAN STOP operation determines the longest substring which
(1)
begIns at the start of a string and (2) does not contain any of a
specified set of characters.
A STOP operation may result in a
null
substring.
The following code fragment illustrates an alternate method
for
the
creation of a
substring descriptor.
It is d~signed to pick up any
substring delimited by a comma or an equal sign.
$STR_SCAN( STRING
line,
STOP = ',=',
SUBSTRING
keyword,
DELIMITER = keyword_delim );

6-16

String Handling Facilities
STRING SCANNING
6.5.5

$STR_SCAN - Returning a Substring

A copy of a substring determined by any type of scan operation
(i.e.,
FIND,
SPAN,
or STOP) can be created automatically through use of the
TARGET= parameter.
The target descriptor must be FIXED or DYNAMIC
class only.
The following code fragment
illustrates the creation of a
descriptor for a copy of the first keyword of a data record.

target

$STR_SCAN{ STRING
line,
SPAN = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 '
TARGET = keyword_copy);
This scan call will isolate any upper-case symbol occuring at the
beginning
of the data line, will make a copy of that symbol, and will
modify the descriptor named "keyword_copy" to describe the copy.

6.5.6

$STR_SCAN -

"Scanning 'l'hrough" a BOUNDED String

In the general case, the $STR SCAN functions make conventional use of
the
source
string descriptor (specified with the STRING= parameter) •
That is, the STR$H LENGTH and STR$A POINTER fields of the descriptor
determine the string to be scanned.However, if a BOUNDED or DYNAMIC BOUNDED descriptor is specified in a
REMAINDER= parameter,
the
remainder string (rather than the bounded
string) is scanned.
In order to use this form of string
scanning,
a
bounded descriptor must be declared and initialized:
LOCAL
scan line:

$STR_DESCRIPTOR{ CLASS

BOUNDED) ;

$STR_DESC INIT{ DESCRIPTOR = scan_line,
CLASS = BOUNDED,
STRING = .data line );
Moreover,
if
the same BOUNDED or DYNAMIC BOUNDED descriptor
is
specified
for
both~e
REMAINDER= and SUBSTRING= parameters, the
special operation of "scanning through a string", one field at a time,
is achieved
in a greatly simplified
fashion.
For example, the
following two code fragments each skip past the sequence of commas and
spaces which can precede the next keyword.
$STR_SCAN{ REMAINDER = scan_line,
SPAN = "
"
scan line );
SUBSTRING
6-17

String Handling Facilities
STRING SCANNING
This fragment is equivalent to:
BEGIN
LOCAL temp desc:
$STR DESCRIPTOR();
$STR_DESC_INIT( DESCRIPTOR = temp_desc, CLASS = FIXED );
$STR_SCAN( STRING = (.scan line[STR$H MAXLEN] .scan line[STR$H LENGTH] .scan line[STR$H PFXLEN],
CH$PLUS{.scan-line[STR$A-POINTER],
.scan_line[STR$H_LENGTH]»
SPAN = I, I,
SUBSTRING = temp_desc );
scan line[STR$H_PFXLEN]
scan line[STR$H LENGTH]
scan-line[STR$A-POINTER]
END;-

6.6

.scan line[STR$H PFXLEN] +
.scan line[STR$H LENGTH];
.temp desc[STR$H LENGTH];
.temp_desc[STR$A_POINTER];

STRING CONVERSION

6.6.1

$STR CONCAT and $STR_FORMAT - ASCII to ASCII String Conversions

The simplest form of string conversion is to
(logically)
modify the
form of an ASCII string.
The pseudo-functions which perform this type
of conversion are $STR CONCAT and $STR FORMAT.
These pseudo-functions
may only be used in conjunction with the STRING= parameter and similar
parameters of XPORT I/O and String Handling functions.
Wherever possible,
the examples in this section
(modifications of) examples presented earlier.

6.6.1.1

are

built

upon

$STR CONCAT

The $STR CONCAT pseudo-function allows two or more strings
logically concatenated to form a single logical string.

The following code fragment illustrates the use of the $STR CONCAT
pseudo-function to specify a single logical string which consists of
two literal strings and a variable string (that is, an
lOB stringdescriptor address;
cf. Chapter 3).

6-18

String Handling Facilities
STRING CONVERSION
$XPO_PUT( lOB = terminal,
STRING = $STR_CONCAT( 'ECHO: "I,
terminal [IOB$T_STRING],

, "'

6.6.1.2

)

);

$STR FORMAT

The $STR FORMAT pseudo-function provides a means of
specifying
non-standard string characteristics or processing.
For example, a
string can be converted to upper-case as part of an append operation.
$STR_APPEND( STRING
$STR FORMAT( terminal[IOB$T_STRING], UP_CASE),
TARGET = message );
Likewise, the case of a string could
comparison or scanning operation, by
transformation.
IF $STR_EQL( STRINGI
STRING2
THEN

in a string
be
'ignored'
means of the same logical

$STR FORMAT( keyword, UP CASE ),
'YES' )

The length and alignment of a
$STR FORMAT:

string

can

also

specified

using

$STR_COPY( STRING = $STR FORMAT ( keyword, LENGTH=20, RIGHT JUSTIFY),
TARGET = message );
$XPO_PUT( lOB = terminal,
STRING = $STR_FORMAT( 'Hello User!', LENGTH=80, CENTER)

6.6.2

);

$STR_ASCII - Binary-Data to ASCII String Conversion

The $STR ASCII pseudo-function provides a means of easily creating
an
ASCII
string
representation of a single binary value.
This pseudofunction, like the $STR CONCAT and $STR FORMAT pseudo-functions, may
only be
used
in conjunction with the STRING= parameter and similar
parameters on XPORT I/O and String Handling functions.
The following sample routine illustrates the use of the $STR ASCII
pseudo-function to output an ASCII number to the user's terminal:

6-19

String Handling Facilities
STRING CONVERSION
ROUTINE put ascii
NOVALUE
BEGIN OWN
number
INITIAL( 1234 ),
negative
INITIAL( -44 ),
terminal
$XPO_IOB();
IF NOT .terminal[ IOB$V OPEN
THEN
$XPO_OPEN( lOB = terminal, FILE SPEC

$XPO OUTPUT );

$XPO_PUT( lOB = terminal,
STRING = $STR_ASCII( .number ) );
RETURN;
END;
A variety of $STR ASCII conversion options permit the user to specify
the exact form of binary to ASCII conversion desired.
For example,
the following list shows the terminal output which would result on
VAX/VMS from the substitution of various $STR ASCII calls in the
previous code fragment.
Terminal Output

STRING=
$STR ASCII (.number)
$STR-ASCII (.number,BASEIO)
$STR-ASCII (.number,BASE8)
$STR-ASCII(.number,BASE8,LENGTH=4)
$STR-ASCII(.number,BASE16)
$STR-ASCII(.number,BASE2,LENGTH=12)
$STR-ASCII(.number,BASE8,LEADING BLANK)
$STR-ASCII (.number,BASEIO,LEADING ZERO)
$STR-ASCII (.number,BASE10,LENGTH=8)
$STR-ASCII (.negative)
$STR-ASCII(.negative,BASEIO)
$STR-ASCII(.negative,BASE8)
$STR-ASCII(.negative,BASE16)
$STR-ASCII(.negative,BASE8,SIGNED)
$STR=ASCII (.negative,BASE10,UNSIGNED)

1234
1234
00000002322
2322
000004D2
010011010010
2322
0000001234
1234
-44
-44
37777777724
FFFFFFD4
-00000000054
4294967252

Table 6.2 shows the possible $STR ASCII integer conversion options and
indicates the option defaults.- Note that the defaults for BASE10
conversion are opposite from the defaults for BASE2, BASE8 and BASE16.

6-20

String- Handling Facilities
STRING CONVERSION
Table 6.2
$STR ASCII Integer Conversion Options
+------------------------~-------------------------------------------+

I
I
I

Option Type

Option

Default

Result radix

BASE2, BASE8
BASElO, BASE16

BASEIO

Integer type

SIGNED,
UNSIGNED

If BASEIO then SIGNED,
else UNSIGNED

Nonsignificant
digit

LEADING BLANK,
LEADING-ZERO

If BASEIO then LEADING_BLANK,
else LEADING ZERO

String length

LENGTH=constant

If LEADING BLANK then
LENGTH=minimum,
else LENGTH=large enough for
maximum value

+--------------------------------------------------------------------+
6.6.3

Nesting $STR_ASCII, $STR_CONCAT, $STR_FORMAT Pseudo-Functions

The $STR ASCII, $STR CONCAT, and $STR FORMAT pseudo-functions may be
nested as desired;
that is, a $STR ASCII, $STR CONCAT, or $STR FORMAT
pseudo-function may be the string argument of eTther a $STR CONCAT or
$STR_FORMAT pseudo-function.
The following sample routine illustrates nesting of string conversion
pseudo-functions.
This routine formats and outputs a single line of
sequence-numbered text (created by an SOS editor) •
ROUTINE put_sos( number, page, text)
BEGIN
$XPO PUT( lOB = terminal,
STRING = $STR CONCAT( $STR ASCII (.number,LENGTH=5,LEADING ZERO),
I

11,-

$STR ASCII (.page,LENGTH=3,LEFT JUSTIFY),
$STR=FORMAT(.text,LENGTH=123,TRUNCATE) )
END;

6-21

String Handling Facilities
STRING CONVERSION
The output of this routine will have the following format:

00150/2

a single line of text

where "00150" is a line sequence number (always 5 digits with leading
zeros)
and
"2"
is a
page number
(left justified with no leading
zeros) •

6.6.4

$STR_BINARY - ASCII String to Binary-Data Conversion

The $STR BINARY function provides a means of easily
ASCII string value into a corresponding binary value.

converting

The following sample routine illustrates the
convert a string value into a binary value.

$STR BINARY

use

ROUTINE echo test
NOVALUE
BEGIN
LOCAL echo count;
OWN
termTnal
$XPO IOB();
$XPO_OPEN ( lOB

terminal, F1LE SPEC

$XPO INPUT);

$XPO GET( lOB = terminal,
-PROMPT = 'Enter number of times to echo each string'
$STR_BINARY( STRING
OPTION
RANGE
RESULT

terminal[IOB$T STRING],
BASEIO,
(1,999 ),
echocount );

$XPO_GET( lOB = terminal,
PROMPT = 'Enter string: ' )
DO
INCR counter FROM 1 TO .echo count DO
$XPO PUT( lOB = t~rminal~
STRING = terminal [IOB$T_STRING]

WHILE

END;

6-22

);

CHAPTER 7
7.1
7.2
7.2.1
7.2.2
7.2.3
7.2.4

BINARY DATA DESCRIPTORS
INTRODUCTION . • . • . • • . . • . • • . • • • • .
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
$XPO DESCRIPTOR -- Creating a Binary Data
Desc~iptor • . . • • • • • . • . . . . . •
••
$XPO DESCRIPTOR -- Compile-Time Descriptor
InitTalization • • . • • • • . . • • • • •
.
$XPO DESC INIT -- Run-Time Data Descriptor
InitTalization . . . . . • • . • . . . . • • • .
Classes Of Descriptors • • • • • • • • . • . . •

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

CHAPTER 7
BINARY DA'l'A DESCRIPTORS

This chapter describes macros related to the manipulation of binary
data
(i.e., non-character-string data).
They are used in conjunction
with the XPORT
I/O and memory-management facilities described
in
Chapters
3 and
4
respectively.
See also Appendix A for reference
descriptions of the macros discussed here.

7.1

INTRODUCTION

A binary-data descriptor is a small block structure used to describe a
binary data
item.
(These descriptors are modelled
on a VA,X/VMS
convention.
The string descriptor concept, as described in Chapter 6,
is
extended
here to include binary data as well.) The XPORT I/O and
memory-management facilities make extensive use of such descriptors
internally,
and
fully support their
use by the
programmer -- a
descriptor address is always a valid form of binary data
parameter,
for example.
Two
macros
are
provided
for
data-descriptor
initialization:
$XPO DESCRIPTOR and $XPO_DESC INIT.

creation

and

Descriptors essentially provide a
mechanism
for
communicating
nonscalar data between independent procedures in an indirect, uniform,
and controlled fashion.
They not only describe the location and
extent of an item, but also describe its "class".
By convention the
class of an item reflects (1) the nature of its allocation and
(2)
a
discipline
to
be observed when
'writing' such an item, i.e., when
modifying the item and
updating
the descriptor accordingly.
This
discipline mainly applies to the recipient of a descriptor, that is,
to a routine to which a descriptor address is passed.
The descriptor classes are:
FIXED, BOUNDED, DYNAMIC, DYNAMIC BOUNDED,
and
undefined.
The specific
usage conventions implied by each of
these classes are described in Section 7.2.3.
It should be noted
here,
however,
that for
the
purposes of reading
an item (i.e.,
fetching
via
the descriptor)
all
classes of
descriptors
are
equivalent to FIXED.
7-1

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZA'I'ION
7.2

BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION

7.2.1

$XPO_DESCRIPTOR -- Creating a Binary Data Descriptor

A binary data descriptor can be created
using
the $XPO DESCRIPTOR
macro
as an attribute of a data declaration (of an OWN or LOCAL
dec~aration, for
example).
The macro expands to an appropriate
structure-attribute and
field-attribute
for the class of descriptor
desired.
For example, the declaration
OWN
data buffer:

$XPO_DESCRIPTOR();

declares a FIXED descriptor, by default.
declaration
GLOBAL
integer_array:

In contrast,

$XPO_DESCRIPTOR ( CLASS

the

following

BOUNDED );

explicitly declares a BOUNDED data descriptor.
As a further example, the declaration
LOCAL
temp_work area:

$XPO DESCRIPTOR{ CLASS

declares a DYNAMIC data descriptor
dynamically allocated storage.

7.2.2

for

use

= DYNAMIC );
in

conjunction

with

$XPO_DESCRIPTOR -- Compile-Time Descriptor Initialization

A binary data descriptor must be initialized prior to its first
use.
A descriptor created
in permanent storage
(OWN or GLOBAL) can be
statically initialized by means of parameters of the $XPO DESCRIPTOR
macro.
Several examples follow:
OWN

$XPO DESCRIPTOR{ CLASS = DYNAMIC,
BINARY_DATA = (0,0)

);

The descriptor is initialized as class DYNAMIC and the data-item size
and
address fields of the descriptor are set to indicate a null item
(zero size and address).
Note that a DYNAMIC descriptor created
in
permanent storage can only be initialized to point to 'no storage' at
~ompile time;
that is, the only dynamic-storage initialization value
acceptable at compile time is BINARY DATA = (0,0).

7-2

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
A FIXED (or BOUNDED) descriptor created in permanent storage can be
preset with a
non-null data-item value, as shown in the following
example:
OWN
set of data
VECTOR[lOO],
set-desc
$XPO_DESCRIPTOR( BINARY DATA =
(lOO~set of_data)

);

By default,
the size expression
(100)
is
interpreted as being
expressed
in BLISS fullwords
(as opposed
to addressable units).
Alternatively,
the size expression could be
indicated
as being
expressed
in addressable units,
as shown in the following example
(BLISS-16/32 only):
OWN
many bytes
byte=desc

VECTOR[lOOO,BYTE] ,
$XPO DESCRIPTOR( BINARY DATA =
( 1000, many_bytes, UNITS ) );

Note that, in the interests of program clarity (and
for
reinitialization),
the alternative keyword
FULLWORDS
specified explicitly, although it is assumed by default.

purposes of
can also be

A descriptor created in temporary (LOCAL) or dynamic storage
dynamically initialized via the $XPO DESC IN IT macro.

7.2.3

must

$XPO_DESC INIT -- Run-Time Data Descriptor Initialization

The executable $XPO DESC INIT macro dynamically initializes all fields
of a binary data descriptor.
This macro must be used for descriptors
created in temporary or dynamic storage.
The dynamic descriptor
initialized as follows:

'declared'

Section

7 • 2. 1

might

$XPO_DESC_INIT( DESCRIPTOR = temp work area,
CLASS = DYNAMIC);
The named descriptor is initialized as a descriptor of dynamic
binary
data.
In the absence of a BINARY DATA parameter, the size and address
fields are set to indicate a null value.
A descriptor
created
in
temporary storage could be initialized to describe an area of local
storage, as follows:

7-3

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
LOCAL
resul t val ues
result-desc

BLOCK[ result size],
$XPO_DESCRIPTOR();

$XPO DESC INIT( DESCRIPTOR = result desc,
BINARY_DATA = ( result_size, result_values)

);

Note particularly that the class that is specified (or defaulted)
in
the $XPO DESC INIT macro must match the class that is either specified
or defaulted Tn the $XPO DESCRIPTOR macro.
(That
is,
the CLASS
parameter may be omitted Tn either or both macros only in the case of
a FIXED descriptor.) Also, the class of a descriptor cannot be changed
"in mid-stream", that is, without reinitialization.

7.2.4

Classes Of Descriptors

All data descriptors contain the following common fields:
0

A si ze field, named XPO$H - LENGTH,

A address field, named XPO $A _ADDRESS,

A class field, named XPO$B _CLASS, and

A data-type

field, named XPO$B DTYPE.

In addition to these fields, BOUNDED and
also contain the following:

DYNAMIC BOUNDED

A prefix-size field, named XPO$H_PFXLEN, and

A maximum-size field, named XPO$H_MAXLEN.

descriptors

Figure 7.1 shows the format a FIXED or DYNAMIC descriptor;
figure 7.3
shows
the
format of a BOUNDED or DYNAMIC BOUNDED descriptor.
Note
that a
BOUNDED descriptor
is simply an- extension of a
FIXED
descriptor.
Figures 7.2 and 7.4 show the format of the
these descriptors.

data

items

described

Figure 7.1
Format of a FIXED or DYNAMIC Descriptor

+-------------------------------------------------------+
I
I
I
I XPO$B CLASS I XPO$B DTYPE I
I
I
I

XPO$H LENGTH

+-------------------------------------------------------+
I
I
I

XPO$A ADDRESS

I
I

+-------------------------------------------------------+
7-4

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
Figure 7.2
Format of a FIXED or DYNAMIC Data Item
+-----------XPO$A POINTER
1

v
+-------------------------------------------+
1

IxxxxxxXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXI
1

+-------------------------------------------+
1

1<--------------XPO$H_LENGTH---------------> 1
Figure 7.3
Format of a BOUNDED or DYNAMIC_BOUNDED Descriptor
+------------------------------------------------------+
1
1
1
1
1 XPO$B CLASS 1 XPO$B DTYPE 1
XPO$H LENGTH
1
1
1
1
1
1------------------------------------------------------I
1

XPO$A ADDRESS

1------------------------------------------------------I
1

1
XPO$H PFXLEN
1
XPO$H_MAXLEN
1
1
1
1
+------------------------------------------------------+
Figure 7.4
Format of a BOUNDED or DYNAMIC BOUNDED Data Item
+----------XPO$A POINTER
1

+-------------------------------------------------------------+
1
1
1
1
1
IxxxxxxXXXXXXXXXXXXXXXXXXXXXI
1
1
1
1
1
+-------------------------------------------------------------+
1
1
1
1
I(---XPO$H PFXLEN--->I<------XPO$H LENGTH------->1
1
1

I<------------------------XPO$H MAXLEN----------------------->1

7-5

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
For each class of descriptor, the usage rules specify which fields
may be modified and which fields may not, by a procedure that is
not the "owner" of the descriptor.
Such a
procedure
is typically a
routine
that
is passed a
descriptor address as one of its calling parameters. Moreover,
the rules only apply where the descriptor is passed in order
that
the called routine can either modify information already described
by the descriptor or can return new information to the caller via
the descriptor.
(Obviously, when a descriptor is used simply to
pass information for reading only, no descriptor
fields need
be
modified by the recipient.
All descriptor classes are, in fact,
equivalent to FIXED for purposes of reading, i.e.,
fetching data
via the descriptor.)
The UNDEFINED class -- which is actually a 'non-class' -- has
rules associated with it and is for intra-program use only.

Table 7.1 gives the usage rules for each class of descriptor.
Table7.1
Descriptor Usage Rules

+----------------------------------------------------+
1
Can recipient modify descriptor field?
1
1
------------+
+---------------1-----------1
1
1

ITEM
Prefix
Maximum
Current
Address
Length
Length
Length
IXPO$H LENGTH XPO$A ADDRESS XPO$H_PFXLEN XPO$H MAXLEN

Descriptor
Class

1---------------1-----=-----IFIXED
NO
1---------------1-----------1 BOUNDED
1
YES
1---------------1-----------IDYNAMIC
YES*
1---------------1-----------1

IDYNAMIC BOUNDEDI

YES

I-------~-------I------------

IUNDEFINED

(n.a.)

YES

YES*

(n.a.)

YES*

YES

YES*

+--------------------------------------------------------------------+
1
1
1

NOTE:

It is always valid (with respect to these rules) to modify
1
content, that is, to change the information described by thel
descriptor, within the limits set by these rules.
1

+--------------------------------------------------------------------+
* Requires interaction with $XPO FREE_MEM and $XPO_GET_MEM.

7-6

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
The rules in Table 7.1 give
rise
to
the
following generalizations
about descriptor classes
(keep in mind that they do not necessarily
apply to the "owner'l of the descriptor):
o

A FIXED descriptor describes a data item, whose location
extent may not be changed.

and

This class of descriptor is typically used to pass an item to
another
routine,
and
is seldom
(almost never)
used
to
describe space.
o

A BOUNDED descriptor describes a
fixed-length data buffer
that contains an item of varying length.
The item may begin
at any addressable point in the buffer and may extend to
the
end of the buffer.
The buffer location and size may not be
changed (presumably it is allocated in OWN, GLOBAL, or
LOCAL
storage);
the item, however, may be moved, shortened and/or
lengthened within the limits of the fixed-size buffer.
This class of descriptor is
typically used
to describe a
space
in which to construct or update an item which, by its
nature, will not exceed a given maximum size.
In addition to describing
a bounded
item,
a
BOUNDED
descriptor implicitly describes three additional data items the "container item",
a
"prefix
item",
and
a
"remainder
item".
The container
item
is
the entire buffer and thus
includes the bounded item.
The prefix item is the portion of
the container item (possibly null) that precedes the bounded
item.
The remainder item is the
portion of
the container
item (possibly nUll) that follows the bounded item.

A DYNAMIC descriptor describes a moveable data
item whose
size may vary from 0
to 64K addressable
units.
It is
generally used for
an
item
to
be
returned
call ed
by a
routine.
Note that this class implies the use of dynamic memory, since
the storage described
is
always assumed to be releasable.
(See Chapter 4 concerning dynamic-memory facilities.)

A DYNAMIC BOUNDED descriptor describes a moveable data buffer
containinij an
item of varying size.
The item may begin at
any addressable point in the buffer and may extend to the end
of the buffer.
As its name implies, this class is a generalization of both
the BOUNDED and DYNAMIC classes.
It can be used to avoid the
maximum-size restriction imposed by BOUNDED;
it can also
be
used
for
a very volatile item, to avoid much of the memorymanagement overhead implied by DYNAMIC (i.e., storage need be
reallocated only when the buffer becomes too small).
7-7

Binary Data Descriptors
BINARY DATA DESCRIPTOR CREATION AND INITIALIZATION
Note that this class also implies the use of dynamic memory,
since
the
storage described
is always assumed
to
be
releasable.
(See Chapter
4
concerning
dynamic-memory
facilities.)
The term "moveable"
implies that
the allocated
storage
(if any)
described by a
passed descriptor can be released and newly-acquired
storage be described in its place.

7-8

APPENDIX A

MACRO DESCRIPTIONS

A.l
DESCRIPTIVE NOTATION AND CONVENTIONS • • . • • •
A.l.l
Syntax Notation
•• . • • • . . . • • • ••
A.l.2
Character-String and Binary-Data Parameters
A.l.2.1
String and Data Descriptors . • • .
A.2
$STR APPEND - Append a String
· • • •
A.2.1
Syntax • . • • - . • • •
• • • .
A.2.2
Restrictions • . • • • • . . • • •
·
Parameter Semantics
A. 2.3
A.2.4
Operational Semantics
Completion Codes . . • •
A.2.S
A.3
$STR ASCII - Binary-to-ASCII Conversion
Pseudo-Function
. • • •
·
A.3.1
Syntax . • • . . • •
. • • • • • • •
Restrictions • • • • • • • • • • • • • •
A.3.2
. •
Parameter Semantics
.•••
A.3.3
Usage Guidelines. • .
• •.•••••
A. 3.4
$STR BINARY - Convert ASCII to Binary
A.4
A. 4. 1
Syntax • • • . • • . • .
•
A.4.2
Restrictions • • • • •
•
A.4.3
Parameter Semantics
A.4.4
Usage Guidelines . . • .
A.4.S
Completion Codes • •
•••.
A.S
$STR_COMPARE - String Comparison
A.S.l
Syntax • . • . • • • • •
• • • •
A.S.2
Restrictions • . • . •
· • • •
Parameter Semantics
A.S.3
• . • •
A.S.4
Operational Semantics
•••.
A.S.S
Completion Codes .
. . • ••
• • • .
A.6
$STR CONCAT - String Concatenation
Pseudo-Function
.•• . • • • . . • • • .
A.6.1
Syntax • • • • • • •
. • • .
A.6.2
Restrictions. . • •
• ••••.
A.6.3
Parameter Semantics
A.6.4
Usage Guidelines
A.7
$STR_COPY - Copy a String
A.7.1
Syntax . • • • • • •
A.7.2
Restrictions . • • • • •
A.7.3
Parameter Semantics
A.7.4
Operational Semantics
A.7.S
Completion Codes • • • •
A.8
$STR_DESCRIPTOR - Declare a String Descriptor
A.8.1
Syntax • . . • . • • • • • •
• • • •
A.8.2
Restrictions • • . • • • . • • . • • • • • • •
A.8.3
Parameter Semantics
•••• • • • • • • • • •
A.9
$STR DESC INIT - Initialize a String Descriptor
A.9.1
Syntax -:- • . • • • •
• • • •
A.9.2
Restrictions • • . • . • •
A.9.3
Parameter Semantics
A.9.4
Completion Code
•• . ••
A .10
$STR EQL - String Equality Comparison
A. 10 • 1
Syntax . • • . • • • •
A. 10 • 2
Restrictions • • . • . • • • • •
A. 10. 3
Parameter Semantics
••• .
A. 10.4
Operational Semantics

• A-I
A-I
A-2
A-3
• A-4
. A-4
• A-4
• A-4
· A-S
• A-6
•
•
•
•
•
·
•
•

A-7
A-7
A-7
A-7
A-8
A-9
A-9
A-9

A-IO
A-IO

A-II
A-12
A-12
A-12
A-12
A-13
A-13
A-14
A-14
A-14
A-14
A-IS
A-16
A-16
A-16
A-16
A-17
A-18
A-19
A-19
A-19
A-19
A-21
A-21
A-21
A-21
A-22
A-23
A-23
A-23
A-23
A-24

A. 10.5
A.ll
A. 11 • 1
A. 11. 2
A. 11. 3
A. 11.4
A.12
A. 12. 1
A. 12. 2
A.12.3
A. 12.4
A.12.5
A.13
A.13.1
A.13.2
A.13.3
A.13.4
A.13.5
A.14
A. 14. 1
A. 14.2
A. 14.3
A. 14.4
A. 14. 5
A.15
A. 15. 1
A. 15 . 2
A. 15. 3
A. 15. 4
A. 15.5
A .16
A. 16. 1
A. 16. 2
A. 16. 3
A. 16. 4
A. 16. 5
A.17
A.17.1
A.17.2
A.17.3
A.17.4
A.17.5
A.18
A.18.1
A.18.2
A.18.3
A. 18.4
A.18.5
A.19
A.19.1
A.19.2
A.19.3
A.19.4
A.20
A. 20. 1

Completion Codes . . . . . • • . • • • • • • •
$STR FORMAT - String Formatting Pseudo-Function
Syntax • • • • • • •
. . . • . •
Restrictions • • • .
Parameter Semantics
••••
Usage Guidelines. • •
. •••
$STR GEQ - String Greater-Than-or-Equal
Com par ison . . • • • • . • • • . . . • • •
Syntax • . • . • . • . .
Restrictions • • • . • • • • • • . • • • •
Parameter Semantics
Operational Semantics
Completion Codes . • •
$STR GTR - String Greater-Than Comparison
Syntax • • . . • . • • •
Restrictions • . . • • .
Parameter Semantics
. • • .
Operational Semantics
.•••
Completion Codes • • • . • • • • . . • • • • .
$STR LEQ - String Less-Than-or-Equal Comparison
Syntax . . . • • • . •
Restrictions • • . • • . . • • • • .
Parameter Semantics
Operational Semantics
•••.
Completion Codes • • • •
. .••
$STR LSS - String Less-Than Comparison
Syntax • . . . • . . •
• • • .
Restrictions • • . • • • . • • .
. .•••
Parameter Semantics
. • • ••
. •.•
Operational Semantics
..••••
Completion Codes • • •
$STR NEQ - String Inequality Comparison
Syntax • • • . . . • . .
Restrictions • • • . . .
Parameter Semantics
Operational Semantics
Completion Codes . . • .
$STR SCAN - String Scanning
Syntax • • • • • • • . •
Restrictions . . • . .
Parameter Semantics
.••.
Operational Semantics
..••••••••
Completion Codes • • . . . • •
$XPO BACKUP - Preserve an Input File .
Syntax • . • • . . . .
••••
Parameter Semantics
Usage Guidelines.
Completion Codes •
Example
•.••
$XPO CLOSE - Close a File
Syntax • . . . • • .
Parameter Semantics
Usage Guidelines . • .
Completion Codes .
$XPO DELETE - Delete a File
Syntax . . . . . .

A-25
A-26
A-26
A-26
A-27
A-27
A-29
A-29
A-29
A-29
A-30
/1.-31
A-32
A-32
A-32
A-32
A-33
A-34
A-35
A-35
A-35
A-35
A-36
A-37
A-38
A-38
A-38
A-38
A-39
A-40
A-4l
A-41
A-41
A-41
A-42
A-43
A-44
A-44
A-44
A-45
A-46
A-47
A-48
A-48
A-48
A-49
A-49
A-50
A-51
A-51
A-51
A-52
A-52
A-54
A-54

A. 20 • 2
A. 20. 3
A.21
A. 21 • 1
A. 21 • 2
A. 21. 3
A.22
A. 22. 1
A. 22. 2
A. 22 • 3
A.23
A. 23.1
A.23.2
A. 23.3
A. 23. 4
A.24
A. 24. 1
A. 24. 2
A. 24. 3
A. 24. 4
A.25
A. 25. 1
A. 25 • 2
A. 25. 3
A. 25. 4
A.26
A. 26. 1
A. 26. 2
A. 26. 3
A.27
A. 27 • 1
A. 27 • 2
A. 27 • 3
A. 27 • 4
A.28
A. 28. 1
A. 28. 2
A. 28. 3
A.29
A.29.1
A.29.2
A. 29. 3
A.30
A.30.1
A. 30. 2
A.30.3
A.30.4
A.30.5
A.31
A. 31 • 1
A. 31 • 2
A. 31. 3
A.32
A. 32. 1
A. 32. 2
A.• 32. 3

Parameter Semantics
•.••••.••••
Completion Codes • • . • • . • • . • . . .
$XPO DESCRIPTOR - Declare a Data Descriptor
Syntax • • • • • . • • • • •
Restrictions • • • • • • . • . . . • • . •
Parameter Semantics
•• • • . . • • . • •
$XPO DESC INIT - Initialize a Data Descriptor
Sy~tax ~ • • • • • • • •
Parameter Semantics
•.•.•..•.
Completion Code
•.•.••••••..
$XPO FREE MEM - Release a Memory Element .
Syntax ~ • • . • . •
Restrictions • • . . .
Parameter Semantics
Completion Codes .
$XPO GET - Read From a File
Sy~tax • • • • • • • • • • • • •
Parameter Semantics
Usage Guidelines . . •
Completion Codes • .
• •••
$XPO GET MEM - Allocate Dynamic Memory Element .
Sy~tax- • . • . • • • • . • • .
Restrictions • . . . • .
Parameter Semantics
••••
Completion Codes • •
$XPO lOB - Declare an lOB
Sy~tax . • . • . • • • . • • • .
Parameter Semantics
Examples • • . • . • • •
$XPO lOB INIT - Initialize an lOB
••••
Syntax . • • . . • .
Restrictions • • • • •
Parameter Semantics
••......••
Completion Code
$XPO OPEN - Open a File
Syntax • • • . . . • • .
Parameter Semantics
. . • • • • .
Completion Codes • • • • • .
$XPO PARSE SPEC - Parse a File Specification
Syntax .-. . . . • • • • •
. .•••
Parameter Semantics
. • • • . • . .
Completion Codes • • . • . • • • • . . • .
$XPO PUT - Write to a File. •
. ••.
Syntax . • . • • . • •
•••.
Restrictions • • • •
Parameter Semantics
Usage Guidelines • • • •
Completion Codes • • .
$XPO PUT MSG - Send a Message
Syntax -. • . . • • . • . . . . . . • . . . . •
Parameter Semantics
....••..•.
Completion Codes . • • • • .
• • . .
$XPO RENAME - Rename a File
Syntax • . • • . . .
Parameter Semantics
Completion Codes . . • .

A-54
A-55
A-57
A-57
A-57
A-57
A-59
A-59
A-59
A-60
A-61
A-61
A-61
A-61
A-62
A-63
A-63
A-63
A-64
A-65
A-67
A-67
A-67
A-67
A-68
A-70
A-70
A-70
A-70
A-71
A-71
A-7l
A-71
A-72
A-73
A-73
A-74
A-77
A-79
A-79
A-79
A-80
A-81
A-8l
A-81
A-82
A-82
A-82
A-84
A-84
A-84
A-85
A-86
A-86
A-87
A-89

A.33

$XPO SPEC BLOCK - Declare a File Specification
.•••
Syntax . . . • • • • • •
. • • • • •
Examples . . • • • . . .
••••••
$XPO TERMINATE - Terminate Program Execution
Syntax • . • •
• • • • . • • • •
Parameter Semantics
••••
Routine Value
.•••.•.••••

Bloc~

A. 33. 1
A.33.2
A.34
A. 34. 1
A. 34 • 2
A. 34. 3

A-90
A-90
A-90
A-9l
A-9l
A-9l
A-9l

APPENDIX A
MACRO DESCRIPTIONS

This appendix presents a detailed description of the macros related to
input/output, memory management,
target-system services, and string
tutorial
handling.
It
is
intended
for
reference
purposes.
A
discussion of these macros and
their
use
is given in Chapters 3
through 6 of this manual.

A.J
A.I.l

DESCRIPTIVE NOTATION AND CONVENTIONS
Syntax Notation

The
notational
conventions used
definitions are the following:
Notation

the

subsequent

macro

syntax

Meaning

UPPERCASE TEXT

must be coded exactly as shown.

lowercase text

must be
replaced
by
user-chosen value.

required-parameter

denotes a macro parameter that must be
specified or a compilation error will
result.

primary-parameter

the
denotes a parameter that affects
nature of the requested operation, and
the
which should be specified
unless
has
corresponding
XPORT lOB
field
is
already been set up or
the
user
certain that
the default (if any) is
acceptable.

A-I

appropriate

Macro Descriptions
DESCRIPTIVE NOTATION AND CONVENTIONS
optional-parameter

denotes a parameter that need
not be
specified
in
many
cases.
These
parameters can be used (1) to
provide
optional
information in a request or
(2) to set up an XPORT lOB
field
for
use in a later I/O operation.

nothing

indicates the null alternative,
i.e.,
shows that the programmer may omit the
associated item.

{ alternativel
{ alternative2

braces enclosing a vertical list of
items indicate syntactic alternatives;
one of the
items must be selected.
The braces are not coded.

ABCIDEFlvalue

vertical bars within braces separate
mutually exclusive alternatives;
that
is, only one of the items displayed in
this manner can be selected for any
given use of the macro in question.
A
default,
if
any, is underlined.
The
braces and the vertical
bar are not
coded.

{ parameter }

, ...

braces enclosing
a
single syntactic
element indicate that the element is
optional.
The braces are not coded.
indicates that the preceding item may
be
repeated.
Commas must appear
between the items.
The
periods are
not coded.

Any other punctuation must be coded exactly as shown.

A.l.2

Character-String and Binary-Data Parameters

Many of the macros described in this appendix require character-string
or
binary-data
information as ·parameters.
Such parameters are
indicated
in
the
syntax
diagrams
as
"char-string-info"
or
"binary-data-info".

A-2

Macro Descriptions
DESCRIPTIVE NOTATION AND CONVENTIONS
The following list describes
information can be specified:

the

Syntax

forms

which

character-string

string

descriptor

Meaning

address

The address
(see below)

'ascii text'

A literal ASCII text string,
enclosed
by
apostrophes,
i.e.,
a
BLISS
quoted-string

( count , pointer )

The number of characters in a
string
and
a pointer to the string, enclosed
in
parentheses and
separated by a
comma.

The
following
list describes
information can be specified:

the

Syntax
address

forms

which

binary-data

Meaning
The address of a data descriptor
below)

(see

size, address { ,FULLWORDS I ,UNITS I nothing} )
A specification of the size of a
collection of'~inary data, the address
of the data, anCt--,an optional
keyword
that
indicates the terms in which the
size is expressed.

A.l.2.l

String and Data Descriptors

Many XPORT functions use a
standard block structure called
a
descriptor
to describe
input or output character strings or binary
data.
(These
transportable
descriptors
are
patterned
after
corresponding VAX/VMS standard descriptors.)
Such descriptors can be created and
initialized
by the
programmer
through
the
use of the $STR DESCRIPTOR and $STR DESC IN IT macros,
respectively, described in this appendix.
A detailed dIscussion of
descriptor usage appears in Section 6.1.

A-3

Macro Descriptions
$STR APPEND - Append a String
A.2

$STR APPEND - Append a String

The $STR APPEND macro calls the XPORT STRING facility to append a copy
of a specified source string to a target string.
The precise behavior
of the operation depends to some extent on the class of the
target
string, which must be described by a descriptor.
See Section A.5.4
for further detail.

A.2.1

Syntax

+--------------------+-----------------------------------------------+
I
I str ing-append
I

I
I $STR APPEND ( parameter ,...
I
-

I
I
I

I parameter

I { optional-parameter }

I
I { STRING = char-string-info
}
I required-parameter I { TARGET = address of a string descriptor}

I
I

I optional-parameter I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine }

I
I

+--------------------+-----------------------------------------------+
I
I { required-parameter}
I
+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I
I { OPTION = TRUNCATE
}
I
+--------------------+-----------------------------------------------+
!
I { address of a string descriptor}
I
I char-string-info

I {

}

I
I

I { ( length , pointer)
}
I { string conversion pseudo-function }

I
I

'literal ascii string'

+--------------------+-----------------------------------------------+
A.2.2

Restrictions

A string descriptor, where specified, must describe a
standard XPORT
string;
that
is,
the data
type must be STR$K_DTYPE T, and the
descriptor class must be STR$K_CLASS_F', _D, _B, or DB.
The target string must not be a r'IXED string.

A.2.3

Parameter Semantics

STRING = char-string-info
describes the source character string
to be appended
to
the
target string.
The source string may be of any class.
This
parameter must be specified.

A-4

Macro Descriptions
$STR APPEND - Append a String
TARGET = address of a descriptor
specifies the address of the
parameter must be specified.

target

string

descriptor.

This

OPTION = TRUNCATE
indicates that (the copy of) the source string is to be truncated
as necessary if the entire string cannot be accomodated within
the target container string, in. the case of a
BOUNDED target
string only.
(In any other case this parameter is ignored.) If
this parameter is not specified and the target string is BOUNDED,
the append operation will fail and return a warning completion
code (see below) if the source string is longer than the target
remainder sub-string.
SUCCESS = address of action routine
specifies the address of an action
routine to be called
upon
successful completion of the
requested operation.
If
this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
requested
operation
is
not successful.
If
FAILURE=O
is
specified,
no
failure
action routine
is called.
If
this
parameter
is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).

A.2.4

Operational Semantics

The $STR APPEND operation extends an existing (possibly null)
target
string Ey adding a copy of the input string.
The manner in which the
target string is extended varies according to the class of the target
string, as follows:
o

FIXED target string
The string-append operation is
invalid
for
FIXED target
strings.
(By definition, FIXED strings cannot be extended.)

BOUNDED target string
The target prefix sub-string is preserved and
the
remainder
sub-string is overwritten as necessary.
If the source string
is longer than the target remainder
sub-string,
the append
operation either fails or truncates the source string to fit
within the container string, as requested by the user.

A-5

Macro Descriptions
$STR APPEND - Append a String
o

DYNAMIC target string
Dynamic memory is reallocated
in order
to accomodate the
extended
target string.
If
the source string is the null
string, however, memory is not reallocated.

DYNAMIC_BOUNDED target string
The target prefix sub-string is preserved and
the remainder
sub-string is overwritten as necessary.
If the source string
is longer
than the target
remainder
sub-string, dynamic
memory is reallocated
in order to accomodate the extended
target string.

In no case is the input "source string" or its descriptor modified
any way.
A detailed discussion of the descriptor/string classes
DYNAMIC, BOUNDED, and DYNAMIC-BOUNDED) appears in Section 6.1.

A.2.S

(FIXED,

Completion Codes

A primary completion code is returned as the
routine-call value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the
function.
Secondary
completion codes,
where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
STR$ NORMAL
Error Codes:
STR$ BAD SOURCE +
STR$-BAD-TARGET +
XPO$-FREE MEM +
XPO$-GET MEM +
-

The string-append operation was successful.
The source string is invalid.
The target string is invalid.
Dynamic memory deal location error occured.
Dynamic memory allocation error occured.

A-6

Macro Descriptions
$STR ASCII - Binary-to-ASCIIConversion Pseudo-Function
A.3

$STR ASCII - Binary-to-ASCII Conversion Pseudo-Function

The $STR ASCII pseudo-function produces an ASCII string representation
of a
bInary field value (fullwor"d or smaller).
This pseudo-function
interprets its value argument as a
signed or
unsigned
integer,
as
requested,
and produces an ASCII string that expresses the value in a
user-specified radix and format.
The "value" of a
$STR ASCII
pseudo-function is the address of a
temporary string descriptor and can only be used as a string argument
wlthin other XPORT macro calls.

A.3.1

Syntax

+--------------------+-----------------------------------------------+
I
I
I

binary-to-ASCIIconversion

$STR_ASCII ( value { ,parameter , ••. } )

+--------------------+-----------------------------------------------+
I

parameter

{

integer-keyword}
string-Iength-parameter }

I
I

+--------------------+-----------------------------------------------+
I
I

integer-keyword

{

BASE2 I BASE8 I BASEIO I BASEl6 }
SIGNED I UNSIGNED
}
LEADING ZERO I LEADING BLANK}

I
I
I

+--------------------+----------=--------------=---------------------+
I
I

string-Iengthparameter

LENGTH

= length-expression

I
I

+--------------------+-----------------------------------------------+
A.3.2

Restrictions

The keyword alternatives shown on a single line in the syntax
are mutually exclusive.

A.3.3

diagram

Parameter Semantics

val ue
is any primary expression that, after evaluation, gives a value
to be converted and returned in string form.
This parameter is
required.

A-7

Macro Descriptions
$STR ASCII - Binary-to-ASCII Conversion Pseudo-Function
BASE2, BASE8, BASElO, or BASEl6
indicates that the binary value is to be expressed as a binary,
octal, decimal,
or hexadecimal
number,
respectively,
in the
string representation.
If
this parameter
is not specified,
BASEIO is assumed.
SIGNED or UNSIGNED
indicates that the
fullword
result of the value-expression
evaluation is to be interpreted as a signed or unsigned integer
respectively.
(Note that this parameter does not affect the mode
of extension of any field value involved in tne evaluation.) If
this parameter is not specified, SIGNED is assumed if the
result
radix is BASEIO;
otherwise UNSIGNED is assumed.
LEADING BLANKS or LEADING ZEROS
indicates whether non-significant digits are to be represented by
blanks or by zeros in the result string.
If this parameter is
not specified, LEADING BLANKS is assumed if the result radix
is
BASElO;
otherwise LEADING ZEROS is assumed.
LENGTH = length-expression
specifies the length of the resulting
string,
i.e.,
number of
character positions.
If the specifi~d string length is less than
the number of significant characters in the converted value,
the
result string
is set to all asterisks (a la FORTRAN).
If this
parameter is not specified,
the mlnlmum number of characters
required to represent the significant portion of the binary value
is assumed if the string format is LEADING BLANKS; otherwise the
number of characters required
to
represent all digits of the
converted value is assumed.

A.3.4

Usage Guidelines

The $STR_ASCII pseudo-function may be used in the following contexts:

As the value of a
STRING= parameter or other similar
parameter of most XPORT I/O, message, and string-processing
macros

As the string
argument
pseudo-function.

$STR_CONCAT

$STR FORMAT

That is, it can be used as char-string-info except where specifically
restricted.
In general, $STR ASCII cannot be used in XPORT structure
declaration or initialization macros.

A-8

Macro Descriptions
$STR BINARY - Convert ASCII to Binary
A.4

$STR_BINARY - Convert ASCII to Binary

The $STR BINARY macro calls the XPORT STRING facility
ASCII string value into a binary value.

convert

argument and one or more
stringThe macro accepts a
string
stores the converted result at a userinterpretation options,
and
specified location.

A.4.1

Syntax

+--------------------+-----------------------------------------------+
I
I

ascii-to-binary

$STR BINARY( parameter ,...

+--------------------+-----------------------------------------------+
r'equired-parameter }
I

I parameter

I { optional-parameter}

{

+--------------------+-----------------------------------------------+
I
I { STRING = char-string-info
}
I
I

required-parameter

optional-parameter

{

= address-expression}

RESULT

+--------------------+-----------------------------------------------+
I
I { OPTION = integer-radix-keyword
}
I
I

{

RANGE = ( min-value-exp, max-value-exp )
SUCCESS = address of action routine
FAILURE = address of action routine

}
}
}

I
I
I

+--------------------+-----------------------------------------------+
integer-radixBASE2
BASE8
BASEIO
BASEl6 }
I

keyword

I
I

+--------------------+-----------------------------------------------+
address of a string descriptor}
I

char-string-info

I
I

{

'literal ascii string'
}
I { ( Ie ng th , po in t e r )
}
I
{
string conversion pseudo-function }
I

{

I
I

+--------------------+-----------------------------------------------+
A.4.2

Restrictions

A string descriptor, if specified,
must describe a
standard XPORT
string;
that
is,
the data type must be STR$K_DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A-9

Macro Descriptions
$STR BINARY - Convert ASCII to Binary
A.4.3

Parameter Semantics

STRING = char-string-info
describes the numeric character string to be converted
binary integer value. This parameter must be specified.

RESULT = address-expression
specifies the address of the location that is to receive the
converted value. The expression must denote a data segment that
is large enough to contain any value within the specified or
default value range for the conversion operation. This parameter
must be specified.
OPTION = integer-radix-keyword
indicates that the character string is to be interpreted as a
binary (BASE2), octal (BASE8), decimal (BASEIO), or hexadecimal
(BASE16)
number.
If
this
parameter
is
not
specified,
OPTION=BASEIO is assumed.
RANGE = ( min-value-exp, max-value-exp
specifies two inclusive limiting values for the result of an
integer conversion operation.
The converted value is tested
against the values yielded by the mlnlmum and maximum value
expressions.
If the result is out of range, the conversion
operation fails.
If this parameter is not specified, the numeric
value represented by the ASCII string must lie within the value
range of a fullword on the target system. That is, the value, i,
must lie in the range
-(2**(%BPVAL-l)) < i < {2**%BPVAL)-1
SUCCESS = address of action routine
specifies the address of an action routine to be called upon
successful completion of the requested operation.
If this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called if the
requested
operation
is
not successful.
If FAILURE=O is
specified, no failure action routine is called.
If
this
parameter is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).

A.4.4

Usage Guidelines

It is possible, in the RESULT parameter, to specify a result field
that is not large enough to accomodate some of the values that fall
within the range of values indicated by the RANGE parameter.
In that
case, the too-large value will be truncated when stored (i.e., highorder significance will be lost) .
A-lO

Macro Descriptions
$STR_BINARY - Convert ASCII to Binary
It is the user's responsibility to specify a result field large enough
to contain the largest value expected.

A.4.5

Completion Codes

A primary completion code is returned as the
routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the
function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
STR$ NORMAL

The ASClI-to-binary conversion was successful.

Etror Codes:
STR$ BAD REQ +
STR$=BAD=SOURCE +

The XPORT request was invalid.
The source string is invalid.

A-II

Macro Descriptions
$STR COMPARE - String Comparison
A.5

$STR COMPARE - String Comparison

The $STR COMPARE macro calls the XPORT STRING facility to compare two
character strings;
that is, to report whether the "value" of a given
string is less than, equal to, or greater than the "value" of another
given string, in the sense of their relative rank in the ASCII
collating sequence.

A.5.1

Syntax

+--------------------+-----------------------------------------------+
I
I compare-strings
I

I
I $STR COMPAREe parameter ,...
I
-

I
I
I

I
I parameter

I { requi red-parameter }
I { optional-parameter }

I
I

+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I
I { STRINGI = char-string-info }
I required-parameter I { STRING2 = char-string-info }

I
I

I
I { FILL = char-value-expression
}
I optional-parameter I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine }

I
I
I

I
I char-string-info
I
I

I
I
I
I

+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I
I
I
I

{
{
{
{

address of a string descriptor}
'literal ascii string'
}
( length , pointer)
}
string conversion pseudo-function }

+--------------------+-----------------------------------------------+
A.5.2

Restrictions

A string descriptor, if specified, must describe a standard XPORT
string;
that is, the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, ~D, _B, or _DB.
-

A.5.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared. The value of the
string described by the STRINGI parameter is compared for a lessthan, equal-to, or greater-than relationship to the value of the
string described by the STRING2 parameter. These parameters must
be specified.
A-12

Macro Descriptions
$STR COMPARE - String Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill
out the shorter of the two strings if they are of unequal
length, prior to the comparison.
The expression value must be
between 0 and 127 (decimal), inclusive.
If this parameter is not
specified, no string extension is performed.

SUCCESS = address of action routine
specifies the address of an action routine to be called
upon
successful completion of the
requested operation.
If
this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
requested operation is not successful, due
to an abnormal
condition (see A.7.S).
Note that, by its nature, an $STR COMPARE
comparison cannot fail.
If FAILURE=O is specified, no failure
action routine is called.
If this parameter
is not specified,
FAILURE=STR$FAILURE is assumed (see Appendix E).

A.S.4

Operational Semantics

A.S.S

Completion Codes

A primary completion code is returned as the routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the
function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Codes:
-1

o
+1
Error Codes:
STR$ BAD STRNGI +
STR$=BAD=STRNG2 +

String-l compared less than string-2.
String-l compared equal to string-2.
String-l compared greater than string-2.
The primary string is invalid.
The secondary string is invalid.

A-13

Macro Descriptions
$STR CONCAT - String Concatenation Pseudo-Function
A.6

$STR CONCAT - String Concatenation Pseudo-Function

The $STR CONCAT pseudo-function accepts as arguments any combination
of strings, and produces a single logical string consisting of the
concatenation of these elements.
$STR ASCII and $STR_FORMAT pseudofunctions are also accepted as $STR_CONCAT string arguments.
The "value" of a $STR CONCAT pseudo-function is the address of a
temporary string descriptor and can only be used as a string argument
wIthIn other XPORT macro calls.

A.6.1

Syntax

+--------------------+-----------------------------------------------+
I
I
I

stringconcatenation

$STR_CONCAT( parameter, parameter , •.• })

+--------------------+-----------------------------------------------+
parameter
char-string-info
+--------------------+-----------------------------------------------+
address of a string descriptor}
I

{

char-string-info

'literal ascii string'
}
(
length, pointer)
}
string conversion pseudo-function }

I
I
I

+--------------------+-----------------------------------------------+
A.6.2

Restrictions

A string descriptor, if specified, must describe a standard XPORT
string;
that
is,
the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.6.3

Parameter Semantics

Each parameter specifies an element of the logical concatenation to be
produced
as the "output string" of the pseudo-function.
The elements
are concatenated in the order of their specification.

A-14

$STR_CONCA'I

A.6.4

Macro Descriptions
String Concatenation Pseudo-Function

Usage Guidelines

The $STR_CONCAT pseudo-function may be used in the following contexts:
o

As
the value of a
STRING= parameter or other similar
parameter of most XPORT I/O, message, and string-processing
macros

As the string
argument
pseudo-function.

$STR CONCAT

$STR FORMAT

That is, it can be used as char-string-info except where specifically
restricted.
In general, $STR CONCAT cannot be used in XPORT structure
declaration or initialization-macros.

A-15

Macro Descriptions
$STR COPY - Copy a String
A.7

$STR COPY - Copy a String

The $STR COpy macro calls the XPORT STRING facility to copy a
specified source string to a target string;
that is, to replace the
contents of the target string by that of the source string.
The
target string (possibly null) must be described by a descriptor.

A.7.1

Syntax

+--------------------+----------------_._-----------------------------+
I
I string-copy
I

I
I $STR COPY ( parameter ,...
I
-

I
I
I

I parameter

I { optional-parameter }

= target-string-info

}

+--------------------+-----------------------------------------------+
I
I { OPTION = TRUNCATE
}
I
I optional-parameter I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine }

I
I

I char-string-info
I
I

I
I
I

+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
I { 'literal ascii string'
}
}
I { ( I eng th , po in te r )
I { string conversion pseudo-function }

+--------------------+-----------------------------------------------+
I
I { address of a string descriptor }
I
I target-string-info I { ( length, pointer)

}

+--------------------+-----------------------------------------------+
A.7.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
string;
that
is,
the data
type must be STR$K_DTYPE_T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.7.3

Parameter Semantics

STRING = char-string-info
describes the source character string to be copied to the target
string.
(The source string may be of any class.) This parameter
must be specified.

A-16

Macro Descriptions
$STR COpy - Copy a String
TARGET = target-string-info
describes the target string.
If the length/pointer notation is
used,
the target string is assumed to be FIXED.
This parameter
must be specified.
OPTION = TRUNCATE
indicates that (the copy of) the source string is to be truncated
as necessary if the entire string cannot be accomodated within
the target string, in the case of a FIXED target string,
or
if
the entire string cannot be accomodated within the target
container string, in the case of a BOUNDED target string.
(In
any other case this parameter is ignored.) If this parameter is
not specified and the target string is either FIXED or BOUNDED,
the copy operation will
fail
if the source string cannot be
accomodated by the target string as described above.
SUCCESS = address of action routine
specifies the address of an action routine to be called
upon
successful completion of the requested operation.
If
this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
requested
operation
is
not successful.
If
FAILURE=Q
is
specified, no
failure action routine
is called.
If
this
parameter
is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).

A.7.4

Operational Semantics

The semantics of the $STR COPY operation is as follows:
o

FIXED target string
Replace the contents of the target string with the source
string.
If
the source string
is smaller than the target
string, fill the remainder of the target string with blanks.
If
the source string is longer than the target string, the
copy operation either fails or truncates the source string to
fit, as requested ,by the user.

DYNAMIC target string
If the source string is the same size as the target string,
simply replace the target string value with the source string
value.
Otherwise, free the dynamic memory occupied by the
target string, create a copy of the source string in dynamic
memory, and update the STR$H LENGTH and STR$A POINTER fields
of the target string descriptor.

A-17

Macro Descriptions
$STR COPY - Copy a String
o

BOUNDED target string
If there is sufficient space in the target bounded and
remainder strings, replace the bounded string value with the
source string value and adjust the STR$H LENGTH field of the
target string descriptor.
If there is Tnsufficient space in
the target bounded and remainder strings, the copy operation
either truncates the source string to fit the container
string or returns an error completion code, as requested by
the user. The prefix portion of the target container string
is not modified by the copy operation.

DYNAMIC BOUNDED target string
If there is sufficient space in the target bounded and
remainder strings, replace the bounded string value with the
source string value and adjust the STR$H LENGTH field of the
target string descriptor.
If there is Insufficient space in
the target bounded and remainder strings, create a larger
container string in dynamic memory, copy the prefix portion
from the original container string and the source string into
the new container string, free the original container string,
and update the STR$H LENGTK, STR$A POINTER and STR$H MAXLEN
fields of the target-string descriptor.
-

(FIXED,
A detailed discussion of the descriptor/string classes
DYNAMIC, BOUNDED, and DYNAMIC-BOUNDED) appears in Section 6.xxxxx.

A.7.5

Completion Codes

A primary completion code is returned as the routine-call value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action routine associated with the function.
Secondary
comp~etion
codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
XPO$ NORMAL

The string-copy operation was successful.

Error Codes:
STR$ BAD SOURCE +
STR$-BAD-TARGET +
XPO $-FREE MEM +
XPO $-GET MEM +

The source string is invalid.
The target string is invalid.
Dynamic memory deallocation error occured.
Dynamic memory allocation error occured.

A-I8

Macro Descriptions
$STR DESCRIPTOR - Declare a String Descriptor
A.B

$STR DESCRIPTOR - Declare a String Descriptor

The $STR DESCRIPTOR macro generates an attribute list for
a
string
descriptor within an OWN,
GLOBAL,
LOCAL, MAP or BIND declaration.
These attributes (1) indicate that the descriptor is a BLOCK structure
of a given length, (2) specify the set of field-names that can be used
tor e fer en c e po r t ion s 0 f
the d esc rip tor ,
and
(3 )
s p e c i f yin i t i a 1
descriptor-field values.
A detailed description of the four
dynamic, bounded, and dynamic-bounded)

types of descriptors
appears in Section 6.1.

(fixed,

A descriptor must be initialized before
it can be used.
If
the
descriptor
is declared within an OWN or GLOBAL declaration, the
descriptor can be statically initialized.
Otherwise,
it must be
initialized by use of the $STR_DESC IN IT macro.

A.B.l

Syntax

+--------------------+-----------------------------------------------+
I
I
I

declare-a-stringdescriptor

$STR_DESCRIPTOR({optional-parameter , •.• })

+--------------------+-----------------------------------------------+
I

optional-parameter

{

CLASS = class-keyword}
STRING = char-string-info }

I
I

+--------------------+-----------------------------------------------+
I

class-keyword

{

FIXED I D Y N A M I C }
BOUNDED I DYNAMIC BOUNDED}

I
I

+--------------------+--------------------=--------------------------+
I

char-string-info

'literal ascii string'
(
count , pointer)

}
}

I
I

+--------------------+-----------------------------------------------+
A.B.2

Restrictions

The STRING parameter may only be specified within
declaration.

A.B.3

OWN

GLOBAL

Parameter Semantics

CLASS = class-keyword
indicates the class of descriptor being declared.
See Section
6.1 for
a complete description of the descriptor classes.
If
this parameter is not specified, CLASS=FIXED is assumed.

A-19

Macro Descriptions
$STR DESCRIPTOR - Declare a String Descriptor
STRING = char-string-info
describes the character string to be described by the descriptor.
If
this parameter
is not specified,
the descriptor
is not
statically initialized.

A-20

Macro Descriptions
$STR_DESC_INIT - Initialize a String Descriptor
A.9

$S'I'R_DESC_INIT - Initialize a String Descriptor

The $STR DESC INIT macro dynamically initializes a string descriptor;
that
is~
thTs macro generates the executable code necessary to
initialize all of the fields of a given descriptor.

A.9.1

Syntax

+--------------------+-----------------------------------------------+
I
I
I setup-a-descriptor I $STR DESC INIT( parameter , ••. )
I
I

I
I
I

+--------------------+-----------------------------------------------+
I parameter
I { requi red-parameter }
I
I { optional-parameter }

+--------------------+-----------------------------------------------+
I required-parameter I DESCRIPTOR = address of descriptor
I
+--------------------+-----------------------------------------------+
I
I { CLASS = class-keyword}
I
I optional parameter I { STRING = char-string-info }

+--------------------+--------------------------~--------------------+

I class-keyword
I

I { FIXED I D Y N A M I C }
I { BOUNDED I DYNAMIC BOUNDED }

I
I

I
I char-string-info
I

I { address of a descriptor}
I { 'literal ascii string'
}
I { ( count , p o i n t e r ) }

I
I
I

+--------------------+--------------------=--------------------------+
+--------------------+-----------------------------------------------+
A.9.2

Restrictions

The STRING parameter may not be used when initializing
DYNAMIC BOUNDED descriptor.

A.9.3

DYNAMIC

Parameter Semantics

DESCRIPTOR = address of descriptor
specifies the address of the descriptor to be initialized.
parameter must be specified.

This

CLASS = class-keyword
indicates the class of descriptor being initialized.
See Section
6.1 for
a
complete description of the descriptor classes.
If
this parameter is not specified, CLASS=FIXED is assumed.

A-21

Macro Descriptions
$STR DESC INIT - Initialize a String Descriptor
STRING = char-string-info
describes the character string to be described by the descriptor.
If
this parameter is not specified, the corresponding descriptor
fields are not initialized.

A.9.4

Completion Code

Success Code:
XPO$_NORMAL

The descriptor was successfully initialized.

A-22

Macro Descriptions
$STR_EQL - String Equality Comparison
A.ID

$STR_EQL - String Equality Comparison

The $STR EQL macro calls the XPORT STRING facility to compare two
character strings for equality; that is, to report whether or not two
specified strings are identical in "value".
Unequal length strings
are not automatically adjusted for length.

A.ID.I

Syntax

+--------------------+-----------------------------------------------+
I
I compare-for-equal
I

I
I $STR EQL ( parameter ,...
I

I
I
I

I parameter

I { optional-parameter }

I optional-parameter I { SUCCESS = address of action routine }
I
I { FAILURE = address of action routine }

I
I

I char-str ing- info
I
I

I
I
I

+--------------------+-----------------------------------------------+
I
I { FILL = char-value-expression
}
I
+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
I { I literal asc i i str ing I
}
}
I { ( length , pointer)
I { string conversion pseudo-function }

+--------------------+-----~-----------------------------------------+

A.ID.2

Restrictions

A string descriptor, if specified, must describe a standard XPORT
string;
that is, the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.ID.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to
These parameters must be specified.

A-23

compared

for

equality.

Macro Descriptions
$STR_EQL - String Equality Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill out the shorter of the two strings if they are of unequal
length, prior to the comparison. The expression value must be
between 0 and 127 (decimal), inclusive. If this parameter is not
specified, no string extension is performed.

SUCCESS = address of action routine
specifies the address of an action routine to be called upon
successful completion of the comparison operation.
If this
parameter is not specified, no success action routine is assumed.
NOTE: A comparison failure is
ope rat ion.

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called if the
comparison
operation
is not successful.
If FAILURE=O is
specified, no failure action routine is called.
If
this
parameter is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE: A $STR_EQL operation will fail only if an input string or
FILL value is invalid.
An unsuccessful comparison does not
constitute an operation failure.

A.IO.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
length and the content, if any, of a string. The value of the null
string, for example, having a length of zero, is not the same as the
value of a string consisting of a NUL character.
No automatic adjustment for strings of unequal length is performed.
Optionally, however, the shorter of two unequal-length strings can be
logically padded "on the right" with a specified fill character.
The comparison operation returns a val ue of 1 if the requested
comparison is satisfied, and a value of 0 if the comparison is
unsatisfied.
If the comparison operation itself fails (e.g., due to an invalid
string descriptor), the operation returns an error completion code
(which always has a low-bit value of 0), unless program execution is
automatically terminated by a failure-action routine.

A-24

Macro Descriptions
$STR_EQL - String Equality Comparison
A.IO.S

Completion Codes

A primary completion code is returned as the
routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
I

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$=BAD=STRNG2 +

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-25

Macro Descriptions
$STR FORMAT - String Formatting Pseudo-Function
A.II

$STR FORMAT - String Formatting Pseudo-Function

The $STR FORMAT pseudo-function accepts a string argument and produces
a
reformatted or otherwise transformed logical string as a result.
$STR ASCII and $STR CONCAT pseudo-functions are also accepted
as
$STR=FORMAT string arguments.
The "value" of a $STR FORMAT pseudo-function is the address of a
temporary string descriptor and can only be used as a string argument
within other XPORT macro calls.

A.II.I

Syntax

+--------------------+-----------------------------------------------+
I
I

string-formatting

$STR FORMAT( string-param, format-param, ••• )
-

I
I

+--------------------+-----------------------------------------------+
string-param
char-string-info
+--------------------+-----------------------------------------------+
format-param
editing-keyword}
I

{

string-Iength-parameter }

+--------------------+-----------------------------------------------+
editing-keyword
LEFT JUSTIFY
CENTER
RIGHT JUSTIFY }
I

UP CASE

+--------------------+-----=-----------------------------------------+
string-IengthLENGTH = length-expression
I

parameter

{

char-string-info

{

+--------------------+-----------------------------------------------+
address of a string descriptor}
I

'literal ascii string'
}
(
length, pointer)
}
string conversion pseudo-function }

I
I
I

+--------------------+-----------------------------------------------+
A.II.2

Restrictions

A string descriptor, if specified, must describe a standard XPORT
string;
that
is,
the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_Fu _D, _B, or DB.
The keyword alternatives shown on a single line in the syntax
are mutually exclusive.

A-26

diagram

Macro Descriptions
$STR FORMAT - String Formatting Pseudo-Function
A.II.3

Parameter Semantics

string-param
specifies
string".

the

string

that

the

pseudo-function's

"input

LEFT JUSTIFY, CENTER, or RIGHT JUSTIFY
indicates a string positioning.option, as follows:
o

LEFT JUSTIFY indicates that the first non-blank character of
the "input string"
is to begin in the first character
position of the logical output string. Any unused
trailing
character positions are blank-filled.

CENTER indicates that the non-blank portion of the "input
string"
is to be centered in the logical output string, with
unused leading and trailing character positions blank-filled.

RIGHT JUSTIFY indicates
that
the
rightmost
non-blank
character of the
"input string"
is to appear in the last
character position of the logical output string.
Any unused
leading character positions are blank-filled.

If a positioning option is to be meaningful,
the
result string
must be longer
than the
input string
(see LENGTH=).
If a
positioning option is not specified, LEFT_JUSTIFY is assumed.
UP CASE
indicates that all alphabetic characters in the "input string"
are to appear as uppercase in the logical output string.
If this
option is not specified, no case conversion is performed.
LENGTH = length-expression
specifies the length of the logical output string,
i.e.,
the
number of character positions to be produced in the result.
If
the specified output-string length is less than the
input-string
length, the output string is set to all asterisks (~ la FORTRAN).
If this parameter is not specified, the output string is assumed
to be th€ same length as the input string.

A.II.4

Usage Guidelines

The $STR_FORMAT pseudo-function may be used in the following contexts:

As the value of a
STRING= parameter or other similar
parameter of most XPORT I/O, message, and string-processing
macros

A-27

Macro Descriptions
$STR FORMAT - String Formatting Pseudo-Function
o

As the string argument of a $STR_CONCAT pseudo-function.

That is, it can be used as char-string-info except where specifically
restricted.
In general, $STR FORMAT cannot be used in XPORT structure
declaration or initialization-macros.

A-28

Macro Descriptions
$STR_GEQ - String Greater-Than-or-Equal Comparison
A.12

$STR_GEQ - String Greater-Than-or-Equal Comparison

The $STR GEQ macro calls the XPORT STRING facility to compare two
character strings for a greater-than-or-equal relationship; that is,
to report whether or not the "value" of a given string is either
greater than or equal to the "value" of another given string, in the
sense of their relative rank in the ASCII collating sequence. Unequal
length strings are not automatically adjusted for length.

A.12.1

Syntax

+--------------------+-----------------------------------------------+
I
compare-forI $STR GEQ( parameter , •••
greater-or-equal I
I

+--------------------+-----------------------------------------------+
I
I { requi red-parameter }
I
I

parameter

{

optional-parameter }

+--------------------+-----------------------------------------------+
STRINGI = char-string-info }
I

I required-parameter I { STRING2 = char-string-info }

+--------------------+-----------------------------------------------+
FILL = char-value-expression
}
I

{

I optional-parameter I { SUCCESS = address of action routine }
I
I
{
FAILURE = address of action routine }

+--------------------+-----------------------------------------------+
address of a string descriptor}
I

char-string-info

{

'literal ascii string'
}
I { ( length , pointer)
}
I
{
string conversion pseudo-function }
I

{

I
I

+--------------------+-----------------------------------------------+
A.12.2

Restrictions

A string descriptor, if specified, must describe a standard XPORT
string;
that is, the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.12.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared. If the value of
the string described by the STRINGI parameter is greater than or
equal to the value of string described by the STRING2 parameter,
the comparison is satisfied;
otherwise the comparison is not
satisfied. These parameters must be specified.
A-29

Macro Descriptions
$STR_GEQ - String Greater-Than-or-Equal Comparison
FILL

SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful
completion of the comparison operation.
If this
parameter is not specified, no success action routine is assumed.
NOTE:
A comparison failure is
operation.

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
comparison
operation
is not successful.
If
FAILURE=O
is
specified,
no
failure
action
routine
is called.
If
this
parameter
is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE:
A $STR_GEQ operation will fail only if an input string or
FILL value
is
invalid.
An
unsuccessful comparison does not
constitute an operation failure.

A.12.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
length and
the content, if any, of a string.
The value of the null
string, for example, having a length of zero, is not the same as
the
value of a string consisting of a NUL character.
No automatic adjustment for strings of unequal
length
is perform~d.
Optionally,
however, the shorter of two unequal-length strings can be
logically padded "on the right" with a specified fill character.
The comparison operation returns a value of 1 if
the
requested
comparison
is satisfied,
and
a value of 0 if the comparison is
unsatisfied.
If the comparison operation itself fails
(e.g.,
due to an
invalid
string
descriptor),
t.he operation returns an error completion code
(which always has a low-bit value of 0), unless program execution is
automatically terminated by a failure-action routine.

A-30

Macro Descriptions
$STR_GEQ - String Greater-Than-or-Equal Comparison
A.12.S

Completion Codes

A primary completion code is returned as the
routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated
with
the
function.
Secondary
completion codes,
where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
I

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$=BAD=STRNG2 +

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-31

Macro Descriptions
$STR GTR - String Greater-Than Comparison
A.I3

$STR GTR - String Greater-Than Comparison

The $STR GTR macro calls the XPORT STRING facility to compare two
charactei strings f~r a greater-than relationship;
that is, to report
whether or not the "value" of a given string
is greater
than the
"value"
of another given string, in the sense of their relative rank
in the ASCII collating
sequence.
Unequal
length strings are not
automatically adjusted for length.

A.13.1

Syntax

+--------------------+-----------------------------------------------+
I
I compare-forI
greater-than
I

I
I $STR_GTR ( parameter ,...
I
I

I
I
I
I

I parameter

I { optional-parameter}

I optional-parameter I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine }

I
I

I char-string-info
I
I

I
I
I

+--------------------+-----------------------------------------------+
I
I { FILL = char-value-expression
}
I
+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
I { 'literal ascii string'
}
I { ( length , pointer)
}
I { string conversion pseudo-function }

+--------------------+-----------------------------------------------+
A.13.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
string;
that
is,
the data type must be STR$K_DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.13.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared.
If the value of
the string described by the STRINGI parameter is greater than the
value of string described by the STRING2
parameter,
the
comparison
is
satisfied;
otherwise
the
comparison
is
unsatisfied.
These parameters must be specified.
A-32

Macro Descriptions
$STR GTR - String Greater-Than Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill out the shorter of the two strings if they are of unequal
length, prior to the comparison. The expression value must be
between 0 and 127 (decimal), inclusive. If this parameter is not
specified, no string extension is performed.

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called if the
comparison
operation
is not successful.
If FAILURE=O is
specified, no failure action routine is called.
If
this
parameter is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE: A $STR_GTR operation will fail only if an input string or
FILL value is invalid.
An unsuccessful comparison does not
constitute an operation failure.

A.13.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
length and the content, if any, of a string. The value of the null
string, for example, having a length of zero, is not the same as the
value of a string consisting of a NUL character.
No automatic adjustment for strings of unequal length is performed.
Optionally, however, the shorter of two unequal-length strings can be
logically padded "on the right" with a specified fill character.
The comparison operation returns a value of 1 if the requested
comparison is satisfied, and a value of 0 if the comparison is
unsatisfied.
If the comparison operation itself fails
(e.g., due to an invalid
st ring desc r i pto r), the ope ra t ion ret urns an e r ro r compl et ion code
(which always has a low-bit value of 0), unless program execution is
automatically terminated by a failure-action routine.

A-33

Macro Descriptions
$STR GTR - String Greater-Than Comparison
A.13.S

Completion Codes

A primary completion code is returned as the
routine-call value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
1

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$-BAD-STRNG2 +

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-34

Macro "Descriptions
$STR_LEQ - String Less-Than-or-Equal Comparison
A.14

$STR_LEQ - String Less-Than-or-Equal Comparison

The $STR_LEQ macro calls the XPORT STRING facility to compare two
character
strings for a less-than-or-equal relationship;
that is, to
report whether or not the "value" of a given string is less than or
equal
to
the "value" of another given string, in the sense of their
relative rank in the ASCII collating sequence.
Unequal length strings
are not automatically adjusted for length.

A.14.1

Syntax

+--------------------+-----------------------------------------------+
I
I compare-for-IessI
than-or-equal
I

I
I $STR_LEQ( parameter ,...
I
I

I
I
I
I

I parameter

I { optional-parameter }

I optional-parameter I { SUCCESS = address of action routine }
I
I { FAILURE = address of actio~ routine }

I
I

I char-string-info
I
I

I
I
I

+--------------------+-----------------------------------------------+
I
I { FILL = char-value-expression
}
I
+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
I { 'literal ascii string'
}
I { ( length , pointer)
}
I { string conversion pseudo-function }

+--------------------+-----------------------------------------------+
A.14.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
string;
that
is,
the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _8, or DB.

A.14.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared.
If the value of
the string described by the STRINGI parameter is less than or
equal to the value of string described by the STRING2 parameter,
the
comparison
is satisfied;
otherwise the comparison is
unsatisfied.
These parameters must be specified.
A-35

Macro Descriptions
$STR_LEQ - String Less-Than-or-Equal Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill out the shorter of the two strings if they are of unequal
length, prior to the comparison. The expression value must be
between 0 and 127 (decimal), inclusive. If this parameter is not
specified, no string extension is performed.

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called if the
comparison
operation
is not successful.
If FAILURE=O is
specified, no failure action routine is called.
If
this
parameter is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE: A $STR LEQ operation will fail only if an input string or
FILL value Is invalid.
An unsuccessful comparison does not
constitute an operation failure.

A.14.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
length and the content, if any, of a string. The value of the null
string, for example, having a length of zero, is not the same as the
value of a string consisting of a NUL character. No automatic
adjustment for strings of unequal length is performed.
Optionally,
however, the shorter of two unequal-length strings can be logically
padded "on the right" with a specified fill character.
The comparison operation returns a value of 1 if the requested
comparison is satisfied, and a value of 0 if the comparison is
unsatisfied.
If the comparison operation itself fails
(e.g., due to an invalid
str i ng desc r i pto r), the ope ra t ion ret urns an e rro r compl et ion cod e
(which always has a low-bit value of 0), unless program execution is
automatically terminated by a failure-action routine.

A-36

Macro Descriptions
$STR_LEQ - String Less-Than-or-Equal Comparison
A.14.S

Completion Codes

A primary completion code is returned as the routine-call value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
I

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$-BAD-STRNG2 +
-

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-37

Macro Descriptions
$STR LSS - String Less-Than Comparison
A.IS

$STR_LSS - String Less-Than Comparison

The $STR LSS macro calls the XPORT STRING facility to compare two
character strings for
a less-than relationship;
that is, to report
whether or not the "value" of a given string is less than the "value"
of another given string, in the sense of their relative rank in the
ASCII
collating
sequence.
Unequal
length
strings
are
not
automatically adjusted for length.

A.IS.I

Syntax

+--------------------+----------------------------------------,-------+
I
I compare-for-Iessthan
I
I

I
I $STR_LSS { parameter ,...
I
I

I
I
I
I

I parameter

I { optional-parameter}

I optional-parameter I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine }

I
I

I char-string-info
I
I

I
I
I

+--------------------+-----------------------------------------------+
I
I { FILL = char-value-expression
}
I
+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
I { 'literal ascii string'
}
I { ( length, pointer)
}
I { string conversion pseudo-function }

+--------------------+-----------------------------------------------+
A.IS.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
str ing;
tha t i s ,
the data type must be STR$K_DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.IS.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared.
If the value of
the string described by the STRINGI parameter is less than the
value of string described by the STRING2
parameter,
the
comparison
is
satisfied;
otherwise
the
comparison
is
unsatisfied.
These parameters must be specified.
A-38

Macro Descriptions
$STR LSS - String Less-Than Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill
out
the shorter of the two strings if they are of unequal
length, prior to the comparison.
The expression value must be
between 0 and 127 (decimal), inclusive.
If this parameter is not
specified, no string extension is performed.

SUCCESS = address of action routine
specifies the address of an action
routine to
be called
upon
successful
completion of the comparison operation.
If this
parameter is not specified, no success action routine is assumed.
NOTE:
A comparison failure is
ope ration.

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
comparison
operation
is not successful.
If
FAILURE=O
is
specified,
no
failure
action
routine
is called.
If
this
parameter
is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE:
A $STR LSS operation will fail only if an input string
or
FILL value Is
invalid.
An
unsuccessful
comparison does not
constitute an operation failure.

A.1S.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
length
and
the content, if any, of a string.
The value of the null
string, for example, having a length of zero, is not the same as
the
value
of a
string consisting of a
NUL character.
No automatic
adjustment for strings of unequal length
is performed.
Optionally,
however,
the
shorter of two unequal-length strings can be logically
padded "on the right" with a specified fill character.
the
requested
The comparison operation returns a value of 1 if
comparison
is satisfied,
and
a value of 0 if the comparison is
unsatisfied.
If the comparison operation itself fails
(e.g.,
due
to an
invalid
string descriptor),
the operation returns an error completion code
(which always has a low-bit value of 0), unless program execution
is
automatically terminated by a failure-action routine.

A-39

Macro Descriptions
$STR LSS - String Less-Than Comparison
A.IS.S

Completion Codes

A primary completion code is returned as the
routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the
function.
Secondary
completion codes,
where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
I

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$-BAD-STRNG2 +
-

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-40

Macro Descriptions
$STR_NEQ - String Inequality Comparison
A.16

$STR_NEQ - String Inequality Comparison

The $STR NEQ macro calls the XPORT STRING facility to compare two
character strings for
a not-equal relationship;
that is, to report
whether or not the "values" of two given string are not equal to each
other.
Unequal
length strings are not automatically adjusted for
leng th.

A.16.1

Syntax

+--------------------+-----------------------------------------------+
compare-fo r-notequal

I
I $STR NEQ( parameter , •••
I
I

+--------------------+-----------------------------------------------+
requi red-parameter }
I

{

parameter

{

required-parameter

{

optional-parameter

{

optional-parameter }

+--------------------+-----------------------------------------------+
STRINGI = char-string-info }
I

STRING2

= char-string-info }

+--------------------+-----------------------------------------------+
FILL = char-value-expression
}
I

I
I

SUCCESS = address of action routine }
FAILURE = address of action routine }

I
I

+--------------------+-----------------------------------------------+
address of a string descriptor}
I

char-string-info

'literal ascii string'
}
(
length , pointer)
}
string conversion pseudo-function }

I
I
I

+--------------------+-----------------------------------------------+
A.16.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
string;
that
is,
the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_F, _D, _B, or DB.

A.16.3

Parameter Semantics

STRINGI = char-string-info
STRING2 = char-string-info
describe the character strings to be compared for inequality.
If
the value of the two strings are not equal, the comparison is
satisfied;
otherwise the comparison
is unsatisfied.
These
parameters must be specified.

A-41

Macro Descriptinns
$STR_NEQ - String Inequality Comparison
FILL

char-value-expression
specifies an ASCII character-code value to be used to (logically)
fill
out
the shorter of the two strings if they are of unequal
length, prior to the comparison.
The expression value must be
between 0 and 127 (decimal), inclusive.
If this parameter is not
specified, no string extension is performed.

SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful completion of the comparison operation.
If this
parameter is not specified, no success action routine is assumed.
NOTE:
A comparison failure is
ope ra t ion".

considered

successful

FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
comparison
operation
is not successful.
If
FAILURE=O
is
specified,
no
failure
action
routine
is called.
If
this
parameter
is not specified, FAILURE=STR$FAILURE is assumed (see
Appendix E).
NOTE:
A $STR NEQ operation will fail only if an input string or
FILL value IS
invalid.
An
unsuccessful
comparison does not
constitute an operation failure.

A.16.4

Operational Semantics

The notion of "value" in the string-handling context includes both the
1 eng th
an d
th e
con ten t, i fan y, 0 f a s t ring • Th e val u e 0 f the null
string, for example, having 8 length of zero, is not the same as
the
value
of a
string
consisting
of a
NUL character.
No automatic
adjustment for strings of unequal length
is performed.
Optionally,
however,
the
shorter of two unequal-length strings can be logically
padded "on the right" with a specified fill character.
The comparison operation returns a value of 1 if
the
requested
comparison
is satisfied,
and
a value of 0
if the comparison is
unsatisfied.
If the comparison operation itself fails
(e.g.,
due to an
invalid
string
descriptor),
the operation
returns an error complet.ion code
(which always has a low-bit value of 0), unless program execution
is
automatically terminated by a failure-action routine.

A-42

Macro Descriptions
$STR_NEQ - String Inequality Comparison
A.16.S

Completion Codes

A primary completion code is returned as the
routine-call
value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
I

The comparison was successful.

Warning Code:

Error Codes:
STR$ BAD STRNGI +
STR$-BAD-STRNG2 +
-

The comparison was not successful.
The primary string is invalid.
The secondary string is invalid.

A-43

Macro Descriptions
$STR_SCAN - String Scanning
A.17

$STR SCAN - String Scanning

The $STR SCAN macro calls the XPORT STRING facility to scan a string
in order to determine a given portion, or substring, of that string.
The substring to be determined can be specified by different types of
pattern strings.

A.17.I

Syntax

+--------------------+-----------------------------------------------+
I
I scan-string
I

I
I $STR SCAN( parameter ,...
I
-

I { optional-parameter}

I { pattern-string }

I { REMAINDER = address-of-a-descriptor }

I pattern-string
I

I { SPAN = char-string-info }
I { STOP = char-string-info }

I
I

+--------------------+-----------------------------------------------+
I parameter
I { requi red-parameter }
I
+--------------------+-----------------------------------------------+
I required-parameter I {source-string }
I
+--------------------+-----------------------------------------------+
I source-string
I { STRING = char-string-info
}
I
+--------------------+-----------------------------------------------+
I
I {FIND
char-string-info}
I
+--------------------+-----------------------------------------------+
I
I { resul t-parameter
}
I
I
I { DELIMITER = address
}
I optional-parameter I { SUCCESS = address of action routine }
I
I { FAILURE = address of action routine}

I
I
I

I { TARGET = descriptor a d d r e s s }

I char-string-info
I
I

I { 'literal ascii string'
}
I { ( length , pointer)
}
I { string conversion pseudo-function }

I
I
I

+--------------------+-----------------------------------------------+
I result-parameter
I { SUBSTRING = descriptor address }
I
+--------------------+-----------------------------------------------+
I
I { address of a string descriptor}
I
+--------------------+-----------------------------------------------+
A.17.2

Restrictions

A string descriptor, if specified, must describe a
standard XPORT
string;
that
is,
the data type must be STR$K DTYPE T, and the
descriptor class must be STR$K_CLASS_r', _D, _B, or DB.
The char-string-info of the STRING= parameter must not be a string
conversion pseudo-function if the SUBSTRING= parameter is specified.
A-44

Macro Descriptions
$STR SCAN - String Scanning
If REMAINDER is specified, the source-string descriptor class must
BOUNDED or DYNAMIC BOUNDED only.

The STRING= and SUBSTRING= parameters
descriptor.

must

not

point

the

same

The STRING=
descriptor.

must

not

point

the

same

and

TARGET=

parameters

If SUBSTRING= is specified, the substring
FIXED or BOUNDED only.

descriptor

The pattern string must not be the null string
string.)

A.17.3

(i.e.,

class
a

must

zero-length

Parameter Semantics

STRING = char-string-info
describes the character string
to be scanned.
The precise
semantics
of
the
scan
operation
is determined by the
pattern-string parameter employed.
Either this parameter or
the
REMAINDER parameter must be specified.
REMAINDER = descriptor address
specifies the address of the descriptor of a bounded or dynamicbounded string
of which the remainder portion is to be scanned.
The precise semantics of the scan operation is determined by the
type of pattern-string parameter employed.
Either this parameter
or the STRING parameter must be specified.
FIND = char-string-info
specifies a particular sequence of characters to
within the source string.
If the specified character
found anywhere in the string the scan operation is
Otherwise, the operation is not successful.
Either a
or STOP parameter must be specified.

be located
sequence is
successful.
FIND, SPAN,

SPAN = char-string-info
specifies the list of characters that may occur in the substring
to be located within the source string.
The semantics of the
SPAN-type scan operation is given in Section A.17.4.
Either a
SPAN, FIND, or STOP parameter must be specified.
STOP = char-string-info
specifies the list of characters that may not occur
in the
substring
to be located within the source string.
The semantics
of the STOP-type scan operation is given
in Section A.17.4.
Either a STOP, FIND, or SPAN parameter must be specified.

A-45

Macro Descriptions
$STR SCAN - String Scanning
DELIMITER = address
specifies a
location in which to
store the character that
"stopped" the scan operation;
that is, the character immediately
following the substring determined by the operation.
If
the
string scan operation fails, the delimiter location is unchanged.
If the substring extends to the end of the source string,
a
NUL
character is returned.
If this parameter is not specified, the
delimiter character is not reported.
SUBSTRING = descriptor address
specifies a descriptor that is to be modified
substring determined by the scan operation.
operation fails, the substring descriptor
is
this parameter
is not specified, substring
reported.
The use of the SUBSTRING parameter
the use of the $STR DESC INIT macro.

to describe the
If the string scan
not changed.
If
information is not
is equivalent to

TARGET = descriptor address
specifies the descriptor that
is to describe a copy of the
substring
obtained by the scan operation.
If the string scan
operation fails, the target descriptor is not changed.
If
this
parameter is not specified, no copy of the substring is provided.
The use of the TARGET parameter is equivalent to the use of the
$STR COpy macro.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful completion of the scan operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
scan operation is not successful due to an abnormal condition
(see Section A.17.5).
Note that an unsuccessful
scan does not
trigger a failure-action routine.
If FAILURE=Q is specified, no
failure action routine is called.
If
this parameter
is not
specified, FAILURE=STR$FAILURE is assumed (see Appendix E).

A.17.4

Operational Semantics

If the patt~rn-string parameter keyword is FIND,
the scan operation
attempts
to
find
a match for the specified pattern anywhere in the
source string, beginning with the
first character position of the
string.
If
such a match is found, the scan operation returns a lowbit value of 1 (STR$ NORMAL, or STR$ END STRING if the scan ends at
end of line).
If no match is found~ the operation returns a value of
Q.

A-46

Macro Descriptions
$STR_SCAN - String Scanning
If the pattern-string parameter keyword is SPAN,
the scan operation
determines the longest substring
that
(1)
begins at the first
character position of the string and (2) consists of anyone or more
of the characters specified in the pattern string and only of those
characters. The SPAN-type scan operation may validly determine a
substring of zero length,
that is,
the null string.
This scan
operation always returns a low-bit value of 1
(STR$ NORMAL,
or
STR$ END STRING if the scan ends at end of line), unless the operation
itself fails due to an abnormal condition (see Section A.17.5).
If the pattern-string parameter keyword is STOP,
the scan operation
determines
the longest substring
that
(1)
begins at the first
character position of the string and (2) does not contain any of the
characters specified
in the pattern string.
The STOP-type scan
operation may validly determine a substring of zero length,
that
is,
the null
string.
This scan operation always returns a low-bit value
of 1 (STR$ NORMAL, or STR$ END STRING if the scan ends at end of
line),
unless the operation itself fails due to an abnormal condition
(see Section A.17.5).
If the same BOUNDED or DYNAMIC BOUNDED descriptor is specified as both
a REMAINDER= and a SUBSTRING= parameter, the typical operation of
"scan thru a string" can be achieved.

A.17.5

Completion Codes

A primary completion code is returned as the routine-call value.
A
secondary
completion
code
(if
any)
is available only in a
failure-action
routine associated with the function.
Secondary
completion codes, where applicable, are indicated by a plus sign (+)
following the corresponding primary code in the listing below.
Success Code:
STR$ NORMAL
STR$=END_STRING

The scan operation was successful.
The scan operation was successful, and the
SPAN-type operation ended at end-of-line.

Warning Code:
STR$_FAILURE

The scan operation was unsuccessful.

Error Codes:
STR$ BAD PATTRN +
STR$-BAD-SOURCE +
STR$-BAD-TARGET +
-

The pattern string is invalid.
The source string is invalid.
The target string is invalid.

A-47

Macro Descriptions
$XPO BACKUP - Preserve an Input File
A.IB

$XPO BACKUP - Preserve an Input File

The $XPO BACKUP macro calls the XPORT I/O facility to perform a
"file
backup" -operation
in a
transportable manner.
This capability is
intended for applications which create an output file with the
same
name as the input file from which it was created (e.g., an editor).
If the host operating-system supports multiple versions of a
file
(e.g., VAX/VMS, RSX-IIM), the output file is renamed to be the same as
the input file except that its version number is one greater than the
highest existing version.
The input file is not renamed.
If the host system does not support multiple versions of a file (e.g.,
TOPS-la,
TOPS-20,
RT-II),
first, a previous backup file, if any, is
deleted.
The
input file
is
then renamed by changing
the
file
extension/type.
Finally,
the output file is then renamed to be the
same as the original name of the input file.

A.IB.I

Syntax

+--------------------+-----------------------------------------------+
"I
1
1

1
1
1

$XPO BACKUP ( parameter , ••• )

{

optional-parameter }

{

NEW=IOB

{

FILE TYPE = char-string-info
}
SUCCESS = address of action routine }
FAILURE = address of action routine}

I char-string-info
I

I { 'literal ascii string'
I { ( count , pointer)

preserve a file

1
1
1

+--------------------+-----------------------------------------------+
1 parameter
1 { requi red-parameter }
1
1

+--------------------+-----------------------------------------------+
1 required-parameter 1 { OLD lOB = address of iob }
1
= add ress 0 f

iob }

+--------------------+-----------------------------------------------+
1
1

optional-parameter

1
I

+--------------------+-----------------------------------------------+
I
1 { address of character-string descriptor}
I
}
}

I
I

+--------------------+-----------------------------------------------+
A.IB.2

Parameter Semantics

OLD lOB = address of lOB
specifies the address of the lOB that describes the
input file.
This
file must be in a closed state, and must have been closed
with the REMEMBER option.
The resultant-file-specification field
of this
lOB
is cleared on completion of the backup operation.
This parameter must be specified.
A-4B

Macro Descriptions
$XPO BACKUP - Preserve an Input File
NEW lOB = address of lOB
specifies the address of the lOB that describes the output file.
This
file must be in a closed state, and must have been closed
with the REMEMBER option.
The resultant-file-specification field
of this
lOB
is cleared on completion of the backup operation.
This parameter must be specified.
FILE TYPE = character-string-info
-describes a file type, or extension, to be used
for
input-file
renaming
if
the
input file cannot be preserved using version
numbers.
The file-type string must include the 'dot' (.) and may
not contain any other parts of a file specification.
If this
parameter is not specified, FILE_TYPE=' .BAK' is assumed.
SUCCESS = address of action routine
specifies the address of an action routine to be called upon
successful completion of the backup operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
backup operation is unsuccessful.
If FAILURE=O is specified, no
failure action routine is called.
If
this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.S).

A.IS.3

Usage Guidelines

The backup operation requires a valid
resultant-file-specification
field
in both lOBs.
This requirement can be satisfied by using the
REMEMBER option of the CLOSE- operation (see A.19).
Note that REMEMBER
is implied for a file specified as $XPO_TEMPORARY.
The backup operation is invalid for files that have never been opened.

A.IS.4

Completion Codes

A primary completion code is returned as the routine-call value, and
is also available in the
IOB$GCOMP CODE field of the
lOB.
A
secondary completion code (if any) Is available in the
IOB$G 2ND CODE
field
of the lOB.
Secondary completion codes, where applicable~ are
indicated by a plus sign (+) following the associated primary code in
the
listing
below.
The secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.

A-49

all

Macro Descriptions
$XPO BACKUP - Preserve an Input File
Success Code:
XPO$ NORMAL

The file backup was successful.

Error Codes:
XPO$ BACKUP +
XPO$-BAD RSLT +
XPO $-BAD-TYPE
XPO$-DELETE +
XPO $-NOT CLOSED
XPO$-RENAME NEW +
XPO$-RENAME-OLD +
-

File could not be backed up.
The old or new file-spec is invalid.
The backup file-type is invalid.
Error deleting a previous backup copy.
One of the lOBs was not closed.
Error renaming the output file.
Error renaming the input file.

Fatal Error Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC
-

One of the lOBs is invalid.
An XPORT logic error was detected.

A.IB.S

Example

The
following
BLISS coding
example
illustrates the sequence
operations which should be followed in using $XPO BACKUP.
$XPO OPEN ( lOB
$XPO=OPEN( lOB

= input-iob, FILE SPEC = input-spec, .•• );
= output-iob, FILE_SPEC = $XPO_TEMPORARY,

Process information from the input file, and
write it to the (temporary) output file.
$XPO CLOSE( lOB
$XPO=CLOSE( lOB

= input-iob, OPTIONS = REMEMBER );
= output-iob );

$XPO_BACKUP( OLD lOB

= input-iob, NEW lOB

A-50

output-iob );

);

Macro Descriptions
$XPO CLOSE - Close a File
A.19

$XPO CLOSE - Close a File

The $XPO CLOSE macro calls the XPORT I/O facility to
terminate the
processing of an input or output file and flush any internal XPORT I/O
buffers.
If a
program terminates without closing
a
file,
the
resulting state of the file is unpredictable.

A.19.1

Syntax

+--------------------+-----------------------------------------------+
I
I

close a file

$XPO CLOSE( parameter , ••. )

+--------------------+-----------------------------------------------+
I

parameter

{

required-parameter}
optional-parameter}

I
I

+--------------------+-----------------------------------------------+
required-parameter
lOB = address of iob
+--------------------+-----------------------------------------------+
I

{

optional-parameter

OPTIONS = option-keyword
}
USER = user-defined value
}
SUCCESS = address of action routine }
FAILURE = address of action routine }

I
I
I
I

+--------------------+-----------------------------------------------+
option-keyword
REMEMBER
+--------------------+-----------------------------------------------+
I

NOTE:

The keyword OPTIONS may be shortened to OPTION.

A.19.2
lOB

Parameter Semantics

= address of lOB
specifies the address of the lOB that describes the
closed.
This parameter must be specified.

OPTIONS = option-keyword
indicates a processing option to be applied
closed.
Option
REMEMBER

the

file

being

Meaning
Remember relevant file attributes (e.g.,
resultant file specification)
so that
the
file can be reprocessed
(e.g.,
reopened,
renamed, deleted, backed up).
This option is assumed by default when a
temporary file
is closed (see Section
3.5) •

A-51

Macro Descriptions
$XPO CLOSE - Close a File
this
File processing options (including
option)
are not remembered, whether or
not this option-Ts specified.
If
this
option is not specified by file close
time, the lOB is reset to an initialized
state after a successful file close.
If this parameter is not specified, the lOB option field
chang ed.

not

USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$Z USER.
If this parameter is not specified,
the lOB user field is ~ot changed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful
completion of the CLOSE operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
CLOSE operation is unsuccessful.
If FAILURE=O is specified, no
failure action routine is called.
If
this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A.19.3

Usage Guidelines

If a files is closed with the
REMEMBER option,
a
subsequent OPEN,
DELETE,
or
RENAME operation will
not perform file-specification
resolution for
the
file,
but will
instead
use
the
'remembered'
resultant-file-specification string described in the lOB.

A.19.4

Completion Codes

A primary completion code is returned as the routine-call value,
and
is
also
available
in the
IOB$G COMP CODE field of the
lOB.
A
secondary completion code (if any) Is available in the
IOB$G_2ND_CODE
field
of the lOB.
Secondary completion codes, where applicable, are
indicated by a plus sign (+) following the associated primary code
in
the
listing
below.
The
secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.
Success Code:
XPO$ NORMAL

The file was successfully closed.
A-52

all

Macro Descriptions
$XPO CLOSE - Close a File
Error Codes:
XPO$ CLOSED
XPO $-F ILE LOCK
XPO$-FREE-MEM +
XPO$-IN USE
XPO$-IO-ERROR +
XPO$-NETWORK +
XPO$-NO ACCESS +
XPO$-NO-C LOSE
XPO $-NO-IVIEMORY
XPO $-NO-S PACE
XPO$-NO-SUPPORT +
XPO$-NO-WRITE
XPO$-NOT EXPIRE
XPO $-NO'I'-ONLINE
XPO$-NOT-OPEN
-

The file has alr~ady been closed.
JFN is locked;
file cannot be closed.
Error freeing lOB-related memory.
The file is currently in use.
A hardware-level I/O error occurred.
A network error has occurred.
The file cannot be accessed.
The file cannot be closed by this process.
Insufficient dynamic memory space.
Quota exceeded or disk full.
The requested function is not supported.
The file is write-protected.
The file-expiration date is not past.
The device was not ready.
The file was not open.

Fatal Error Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC
-

The lOB is invalid.
An XPORT logic error was detected.

A-53

Macro Descriptions
$XPO DELETE - Delete a File
A.20

$XPO DELETE - Delete a File

The $XPO DELETE macro calls the XPORT I/O facility to delete an
existing- file.
This operation, like OPEN and RENAME, performs
file-specification resolution as necessary.

A. 20.1

Syntax

+--------------------+-----------------------------------------------+
I
I delete a file
I

I
I $XPO DELETE( parameter , .•• )
I
-

I
I
I

+--------------------+-----------------------------------------------+
I
I parameter
I

I { required-parameter}
I { pr imary-parameter }
I { optional-parameter}

I
I
I

+--------------------+----------------_._-----------------------------+
I required-parameter I rOB = address of iob
I
+--------------------+----------------_._-----------------------------+
I primary-parameter
I FILE SPEC = char-string-info
I
+--------------------+-----=-----------------------------------------+
DEFAULT = char-string-info
}
RELATED = char-string-info
}
USER = user-defined value
}
SUCCESS = address of action routine}
FAILURE = address of action routine }

I
I
I
I
I

I { address of character-string descriptor}
I { 'literal ascii string'
}
I { ( co un t , po in t e r )
}

I
I
I

I
I {
I
I {
I optional-parameter I {
I
I {
I
I {

+--------------------+-----------------------------------------------+
I
I char-string-info
I

+--------------------+-----------~-----------------------------------+

A.20.2

Parameter Semantics

lOB = address of rOB
specifies the address of an lOB for the file to be deleted. This
lOB must be initialized, but it must not be open when the DELETE
call is made. This parameter must be specified.
FILE SPEC = character-string-info
-describes the file specification given by the end user.
Unless
the lOB was previously closed with the REMEMBER option, this file
specification is combined with the default and related file
specifications, if any, to form the resultant file specification
(see Section 3.6.1).
rf this parameter is not specified, the
corresponding lOB fields are not changed.

A-54

Macro Descriptions
$XPO DELETE - Delete a File
DEFAULT = character-string-info
describes
a
default
file
specification.
During
file-specification
resolution,
this
file
specification
is
combined with the user and related file specifications,
if any,
to form the resultant file specification (see Section 3.6.1).
If
this parameter is not specified, the corresponding rOB fields are
not changed.
RELATED = character-string-info
describes a file specification that is related to the file being
deleted.
During
file-specification
resolution,
this
file
specification
is combined with
the
user and default
file
specifications,
if any, to form the resultant file specification
(see Section 3.6.1).
If this parameter
is not specified,
the
corresponding lOB fields are not changed.
USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$Z USER.
If this parameter is not specified,
the lOB user field is not changed.
SUCCESS = address of action routine
specifies the address of an action
routine
to
be called
upon
successful completion of the delete operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
delete operation is unsuccessful.
If FAILURE=O is specified, no
failure action routine is called.
If
this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A.20.3

Completion Codes

A primary completion code is returned as the routine-call
value,
and
is
also
available
in the
IOB$G COMP CODE field of the
lOB.
A
secondary completion code (if any) Is available in the
IOB$G_2ND_CODE
field
of
the lOB.
Secondary completion codes, where applicable, are
indicated by a plus sign (+) following the associated primary code
in
the
listing
below.
The
secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.
Success Code:
XPO$ NORMAL

The file was successfully deleted.

A-55

all

Macro Descriptions
$XPO DELETE - Delete a File
Error Codes:
XPO$ BAD ACCT
XPO$-BAD-ATTR
XPO$-BAD-DELIM
XPO$-BAD-DEVICE
XPO$-BAD-DFLT +
XPO$-BAD-DIRECT
-

XPO $ BAD NAME
XPO$-BAD-PROT
XPO$-BAD-REQ +
XPO$-BAD-RLTD +
XPO$-BAD-RSLT +
XPO$-BAD-SPEC +
XPO $-BAD-TEMP
XPO$-BAD-VER
XPO$-CHANNEL +
XPO $-CORRUPTED
XPO$-FREE MEM +
XPO $-GET MEM +
XPO$-IN USE
XPO$-IO-ERROR +
XPO$-NETWORK +
XPO$-NO ACCESS +
XPO $-NO-CHANNE L
XPO$-NO-CONCAT
XPO$-NO-DELETE
XPO $-NO-DIRECT
XPO $-NO-F ILE
XPO $-NO-S PACE
XPO $-NO-S UBDIR
XPO$-NO-SUPPORT +
XPO$-NO-WRITE
XPO$-NOT EXPIRE
XPO $-NOT-ONLINE
XPO $-0 PEN
XPO$-PROTECTED
Fatal Error Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC

Invalid account field.
Invalid attribute field in file spec.
Invalid punctuation used in a quoted string.
A nonexistent device was specified.
The default file specification is invalid.
Directory-access privilege required, or invalid
directory format.
No filename was specified.
Invalid protection field.
The XPORT request was invalid.
The related file specification is invalid.
The resultant file specification is invalid.
The user file specification is invalid.
Multiple ";T"s specified.
Generation number not numeric.
A channel-assignment error occurred.
Invalid FDB format, or FDB not found.
Error freeing lOB-related memory.
A memory-allocation error occured.
The file is currently in use.
A hardware-level I/O error occurred.
A network error has occurred.
The file cannot be accessed.
No I/O channel was available.
Concatenated file-spec not allowed.
The file cannot be deleted.
The indicated directory was not found.
The file does not exist.
Disk working space is exhausted.
The sub-directory does not exist.
The requested function is not supported.
The file is write-protected.
The file-expiration date is not past.
The device was not ready.
The file is currently open.
Access to the file is denied.
The lOB is invalid.
An XPORT logic error was detected

A-56

Macro Descriptions
$XPO DESCRIPTOR - Declare a Data Descriptor
A.21

$XPO DESCRIPTOR - Declare a Data Descriptor

The $XPO DESCRIPTOR macro generates an attribute list for
a
binary
data descriptor within an OWN, GLOBAL, LOCAL, MAP or BIND declaration.
These attributes (1) indicate that the descriptor is a BLOCK structure
of a given length, (2) specify the set of field-names that can be used
to reference portions of the descriptor,
and
(3)
specify initial
descriptor-field values.
A detailed description of the
four
dynamic, bounded, and dynamic-bounded)

types of descriptors
appears in Section 7.1.

(fixed,

A descriptor must be initialized before it can be used.
If
the
descriptor
is declared within an OWN or GLOBAL declaration, the
descriptor can be statically initialized.
Otherwise,
it must be
initialized by use of the$XPO_DESC INIT macro.

A.21.1

Syntax

+--------------------+-----------------------------------------------+
declare-a-datadescriptor

I
I $XPO DESCRIPTOR({optional-parameter , .•• })
I
I

+--------------------+-----------------------------------------------+
I

optional-parameter

{

CLASS = class-keyword
}
BINARY DATA = binary-data-info }

I
I

+--------------------+---------=-------------------------------------+
I

class-keyword

{

FIXED I D Y N A M I C }
BOUNDED I DYNAMIC_BOUNDED}

(

s i ze

I
I

+--------------------+-----------------------------------------------+
I
I

bin a r y- d a t a - in f 0

I
I

{
,
FULLWORDS }
, add res s { , UN ITS
})
{
nothing}

I
I
I

+--------------------+-----------------------------------------------+
A.21.2

Restrictions

The BINARY DATA parameter may only
GLOBAL declaration.

A.21.3

specified

within

OWN

Parameter Semantics

CLASS = class-keyword
indicates the class of descriptor being declared.
See Section
7.1 for
a complete description of the descriptor classes.
If
this parameter is not specified, CLASS=FIXED is assumed.
A-57

Macro Descriptions
$XPO DESCRIPTOR - Declare a Data Descriptor
BINARY DATA

= binary-data-info

d~scribes the binary data

item to be described by the descriptor.
If this parameter is not specified, the size and length fields of
the descriptor are not statically initialized.

A-58

Macro Descriptions
$XPO_DESC INIT - Initialize a Data Descriptor
A.22

$XPO DESC INIT - Initialize a Data Descriptor

The $XPO DESC INIT macro dynamically initializes a
binary
descriptor;
that
is,
this macro generates the executable
necessary to initialize all of the fields of a given descriptor.

A.22.1

data
code

Syntax

+--------------------+-----------------------------------------------+
I
I setup-a-datadescriptor
I
I

I
I $XPO_DESC_INIT( parameter , •.• )
I
I

I
I
I
I

I parameter
I

I { required-parameter}
I { optional-parameter}

I
I

+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I required-parameter I DESCRIPTOR = address of descriptor

+--------------------+-----------------------------------------------+
I optional parameter I { CLASS = class-keyword
}
I
I { BINARY DATA = binary-data-info }

I
I

I class-keyword
I

I
I

+--------------------+---------=-------------------------------------+
I { FIXED I D Y N A M I C }
I { BOUNDED I DYNAMIC BOUNDED }

+--------------------+--------------------=--------------------------+
I
I
I bin a r y - d a t a - in f 0
I

I
I
I
I

{ address of binary data descriptor }
{
{ , FULLWORDS}}
{ ( s i z e , add res s { , UN ITS
})}
{
{ nothing
}}

I
I
I
I

+--------------------+-----------------------------------------------+

A.22.2

Parameter Semantics

DESCRIPTOR = address of descriptor
specifies the address of the descriptor to be initialized.
parameter must be specified.

This

CLASS = class-keyword
indicates the class of descriptor being initialized.
See Section
7.1 for
a complete description of the descriptor classes.
If
this parameter is not specified, CLASS=FIXED is assumed.
BINARY DATA = binary-data-info
describes the binary data item to be described by the descriptor.
If
this parameter is not specified, the corresponding descriptor
fields are not initialized.

A-59

Macro Descriptions
$XPO DESC INIT - Initialize a Data Descriptor
A.22.3

Completion Code

Success Code:
XPO$ NORMAL

The descriptor was successfully initialized.

A-60

Macro Desdriptions
$XPO FREE MEM - Release a Memory Element
A.23

$XPO FREE MEM - Release a Memory Element

release a
The $XPO FREE MEM macro calls the XPORT MEMORY facility to
previously allocated
element of memory.
The memory element may
optionally be cleared before it is released.

A.23.1

Syntax

+--------------------+-----------------------------------------------+
I
I

release memory

$XPO FREE MEM ( parameter , ••• )

+--------------------+-----------------------------------------------+
I parameter
I { requi red-parameter }
I
I

I { optional-parameter}

I { BINARY DATA

+--------------------+-----------------------------------------------+
I required-parameter I { STRING = char-string-info}
I
= binary-data-info

}

+--------------------+---------=-------------------------------------+
I
I { FILL = memory clearing value
}
I
I

optional-parameter

SUCCESS
FAILURE

= address of action routine }

{

I { ( count , pointer)

= address of action routine }

+--------------------+-----------------------------------------------+
char-string-info
address of character string descriptor}
I

}

+--------------------+-----------------------------------------------+
address of binary data descriptor
}
I

I {

{

I binary-data-info
I

I { ( size, address { , UNITS
{ nothing
I {

{ , FULLWORDS}}
})}
}}

I
I

+--------------------+-----------------------------------------------+
A.23.2

Restrictions

The STRING and BINARY DATA parameters are mutually exclusive.
As
indicated
in the syntax diagram, a literal-string is not valid as a
character-string-info parameter in this macro.

A.23.3

Parameter Semantics

STRING = char-string-info
describes a character-string memory element to be released.
The
element described must begin on a BLISS fullword boundary;
its
length
is rounded
up,
if necessary,
to
the next fullword
boundary.
If a
string descriptor is specified, the count and
pointer fields are zeroed to reflect the memory released.
Either
this parameter or the BINARY DATA parameter must be specified.
A-61

Macro Descriptions
$XPO FREE_MEM - Release a Memory Element
BINARY DATA = binary-data-info
describes a binary-data memory element.
The data area described
must begin on a BLISS fullword boundary;
its length is rounded
up,
if necessary,
to
the next fullword
boundary.
If
a
binary-data descriptor is specified, the size and pointer fields
are zeroed to reflect the memory released.
Either this parameter
or the STRING parameter must be specified.
FILL = memory clearing value
specifies a
fullword
binary value which
is to
be used
to
If this
overwrite the memory element before
it is released.
parameter is omitted, no memory clearing is performed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful completion of the release memory operation.
If this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
release memory operation is unsuccessful.
If
FAILURE=O
is
specified,
no
failure
action routine
is called.
If
this
parameter
is nDt specified, FAILURE=XPO$FAILURE is assumed (see
Section 3.8).

A.23.4

Completion Codes

Success Code:
XPO$ NORMAL

The element was released.

Error Codes:
XPO$ BAD ADDR
XPO $-BAD-ALIGN
XPO$-BAD-DESC
-

The element is not in allocated dynamic memory.
Invalid string/data alignment.
Invalid string/data descriptor.

Fatal Error Code:
XPO$ - BAD- LOGIC

An XPORT logic error was detected.

A-62

Macro Descriptions
$XPO GET - Read From a File
A.24

$XPO GET - Read From a File

The $XPO GET macro calls the XPORT I/O facility (1) to read
the next
logical -record in an input file, 6r (2) to read a specified amount of
character or binary data.
At the completion of a
successful
$XPO GET operation,
the
lOB
is
updated
to reflect the data that has been read into an internal XPORT
buffer.
Note that $XPO GET is a "locate mode"
operation;
that
is,
the data is not read into a caller-provided buffer.

A.24.1

Syntax

+--------------------+-----------------------------------------------+
I
I

read from a file

$XPO GET( parameter, •.• )

{

+--------------------+-----------------------------------------------+
parameter
requi red-parameter }
I

optional-parameter }

+--------------------+-----------------------------------------------+
required-parameter
lOB = address of iob
+--------------------+-----------------------------------------------+
PROMPT = char-string-info
}
I

optional-parameter

CHARACTERS = number of characters
FULLWORDS = number of binary fullwords
UNITS = number of binary units
USER = user-defined value
SUCCESS = address of action routine
FAILURE = address of action routine

}
}
}
}
}
}

'literal ascii string'
(
co un t , po in t e r )
string conversion pseudo-function

}
}
}

I
I
I
I
I
I

+--------------------+-----------------------------------------------+
address of character-string descriptor}
I

char-string-info

I
I
I

+--------------------+-----------------------------------------------+
A.24.2
lOB

Parameter Semantics

= address of lOB
specifies the address of the lOB that describes the
read.
This parameter must be specified.

file

PROMPT = char-string-info
describes a terminal
input-prompt string.
This parameter
is
ignored if the input device is not a terminal.
If this parameter
is not specified, the lOB prompt descriptor is not changed.

A-63

Macro Descriptions
$XPO GET - Read From a File
CHARACTERS = number of characters
FULLWORDS = number of binary fullwords
UNITS = number of binary units
specify the amount of data
to
be read.
Only one of these
parameters may be specified.
The CHARACTERS parameter must be
given for character-stream GET operations (see ATTRIBUTES=STREAM
in A.28).
This parameter specifies the number of characters to
be read.
The FULLWORDS or UNITS parameter must be given
for
binary GET operations
(see ATTRIBUTES=BINARY in A.28).
These
parameters specify the amount of data to
be read
in terms of
BLISS
fullwords
(FULLWORDS)
or addressable units
(UNITS).
Specifying UNITS limits program transportability;
that
is,
a
program usually will not behave correctly in both the 36-bit and
l6/32-bit environments if UNITS is specified.
These
parameters
are ignored for record-mode GET operation~ (see ATTRIBUTES=RECORD
in A.28).
If no I/O length parameter is specified, the
lOB
I/O
length field is not changed.
USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$Z USER.
If this parameter is not specified,
the lOB user field is not changed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful
completion of the $XPO GET operation.
If
this
parameter is not specified, no success-action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
$XPO GET operation is unsuccessful.
If FAILURE=O is specified,
no failure action routine is called.
If this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A.24.3

Usage Guidelines

The following lOB fields are updated at the completion of an
character operation:
IOB$T STRING
IOB$A-STRING
IOB$H-STRING.
IOB$H-PAGE NUMB
IOB$Z=SEQ_NUMB

Character string descriptor:
pointer to the character string
number of characters read
Page number (sequenced file only)
Record sequence number (sequenced file only)
or record number (non-sequenced file)

The following lOB fields are updated at the completion of an
binary operation:
IOB$T DATA

$XPO GET

Binary data descriptor:
A-64

$XPO GET

Macro Descriptions
$XPO GET - Read From a File
10B$A DATA
10B$H-UNITS
lOB $H-F ULLWORDS

A.24.4

address of the binary data
number of addressable units read
number of fullwords read

Completion Codes

A primary completion code is returned as the routine-call
value,
and
is
also
available
in the
10B$G COMP CODE field
of the
lOB.
A
secondary completion code (if any) 1s available in the
10B$G_2ND_CODE
field
of
the lOB.
Secondary completion codes, where applicable, are
indicated by a plus sign (+) following the associated primary code
in
the
listing
below.
The
secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.
Success Code:
XPO$ NORMAL
XPO $ INC OMPLETE
XPO$_NEW_FILE
XPO$ NEW PAGE
warning-Code:
XPO$ END FILE
Error Codes:
XPO$ BAD PROMPT +
XPO$-BAD-RECORD +
XPO$-BAD-REQ +
XPO$-FREE MEM +
XPO $-GET MEM +
XPO$-10 BUFFER +
XPO$-10-ERROR +
XPO$-NETWORK +
XPO$-N.,.P MEMORY
XPO $-NO-S PACE
XPO$-NO-SUPPORT +
XPO $-NO-WRITE
XPO$-NOT INPUT
XPO $-NOT-ONLINE
XPO$-NOT-OPEN
XPO $-REC-LOC K
Fatal Error-Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC
-

all

The $XPO GET operation was successful - the lOB
data pointer and length fields describe the
data which has just been read.
An incomplete amount of data has been read
(STREAM or BINARY mode only).
The first read on a concaten~ted input file was
successful - implies new page.
The first read on a new page was successful.
No more data exists in the input file,
attempt to read past end-of-file.

i.e.,

The input prompt is invalid.
An invalid record was encountered.
The I/O request is invalid.
Error freeing lOB-related memory.
A memory allocation error occurred.
An I/O buffering error occurred.
An I/O error occurred reading the file.
A network error has occurred.
Insufficient dynamic memory space.
Quota exceeded or disk full.
The requested function is not supported.
The file is write-protected.
The file is not open for input.
The device was not ready.
The file is not open.
A record is locked by another task.
The lOB is invalid.
An XPORT logic error was detected.

A-65

Macro Descriptions
$XPO GET - Read From a File
If input-file concatenation is in effect (see Section 3.2.2.1),
OPEN
or CLOSE failure
codes are
returned
if either of these automatic
operations fails.

A-66

Macro Descriptions
$XPO_GET_MEM - Allocate Dynamic Memory Element
A.2S

$XPO GET MEM - Allocate Dynamic Memory Element

The $XPO GET MEM macro calls the XPORT MEMORY facility to allocate an
element of dynamic memory.
An allocated memory element may optionally
be ini tial i zed.

A.2S.1

Syntax

+--------------------+-----------------------------------------------+
I
I allocate memory
I

I
I $XPO GET MEM ( parameter , ••• )
I
-

I
I
I

I { optional-parameter}

I result-parameter

I size-parameter
I

I { FULLWORDS = number of fullwords
}
I { UNITS = number of addressable units}

I
I

I { DESCRIPTOR = address of descriptor}

= address of action routine}

I
I

+--------------------+-----------------------------------------------+
I parameter
I { requi red-parameter }
I
+--------------------+-----------------------------------------------+
I required-parameter I size-parameter
I
+--------------------+-----------------------------------------------+
I
I { CHARACTERS = number of characters}
I
+--------------------+-----------------------------------------------+
I result-parameter
I { RESULT = address for result
}
I
+--------------------------------------------------------------------+
I
I { FILL = memory initialization value}
I
I optional-parameter I { SUCCESS
I
I { FAILURE

= address of action routine}

+--------------------+-----------------------------------------------+
A.2S.2

Restrictions

The
CHARACTERS,
exclusive.

A.2S.3

FULLWORDS,

and

UNITS

parameters

are

mutually

Parameter Semantics

CHARACTERS = number of characters
FULLWORDS = number of fullwords
UNITS = number of addressable units
specify the size of the memory element to be allocated.
only one, of these parameters must be specified.

A-67

One, and

Macro Descriptions
$XPO GET MEM - Allocate Dynamic Memory Element
RESULT = address of result
specifies the address of an area
in which the allocation
operation
(if successful) will store a pointer to the allocated
string element, or will
store the address of the allocated
binary~data
element,
respectively.
Note
that the RESULT
parameter or the DESCRIPTOR parameter must be specified.
DESCRIPTOR = address of descriptor
specifies the address of a DYNAMIC or DYNAMIC BOUNDED descriptor.
If the allocatiDn operation is successful, the descriptor is
updated to describe the allocated string or binary-data element.
The following indicates the descriptor fields that are changed:
STR$H LENGTH or XPO$H LENGTH:
size of element if-DYNAMIC and zero if DYNAMIC BOUNDED
STR$H MAXLEN or XPO$H MAXLEN:
size of element only if DYNAMIC BOUNDED
STR$A POINTER or XPO$A ADDRESS:
element POINTER or ADDRESS
Note that the DESCRIPTOR parameter or the RESULT
be specified.

parameter

must

FILL = memory initialization value
specifies an appropriate value to
be used
to
initialize each
character,
fullword, or unit in an allocated memory element.
If
this parameter is not specified,
the content of an allocated
memory element is unpredictable.
SUCCESS = address of action routine
specifies the address of an action routine to be called
upon
successful completion of the memory allocation operation.
If
this parameter is not specified, no
success action routine
is
assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
memory allocation operation is unsuccessful.
If FAILURE=Q is
specified,
no
failure
action routine
is called.
If
this
parameter
is not specified, FAILURE=XPO$FAILURE is assumed (see
Section 3.8).

A.25.4

Completion Codes

Success Cod~:
XPO$ NORMAL

The memory element was successfully allocated.

A-68

Macro Descriptions
$XPO_GET_MEM - Allocate Dynamic Memory Element
Error Codes:
XPO$ NO MEMORY
XPO$-BAD DESC
-

Insufficient memory to satisfy request.
Invalid string/data descriptor.

Fatal Error Code:
XPO$ - BAD- LOGIC

An XPORT logic error was detected.

A-69

Macro Descriptions
$XPO lOB - Declare an lOB
A.26

$XPO lOB - Declare an lOB

The $XPO lOB macro is used, in a data- or bind-data-declaration,
to
create and possibly initialize an XPORT I/O control block (lOB).
The
$XPO lOB macro generates a structure-attribute and field-attribute for
an
lOB data-segment name,
and causes the data segment to
be
initialized if it is allocated in permanent storage.
The macro itself is specified as an attribute
in an OWN,
GLOBAL,
LOCAL, MAP or BIND declaration.
The generated attributes (I) indicate
that the lOB is a BLOCK structure of a given length,
and
(2)
define
the field-names that can be used to reference portions of the lOB.
An lOB that is created in temporary storage (LOCAL declaration) or
in
dynamic
storage must be explicitly initialized with the $XPO lOB INIT
macro before it can be used.
(See Section A.25.)

A. 26.1

Syntax

+--------------------+-----------------------------------------------+
I
I declare an iob
I

I
I $XPO lOB ( )
I

I
I
I

+--------------------+-----------------------------------------------+
A.26.2

Parameter Semantics

The $XPO lOB macro takes no parameters at the present time.

A.26.3

Examples

OWN
input iob :
$XPO lOB () ,
output iob :
$XPO IOB{);
LOCAL
t em po r a r y _ i 0 b
MAP
dynamic iob:
REF $XPO IOB{);
BIND
selected iob
iobset[.index, 0,0,0,0]

A-70

$XPO lOB ()

Macro Descriptions
$XPO lOB INIT - Initialize an lOB
A.27

$XPO lOB INIT - Initialize an lOB
-

The $XPO lOB INIT macro dynamically initializes an XPORT lOB;
that
is,
it -generates the executable code necessary to initialize all of
the fields of an lOB.
Dynamic initialization is necessary for
lOBs
created
in temporary storage
(i.e.,
declared as
LOCAL)
or
in
dynamically-acquired storage.
The user-related lOB fields are initialized to a user-specified value
(for subsequent operations), or to zeroes if no values are specified.

A.27.1

Syntax

+--------------------+-----------------------------------------------+
I
I

setup an iob

$XPO lOB INIT( parameter , ••• )

I
I

+--------------------+-----------------------------------------------+
parameter
required-parameter}
I

{

optional-parameter }

+--------------------+-----------------------------------------------+
required-parameter
IOB=address of iob
+--------------------+-----------------------------------------------+
USER = user-defined value }
I

optional-parameter

{

$XPO CLOSE parameters}
$XPO-DELETE parameters
}
$XPO-GET p a r a m e t e r s }
$XPO-OPEN p a r a m e t e r s }
$XPO-PUT p a r a m e t e r s }
$XPO-RENAME parameters
}

I
I
I
I
I
I

+--------------------+-------=---------------------------------------+
A.27.2

Restrictions

The SUCCESS and FAILURE parameters may not be specified
(as optional
parameters of the other macros listed above).
In addition, the
parameters that are unique to
the $XPO RENAME macro
NEW_SPEC,
NEW_DEFAULT, and NEW RELATED -- may not be specified.

A.27.3

Parameter Semantics

lOB = address of lOB
specifies the address of the
parameter must be specified.

A-71

lOB

initialized.

This

Macro Descriptions
$XPO lOB INIT - Initialize an rOB
USER

= user-defined value
specifies an application-dependent fullword value to be placed in
the lOB field IOB$Z USER.
rf this parameter is not specified, no
user value is assumed.

$XPO CLOSE parameter
$XPO-DELETE parameter
$XPO-GET parameter
$XPO-OPEN parameter
$XPO-PUT parameter
$XPO-RENAME parameter
-initialize rOB fields for subsequent r/o operations.

A.27.4

Completion Code

Success Code:
XPO$ NORMAL

The rOB was successfully initialized.

A-72

Macro Descriptions
$XPO_OPEN - Open a File
A.28

$XPO_OPEN - Open a File

The $XPO OPEN macro calls the XPORT I/O facility to prepare a file for
reading -or writing.
Before a file is opened, the lOB defaults are
established and an lOB validity check is made. When a file is opened
for
input, the file attributes are checked against those specified in
the lOB to ensure against a conflict (e.g., RECORD vs.
BINARY,
see
below) •
This operation performs file-specification
resolution as
necessary.

A.28.1

Syntax

+--------------------+-----------------------------------------------+
I
I open a file
I

I
I $XPO OPEN ( parameter , ••. )
I
-

I
I
I

I
I parameter
I

I { required-parameter}
I {primary-parameter }
I { optional-parameter }

I
I
I

I
I primary-parameter
I

I { FILE SPEC = char-string-info
}
I { OPTIONS = (option-keyword, ••• )
}
I { AT T RIB UT ES = (at t rib u t e- k e ywo r d , ••• )}

I
I
I

I
I { DEFAULT = char-string-info
}
}
I
I { RELATED = char-string-info
I
I { RECORD SIZE = fixed length of record }
}
I
I { RECORD-SIZE = VARIABLE
I
I { BLOCK SIZE = fixed length of block}
I optional-parameter I { USER ~ user-defined value
}
I
I { SUCCESS = address of action routine}
I
I { FAILURE = address of action routine}
I
I { any $XPO CLOSE parameter
}
I
I { any $XPO-GET parameter
}
I
I { any $XPO-PUT parameter
}

I
I
I
I
I
I
I
I
I
I
I

I
I char-string-info
I

I { address of character string descriptor}
I { 'literal ascii string'
}
}
I { ( co un t , po in t e r )

I
I
I

I
I option-keyword
I

I { IN P U T }
I { OUTPUT}
I { OVERWRITE I APPEND }

I
I
I

+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I required-parameter I lOB = address of iob
I
+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+

+--------------------+-----------=-----------------------------------+
+--------------------+-----------------------------------------------+
+--------------------+-----------------------------------------------+
I
continued on the next page
I
+--------------------------------------------------------------------+
A-73

Macro Descriptions
$XPO_OPEN - Open a File

+--------------------+-----------------------------------------------+
I attribute-keyword I { RECORD I STREAM I BINARY }
I
I

I { SEQUENCED}

+--------------------+-----------------------------------------------+
NOTE:
The keywords OPTIONS and ATTRIBUTES may be shortened to
and ATTRIBUTE respectively.

A.28.2
lOB

OPTION

Parameter Semantics

= address of lOB
specifies the address of the lOB that describes the
opened.
This parameter must be specified.

file

FILE SPEC = character-string-info
-describes a file specification provided by an end
user.
Unless
the lOB was previously closed with the REMEMBER option, this user
file specification is combined with the default and related
file
specifications,
if any, to form the resultant file specification
(see Section 3.6.1).
Unless otherwise specified by file open
time, a null user file specification is assumed.
OPTIONS = (option-keyword , ••• )
indicates the processing options that apply to
the
file being
opened.
One or more of the options described in the following
table can be specified.
Note that some of these options are
mutually exclusive;
any errors will be detected at file open
time.
Option

Description

INPUT

The file is opened
(default option) •

OUTPUT

The file is opened as an output file.
If
neither OVERWRITE nor APPEND is
specified, a new output file is created.
If
this
is not possible,
the file
opening will fail.

OVERWRITE

If a
file being opened
for
output
already exists,
it is overwritten from
the beginning.
If
this
option
is
specified, OUTPUT is assumed.

APPEND

If a
file being opened
for
output
already exists, it is appended to rather
than overwritten.
If
this option
is
specified, OUTPUT is assumed.

A-74

input

file

Macro Descriptions
$XPO_OPEN - Open a File
A device that is not file-structured and that can be both read
and written (e.g., terminal, DECnet link), may be opened for both
INPUT and OUTPUT, and will be so opened by default;
for
all
other
devices,
the
INPUT and
OUTPUT options are mutually
exclusive.
Unless otherwise specified by file open
time,
OPTIONS=INPUT is assumed.
ATTRIBUTES = attribute-keyword , •••
indicates the attributes that apply to the file described by the
lOB.
One or more of the attributes described in the following
table can be specified.
Note that some of these attributes are
mutually exclusive;
any errors will be detected at file open
time.
Attribute

Description

RECORD

Character data is read
and
terms of logical records.

STREAM

Character data is read
and
written as
streams
of
characters.
(Control
characters, e.g., CR,
LF,
VT,
may be
read
and written in this mode).
GET
operations in
STREAM
mode
require
specification
of
the
CHARACTERS=
parameter (see A.24).

SEQUENCED

an
have
All output records are to
this
sequence number.
If
associated
is
specified,
RECORD
attribute is
assumed.

BINARY

The file contains binary data.

Unless otherwise specified by file open
is assumed.

time,

written

ATTRIBUTES=RECORD

DEFAULT = character-string-info
describes
a
default
file
specification.
During
file-specification
resolution,
this
file specification is
combined with the user and related file specifications,
if any,
to
form
the resultant file specification (see Section 3.6.1).
Unless otherwise specified by file open time,
no default file
specification is assumed.
RELATED = character-string-info
describe a file specification that is related to the
file being
opened.
For example, an application that creates an output file
as a modification or "update" of an input file,
e.g.,
a
text
editor, will typically treat the input file as a related file.

A-75

Macro Descriptions
$XPO_OPEN - Open a File
During
file-specification
resolution,
a
related
file
specification
is combined with
the
user and
default file
specifications, if any, to form the resultant file
specification
(see
Section 3.6.1).
Unless otherwise specified by file open
time, no related file specification is assumed.
RECORD SIZE = fixed length of record
specifies the size of a record in an output file.
This parameter
should only be specified for fixed-length, record-oriented output
files
(see
ATTRIBUTES=RECORD above).
The
record
length
is
expressed
in terms of characters.
Unless otherwise specified by
file open time, "RECORD_SIZE = VARIABLE" is assumed.
RECORD SIZE = VARIABLE
specifies that an output-file
record
is of variable length .•
This
parameter
is
the
RECORD SIZE default for record-oriented
output files (see ATTRIBUTES=RECORD above) .
BLOCK SIZE = fixed length of block
specifies the physical block size of an output
file.
It has
meaning
only for
those devices which support a user-specified
block size
(e.g.,
magnetic
tape).
On a
system which uses
Files-II
disk-file
structure,
this
block-size
parameter
corresponds to the "RMS bucket size".
This parameter should only
be
specified
for
output
files.
A block size is expressed in
terms of "bytes" (i.e., 9 bits on a PDP-IO, 8 bits on a PDP-II or
VAX-II).
Unless otherwise specified
by file
open time,
a
device-dependent block size is assumed.
/REVIEWERS:

SHOULD THE BLOCK-SIZE VALUE BE FULLWORDS OR BYTES?/

USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$Z USER.
If this parameter is not specified,
the lOB user field is not changed.
SUCCESS = address of action routine
specifies the address of an action
routine to
be called
upon
successful
completion of the OPEN operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
OPEN operation
is unsuccessful.
If FAILURE=O is specified, no
failure action routine is called.
If
this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).
any $XPO CLOSE parameter
any $XPO-GET parameter
any $XPO-PUT parameter
initialize lOB fields for subsequent I/O operations.

A-76

Macro Descriptions
$XPO_OPEN - Open a File
A.2S.3

Completion Codes

A primary completion code is returned as the routine-call
value,
and
is also
available
in the
IOB$G COMP CODE field
of the
lOB.
A
secondary completion code (if any) IS available in the
IOB$G_2ND_CODE
field
of the lOB.
Secondary completion codes, where applicable, are
indicated by a plus sign (+) following the associated primary code
in
the
listing
below.
The secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.
Success Code:
XPO$ NORMAL
XPO$-CREATED
Error Codes:
XPO$ BAD ACCT
XPO$-BAD-ATTR
XPO$-BAD-DELIM
XPO $-BAD-DEVICE
XPO$-BAD-DFLT +
XPO$-BAD-DIRECT
XPO$ BAD FORMAT
XPO $=BAD=IO _OPT
XPO $ BAD NAME
XPO$-BAD-ORG
XPO$-BAD-PROT
XPO $-BAD-RECORD
XPO$-BAD-REQ +
XPO$-BAD-RLTD +
XPO$-BAD-RSLT +
XPO$-BAD-SPEC +
XPO $-BAD-TEMP
XPO $-BAD-VER
XPO$-CHANNEL +
XPO $-CORRUPTED
XPO $-E XISTS
XPO$-FILE LOCK
XPO$-FREE-MEM +
XPO $-GET MEM +
XPO$-IN USE
XPO$-IO-ERROR +
XPO$-NETWORK +
XPO$-NO ACCESS +
XPO $-NO-CHANNE L
XPO$-NO-CREATE +
XPO $-NO-DIRECT
XPO$-NO-FILE

all

The file was successfully opened.
The file was created and successfully opened.
Invalid account field.
Invalid attribute field in file spec.
Invalid punctuation used in a quoted string.
An invalid device was specified.
The default file specification is invalid.
Directory-access privilege required, or invalid
directory format.
The record format is invalid.
An invalid I/O option was specified (e.g.,
binary terminal I/O).
No filename was specified.
The file organization is invalid.
Invalid protection field.
An invalid record was encountered.
The XPORT request was invalid.
The related file specification is invalid.
The resultant file specification is invalid.
The user file specification is invalid.
Multiple ";T"s specified.
Generation number not numeric.
A channel-assignment error occurred.
The file header contains invalid information.
The file already exists.
The file is locked.
Error freeing lOB-related memory.
A memory-allocation error occured.
The file is currently in use.
A hardware-level I/O error occurred.
A network error has occurred.
The file cannot be accessed.
All I/O channels are currently in use.
The file could not be created.
The indicated directory was no found.
The file does not exist.
A-77

Macro Descriptions
$XPO_OPEN - Open a File
XPO$ OPEN
XPO $-NO SPACE
XPO$ NO SUBDIR
XPO$-NO-SUPPORT +
XPO$-NO-WRI'I'E
XPO$-NOT EXPIRE
XPO $-NOT-ONLINE
XPO$-PROTECTED
Fatal Error Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC

The file has already been opened.
Insufficient space on the requested or implied
device.
The sub-directory does not exist.
The requested function is not supported.
The file is write-protected.
The file-expiration date is not past.
The device was not ready.
Access to the file is denied.
The lOB is invalid.
An XPORT logic error was detected.

A-78

Macro Descriptions
$XPO_PARSE_SPEC - Parse a File Specification
A.29

$XPO PARSE SPEC - Parse a File Specification

The $XPO PARSE SPEC macro calls the XPORT I/O facility to
parse a
file-specification string into its component parts (e.g., device name,
file name, file version).
The parsing operation
includes a
targetsystem-dependent syntax check of the file specification.
A failure completion code indicates that an invalid component was
encountered
in the parsing
operation.
The
results of the parse,
including any diagnostic information, is stored
in a
user-supplied
File Specification Block
(see the $XPO SPEC BLOCK macro, Section
A. 31) •

A.29.1

Syntax

+--------------------+-----------------------------------------------+
I
I parse a file-spec
I

I
I $XPO PARSE SPEC( parameter , ..• )
I

I
I
I

I { optional-parameter}

I { SPEC-BLOCK = address of file-spec block}

I { FAILURE = address of action routine

I char-string-info
I

I { 'literal ascii string'
I { ( co un t , po i n t e r )

+--------------------+-----------------------------------------------+
I
I { address of character string descriptor}
I
}
}

I
I

+--------------------+-----------------------------------------------+
A.29.2

Parameter Semantics

FILE SPEC = character-string-info
-describes the file specification to be
must be specified.

parsed.

This

parameter

SPEC BLOCK = address of file-spec block
-specifies the address of an XPORT File Specification Block
A.31)
that
is
to
receive the
results of the parsing.
parameter must be specified.

A-79

(see
This

Macro Descriptions
$XPO PARSE_SPEC - Parse a File Specification
SUCCESS = address of action routine
specifies the address of an action routine to be called upon the
successful completion of the PARSE SPEC operation.
If this
parameter is not specified, no success-action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if the
PARSE SPEC operation is unsuccessful.
If FAILURE=O is specified,
no faIlure action routine is called.
If this parameter is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A.29.3

Completion Codes

Success Code:
XPO$ NORMAL
Error Codes:
XPO$ BAD DELIM
XPO$-BAD-DEVICE +
XPO$-BAD-DIRECT +
XPO$-BAD-NAME +
XPO$-BAD-NODE .+
XPO$-BAD-TYPE +
XPO$-BAD-VER +
-

The file specification was successfully parsed.
Invalid
Invalid
Invalid
Invalid
Invalid
Invalid
Invalid

delimiter.
device name.
directory specification.
file name.
node name.
rile type (or extension).
file version.

A-80

Macro Descriptions
$XPO PUT - Write to a File
A.30

$XPO PUT - Write to a File

The $XPO PUT macro calls the XPORT I/O facility to write data to an
output flle at its current position.
See the OPTIONS parameter of the
$XPO OPEN macro (A.28) for information about initial positioning of an
output file.

A.30.1

Syntax

+--------------------+----------------------------,-------------------+
I
I

write into a file

$XPO PUT( parameter , .•• )

+--------------------+-----------------------------------------------+
required-parameter}
I

parameter

{

{primary-parameter }
{
optional-parameter}

{

I
I

+--------------------+-----------------------------------------------+
required-parameter
IOB = address of iob
+--------------------+-----------------------------------------------+
primary-parameter
STRING = char-string-info
}
I

BINARY DATA

= binary-data-info

}

+--------------------+---------=-------------------------------------+
I
I { USER = user-defined value
}
I
I

optional-parameter

SUCCESS
FAILURE

= address of action routine }

+--------------------+-----------------------------------------------+
I
I { address of character string descriptor}
I
I

char-string-info

'literal ascii string'
(
count , pointer)
string conversion pseudo-function

{

I binary-data-info
I

I { ( size, address { , UNITS
I {
{ nothing

}
}
}

I
I
I

+--------------------+-----------------------------------------------+
I
I { address of binary data descriptor }
I
{

FULLWORDS}}
})}
}}

I
I

+--------------------+-----------------------------------------------+
A.30.2

Restrictions

The character-string parameters (STRING, PAGE NUMBER, SEQUENCE_NUMBER)
and the BINARY DATA parameter are mutually exclusive.

A-81

Macro Descriptions
$XPO PUT - write to a File
A.30.3

Parameter Semantics

lOB = address of lOB
specifies the address of the lOB that describes
written.
This parameter must be specified.

the

file

being

STRING = character-string-info
describes an output record or stream composed of characters.
If
this parameter is not specified, the lOB character-output-string
descriptor is not changed.
BINARY DATA = binary-data-info
describes an output binary data stream.
If this parameter is not
specified, the lOB binary-output-data descriptor is not changed.
USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$2 USER.
If this parameter is not specified,
the lOB user field is not changed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful
completion of the $XPO PUT operation.
If
this
parameter is not specified, no success-action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
$XPO PUT operation is unsuccessful.
If FAILURE=O is specified,
no failure action routine is called.
If this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A.30.4

Usage Guidelines

For
a character-stream PUT operation
(see ATTRIBUTES=STREAM
in
$XPO OPEN,
A.28)
no carriage return,
line
feed,
or any other
formit-control characters are supplied by XPORT in the output record.
In
this mode, it is the user's exclusive responsibility to supply in
the character string any and
all
control character
that might be
desired in the output record.

A.30.S

Completion Codes

A primary completion code is returned as the routine-call value,
and
is also
available in the
IOB$G COMP CODE field of the
lOB.
A
secondary completion code (if any) IS aviilable in the
IOB$G_2ND_CODE
field
of the lOB.
Secondary completion codes, where applicable, are
indicated by a plus sign (+) following the associated primary code
in
the
listing below.
The secondary completion codes are listed and
described in Appendix C.
A-82

Macro Descriptions
$XPO PUT - write to a File
NOTE:
Some of the completion codes listed below may not apply to
operating systems.

all

Success Code:
XPO$ NORMAL

The record was successfully written.

Error Codes:
XPO$ BAD REQ +
XPO$-CORRUPTED
XPO$-FREE MEM +
XPO $-GET MEM +
XPO$-IO ERROR +
XPO $-NETWORK +
XPO$-NO ACCESS +
XPO $-NO-S PACE
XPO$-NO-SUPPORT +
XPO$-NO-WRITE
XPO$-NOT ONLINE
XPO $-NOT-OPEN
XPO$-NOT-OUTPUT
XPO$-REC-LOCK
XPO$-TRUNCATED

The I/O request is invalid.
The file header contains invalid information.
Error freeing lOB-related memory.
A memory-allocation error occurred.
An I/O error occurred writing the file.
A network error has occurred.
The file cannot be accessed.
The file cannot be extended, device is full.
The requested function is not supported.
The file is write-protected.
The device was not ready.
The file is not open.
The file is not open for output.
A record is locked by another task.
A truncated record was successfully written.

Fatal Error Codes:
XPO$ BAD lOB +
XPO$=BAD=LOGIC

The lOB is invalid.
An XPORT logic error was detected.

A-83

Macro Descriptions
$XPO PUT MSG - Send a Message
A.31

$XPO_PUT_MSG - Send a Message

The $XPO PUT MSG macro calls the XPORT MESSAGE
facility to
single- or multiple-line message to the user of the program.

send

The routing of a message depends on
its associated
severity.
All
messages,
regardless of severity,
are sent to the standard XPORT
output device ($XPO OUTPUT), normally the user's terminal in the case
of
an
interactive- program.
Messages with a
severity other than
SUCCESS are also sent to the standard XPORT error device
($XPO ERROR)
if that device is different from the standard output d~vice.
Sending a FATAL message will result in automatic
at the completion of message processing.

A.31.1

program

termination

Syntax

+--------------------+-----------------------------------------------+
1
1
1

send a message

1
1
1

$XPO PUT MSG( parameter , ••. )
-

1
1
1

+--------------------+-----------------------------------------------+
1
1

parameter

1 { required-parameter}
1 {primary-parameter
}

1
1

optional-parameter}

CODE = completion code
}
STRING = char-string-info }

1
1

{

+--------------------+-----------------------------------------------+
1
1

required-parameter

1
1

optional-parameter 1 { SUCCESS
1 { FAILURE

1
1
1

char-string-info

1 {
1 {

+--------------------+-----------------------------------------------+
1 primary-parameter
1 SEVERITY = { SUCCESSIWARNINGIERRORIFATAL}
1
+--------------------+-----------------------------------------------+
= address of action routine}
= address of action routine }

1
1

+--------------------+-----------------------------------------------+
1 {
1 {
1 {

address of character string descriptor}
'literal ascii string'
}
( count , pointer)
}

1
1
1

+--------------------+-----------------------------------------------+
A.31.2
CODE

Parameter Semantics

completion code
specifies an XPORT
completion
code.
The
message
text
corresponding
to
this completion code is retrieved and sent to
the appropriate devices (see SEVERITY below).
This parameter may
be specified more
than once
in a
single macro call;
each
occurence results in a single message.
Either this parameter or
the STRING parameter must be specified.

A-84

Macro Descriptions
$XPO PUT MSG - Send a Message
STRING = character-string-info
describes a message string.
This parameter may be specified more
than once
in a single macro call;
each occurence results in a
single message.
Either this parameter or the CODE parameter must
be specified.
SEVERITY = severity-level keyword
specifies the severity to be associated with
the message.
A
result in automatic program termination.
If
FATAL level will
this parameter is not specified and
CODE
is specified,
the
severity code is determined from the completion code.
Otherwise,
if this parameter is not specified, SEVERITY=ERROR is assumed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful
completion of the message output operation.
If this
parameter is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
message output operation is unsuccessful.
If
FAILURE=O
is
specified,
no
failure
action routine
is called.
If
this
parameter
is not specified, FAILURE=XPO$FAILURE is assumed (see
Section 3.8).

A.31.3

Completion Codes

Success Code:
XPO$ NORMAL
Error Codes:
XPO$ BAD ARGS
STR$-BAD-SOURCE

Fatal Error Codes:
XPO$ BAD LOGIC
-

The message was successfully processed.
The message argument list is invalid.
The string descriptor is invalid.
(Failure completion codes from $XPO GET MEM.)
(Failure completion codes from $XPO-PUT~ see
below.)
An XPORT logic error was detected.

Note that $XPO_PUT may be used to output messages to
the standard
XPORT output and/or error devices.
If the $XPO PUT operation fails,
the failure completion code from that operation is passed back as the
$XPO_PUT_MSG completion code.

A-85

Macro Descriptions
$XPO RENAME - Rename a File
A.32

$XPO RENAME - Rename a File

The $XPO RENAME macro calls the XPORT I/O facility to change one or
more
of- the
following
attributes of an existing file:
directory
specification, file name, file extension (or type), and
file version
(if
any).
After a
successful
file
renaming,
the
lOB user and
resultant file specifications are updated to reflect the changes that
were made.
This operation, like
OPEN
resolution as necessary.

A. 32. I

and

DELETE,

performs

file-specification

Syntax

+--------------------+-----------------------------------------------+
I
I

rename a file

$XPO RENAME ( parameter , ••. )

I
I

+--------------------+-----------------------------------------------+
requi red-parameter }
I

{

parameter

pr imary-parameter
}
optional-parameter }

I
I

{

NEW SPEC = char-string-info
}
I
+--------------------+------~----------------------------------------+
I
I
{
DEFAULT = char-string-info
}
I
I
I
{
NEW DEFAULT = char-string-info
}
I
I
I
{
RELATED = char-string-info
}
I
I
optional-parameter I { NEW RELATED = char-string-info
}
I
I
I
{
OPTIONS = option-keyword
}
I
I
I
{
USER = user-defined value
}
I
I
I
{
SUCCESS = address of action routine }
I
I
I
{
FAILURE = address of action routine }
I
I

{

+--------------------+-----------------------------------------------+
I

{

char-string-info

address of character string descriptor}
'literal ascii string'
}
(
count , pointer)
}

I
I
I

+--------------------+-----------------------------------------------+
option-keyword
REMEMBER
+--------------------+--------'---------------------------------------+
NOTE:

The keyword OPTIONS may be shortened to OPTION.

A-86

Macro Descriptions
$XPO RENAME - Rename a File
A.32.2
lOB

Parameter Semantics

= address of lOB
specifies the address of an lOB for the file to be renamed.
This
lOB must be initialized, but it must not be open when the RENAME
call is made.
This parameter mvst be specified.

FILE SPEC = character-string-info
-describes a file specification provided by the end user.
Unless
the lOB was previously closed with the REMEMBER option, this user
file specification is combined with the default and related
file
specifications,
if any, to form the resultant file specification
(see Section 3.6.1).
If this parameter
is not specified,
the
corresponding lOB string-descriptor field is not changed.
NEW_SPEC = character-string-info
describes the new file specification, typically also provided
by
the end
user.
This new file specification is combined with the
new-default and new-related file specifications, if any, to
form
the
resultant new file specification (see Section 3.6.1).
If
this parameter
is not
specified,
the
corresponding
lOB
string-descriptor field is not changed.
DEFAULT = character-string-info
describes
a
default
file
specification.
During
file-specification
resolution,
this
file specification
is
combined with the user and related file specifications,
if any,
to
form
the resultant file specification.
If this parameter is
not specified, the corresponding lOB string-descriptor
field
is
not changed.
NEW DEFAULT = character-string-info
- describes a default for the new file specification.
This file
specification is combined with
the new and new-related file
specifications,
if any,
to
form
the
resultant
new
file
the
specification.
If
this
parameter
is not specified,
corresponding lOB string-descriptor field is not changed.
RELATED = character-string-info
describes a file specification that is related to the file being
renamed.
During
file-specification
resolution,
this
file
specification is combined with the
user and default
file
specifications, if any, to form the resultant file specification.
If
this parameter
is not specified,
the corresponding
lOB
string-descriptor field is not changed.

A-87

Macro Descriptions
$XPO RENAME - Rename a File
NEW RELATED = character-string-info
describes a file specification that is related to
the new file
specification
for
the
file
being
renamed.
This
file
specification is combined with
the new and
new-default file
specifications,
if
any,
to
form
the
resultant new file
specification.
If this parameter is not specified, the resultant
old file
specification is assumed
as
the new-related
file
specification.
OPTIONS = option-keyword
indicates a processing option to be applied
renamed.

the

file

being

Meaning
REMEMBER

Remember relevant file attributes (e.g.,
resultant file specification)
so that
the
file can be
reprocessed
(e.g.,
opened, read, written, backed up).
File
processing
options
(including
this
option)
are not remembered, whether or
not this option-is specified.
If
this
option is not specified by file rename
time, the lOB is reset to an initialized
state after successful renaming.

If this parameter is not specified, the lOB option field
changed.

not

USER = user-defined value
specifies an application-dependent fullword value to be placed in
the
lOB
field
IOB$2 USER.
If this parameter is not specified,
the lOB user field is not changed.
SUCCESS = address of action routine
specifies the address of an action routine to
be called
upon
successful completion of the rename operation.
If this parameter
is not specified, no success action routine is assumed.
FAILURE = address of action routine
specifies the address of an action routine to be called
if
the
rename operation is unsuccessful.
If FAILURE=O is specified, no
failure action routine is called.
If this parameter
is not
specified, FAILURE=XPO$FAILURE is assumed (see Section 3.8).

A-88

Macro Descriptions
$XPO RENAME - Rename a File
A.32.3

Completion Codes

A primary completion code is returned as the routine-call value,
and
is
also
available
in the
IOB$G COMP CODE field of the
lOB.
A
secondary completion code (if any) is available in the
IOB$G 2ND CODE
field
of the lOB.
Secondary completion codes, where applicable~ are
indicated by a plus sign (+) following the associated primary code
in
the
listing
below.
The
secondary completion codes are listed and
described in Appendix C.
NOTE:
Some of the completion codes listed below may not apply to
operating systems.
Success Code:
XPO$_NORMAL

The file was successfully renamed.

Error Codes:
XPO$ BAD ACCT
XPO$-BAD-ATTR
XPO$-BAD-DELIM
XPO$-BAD-DEVICE
XPO$-BAD-DIRECT +
XPO$-BAD-DFLT +
XPO$-BAD-NAME
XPO$-BAD-NEW +
XPO$-BAD-PROT
XPO$-BAD-REQ +
XPO$-BAD-RLTD +
XPO$-BAD-TEMP
XPO$-BAD-VER
XPO$-BAD-RSLT +
XPO$-BAD-SPEC +
XPO$-CHANNEL +
XPO$-FREE MEM +
XPO$-GET MEM +
XPO$-IO ERROR +
XPO$-NO-ACCESS +
XPO$-NO-CHANNEL
XPO$-NO-DIRECT
XPO $-NO-F ILE
XPO$-NO-RENAME +
XPO $-NO-S PACE
XPO$-NO-SUBDIR
XPO$-NO-SUPPORT +
XPO $-NO-WRITE
XPO$-NOT ONLINE
XPO$-OPEN
XPO$-PROTECTED

Invalid account field.
Invalid attribute field in file spec.
Invalid punctuation used in a quoted string.
An invalid device was specified.
Error entering filename in directory.
The default file specification is invalid.
No filename was specified.
The new file specification is invalid.
Invalid protection field.
The XPORT request was invali6.
The related file specification is invalid.
Multiple ";T"s specified.
Generation number not numeric.
The resultant file specification is invalid.
The user file specification is invalid.
A channel-assignment error occurred.
Error freeing lOB-related memory.
A memory-allocation error occured.
A hardware-level I/O error occurred.
The file cannot be accessed.
No I/O channel was available.
The indicated directory was not found.
The file does not exist.
The file cannot be renamed.
File space exhausted.
The sub-directory does not exist.
The requested function is not supported.
The file is write-protected.
The device was not ready.
The file is currently open.
Access to the file is denied.

Fatal Error Codes:
XPO$ BAD lOB +
XPO$-BAD-LOGIC
-

The lOB is invalid.
An XPORT logic error was detected.
A-89

all

Macro Descriptions
$XPO SPEC BLOCK - Declare a File Specification Block
A.33

$XPO SPRC BLOCK - Declare a File Specification Block

The $XPO SPEC BLOCK macro generates an attribute list for
an XPORT
file
specification block allocated within an OWN, GLOBAL, LOCAL, MAP
or BIND declaration.
These attributes
(1)
indicate that the
file
specification block
is a BLOCK structure of a given length, and (2)
define the field-names that can be used to reference portions of the
block.
A file specification block is used
in
conjunction
with
the
The format of a file specification
$XPO PARSE SPEC macro (see A.27).
block is gTven in Appendix B.

A.33.l

Syntax

+--------------------+----------------_._-----------------------------+
I
I
I declare spec-block I $XPO SPEC BLOCK
I
I
-

I
I
I

+--------------------+-----------------------------------------------+
A.33.2

Examples

OWN
input spec blk :
output_spec_blk
LOCAL
temp_spec blk

$XPO SPEC BLOCK,
$XPO_S PEC_B LOCK;
$XPO SPEC_BLOCK;

MAP
passed_spec blk

A-gO

Macro Descriptions
$XPO TERMINATE - Terminate Program Execution
A.34

$XPO TERMINATE - Terminate Program Execution

The $XPO TERMINATE macro terminates program execution after sending
the
user a
termination message.
The message that
is issued is
determined by the completion code associated with the macro call.

A.34.1

Syntax

+--------------------+-----------------------------------------------+
I
I terminate program
I

I
I $XPO TERMINATE( {optional-parameter} )
I
.

I
I
I

+--------------------+-----------------------------------------------+
I optional-parameter I CODE = completion code
I
+--------------------+-----------------------------------------------+
A.34.2
CODE

Parameter Semantics

completion code
specifies an XPORT completion code.
This code is used to
select
the
program termination message that is sent to the user.
If
this parameter
is not specified,
CODE = XPO$_TERMINATE
is
assumed.

A.34.3

Routine Value

This XPORT function does not return a value or a completion code since
it results in program termination.
However, the specified or assumed
completion code becomes the program termination code.

A-91

APPENDIX B
B.l
B.2

B.3
B.4

CONTROL BLOCKS
IN PUT lOUT PUT BLOCK (lOB)
STRING DESCRIPTORS
• •
BINARY DATA DESCRIPTORS
• • • •
FILE SPECIFICATION PARSE BLOCK.

•
•

•

•
•
•

•

•
•

•
•
•
•

B-2
B-4
B-5
B-6

APPENDIX B
CONTROL BLOCKS

This appendix presents a detailed description of the control blocks
that
are
involved
in the use of XPORT facilities.
This appendix is
intended for reference use.
A tutorial discussion of these control
blocks and their usage is given earlier in this manual, beginning with
Chapter 3.

B-1

Control Blocks
INPUT/OUTPUT BLOCK (lOB)
B.l

INPUT/OUTPUT BLOCK (lOB)

The following table describes the lOB fields and literals that may be of interest to an XPORT
I/O
user.
The entries under the columns "Used By" and "Set By" indicate which XPORT I/O functions use
the corresponding field value (typically set by macro keyword parameters), and which functions set
the corresponding field value.

+-----------------+---------+------------+------------+------------------------------------------+
I
Symbol
I Type
I Used By*
! Set By*
I
Description
I
+-----------------+---------+------------+------------+------------------------------------------+
I

IOB$H LENGTH
10B$T=:RESULTANT

integer
desc

I all
I close,
backup

init
open,
delete,

Length of lOB (number of elements)
Resultant file specification descriptor

10B$A_ASSOC lOB

address

backup,
rename

Address of associated lOB

10B$B FUNC'I'ION
IOB$K-OPEN
10B$K-CLOSE
10B$K-DELETE
IOB$K-RENAME
10B$K-BACKUP
lOB $K-GET
10B$K=:PUT

byte
1
2
3

all

6
7

I/O function code:
open file
close file
delete file
rename file
create backup copy of input file
get record (locate mode)
put record (move mode)

10B$V OPTIONS
10B$V-INPUT
10B$V-OUTPU'I'
lOB $V-OVERWRITE
10B$V-APPEND
IOB$V-REMEMBER
lOB $V=:MA X_V ERS I

16 bits
bit
bit
bit
bit
bit
bit

IOB$V ATTRIBUTE
IOB$V=:BINARY

16 bits
bit

10B$V_STREAM

bit

IOB$V_RECORD

bit

lOB $V _S EQUENCED

bit

10B$V STATUS
10B$V-OPEN
10B$V-EOF
10B$V-CLOSED
10B$V-AUTO CONC
10B$V-TERMINAL
lOB $V=:TEM PORARY

16 bits
bit
bit
bit
bit
bit
bit

lOB $V _CONC_S PEC

bit

lOB $V _CH_ASSIGN

bit

10B$T STRING
10B$H-STRING
10B$A=:STRING

desc
2 bytes
pointer

10B$T_DATA

desc

10B$H_UNITS

2 bytes

10B$A_DATA

add ress

get-bin

Binary input data descriptor (overlays
IOB$T STRING):
lengtn of the data in addressable
units
address of the data

10B$H_FULLWORDS

2 bytes

get-full

length of the data in BLISS fullwords

4
5

I/O option flags:
open for input
open for output
overwrite existing output file
append to existing output file
file will be reprocessed after close
maximize file version number
(internal)

open, get
open, put
open-out
open-out
close
open,
rename
open, get,
put
open, get,
put
open, get,
put
open-out,
put

File attributes:
binary data
stream-oriented character data
record-oriented character data
open-in

all
get, put
open
open
get, put
open,
close
close

open
get, put
close
get-conc
open
open

open,
delete,
rename

get-stream

get-char
get-char

get-bin

open

sequence-numbered records
Current file status:
file is open
end-of-file detected
file is closed
input file switching in progress
I/O device is a terminal
XPORT temporary file
primary file-spec is a concatenated
file-spec
channel has been assigned

Character input string descriptor:
length of the character string
pointer to the character string

+-----------------+---------+------------+------------+------------------------------------------+
I
continued on the next page
I
+------------------------------------------------------------------------------------------------+
B-2

Control Blocks
INPUT/OUTPUT BLOCK (lOB)

+-----------------+---------+------------+------------+------------------------------------------+
I
Symbol
I Type
I Used By*
I Set By*
I
Description
I
+-----------------+---------+------------+------------+------------------------------------------+
I

IOB$H PAGE NUMB
IOB$G-SEQ NUMB
IOB$G=PREV_REC

integer I
integer I put-seq
integer I

lOB $G REC NUMB
IOB$G=REC=SIZE

integer I
integer I open-out

get-seq
get

lOB $G_B LK _S IZE
IOB$G COMP CODE
IOB$G=2ND_CODE

I
integer I open-out
I
integer I
integer I
I

IOB$Z USER
IOB$G=USER CODE

integer
integer

IOB$A BUFFER CB
IOB$A-RMS FAB
IOB$A-RMS-RAB
IOB$A=FCS=FDB

address
address
address
address

IOB$A_RSTS_CB

address

IOB$H_CHANNEL

integer

open
open
all
all

I
I Current page number
I Sequence number of current record
I Number of last direct record read or
I
written (future)
I Direct-access record number (future)
I ~ixed record size (0 = variable length
records)
I
I Block size
I
I Completion code of current operation
I Secondary completion code

I
I
I
I
I
I
I

User-defined value
User-defined completion code
get, put
close
get, put
get put
close
get put
close
get put
close

open
open
open
open

Address
Address
Address
Address

of
of
of
of

TOPS-IO
RMS FAB
RMS RAB
FCS FDB

buffer control block
(system-specific)
(system-specific)
(system-specific)

open

Address of RSTS control block

open

I/O channel number (system-specific)

+-----------------+---------+------------+------------+------------------------------------------+
* Code-names for XPORT I/O functions:
all
init
open
open-in
open-out
open-conc
close
get
get-char
get-stream
get-conc
get-bin
get-full
put
put-seq
delete
rename
backup

All I/O functions
lOB initialization
Open either input file or output file
Open input file
Open output file
Automatic open of concatenated input file
Close file
All binary and character get operations
Get character string
Get character stream data
Get with automatic input concatenation
Get binary data
Get binary fullwords
All binary and character put operations
Put sequenced output record
Delete file
Rename file
Backup file

Declaration macro:
Initialization macro:

$XPO_IOB INIT

B-3

Control Blocks
STRING DESCRIPTORS
B.2

STRING DESCRIPTORS

The following table describes the fields of a string descriptor
Section 6.1), and the literals associated with these descriptors.

(see

+-----------------+---------+----------------------------------------+
I
Symbol
I Type
I
Description
I
+-----------------+---------+----------------------------------------+
I
I S'l'R$H LENG'l'H
I
I S'I'R$B DTYPE
I STR$K-D'l'YPE XXX
I S'lR$K=DTYPE=T
I
I S'l'R$B CLASS
I S'l'R$K-C LASS Z
I STR$K-CLASS-F'
I STR$K-CLASS-D
I STR$K-CLASS-B
I STR$K-CLASS-DB
I S'l'R $K=C LASS=XT
I
I S'lR$A POINTER
I
I S'l'R$H MAXLEN
I STR$H-PF'XLEN
I

2 bytes

Number of characters in the string

byte

Atomic data type code:
Erroreous XPORT temporary string
ASCII text string

o
14

190
189

Descriptor class code:
unspecified
fixed str ing
dynamic string
bo und ed str i ng
dynamic bounded string
XPORT tempo ra ry string (dynamic)

pointer

Pointer to the character string

2 bytes
2 bytes

Length of the container string
Length of the prefix string

byte

o
1
2

+-----------------+---------+----------------------------------------+
Declaration macro:

$STR DESCRIPTOR

Initialization macro:

$STR DESC INIT

B-4

Control Blocks
BINARY DATA DESCRIPTORS
B.3

BINARY DATA DESCRIPTORS

The following table describes the fields of a binary data descriptor
(see Section 7.1), and the literals associated with these descriptors.

+-----------------+---------+----------------------------------------+
I
Symbol
I Type
I
Description
I
+-----------------+---------+----------------------------------------+
I

2 bytes I Length of the binary data units
XPO$B DTYPE
XPO$K=DTYPE_BU
XPO$B CLASS
XPO $K-C LASS Z
XPO$K-CLASS-F
XPO $K-C LASS-D
XPO $K-C LASS-B
XPO $K=C LASS=DB
XPO$A_ADDRESS
XPO $H MAXLEN
XPO$H=PFXLEN

I
I Atomic data type code:
2
I
XPORT binary data (binary units)
I
byte
I Descriptor class code:
o
unspecified
I
fixed binary data
1
I
2
dynamic binary data
I
bounded binary data
3
I
190
dynamic bounded binary data
I
I
pointer I Address of the binary data
I
2 bytes I Maximum length of the binary data
2 bytes I Length of the binary data prefix
I
byte

+-----------------+---------+----------------------------------------+
Declaration macro:

$XPO DESCRIPTOR

Initialization macro:

$XPO DESC INIT
-

B-5

Control Blocks
FILE SPECIFICATION PARSE BLOCK
B.4

FILE SPECIFICA1ION PARSE BLOCK

The following table describes all XPORT File Specification Parse Block
fields and literals (see Section 3.6.2).

+-----------------+---------+----------------------------------------+
I
Symbol
I Type
I
Description
I
+-----------------+---------+----------------------------------------+
I

XPO$V SPEC STAT
XPO $V-DIR N"Alv'lE
XPO$V-PPNXPO$V-SFD
XPO$V-WILD CARD
XPO $V-WILD-NODE
XPO$V-WILD-DEV
XPO$V-WILD-DIR
XPO$V-WILD-NAME
XPO $V-WILD-TYPE
XPO$V-WILD-VER
XPO$V=WILD=ATTR

16 bits I File specification indicators:
bit
<directory-name> specified
I
bit
[proj ect, prog rammer] spec i f ied
I
bit
[, ,SFD] specified (TOPS-IO only)
bit
wild-card somewhere in file-spec
bit
wild-card node name
bit
wild-card device name
bit
wild-card in directory name
bit
wild-card file name
wild-card file type (extension)
bit
wild-card file version number
bit
bit
wild-card file attributes

XPO$T NODE
XPO$H-NODE
XPO$A-NODE

desc
2 bytes
pointer

Network node name descriptor:
length of the node name
pointer to the node name

XPO$T DEVICE
XPO $H-DEVICE
XPO$A-DEVICE

desc
2 bytes
pointer

Device name descriptor:
length of the device name
pointer to the device name

XPO$T DIRECT
XPO $H-DIREC'l'
XPO$A-DIRECT

desc
2 bytes
pointer

Directory specification descriptor:
length of the directory spec
pointer to the directory spec

XPO$H PROJ NUMB
XPO$H-PGMR-NUMB
-

2 bytes
2 bytes

Project number (binary)
Programmer number (binary)

XPO $1' FILE NAME
XPO$H-FILE-NAME
XPO $A -F' ILE-NAME
-

desc
2 bytes
pointer

File name descriptor:
length of the file name
pointer to the file name

XPO$T FILE TYPE
XPO$H-FILE-TYPE
XlJO$A-FILE-TYPE
-

desc
2 bytes
pointer

File type (extension) descriptor:
length of the file type
pointer to the file type

XPO$T FILE VER
XPO$H-FILE-VER
XPO$A=FILE=VER

desc
2 bytes
po inter

File version number descriptor:
length of the file version
pointer to the file version

+-----------------+---------+----------------------------------------+
I
continued on the next page
I
+--------------------------------------------------------------------+
B-6

Control Blocks
FILE SPECIFICATION PARSE BL0CK

+-----------------+---------+----------------------------------------+
I
Symbol
I Type
I
Description
I
+-----------------+---------+----------------------------------------+
I
I
I
I
I File protection descriptor (RSTS
I
I XPO$T FILE PROT I desc
I
I
onl y) :
I
I
I XPO$H FILE PROT I 2 bytes I
length of the protection
I
I XPO$A-FILE-PROT I pointer I
pointer to the protection
I
I
I XPO$T EXTRA
I XPO$H-EXTRA
I XPO$A-EXTRA
I

I
I desc
I 2 bytes
I pointer
I

I
I File 'EXTRA' information descriptor:
I
length
I
pointer
I

I
I
I
I
I

+------~----------+---------+------------------------- ---------------+

Declaration macro:

$XPO SPEC BLOCK
-

Initialization macro:

Not needed

B-7

APPENDIX C
COMPLETION CODES

The following table lists all XPORT completion codes together with
their
numeric values and corresponding message texts.
Note that the
numeric values are given for debugging purposes only;
they should not
be 'hard-coded' into a program.

C-l

Completion
Code Name

()

I
N

S'l'RS FAILURE
STRS-NORMAL
XPO S-NORMA L
XPO S-CREATED
XPOS-INCOMPLETE
XPOS-NEW FILE
XPOS-NEW-PAGE
STRS-END-STRING
S'l'RS-TRUNCATED
STRS-NOT TEMP
XPOS-END-FlLE
XPO $-BAD-A DDR
XPOS-BAD-ALIGN
XPO S-BAD-ARGS
XPO S-BAD-C ONCAT
XPOS-BAD-OELIM
XPO S-BAD-DESC
XPO S-BAD-OEVICE
XPOS-BAD-OFLT
XPOS-BAD-OIRECT
XPO S-BAD-DTYPE
XPOS-BAD-FORMAT
XPOS-BAD-IO OPT
XPOS-BAD-LENGTH
XPOS-BAD-NAME
XPOS-BAD-NEW
XPOS-BAD-NODE
XPOS-BAD-ORG
XPO S-BAD-PROMPT
XPO S-BAD-RECORD
XPOS-BAD-REQ
XPO S-BAD-R LTD
XPOS-BAD-RSLT
XPOS-BAD-SPEC
XPO S-BAD-TYPE
XPOS-BAD-VER
XPOS-CHANNEL
XPO S-C LOSED
XPOS-CONFLICT
XPOS-CORRUPTED
XPOS-EXISTS
XPOS-F ILE LOCK
XPO S-FREE-MEM
XPO S-GET MEM
XPO()N USE

Code Val ue
Severity

BLISS-16/36

warning
success
success
success
success
success
success
success
success
success
warning
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error

o
1
1
9

17
25
33
2049
2057
2065
4096
8194
8202
8210
8218
8226
8234
8242
8250
8258
8266
8274
8282
8290
8298
8306
8314
8322
8330
8338
8346
8354
8362
8370
8378
8386
8394
8402
8410
8418
8426
8434
8442
8450
8458

%0'000000'
%0'000001'
%0'000001'
%0'000011'
%0'000021'
%0' 000031'
%0' 000041'
%0'004001'
%0'004011'
%0 '004021'
%0'010000'
%0' 020002'
%0'020012'
%0' 020022'
%0'020032'
%0' 020042'
%0'020052'
%0'020062'
%0'020072'
%0'020102'
%0' 020112'
%0' 020122'
%0'020132'
%0'020142'
%0'020152'
%0 '020162'
%0' 0201 72'
%0'020202'
%0'020212'
%0' 020222'
%0'020232'
%0' 020242'
%0'020252'
%0'020262'
%0' 020272'
%0' 02030 2'
%0'020312'
%0'020322'
%0'020332'
%0' 020342'
%0'020352'
%0' 020362'
%0' 020372'
%0' 02040 2'
%0'020412'

Message Text

BLISS-32
2129920
2129921
2129921
2129929
2129937
2129945
2129953
2394113
2394121
2394129
2134016
2138114
2138122
2138130
2138138
2138146
2138154
2138162
2138170
2138178
2138186
2138194
2138202
2138210
2138218
2138226
2138234
2138242
2138250
2138258
2138266
2138274
2138282
2138290
2138298
2138306
2138314
2138322
2138330
2138338
2138346
2138354
2138362
2138370
2138378

%X'208000'
%X'208001
%X'208001'
%X'208009'
%X'208011'
%X'208019'
%X'208021'
%X'248801'
%X'248809'
%X '248811'
%X' 209000'
%X'20A002'
%X'20AOOA'
%X'20A012'
%X' 20A01A'
%X'20A022'
%X'20A02A'
%X'20A032'
%X' 20A03A'
%x'20A042'
%X'20A04A'
%X'20A052'
%X'20A05A'
%X'20A062'
%X '20A06A'
%X'20A072'
%X'20A07A'
%X'20A082'
%X'20A08A'
%X'20A092'
%X' 20A09A'
%X' 20AOA2'
%X'20AOAA'
%X'20AOB2'
%X' 20AOBA'
%X'20AOC2'
%X' 20AOCA'
%X '20AOD2'
%X'20AODA'
%X '20AOE2'
%X'20AOEA'
%X'20AOF2'
%X'20AOFA'
%X'20AI02'
%X'20AI0A'

unsuccessful completion
normal completion
normal completion
file was successfully created and opened
incomplete amount of data read
first read on concatenated file was successful
first read on a new page was successful
end of string reached
string was truncated
not a temporary string
end-of-file has been reached
invalid memory address
memory element not on a fullword boundary
invalid argument list
invalid concatenated file specification
invalid punctuation
invalid descriptor
invalid device
invalid default file specification
invalid directory
invalid data type
invalid record format
invalid I/O option
invalid length
invalid file name
invalid new file
invalid node
invalid file organization
invalid prompt
invalid record
invalid request
invalid related file specification
invalid resultant file specification
invalid file specification
invalid file type
invalid file version
I/O channel assignment error
file is already closed
conflicting options or attributes
file is corrupted
file already exists
file is locked
dynamic memory deallocation error
dynamic memory allocation error
file is currently in use

continued on the next page

()

:s:

I"tJ

t""

1-3
H

o
Z

()

(fl

Completion
Code Name

()

XPO$ 10 BUFFER
XPO $-1 O-ERROR
XPO$-MISSING
XPO$-NETWORK
XPO $-NO ACCESS
XPO $-NO-BACKUP
XPO $-NO-CHANNEL
XPO$-NO-CLOSE
XPO $-NO-C ONCAT
XPO$-NO-CREATE
XPO$-NO-DELETE
XPO$-NO-DIRECT
XPO$-NO-FILE
XPO $-NO-MEMORY
XPO$-NO-OPEN
XPO $-NO-READ
XPO $-NO-RENAME
XPO $-NO-S PACE
XPOS-NO-S UBDIR
XPO $-NO-S UPPORT
XPO $-NO-WRITE
XPOS-NOT CLOSED
XPO $-NOT-E XPIRE
XPO $-NOT-INPUT
XPOS-NOT-ONLINE
XPOS-NOT-OPEN
XPO S-NOT-OUT PUT
XPO$-OPEN
XPO$-PREV ERROR
XPOS-PRIVILEGED
XPOS-PROTECTED
XPOS-PUT MSG
XPO S-REC-LOC K
XPO$-RENAME NEW
XPO$-RENAME-OLD
XPO $-TRUNCATED
X?OS-WILDCARD
XPOS-BAD ACCT
XPO$-BAD-ATTR
XPO$-BAD-DA'I'A
XPO $-BAD-MEDIA
XPO S-BAD-MEMORY
XPO()AD=PROT

Code Va] ue
Severity
error
error
error
error
error
error
error
error
error
erro.r
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error

BLISS-16/36
8466
8474
8482
8490
8498
8506
8514
8522
8530
8538
8546
8554
8562
8570
8578
8586
8594
8602
8610
8618
8626
8634
8642
8650
8658
8666
8674
8682
8690
8698
8706
8714
8722
8730
8738
8746
8754
8762
8770
8778
8786
8794
8802

%0' 0204 22'
%0' 0204 32'
%0'020442'
%0'020452'
%0'020462'
%0'020472'
%0'020502'
%0'020512'
%0'020522'
%0'020532'
%0'020542'
%0'020552'
%0'020562'
%0'020572'
%0'020602'
%0' 020612'
%0'020622'
%0'020632'
%0'020642'
%0'020652'
%0'020662'
%0'020672'
%0'020702'
%0'020712'
%0' 020722'
%0'020732'
%0'020742'
%0'020752'
%0'020762'
%0'020772'
%0' 021002'
%0'021012'
%0'021022'
%0' 0210 32'
%0' 021042'
%0' 0210 52'
%0'021062'
%0'021072'
%0'021102'
%0' 021112'
%0'021122'
%0'021132'
%0'021142'

BLISS-32
2138386
2138394
2138402
2138410
2138418
2138426
2138434
2138442
2138450
2138458
2138466
2138474
2138482
2138490
2138498
2138506
2138514
2138522
2138530
2138538
2138546
2138554
2138562
2138570
2138578
2138586
2138594
2138602
2138610
2138618
2138626
2138634
2138642
2138650
2138658
2138666
2138674
2138682
2138690
2138698
2138706
2138714
2138722

%X '20A112'
%X' 20AllA'
%X'20A122'
%X '20A12A'
%X '20A132'
%X '20A13A'
%X '20A142'
%X '20A14A'
%X'20A152'
%X'20A15A'
%X'20A162'
%X'20A16A'
%X '20A172'
%X'20A17A'
%X '20A182'
%X '20A18A'
%X '20A192'
%X '20A19A'
%X '20AIA2'
%X'20AIAA'
%X '20AIB2'
%X'20AIBA'
%X '20AIC2'
%X'20AICA'
%X'20AID2'
%X'20AIDA'
%X'20AIE2'
%X'20AIEA'
%X'20AIF2'
%X '20AlFA'
%X' 20A202 '
%X' 20A20A'
%X '20A212'
%X' 20A21A'
%X '20A222'
%X '20A22A'
%X '20A232'
%X '20A23A'
%X '20A242 '
%X'20A24A'
%X '20A252'
%X '20A25A'
%X '20A262'

Message Text
I/O buffering error
I/O error
required parameter, option or attribute missing
network error
file cannot be accessed
file cannot be backed up
all I/O channels are in use
file cannot be closed
concatenated file specification not allowed
file cannot be created
file cannot be deleted
directory does not exist
file does not exist
insufficient dynamic memory
file cannot be opened
file cannot be read
file cannot be renamed
insufficient space
sub-directory does not exist
requested function not supported
file cannot be written
file has not been closed
expiration date has not been reached
file is not open for input
device is not online
file has not been opened
file is not open for output
file is currently open
program terminated due to previous error
privileged operation
file protection denies access
message output error
record is locked
new file cannot be renamed
old file cannot be renamed
record was truncated
wildcard error
invalid account attribute
invalid attribute
invalid data
disk/tape cannot be read/written
free storage chain is invalid
invalid protection attribute

continued on the next page

()

'i:l

l'
t'l

1-3
H

o
Z

()

t:l

t'l

(f)

Completion
Code Name

(")

I
~

XPO$ BAD PTR
XPO $-BAD-RECNUM
XPO$-BAD-SIZE
XPO$-BAD-TEMP
XPO $-CHAN USED
XPO$-HOST-ERROR
XPO$-NO NODE
XPO$-NO-STACK
XPO$-SYS ERROR
XPO$-BAD-C LASS
XPO$-NO TEMP
XPO$-FOREGROUND
XPO$-NO APPEND
XPO$-NO-SEQ
XPO $-BAD ORDER
XPO$-BAD-SYNTAX
S TR $-BAD-C HAR
STR$-BAD-C LASS
STR$-BAD-DESC
STR$-BAD-DTYPE
STR$-BAD-LENGTH
STR$-BAD-MAXLEN
STR$-BAD-PATTRN
STR$-BAD-PTR
STR$-BAD-REQ
STR$-BAD-SOURCE
STR$-BAD-STRNG 1
STR$-BAD-STRNG2
STR$-BAD-TARGET
STR$-CONFLICT
STR$-NO SPACE
STR$-NO-STRING
STR$-NO-S UP PORT
STR$-NO-TEMP
STR$-NULL STRNG
STR$-OUT RANGE
XPO$-BAD-IOB
XPO $-BAD-LOG IC
XPO$-TERMINATE
STR()AD_LOGIC

Code Value
Severity
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
error
fatal
fatal
fatal
fatal

BLISS-16/36
8810
8818
8826
8834
8842
8850
8858
8866
8874
8882
8890
8898
8906
8914
8922
8930
10242
10250
10258
10266
10274
10282
10290
10298
10306
10314
10322
10330
10338
10346
10354
10362
10370
10378
10386
10394
16388
16396
16404
18436

%0 '021152'
%0'021162'
%0' 0211 72'
%0' 02120 2'
%0'021212'
%0'021222'
%0'021232'
%0' 02124 2'
%0'021252'
%0'021262'
%0' 021272'
%0'021302'
%0'021312'
%0'021322'
%0' 021332'
%0' 02134 2'
%0' 024002'
%0'024012'
%0' 0240 22'
%0' 0240 32'
%0' 024042'
%0' 0240 52'
%0'024062'
%0'024072'
%0' 024102'
%0' 024112'
%0' 024122'
%0'024132'
%0' 02414 2'
%0' 024152'
%0 '024162'
%0' 0241 72'
%0'024202'
%0'024212'
%0'024222'
%0'024232'
%0'040004'
%0'040014'
%0'040024'
%0'044004'

BLISS-32
2138730
2138738
2138746
2138754
2138762
2138770
2138778
2138786
2138794
2138802
2138810
2138818
2138826
2138834
2138842
2138850
2402306
2402314
2402322
2402330
2402338
2402346
2402354
2402362
2402370
2402378
2402386
2402394
2402402
2402410
2402418
2402426
2402434
2402442
2402450
2402458
2146308
2146316
2146324
2410500

%X' 20A26A'
%X' 20A272'
%X' 20A27A'
%X' 20A282'
%X' 20A28A'
%X '20A292'
%X' 20A29A'
%X' 20A2A2'
%X' 20A2AA'
%X'20A2B2'
%X '20A2BA'
%X' 20A2C2'
%X' 20A2CA'
%X '20A2D2'
%X' 20A2DA'
%X '20A2E2'
%X' 24A802 '
%X' 24A80A'
%X'24A812'
%X'24A81A'
%X'24A822'
%X' 24A82A'
%X' 24A832 '
%X '24A83A'
%X'24A842'
%X'24A84A'
%X'24A852'
%X' 24A85A'
%X'24A862'
%X' 24A86A'
%X '24A872 '
%X'24A87A'
%X'24A882'
%X'24A88A'
%X' 24A892'
%X'24A89A'
%X' 20C004 '
%X'20COOC'
%X '20C014 '
%X' 24C804 '

Message Text
invalid character pointer
invalid record number
invalid size
invalid temporary file attribute
I/O channel is currently in use
host operating system error
network node does not exist
insufficient stack space
unexpected operating system error
invalid descriptor class
temporary file not permitted
foreground jobs not permitted
append function not permitted
sequenced files not permitted
field is misplaced or duplicated
invalid syntax
invalid character
invalid descriptor class
invalid string descriptor
invalid descriptor data type
invalid string length
invalid maximum string length
invalid pattern string
invalid string pointer
invalid string request
invalid source string
invalid primary string
invalid secondary string
invalid target string
conflicting string function arguments
insufficient space
no string specified
requested function not supported
temporary string not permitted
null string not permitted
integer value out of range
invalid lOB
XPORT logic error detected
program terminated due to program request
XPORT string logic error detected

(")

3:
"tJ

J:1j

>-3
H

o
Z

o
J:1j
en

APPENDIX D
SAMPLE PROGRAM

This appendix presents a programming example that uses most of the
XPORT facilities in a realistic context. The program reads a BLISS
source file and merges into it the contents of any REQUIRE files
referred to in the original.

D-l

Sample Program

MODULE MERGER ( IDENT = 'Vl.O-l',
%TITLE 'BLISS REQUIRE File Merger'
MAIN = MERGER
%BLISS32(,ADDRESSING MODE ( EXTERNAL=LONG_RELATIVE ) )

) =

BEGIN
1++
I

F'ACILITY:

BLISS User Program Library

ABSTRACT:
This program "merges" the contents of any REQUIRE files declared
in a primary source file into that primary file. It also provides
a visually-distinctive header for each segment of REQUIRE-file
code.
•
ENVIRONMENT:
AUTHORS:

User Mode with XPORT Faciliity; system independent.

Ed Williams and Ward Clark,

CREATION DA'lE:

21 June 1979

1--

1
I

TABLE OF CONTENTS:

FORWARD ROUT INE
MERGER,
REQUIRE DECL,
OPEN_REO_FAIL;

Primary file merging control routine
REQUIRE declaration parser
Open failure action routine

INC LUDE FILES:
LIBRARY 'BLI:XPORT';

XPORT definitions

MACROS:

MACRO
ski P ( s t ring ) =
(%STRING( %CHAR(cr), %CHAR(lf), string» %;
EQUATED SYMBOLS:
LI'l'ERAL
true = 1,
fal se = 0,
ht
%0'11',
cr
%0'15',
1f
%0' 12 ' ,
ff
%0'14';
OWN STORAGE:
OWN

term inal : $XPO lOB () ,
primary file : $XPO lOB () ,
require-file: $XPO-IOB(),
output_Tile: $XPO_IOB () ;

lOB
lOB
lOB
lOB

EXTERNAL REFERENCES:

D-2

for
for
for
for

terminal I/O
primary input file
current REQ file
output file

Sample Program

ROUTINE MERGER

Program entry point

1++
I

I FUNCTIONAL DESCRIPTION:
I
I
I
I
I
I

This routine performs all of file merging except for the parsing
of BLISS source statements (see the REQUIRE DECL routine) and trying
alternate REQUIRE file default file-types (see the OPEN REQ FAIL
action routine).
-

I FORMAL PARAMETERS:
None
IMPLICIT INPUTS:
None
IMPLICIT OUTPUTS:
None
COMPLETION CODES:
I

XPO$_NORMAL

Successful completion

I SIDE EFFEC'l'S:
I

None

I
1--

BEGIN
1+
I
Open the user's terminal for input/output and greet the user.
1-

$XPO_OPEN ( lOB = terminal, InLE_SPEC = $XPO_INPUT );
$XPO PUT( lOB = terminal, STRING = skip('BLISS REQUIRE File Merger')
1+ .
I
Ask the user for a BLISS source file-spec and open the file.

);

WHILE 1 DO
1 Loop until the user gives a valid file-spec.
BEGIN
IF ~OT $XPO GET( lOB = terminal,
PROMPT = skip( 'Enter name of BLISS source file (.BLI assumed): ') )
THEN
RETURN XPO$_NORMAL;
1 Exit if the user types ~Z.
IF $XPO_OPEN( lOB = primary file,
FILE SPEC =-terminal [IOB$T STRING],
DEFAULT
'.BLI' ,
FAILURE = XPO$IO_FAILURE
THEN
EXITLOOP;
END;
1+
I

Ask the user for an output file-spec and open the output file.

IF NOT $XPO GET( lOB = terminal,
-PROMPT = skip('Enter name of output file
THEN
RETURN XPO$_NORMAL;

(*.BLl assumed):

)

Exit if the user types

~Z.

output file[IOB$V SEQUENCED]
.primary_file[IOB$V_SEQUENCED];

Make the output file sequenced
if the input file is sequenced.

IF .terminal[IOB$H STRING] GTR 0
THEN
$XPO OPEN( lOB = output file,
FILE SPEC = ter~inal[IOB$T STRING],
DEFAULT =
'*.BLI' ,
RELATED = primary file [IOB$T RESULTANT],
OPTION = OUTPUT )ELSE
$XPO_OPEN( lOB = output file,
FILE SPEC = $XPO TEMPORARY,
OPTION = OUTPUT );
1+
I
Primary input file processing loop.

If the user gave a file-spec,
open the specified file for output.

Otherwise, open a temporary output file.

WHILE $XPO GET( lOB = primary file)
BEGIN IF NOT REQUIRE_DECL()

Read until end-of-file.

If this line is not a REQUIRE statement,

D-3

Sample Program

'l'HEN
$XPO PUTt lOB = output file,
copy the line into the output file.
STRING = primary fTle[IOB$T STRING],
SEQUENCE_NUMBER ~ .primary_file[IOB$G_SEQ_NUMB]
1+
I
1-

REQUIRE file processing loop.

ELSE
BEGIN
WhILE I DO
IF $XPO OPEN( lOB
require file,
-FAILURE
OPEN_REQ_FAIL )
'lHEN
EXI'l'LOOP;
$XPO_PUT( lOB = output file,
STRING = %STRING( %CHAR (ff)
SEQUENCE_NUMBER = 0 );

REQUIRE DECL sets up FILE SPEC= and DEFAULT=.
Action routine sets up alternate file types.

Put an SOS page mark before the REQUIRE file.
),

WHILE $XPO GET( lOB = require file) DO
1 Copy the entire REQUIRE file
$XPO PU'l' ( lOB = output file,
1 into the output file.
STRING = require file[IOB$T STRING],
SEQUENCE_NUMBER ~ .require_file[IOB$G_SEQ_NUMB] );
$XPO_PUT( lOB = output file,
STRING = %STRING( %CHAR(ff)
SEQUENCE_NUMBER = 0 );

1 Put an SOS page mark after

the REQUIRE file.

$XPO CLOSEt lOB = require_file );
END;-

Then close the REQUIRE file

END;

and continue processing the primary source file.

Cleanup after reaching the end of the primary source file.
1-

$XPO_CLOSE( lOB = primary file,
OPTION = REMEMBER );

Close the source file and remember its name.

$XPO_CLOSE( lOB = output_file );

Close the output file (Note: its name will be
remembered i f it is a temporary file).

Rename the output file and backup the input file if the user
did not provide an output file specification.
1-

IF .output file[10B$V TEMPORARY]
THEN
$XPO BACKUP ( OLD lOB = primary file,
NEW_lOB ~ output_file );
1+

Tell the user that the file merging was successfully completed.
1-

$XPO PUTt lOB = terminal,
5'l'RING = skip('REQUIRE file merging successfully completed')
$XPO_CL05E ( lOB = terminal );
RETURN XPO$_NORMAL
END;

D-4

);

Sample Program

ROUTINE REQUIRE_DECL
1++
I

I FUNCTIONAL DESCRIPTION:
1
1
This routine determines whether the current source line is a REQUIRE file declaration.
1
1 FORMAL PARAMETERS:
1
1
None
1
1 IMPLICIT INPUTS:

primary_f.ile[IOB$T_STRING]

1
I

current source line descriptor

1 IMPLICIT OUTPUTS:
1
1
require_file[IOB$A_FILE SPEC]
1
1 COMPLETION CODES:

address of REQUIRE file name descriptor

1
true - line is a REQUIRE declaration
1
false - line is not a REQUIRE declaration
1
1 SIDE EFFECTS:
1

None

1
1--

BEGIN
OWN
statement

spaces

$STR_DESCRIPTOR( CLASS

DYNAM IC, STR ING

$STR_DESCRIPTOR( CLASS

BOUNDED) ,

$STR_DESCRIPTOR( STRING = %STRING('

(0,0)

',%CHAR(ht))

);

Create a local, upper-case version of the BLISS statement.

$STR COpy ( STRING = primary_file[IOB$T_STRING], TARGET = statement, OPTION
1+

UP CASE );

Initialize the BLISS source line descriptor.
1-

$STR DESC INIT( DESCRIPTOR
1+

Bypass any leading
1-

$STR SCAN( REMAINDER

= line scan, CLASS = BOUNDED, STRING

spac~s

statement) ;

and/or tabs.

= line_scan, SPAN = spaces, SUBSTRING

Test for a REQUIRE statement.

line_scan);

$STR SCAN( REMAINDER = line scan, STOP = spaces, SUBSTRING = line_scan );
IF' NOT $STR EQL (STRING]
line_scan, STRING2 = 'REQUIRE' )
THEN
RETURN false;
1+

Locate the name of the REQUIRE file in the source line.

IF $STR SCAN( REMAINDER = line scan, STOP = " " , SUBSTRING
line_scan) NEQ STR$_END_STRING
THEN
BEGIN
line scan[STR$H LENGTH]
.line scan[STR$H LENGTH] + 1;
IF $STR SCAN( REMAINDER
line_scan, STOP ~ " " , SUBSTRING
line scan) NEQ ST'R$_END STRING
THEN
BEGIN
1+

Put the REQUIRE file name into the REQUIRE-file lOB.
1-

$XPO lOB IN IT ( lOB = requi re_file, FILE_SPEC
1+

Return a success code to the caller.

line_scan, DEFAULT

'.REQ' );

RETURN true
END;
END;
1+

Tell the user about an invalid REQUIRE declaration and terminate program execution.

$XPO PUT MSG( STRING = 'Cannot find a file-spec in the following BLISS REQUIRE statement:',
STRING = primary file[IOB$T STRING],
SEVERITY = FATAL-)
! NOTE: Fatal message terminates prog ram ..
END;

D-5

Sample Program

ROUTINE OPEN_REQ_FAIL( function_code, primary_code, secondary_code, iob )
1++
!
! 'FUNC'l'IONAL DESCRIPTION:

This failure action routine is used to supply a series of default
file types to open a REQUIRE file.
FORMAL PARAMETERS:
function code - action routine function code - ignored
primary code - primary $XPO OPEN failure completion code
secondary code - secondary $XPO OPEN failure completion code
iob - address of the REQUIRE file lOB
IMPLICIT INPUTS:
iob[IOB$~_USER]

number of times this routine has been called

IMPLICIT OUTPUTS:
None
COMPLETION CODES:
XPO$_NORMAL - alternate REQUIRE file successfully opened
SIDE EFF'EC'l'S:
This routine terminates program execution if a REQUIRE file
cannot be successfully opened.
1--

BEGIN
MAP
iob

REF $XPO IOB();

BIND
recursion level

iob[IOB$Z USER];

EXTERNAL ROUTINE
! Default I/O failure action routine
XPO$FAILURE;
!+
Perform default file type sequencing only for "file not found" errors.
IF .primary code NEQ XPO$_NO_FILE
THEN
BEGIN
XPO$FAILURE{ .function code, .primary_code, .secondary_code, .iob );
RETURN .primary code
END;
!+
Increment the recursion counter.
!-

recursion_level = .recursion_level + 1;
!+
Try a new default file type for the REQUIRE file.
1-

CASE .recursion level FROM 1 TO
OF
SET
1
iob[IOB$A DEFAULT]
%ASCID'.R16';
2
iob[IOB$A-DEFAULT]
%ASCID'.R32';
3
iob[IOB$A-DEFAULT]
%ASClD'.R36';
4
iob[IOB$A-DEF'AULT]
%ASCID'.BLI';
5
iob[IOB$A-DEF'AULT]
%ASClD' .B16';
6
iob[IOB$A-DEF'AULT]
%ASClD'.B32';
7
iob[IOB$A-DEF'AULT]
%ASCID'.B36';
8
$XPO PUT ~SG( STRING = 'cannot open the file named in the following REQUIRE declaration:',
STRING = primary file[IOB$T STRING],
SEVERITY = F'ATAL-);
NOTE: Fatal message terminates program.
'rES;
!+
Return the primary failure completion code to the caller.
1-

RETURN .primary_code
END;
END
ELUDOM

D-6

APPENDIX E

E.I
E.I.I
E.I.2
E.2
E.3

ACTION ROUTINES
ACTION-ROUTINE CALLS AND RETURNS • • .

•

E-I

Action Routine Calls • • • • • • • • . • • • • • E-I
• E-3
Action Routine Return Values • • • . • •
E-4
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING •
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING.

E-15

APPENDIX E
ACTION ROUTINES

This appendix contains information related
to
the coding
of usersupplied
action
routines,
and
presents the XPORT default failureaction routines, XPO$FAILURE and
STR$FAILURE,
as examples of and
models for such routines.
This appendix is intended for reference use.
action
routines and
their
usa is given
beginning with Chapter 3.

E.I

A tutorial discussion of
earlier
in this manual,

ACTION-ROUTINE CALLS AND RETURNS

Any action routine that applies to a given operation is called by the
XPORT function
in question just before
it returns control to the
original caller.
The routine is passed several values related to
the
operation.
(A success-action
routine
is called
in the case of a
success completion code;
a failure-action routine is called
for
any
other code including a warning code.)
On completing its processing, the action routine returns a value to
its caller
that becomes the completion code returned to the original
call site.

E.I.l

Action Routine Calls

All action routines called by XPORT functions are
passed
parameters
which describe the
function,
its arguments,
success or
failure
completion codes, etc.
Although the number of parameters and
the
meaning
of each parameter varies somewhat depending on the calling
function, the general format of an action-routine call is:
routine-address( function-code, primary-code,
secondary-code, action-argument,
Table E.l describes the action-routine
passed by each XPORT function.

E-l

arguments

that

are

actually

Act ion Ro uti n e s
ACTION-ROUTINE CALLS AND RETURNS
Table E.l
Action Routine Arguments

+----------------- --------------------------------------------------+
F'unc tion
Argument Description
1
--------------------------------------------------1
1

$XPO OPEN
$XPO-CLOSE
$XPO-GET
$XPO-PUT
$XPO-DELETE
$XPO-RENAME
$XPO-BACKUP

$XPO PARSE SPEC
1
1

1:
2:
3:
4:

XPO$K 10
Primary completion code
Secondary completion code
Address of
rOB

1:
2:
3:
4:

XPO$K PARSE
Primary completion code
Secondary completion code
Address of file-spec string descriptor

1
1

1-----------------1-------------------------------------------------1
1

$XPO_GET_MEM

1
1
1

1:
2:
3:
4:

XPO$K GET MEM
Primary completion code
Secondary completion code
Address of memory-request descriptor

1----------------- -------------------------------------------------1

$XPO FREE MEM
-

1:
2:
3:
4:

XPO$K FREE MEM
Primary completion code
Secondary completion code
Address of allocated-memory descriptor

$XPO - PUT - MSG

1:
2:
3:
4:

XPO$K PUT MSG
Primary completion code
Secondary completion code
Serverity of first message

$STR EQL
$S'I'R-NEQ
$STR-LSS
$STR-LEQ
$STR-GEQ
$STR-GTR
$STR-COMPARE

1:
2:
3:
4:
5:
6:

STR$K COMPARE
Primary completion code
Secondary completion code
Address of relationship string descriptor
Address of primary-string descriptor
Address of secondary-string descriptor

+------------------------------------_._------------------------------+
E-2

Action Ro uti nes
ACTION-ROUTINE CALLS AND RETURNS
Table E.l (Continued)
Action Routine Arguments

+----------------- --------------------------------------------------+
Function
Argument Description
1
1----------------- --------------------------------------------------/
1

$STR COPY

1:
2:
3:
4:
5:

STR$K COPY
Primary completion code
Secondary completion code

I
I
I
1

Address of source-string descriptor
6 : Address of target-string descriptor

I
/

$STR APPEND

1:
2:
3:
4:
5:
6:

STR$K APPEND
Primary completion code
Secondary completion code
Address of source-string descriptor
Address of target-string descriptor

$STR SCAN

1:
2:
3:
4:
5:
6:

STR$K SCAN
Primary completion code
Secondary completion code
Internal $STR SCAN function code
Address of source-string descriptor
Address of pattern-string descriptor

$STR BINARY

1:
2:
3:
4:
5:
6:

STR$K BINARY
Primary completion code
Secondary completion code
Internal $STR BINARY. function code
Address of source-string descriptor
Address of internal result area

+--------------------------------------------------------------------+
E.I.2

Action Routine Return Values

An action routine must have a return value.
This value is returned to
the
original
call
site as
the
final completion code of the XPORT
function.

E-3

Action Routines
ACTION-ROUTINE CALLS AND RETURNS
Action routines for I/O functions are passed the primary and secondary
I/O completion codes in the associated lOB as well as in the actionroutine
argument
list.
The
corresponding
lOB
fields
are
IOB$G COMP CODE and IOB$G 2ND CODE respectively.
XPORT updates the
contents of IOB$G COMP CODE-(only) to agree with the completion code
returned by the- actIon routine -- assuming
it differs from the
original. The action routine may modify the content of IOB$G 2ND CODE
as necessary before returning.
-

E.2

XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

The source module XFAIL, reproduced below, contains the default XPORT
failure-action routine XPO$FAILURE, together with the four functionspecific routines called by XPO$FAILURE.
These supporting routines
are XPO$IO FAILURE for
I/O functions, XPO$GM FAILURE for the getmemory function, XPO$FM FAILURE for the free-memory function,
and
XPO$PM_FAILURE for the put-message function.
Note that XPO$FAILURE terminates program execution for any error
condition, after calling one of the function-specific routines. The
function-specific routines simply issue appropriate error messages.
Since these routines have the same parameter list as XPO$FAILURE, any
of them can be used directly in place of the default failure-action
routine (e.g., FAILURE = XPO$IO_FAILURE for I/O calls).

E-4

Action Routines
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

MODULE XFAIL (

IDENT = 'Vl.O-14'
%TITLE 'XPO$FAILURE - Default Failure Action Routine'
%BLISS32( ,ADDRESSING MODE ( EXTERNAL=LONG RELATIVE) )
%BLISS36( ,ENTRY( XPOSFAILURE, XPO$IO FAILURE, XPO$PS FAILURE, XPO$GM FAILURE,
XPO$FM_FAILURE, XPO$PM_FAILURE ),OTS=")
) =

BEGIN
COPYRIGHT (c) 1981 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
1++
1
1 FACILITY:
1
1 ABSTRACT:

ITS

BLISS Library

1
This module is the default XPORT failure action routine.
1
User Mode - system-independent
1 ENVIRONMENT:
1
1 AUTHOR:
Ward Clark, CREATION DATE:
11 July 1978
1
1--

TABLE OF CONTENTS:
FORWARD ROUTINE
XPO$FAILURE;

1 Failure action routine dispatcher

%IF %BLISS(BLISS16) %THEN
EXTERNAL ROUTINE
%ELSE
FORWARD ROUTINE
%FI
XPO$IO FAILURE,
XPO$PS-FAILURE,
XPO$GM-FAILURE,
XPO$FM-FAILURE,
XPO$PM=FAILURE;

XPORT I/O failure action routine
$XPO PARSE SPEC failure action routine
$XPO-GET MEM failure action routine
$XPO-FREE MEM failure action routine
$XPO=PUT_MSG failure action routine

INCLUDE FILES:
LIBRARY
LIBRARY

'XPORT';
'XPOSYS';

Public XPORT control block and macro definitions
Internal XPORT macro definitions

MACROS:

EQUATED SYMBOLS:

PSECT DECLARATIONS:
Declare XPORT PSECT names and attributes

E-S

Action Ro ut i nes

XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

OWN STORAGE:

See each function-specific failure action routine.
EXTERNAL REFERENCES:

See each function-specific failure action routine.

E-6

Action Routines
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$FAILURE( function_code, primary_code, secondary_code, action_argument
1++
1

1 FUNCTIONAL DESCRIPTION:
1

This rO,utine dispatches a failure action routine call to the
appropriate processing routine for the function which failed.

1
1

1 FORMAL PARAMETERS:
1

function code - XPORT failure action routine function code
primary code - primary failure completion code
secondary code - secondary failure competion code
action_argument - function-specific action routine argument

1
1
1
1
1

1 IMPLICIT INPUTS:
1

None

1 IMPLICIT OUTPUTS:
1
1

None

1 ROUTINE VALUE:
1
1

.primary_code - primary completion code passed by caller

1 SIDE EFFECTS:
1

This routine returns to the caller if the completion code
severity is SUCCESS or WARNING. If the severity is ERROR or
FATAL, this routine terminates program execution.

1
1
1
1--

BEGIN
LOCAL
action_routine;
Select the appropriate failure processing routine •
action_routine = ( CASE • function code FROM 1 to XPO$K_PUT_MSG OF
SET XPO$IO FAILURE
[ XPO$K 10 1 :
XPO$PS-FAILURE
[ XPO$K-PARSE 1
XPO$GM-FAILURE
[ XPO$K-GET MEM 1 :
XPO$FM-FAILURE
[ XPO$K-FREE MEM 1 :
[ XPO$K-PUT MSG 1 :
XPO$PM=FAILURE
TES ); Call the action routine.
(.action_routine) ( .function_code, .primary_code, .secondary_code, .action_argument );
Terminate program execution or return to the caller.
If the completion code is a success code
or has a WARNING severity,

IF .primary code OR
.primarY code<O,3,O> EQL XPO$_WARNING
RETURN .primary code
ELSE
$XPO_TERMINATE( CODE
XPO$_PREV_ERROR

THEN

return the input completion code to the caller.
Otherwise, terminate program execution.

END;
$XPO_MODULE( XFAILI )

E-7

Action Ro ut i nes
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$IO_FAILURE( function_code, primary_code, secondary_code, iob )
1++
1

1 FUNCTIONAL DESCRIPTION:
1
1

This routine sends the user a message sequence similar to the following:

error opening 'file-spec' as input
primary completion code message
secondary completion code message

1
1
1
1

1 FORMAL PARAMETERS:
1
1
1
1
1
1

function code - failure action routine function code (XPO$K_IO)
primary code - primary I/O failure completion code
secondary code - secondary failure competion code
iob - address of the associated lOB

1 IMPLICIT INPUTS:
1
1
1

None

1 IMPLICIT OUTPUTS:
1
1
1

None

1 COMPLETION CODES:
1
1
1

.primary_code - primary completion code passed by caller

1 SIDE EFFECTS:
1
1
1

None

1--

BEGIN
MAP
iob

REF $XPO_IOB();

BIND
file spec
resultant -

.iob[IOB$A FILE SPEC]:
$STR DESCRIPTOR(),
iob[IOB$T_RESULTANT]
$STR_DESCRIPTOR();

OWN
initial text:
$STR DESCRIPTOR( STRING
'error'),
open text:
$STR DESCRIPTOR( STRING· 'opening' ),
close text:
$STR DESCRIPTOR ( STRING = 'closing' ),
delete text
$STR DESCRIPTOR ( STRING = 'deleting' ),
rename=text
$STR-DESCRIPTOR( STRING = 'renaming' ),
backup text:
$STR-DESCRIPTOR( STRING = 'backing up , ),
put_text: $STR DESCRIPTOR( STRING = 'writing to ' ),
get text:
$STR-DESCRIPTOR( STRING = 'reading from' ),
auto open text :- $STR DESCRIPTOR( STRING = 'auto-opening' ),
auto-close text:
$STR DESCRIPTOR ( STRING = 'auto closing' ),
bad tunc text:
$STR DESCRIPTOR( STRING = 'invalid operation on '
input text:
$STR DESCRIPTOR( STRING = ' for input' ),
and output text: -$STR DESCRIPTOR( STRING = ' and output' ),
output text:
$STR DESCRIPTOR( STRING = , for output' ),
to_text:
$STR_DESCRIPTOR( STRING = , to ' );
EXTERNAL ROUTINE
XST$INIT MSG
XST$STRING :
XST$QUOTED :

NOVALUE,
NOVALUE,
NOVALUE;

Failure message initialization routine
Append string to failure message routine
Append quoted string to failure message routine

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Don't issue a message for SUCCESS or WARNING conditions.
IF .primary code OR
.primarY code<O,3,O> EQL XPO$_WARNING
THEN
RETURN .primary_code;

If this is a SUCCESS or WARNING condition,
return without doing anything.

Create the initial function-specific message.

E-8

Action Ro uti nes
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING
IF .iob[IOB$B FUNCTION] LEQ IOB$K PUT
"error".
THEN
XST$INIT_MSG( initial_text );

1 All messages except "invalid function" start with

CASE .iob[IOB$B FUNCTION]
FROM IOB$K OPEN TO IOB$K PUT OF
SET
OUTRANGE ] :
XST$INIT MSG( bad func text );
IOB$K OPEN]:
XST$STRING( open text );
IOB$K-CLOSE ] : XST$STRING( close text );
IOB$K-DELETE]
XST$STRING( delete text );
IOB$K-RENAME ] : XST$STRING( rename-text );
IOB$K-BACKUP ] :
XST$STRING( backup-text );
IOB$K-PUT ] : XST$STRING( put text );
IOB$K-GET ] :
IF ~iob[IOB$V AUTO CONC]
THEN
-IF .iob[IOB$V OPEN]
THEN
XST$STRING( auto_close_text)
ELSE
XST$STRING( auto_open_text
ELSE
XST$STRING( get_text );
TES;
IF .resultant[STR$H LENGTH] NEQ 0
THEN
XST$QUOTED( resultant
ELSE
XST$QUOTED( file_spec );

Use the XPORT function code to select
the next part of the message.

If input switching is in progress,
special open and close text will be needed.

1 Otherwise, use the normal input failure text.
Put the best file name into the message:
resultant file-spec (if one exists)
user file-spec

SELECTONE .iob[IOB$B FUNCTION] OF
SET
IOB$K OPEN, IOB$K CLOSE] :
IF ~iob[IOB$V INPUT]
THEN
BEGIN
XST$STRING( input text);
IF .iob[IOB$V OUTPUT]
THEN
XST$STRING( and output_text );
END
ELSE
XST$STRING( output_text );

Special OPEN/CLOSE message suffix:
Indicate whether this is an
input or an output file.

IOB$K RENAME ] :
BEGIN
BIND
new_iob = .iob[IOB$A_ASSOC lOB] :
$XPO IOB(),
new_result = new iob[IOB$T RESULTANT]
SSTR_DESCRIPTOR();

Special RENAME message suffix:

XST$STRING( to_text );
IF .new result[STR$H LENGTH] NEQ 0
THEN
XST$QUOTED( new result)
ELSE
XST$QUOTED(.new_iob[IOB$A_FILE SPEC]);

Add the new resultant file-spec
or the new primary file-spec.

Send a multi-line failure message to the user.
IF .iob[IOB$G COMP CODE] EQL XPO$ BAD NEW
AND .iob[IOB$G-2ND CODE] EQL 0
BEGIN
$XPO PUT MSG( STRING = XST$MESSAGE,
CODE-= XPO$ BAD NEW,
CODE = .new-iobTIOB$G COMP CODE],
CODE = .new-iob[IOB$G-2ND CODE],
FAILURE = 0-);
--

Test for special linked RENAME messages.

THEN

RENAME-specific message:
"invalid new file"
primary new file completion code
secondary new file completion code
Return after a special RENAME message.

RETURN .primary_code
END;
END;
TES;
$XPO PUT MSG( STRING = XST$MESSAGE,
CODE
• iob [IOB$G COMP CODE] ,
CODE = .iob[IOB$G=2ND_CODE],

Function-specific message
Primary completion code
Secondary competion code, if any

E-9

Action Ro uti nes
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

FAILURE = 0 );
Return to the caller.
RETURN .primary_code

END;
$XPO_MODULE( XFAIL2 )

E-IO

Return the original completion code to the caller.

Action Routines
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$PS_FAILURE( function_code, primary_code, secondary_code, file_spec)
1++
1

1 FUNCTIONAL DESCRIPTION:
1
1
1
1
1
1
1

This routine sends the user a message sequence similar to the following:
error parsing 'file-spec'
primary completion code message
secondary completion code message

1 FORMAL PARAMETERS:
1
1
1
1
1
1

function code - failure action routine function code (XPO$K PARSE)
primary code - primary $XPO PARSE SPEC failure completion code
secondary code - secondary failure competion code
file_spec-- address of file-spec string descriptor

1 IMPLICIT INPUTS:
1
1
1

None

1 IKPLICIT OUTPUTS:
1
1
1

None

1 COMPLETION CODES:
1
1
1

.primary_code - primary completion code passed by caller

1 SIDE EFFECTS:
1

None

1
1
1--

BEGIN
initial_text
EXTERNAL ROUTINE
XST$INIT MSG
XST$QUOTED:

$STR_DESCRI PTOR( STRING

'error parsing' );

NOVALUE,
NOVALUE;

Failure message initialization routine
Append quoted string to failure message routine

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG( initial text );
XST$QUOTED( .file_spec );
Send a multi-line failure message to the user.
$XPO_PUT MSG( STRING = XST$MESSAGE,
CODE ~ .primary code,
CODE = .secondary code,
FAILURE = 0);
-

Tell the user that $XPO PARSE SPEC failed
and what the failure was.
-

Return to the caller.
! Return the original completion code to the caller.

RETURN .primary_code
END;
$XPO_MODULE( XFAIL3 )

E-ll

Action Ro uti nes
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$GM_FAILURE( function_code, primary_code, secondary_code, descriptor)
!++
I

FUNCTIONAL DESCRIPTION:
This routine sends the user a message sequence similar to the following:
dynamic memory allocation error
primary completion code message
secondary completion code message
FORMAL PARAMETERS:
function code - XPORT failure action routine function code (ignored)
primary code - primary $XPO GET MEM failure completion code
secondary code - secondary failure competion code
descriptor - address of $XPO_GET_MEM request descriptor
IMPLICIT INPUTS:
None
IMPLICIT OUTPUTS:
None
COMPLETION CODES:
.primary_code - primary completion code passed by caller
SIDE EFFECTS:
None

BEGIN
MAP
descriptor

Redefine the descriptor argument.

REF $STR_DESCRIPTOR();

Send a three-line error message to the user.
$XPO_PUT MSG( CODE = XPO$ GET MEM,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
-

Tell the user that $XPO GET MEM failed
and what the failure was. -

RETURN .primary_code

Return the original completion code to the caller.

END;
$XPO_MODULE( XFAIL4 )

E-12

Action Routines
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$FM_FAILURE( function_code, primary_code, secondary_code, descriptor)
1++

1 FUNCTIONAL DESCRIPTION:
This routine sends the user a message sequence similar to the following:
dynamic memory deal location error
primary completion code message
secondary completion code message
FORMAL PARAMETERS:
function code - XPORT failure action routine function code (ignored)
primary code - primary $XPO FREE MEM failure completion code
secondary code - secondary failure competion code
descripto! - address of $XPO_FREE MEM request descriptor
IMPLICIT INPUTS!
None
IMPLICIT OUTPUTS:
None
COMPLETION CODES:
.primary_code - primary completion code passed by caller
SIDE EFFECTS:
None
1--

BEGIN
MAP
descriptor

Redefine the descriptor argument.

REF $STR_DESCRIPTOR();

Send a three-line error message to the user.
$XPO_PUT MSG( CODE = XPO$ FREE MEM,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
RETURN .primary_code

Tell the user that $XPO FREE MEM failed
and what the failure was.
-

1 Return the original completion code to the caller.

END;
$XPO_MODULE( XFAIL5 )

E-13

Action Routines
XFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE XPO$PM_FAILURE( function_code, primary_code, secondary_code, actual severity
1++
1
1 FUNCTIONAL DESCRIPTION:
1
1
This routine sends the user a message sequence similar to the following:
1
1
message output error
1
primary completion code message
1
secondary completion code message
1
1 FORMAL PARAMETERS:
1

function code - XPORT failure action routine function code (ignored)
primary code - primary $XPO PUT MSG failure completion code
secondary code - secondary failure competion code
actual_severity - actual severity of 1st message

IMPLICIT INPUTS:
None
IMPLICIT OUTPUTS:
None
COMPLETION CODES:
.primary_code -

primary completion code passed by caller

1 SIDE EFFECTS:

None

1
1--

BEGIN
Send a three-line error message to the user.
$XPO PUT MSG( CODE = XPO$ PUT MSG,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
RETURN .primary_code

Tell the user that PUT MESSAGE failed
and what the failure was
(blocking failure recursion).
1 Return

END;
END
ELUDOM

E-14

the original completion code to the caller.

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING
E.3

SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

The source module SFAIL, reproduced below, contains the default XPORT
failure-action
routine STR$FAILURE, together with the five functionspecific routines called by STR$FAILURE.
These supporting
routines
are STR$X FAILURE for comparison functions, STR$C FAILURE for the copy
function,-STR$A FAILURE for the append function, STR$S FAILURE for the
scan
function~
and
STR$B FAILURE for
the conversion-to-binary
function.
Note that STR$FAILURE terminates program execution for any error
condition, after calling one of the function-specific routines.
The
function-specific routines simply issue appropriate error messages.
Since
these routines have the same parameter list as STR$FAILURE, any
of them can be used directly in place of the default failure-action
routine (e.g., FAILURE = STR$X_FAILURE for string-comparison calls).

E-15

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

MODULE SFAIL (

IDENT = 'Vl.0-8'
%TITLE 'STR$FAILURE - String Failure Action Routine'
%BLISS32( ,ADDRESSING MODE ( EXTERNAL=LONG RELATIVE) )
%BLISS36( ,ENTRY( STR$FAILURE, STR$X FAILURE,
STR$C FAILURE, S~R$A FAILURE,
STR$S=FAILURE, STR$B=FAILURE ),OTS="

) =

BEGIN

COPYRIGH~ (c) 1981 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ~CCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEIREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED••
THE INFORM~ION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

ITS

1++
1
1 FACILITY:
1
1 ABSTRACT:
1

BLISS Library

1
This module includes all standard String Handling failure
1
action routine processing.
1
1 ENVIRONMENT:
User mode - multiple host operating/file systems
1
1 AUTHOR:
1
1--

Ward Clark,

CREATION DATE:

28 February 1980

TABLE OF CONTENTS:
FORWARD ROUTINE
STR$FAILURE;
'IF %BLISS(BLISS16) %THEN
EXTERNAL ROUTINE

1 Failure action routine dispatcher

%ELSE

FORWARD ROUTINE
tFI

String comparison failure action routine
$STR COPY failure action routine
$STR-APPEND failure action routine
$STR-SCAN failure action routine
$STR=BINARY failure action routine

STR$X FAILURE,
STR$C-FAILURE,
STR$A-FAILURE,
STR$S-FAILURE,
STR$B=FAILURE;
INCLUDE FILES:
LIBRARY
LIBRARY

Public XPORT control block and macro definitions
Internal XPORT macro definitions

'BLI:XPORT'
'XPOSYS';

MACROS:

EQUATED SYMBOLS:

PSECT DECLARATIONS:
$XPO_PSECTS

E-16

Declare XPORT PSECT names and attributes

Ac tion Ro uti nes
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

OWN STORAGE:

See each function-specific failure action routine.
EXTERNAL REFERENCES:

See each function-specific failure action routine.

E-17

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$FAILURE( function_code, primary_code, secondary_code, action_argl, action_arg2,
action_arg3 I =
1++
1

1 FUNCTIONAL DESCRIPTION:
1
1
1
1
1

This routine dispatches a failure action routine call to the
appropriate processing routine for the function which failed.
FORMAL PARAMETERS:

1
1
1

function code - String Handling failure action routine function code
primary code - primary failure completion code
secondary code - secondary failure completion code
action_argl,2,3 - function-specific action routine arguments

1
1
1 IMPLICIT INPUTS:
1

None
1
1
1 IMPLICIT OUTPUTS:
1

None

1
I
I
I
I
I

ROUTINE VALUE:
primary completion code (value passed as a formal parameter)

1 SIDE EFFECTS:
1
This routine returns to the caller if the completion code
1

severity is SUCCESS or WARNING.
If the severity is ERROR or
FATAL, this routine terminates program execution.

I
I
I
1--

BEGIN
LOCAL
action_rout ine;

Address of action routine to be called

Select the appropriate failure processing routine.
action_routine = ( CASE .function code FROM
SET [ STR$K COMPARE
r STR$K-COPY 1
[ STR$K-APPEND
[ STR$K-SCAN 1
r STR$K-B INARY
TES ); -

TO STR$K_BINARY OF
STR$X FAILURE;
STRSC-FAILURE;
STR$A-FAILURE;
STR$S-FAILURE;
STR$B::::rAILURE;

Call the action routine.
(.action rout ine) ( • function_code, .pr imary_code, .secondary_code, .action_argl, .action_arg2,
.action_arg3-) ;
Terminate program execution or return to the caller.
If the completion code is a success code
or has a WARNING severity,

IF .primary code OR
.primarY code<O,3,O> EQL XPO$_WARNING
RETURN .primary code
ELSE
$XPO_TERMINATE( CODE
XPO$_PREV_ERROR

THEN

return the input completion code to the caller.
Otherwise, terminate program execution.

END;
$XPO_MODULE( SFAILl )

E-18

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$X_FAILURE( function_code, primary_code, secondary_code, relation, stringl, string2 )
1++
1

1 FUNCTIONAL DESCRIPTION:
1
This routine sends the user a message sequence similar to the following:
1
1
1
comparison error:
'stringl' equal to 'string2'
primary completion code message
1
1
secondary completion code message
1
1 FORMAL PARAMETERS:
1
1
function code - action routine function code (STR$K COMPARE)
primary code - primary completion code
1
1
secondary code - secondary completion code
1
relation
comparison relationship string (e.g., , compared to ')
1
stringl - address of primary string descriptor
1
string2 - address of secondary string descriptor
1
1 IMPLICIT INPUTS:
1
None
1
1
1 IMPLICIT OUTPUTS:
1
None
1
1
1 COMPLETION CODES:
1
.primary_code - primary completion code passed by caller
1
1
1 SIDE EFFECTS:
1

None

1
1--

BEGIN
$STR_DESCRIPTOR( STRING

initial text
EXTERNAL ROUTINE
XST$INIT MSG
XST$STRING :
XST$QUOTED :

'comparison error:

NOVALUE,
NOVALUE,
NOVALUE;

');

! Failure message initialization routine
Append string to failure message routine
Append quoted string to failure message routine

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG( initial text );
XST$QUOTED( .stringl );
XST$STRING( .relation );
XST$QUOTED( .string2 );
Send a mUlti-line failure message to the user.
Function-specific message
Primary failure completion code
Secondary failure completion code

$XPO PUT MSG( STRING = XST$MESSAGE,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
Return to the caller.
RETURN .primary_code
END;
$XPO_MODULE( SFAIL2 )

E-19

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$C_FAILURE( function_code, primary_code, secondary_code, dummy, string, target)
1++
1

1 FUNCTIONAL DESCRIPTION:
1

1
1

This routine sends the user a message sequence similar to the following:
error copying 'string'
primary completion code message
secondary completion code message
FORMAL PARAMETERS:
function code - action routine function code (STR$K_COMPARE)
primary code - primary completion code
secondary code - secondary completion code
dummy - dummy argument (not used)
string - address of source string descriptor
target - address of target string descriptor
IMPLICIT INPUTS:
None
IMPLICIT OUTPUTS:
None
COMPLETION CODES:
.primary_code -

primary completion code passed by caller

SIDE EFFECTS:
None
!--

BEGIN

OWN
$STR_DESCRIPTOR( STRING

initial text
EXTERNAL ROUTINE
XST$INIT MSG
XST$QUOTED:

'error copying'

NOVALUE,
NOVALUE;

EXTERNAL
XST$MESSAGE;

);

I
I

Failure message initialization routine
Append quoted string to failure message routine

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG( initial text );
XST$QUOTED( .string )~
Send a multi-line failure message to the user.
Function-specific message
Primary failure completion code
Secondary failure completion code

$XPO_PUT MSG{ STRING = XST$MESSAGE,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
I

Return to the caller.
RETURN .primary__ code
END;

$XPO_MODULE( SFAIL3 )

E-20

Action Routines
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$A_FAILURE( function_code, primary_code, secondary_code, dummy, string, target)
1++
1
1 FUNCTIONAL DESCRIPTION:
1
This routine sends the user a message sequence similar to the following:
1
1
error appending 'string' to 'target'
1
primary completion code message
1
secondary completion code message
1
1
1 FORMAL PARAMETERS:
1
1
1
1

function code - action routine function code
primary code - primary completion code
secondary code - secondary completion code
dummy - dummy argument (not used)
string - address of source string descriptor
target - address of target string descriptor

1
1

1 IMPLICIT INPUTS:
1
1
1

None

1 IMPLICIT OUTPUTS:
1
1

None

1 COMPLETION CODES:
1

.primary_code -

1
1

primary completion code passed by caller

1 SIDE EFFECTS:
1
None
1
1
1--

BEGIN
initial text:
$STR DESCRIPTOR( STRING = 'error appending'
to_text-:
$STR_DESCRIPTOR( STRING = ' to ' );
EXTERNAL ROUTINE
XST$INIT MSG
XST$STRING :
XST$QUOTED :

NOVALUE,
NOVALUE,
NOVALUE;

Failure message initialization routine
Append string to failure message routine
Append quoted string to failure message routine

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG( initial text );
XST$QUOTED( .string );
XST$STRING( to text );
XST$QUOTED( .target );
Send a multi-line failure message to the user.
$XPO_PUT MSG( STRING = XST$MESSAGE,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
-

Function-specific message
Primary failure completion code
Secondary failure completion code

Return to the caller.
RETURN .primary_code
END;
$XPO_MODULE( SFAIL4 )

E-21

Ac tion Ro uti nes
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$S_FAILURE( function_code, primary_code, secondary_code, scan_function, string, pattern)
1++
1

1 FUNCTIONAL DESCRIPTION:
1

This routine sends the user a message sequence similar to the following:
1
1
error scanning 'string' to find 'pattern'
1
primary completion code message
1
secondary completion code message
1
1
1 FORMAL PARAMETERS:
1
function code - action routine function code (STR$K_COMPARE)
1
primary code - primary completion code
1
secondary code - secondary completion code
1
scan function - $STR SCAN function code
1
string - address of source string descriptor
1
pattern - address of pattern string descriptor
1
1
1 IMPLICIT INPUTS:
1

None

I
I

IMPLICIT OUTPUTS:

I
None
I
I
I COMPLETION CODES:
I
.primary_code I
I
I SIDE EFFECTS:
I
None
I
I
1--

primary completion code passed by caller

BEGIN
OWN
initial text:
$STR D'ESCRIPTOR( STRING = 'error scanning' ),
find text
$STR DESCRIPTOR( STRING
' t o find' ),
span-text: $STR-DESCRIPTOR( STRING
spanning' ),
stop=text: $STR=DESCRI PTOR( STRING =
stopping at ' );
EXTERNAL ROUTINE
XST$INIT MSG
XST$STRING :
XST$QUOTED :

Failure message initialization routine
Append string to failure message routine
Append quoted string to failllre message routine

NOVALUE,
NOVALUE,
NOVALUE;

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG ( ini tial tex t );
XST$QUDTiD( .string )~
CASE .scan function FROM STR$K_FIND TO STR$K_STOP OF
SET
XST$STRING( find text );
[ STR$K FIND
[ STR$K-S PAN
XST$STRING( span-text );
[ STR$K-STOP
XST$STRING ( stop=text );
TES;
XST$QUOTED( .pattern );
Send a multi-line failure message to the user.
$XPO PUT MSG( STRING = XST$MESSAGE,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
-

Function-specific message
Primary failure completion code
Secondary failure completion code

Return to the caller.

E-22

Action Ro uti nes
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

RETURN .primary_code
END;
$XPO_MODULE( SFAIL5 )

E-23

Action Ro uti nes
SFAIL.BLI FAILURE-ACTION ROUTINE LISTING

GLOBAL ROUTINE STR$B_FAILURE( function_code, primary_code, secondary_code, convert_function, string, result
) =
1++
1
1 FUNCTIONAL DESCRIPTION:
1
This routine sends the user a message sequence similar to the following:
1
1
? error converting 'string' to binary
1
primary completion code message
1
secondary completion code message
1
1
1 FORMAL PARAMETERS:
1
function code - action routine function code (STR$K_COMPARE)
1
primary code - primary completion code
1
secondary code - secondary completion code
1
convert function - $STR BINARY function code
1
string
address of source string descriptor
1
result - address of result area
1

1
1 IMPLICIT INPUTS:

None
1
1
1 IMPLICIT OUTPUTS:
1
None
1
1
1 COMPLETION CODES:
.primary_code -

primary completion code passed by caller

SIDE EFFECTS:
None
1
1--

BEGIN
OWN
$STR DESCRIPTOR( STRING = 'error converting
initial text:
binary_text :
$STR_DESCRIPTOR ( STRING = ' to binary' );
EXTERNAL ROUTINE
XST$INIT MSG
XST$STRING :
XST$QUOTED :

, ),

Failure message initialization routine
Append string to failure message routine
Append quoted string to failure message routine

NOVALUE,
NOVALUE,
NOVALUE;

EXTERNAL
XST$MESSAGE;

Failure message string descriptor

Create the initial function-specific message.
XST$INIT MSG( initial text);
XST$QUOTED( .string );
XST$STRING( binary_text );
Send a multi-line failure message to the user.
Function-specific message
Primary failure completion code
Secondary failure completion code

$XPO_PUT MSG( STRING = XST$MESSAGE,
CODE = .primary code,
CODE = .secondary code,
FAILURE = 0);
Return to the caller.
RETURN .primary_code
END;
END
ELUDOM

E-24

APPENDIX F
F.l
F.2
F.3

COMPILING AND LINKING
DEFINING A TRANSPOR~ABLE LOGICAL DEVICE
F-l
COMPILING
. . . • . . . • . • • • . . F-2
LINKING . • • . • . • . . • • • . • • . .
. . F-3

APPENDIX F
COMPILING AND LINKING

This appendix contains information related
to
the compilation and
linking
of BLISS programs that contain references to the programming
tools described in this manual.
It contains the relevant source and
object file specifications for all target systems on which these tools
are currently implemented.
It also suggests an operational
technique
that
facilitates both transportable compilation and more convenient
program linking.

F.I

DEFINING A TRANSPORTABLE LOGICAL DEVICE

For purposes of both transportability and operational convenience,
we
suggest that you define, on each development system, a 'logical device
name' -- say BLI -- that stands for the device,
directory,
etc.,
in
which
the
XPORT files reside on that particular system.
The uses of
such a name are illustrated in subsequent sections.
The system-level command that would be used to define a
on several BLISS-development systems are as follows:

logical

TOPS-IO

(No user command available; see below)

TOPS-20

@DEFINE B LI:

VAX/VMS

$ DEFINE BLI partial-file-spec
or
$ ASSIGN partial-file-spec BLI

This type of command would
command file;
see below.

name

partial-file-spec

normally

F-l

executed

from

your

Compiling and Linking
DEFINING A TRANSPORTABLE LOGICAL DEVICE
A typical example of such a command on TOPS-20 might be:
@DEFINE

BLI:

PS:(SUBSYS>

and for VAX/VMS:
$ DEFINE

BLI

SYS$LIBRARY:

In order to fill in the "partial-file-spec"
in the formats given
above,
you must find
out where in your system the XPORT files have
been installed.
You can do
this either by inspection,
i.e.,
by
'looking through' the file system, or by asking your system manager.
The reason that we suggest the name BLI is that, in many cases,
the
system manager will already have appropriately defined that name on a
system-wide basis.
If this is the case, you do not have to
perform
the definition yourself, of course.
(You cannot under TOPS-IO in any
case.)
Since the commands described above are only effective for the duration
of
the session in which they are executed, it is strongly recommended
that the appropriate command be placed in your command
file that
is
automatically executed at login time, e.g., LOGIN.COM (VMS), LOGIN.CMD
(TOPS-20).

F.2

COMPILING

Assuming that a definition exists for
the logical name BLI as
discussed in Section F.I, include the following LIBRARY declaration in
your BLISS source modules:
LIBRARY 'BLI:XPORT' ;
Given appropriate definitions of BLI,
this single declaration will
work
for
all
BLISS compilers;
the relevant XPORT.Lnn Library file
will be selected by default in each case:
XPORT.L32, or XPORT.L36.
The source-time portion of the XPORT package, containing macro,
literal, and control-block definitions, is provided in two forms.
One
is the BLISS Library file just discussed, XPORT.Lnn, which is intended
for
use in normal compilations.
The other is a BLISS Require file,
XPORT.REQ, which is provided only for non-standard uses such as
the
construction of a user Library file that contains XPORT source as well
as other code, in precompiled form.
(Use of Require files rather than
Library files
in standard compilations incurs a significant increase
in compilation cost.)

F-2

Compiling and Linking
LINKING
F.3

LINKING

is provided on each BLISS
A standard (default) XPORT object file
development system.
Use of this file presumes that the development
system and the intended target system are one and the same.
The name
of
this
file is either XPORT.OLB (for VAX) or XPORT.REL (for TOPS-IO
and TOPS-20).
A LINK command of the general form
LINK

program, BLI:XPORT [ •••

(or its equivalent) will incorporate the standard
for the system in use.

XPORT

object

file

Additional object files are provided where necessary for debugging
(36-bit systems only)
and for cross-linking, that is, linking for a
target system other than the development system.
Also, an object file
named
specifically for the host system (and identical to the default
object file) is provided on each system;
for example,
XPOTIO.REL is
the same as XPORT.REL on a TOPS-IO system.
The special debug objects provided on the 36-bit systems, which have
the
file-type
.DBG,
are for use with the SIXl2 Debugger.
Note that
they can only be used if the module containing the program entry point
has been compiled with the /DEBUG switch.
A listing of the currently available object files
follows.
Arrows
(-»
preceding
the
file names
indicate which pairs of files are
identical in content.
o

On a TOPS-IO system:
-) XPORT.REL and XPORT.DBG
-) XPOTIO.REL and XPOTIO.DBG

On a TOPS-20 system:
-) XPORT.REL and XPORT.DBG
XPOTIO.REL and XPOTIO.DBG
-) XPOT20.REL and XPOT20.DBG

On a VAX/VMS system:
-) XPORT.OLB
-) XPOVMS.OLB

Note that special debug object
target systems.

files

F-3

are

not

required

for

32-bit

Compiling and Linking
LINKING
Typical program-linking command sequences for the several development
systems are shown below.
These command sequences assume that the
logical name BLI has been defined as discussed in Section F.l.
o

On a TOPS-IO system:
.R LINK
*program, BLI:XPORT/SEARCH/GO
• SAVE

On a TOPS-20 system:
@LINK
*program, BLI:XPORT/SEARCH/GO
@SAVE

On a VAX/VMS system:
$LINK program, BLI:XPORT/LIBRARY/NOTRACEBACK [/DEBUG]

F-4

APPENDIX G
G.l
G.l.l
G.l.2
G.l.3
G.l.4
G.2
G. 2.1

G.2.2

XDUMP UTILITY PROGRAM
XDUMP - XPORT DATA STRUCTURE DISPLAY UTILITY
Running the XDUMP Utility • • • • • • . • • •
Compiling a Structure Display Module • . • •
Linking a Structure Display Module • • • • •
Displaying a User Declared Structure While
Debugging
• • • • • • • ••
••
XDESC, XIOB, and XSPEC - XPORT STRUCTURE DISPLAY
MODULES
• • • • • • • • • • • • • • • • • •
Linking an XPORT Structure Display Module
Displaying an XPORT Structure While Debugging

• G-l
• G-l
G-2
G-3
• G-3
• G-3
• G-3
· G-4

APPENDIX G
XDUMP UTILITY PROGRAM

This appendix describes the use of the XbUMP Utility program during
debugging
of user programs that employ the XPORT data-structuring
facilities (see Chapter 2).

G.l

XDUMP - XPORT DATA STRUCTURE DISPLAY UTILITY

The XP.oRT XDUMP utility generates an executable BLISS module that
be called during program debugging
to symbolically display
contents of a specific program data structure.

G.l.l

can
the

Running the XDUMP Utility

The XDUMP utility is provided in executable form as part of an XPORT
release.
Although its location on your system is determined by your
system manager, it will typically be located in the standard
system
executable-image library (e.g., SYS$SYSTEM on VAX/VMS).
To invoke the XDUMP utility, enter a command similar to the
VAX/VMS DCL command:

following

$ RUN XDUMP
XDUMP will then ask for
the name
includes
the definition of the
follows:

of a
BLISS REQUIRE file which
desired program data structure, as

BLISS REQUIRE file name (default

= .REQ)?

XDUMP will then ask for the name of the desired data structure:
Name of structure?
XDUMP then searches the REQUIRE file for a BLISS comment statement
G-l

XDUMP UTILITY PROGRAM
XDUMP - XPORT DATA STRUCTURE DISPLAY UTILITY
the form
structure-name .
where "structure-name" is an arbitrary name which you assign
to
your
structure.
This
comment statement may include text following the
structure name.
NOTE
It is recommended that a structure-name be no more
than six characters long
since this name will
become the name of the generated display module
and
the name of the display routine within this
module.
The data structure must be defined using the XPORT Transportable Data
Structure definition facilities
(see Chapter 2).
If the desired
structure definition is not the last structure definition
in the
REQUIRE file,
a
comment statement of the following form must follow
the structure definition:
End of structure-name
Upon completion of XDUMP processing, the name of the generated display
module will be reported, as follows:
structure-name.BLI display module generated

G.I.2

Compiling a Structure Display Module

To compile the structure display module generated by the
XDUMP
utility, enter a command similar to the following VAX/VMS DCL command:
$ BLISS structure-name

This compilation command assumes that the logical device
BLI:
has
been defined
to point to the device and directory in which the XPORT
LIBRARY file exists (see Appendix F).

G-2

XDUMP UTILITY PROGRAM
XDUMP - XPORT DATA STRUCTURE DISPLAY UTILITY
G.I.3

Linking a Structure Display Module

The structure-display object module can be
included
in a
linked
program image in the same manner as any other program subroutine.
For
example, a command similar to the following VAX/VMS DCL command should
be entered:
$ LINK main-program, structure-name, •.• , BLI:XPORT/LIBRARY/DEBUG

G.I.4

Displaying a User Declared Structure While Debugging

While debugging, the current contents of a
data structure can be
displayed by entering a command similar to the following VAX/VMS DEBUG
command:
DBG)CALL structure-name (address-of-structure)
NOTE
Some current debuggers (e.g.,
DDT,
ODT)
do
not
include a CALL-type command and are therefore not
compatible with the XDUMP utility.
The contents of specified structure will be displayed, one
line, in a form similar to the following:

field

per

field-name = symbolic-field-value
where
"field-name"
is
the name of
the
field
in the
structure
definition
and
"symbolic-field-value" is the current contents of the
field displayed in symbolic form based on the "type" of the field.

G.2
G.2.l

XDESC,

XIOB, and XSPEC - XPORT STRUCTURE DISPLAY MODULES

Linking an XPORT Structure Display Module

The XPORT distribution includes structure display modules which can be
used durin~ program debugging to display an XPORT descriptor, an XPORT
lOB structure, or an XPORT File Specification Parse Block.
If any of these standard XPORT display modules (XDESC, XIOB, XSPEC) is
desired
during
debugging,
each must be explicitly requested during
program linking.
For example, on a VAX/VMS system:
$ LINK program, BLI:XPORT/LIBRARY/INCLUDE=XIOB/DEBUG
G-3

XDUMP UTILITY PROGRAM
XDESC, XIOB, and XSPEC - XPORT STRUCTURE DISPLAY MODULES
Alternatively, you can include any of the statements shown below in
your
program to
force automatic
inclusion of these standard XPORT
display modules in your program image:
EXTERNAL ROUTINE XDESC;
EXTERNAL ROUTINE XIOB;
EXTERNAL ROUTINE XSPEC;

G.2.2

Displaying an XPORT Structure While Debugging

While debugging, the XPORT data structures (i.e., XDESC, XIOB,
XSPEC)
can be displayed
by entering a command similar to the VAX/VMS DEBUG
command shown in Section G.l.4.
DBG)CALL XIOB

(name of lOB)

APPENDIX Z
Z.1
Z.2
Z.3
Z. 3. 1
Z.3.2
Z.3.3
Z.3.4
Z. 3. 5
Z.3.6
Z.4
Z.4.1
Z.4.2
Z. 4. 3
Z.4.4
Z.4.5
Z.5

EASY-TO-USE I/O PACKAGE

(EZIO)

OVERVIEW • • • • . • .
. •
LIMITATIONS
• • . • • . . . • • • . • • • • . • •
FUNCTIONAL DESCRIPTION •
.
The FILOPN Routine • • • • • • • • • .
.
The FILIN Routine
• • • • • • • • • •
The FILOUT Routine
••••••••.••••
The FILCLS Routine
••••••.
• •
Restrictions . • • • • • • • • . • • • • • • • •
Example
•••• • • . • • • • . • • • • • • • •
LOADING EZIO WITH USER PROGRAM • • . • • • • . • •
EZIOFC - File Services 11 (RSX-IIM)
EZIORT - RT-ll • • • • • • • • • • • . . • • • •
EZIOI0 - TOPS-IO • • • • • • • • • • • • •
•
EZI020 - TOPS-20
• • . • • • •
.
EZ IOVX - VAX/VMS . • . • . . • • • • • • • • • •
PACKAGING • • • • •
• • . • • •

Z-1
Z-1
Z-2
Z-2
Z-4
Z-4
Z-5
Z-5
Z-6
Z-7
Z-7
Z-8
Z-8
Z-8
Z-8
Z-8

APPENDIX Z
EASY-TO-USE I/O PACKAGE

Z.l

(EZIO)

OVERVIEW

EZIO is a very basic I/O package for BLISS programs that predates the
development of XPORT.
(It is documented here for historical reasons
only;
it is not a supported product.)
EZIO provides only sequential character-string I/O, such as line input
and
line output.
It
is functionally the same on all major Digital
operating systems.
EZIO was intended for the BLISS programmer who wanted
to write a
'throwaway'
program, e.g.,
a
prototype or a temporary tool, both
transportably and with a minimum of effort.
(Prior to the development
of XPORT I/O, the only alternative for I/O was direct monitor calls.)
That is to say, EZIO was intended to be a disposable tool.
It is very
easy to use, but is not a particularly capable tool.

Z.2

LIMITATIONS

The EZIO package does not provide a complete set of I/O facilities for
any system.
More specifically,
the following functionality is not
provided:
o

Binary I/O

Sequenced files

Random I/O

More than 3 file I/O channels open concurrently.

Concurrent use of monitor calls for I/O processing (which may
be precluded due to the way that EZIO does file I/O).

(record and page numbers, as with SOS)

Z-l

Easy-to-Use I/O Package (EZIO)
LIMITATIONS
The maximum number of I/O channels that may be opened can be increased
in most implementations by modifying and recompiling the EZIO sources;
see Section Z.3.S.

Z.3

FUNCTIONAL DESCRIPTION

The EZIO package provided in the BLISS Library is a
set of routines
that are called to perform I/O operations.
The routines are:
1.

FILOPN - Opens a specified file on a logical channel.

FILIN - Reads a line of
text from
a
specified channel.
It
returns
the
actually transferred.

FILOUT - Transfers data from a string to a file opened on the
specified channel.

FILCLS - Closes the file on a specified channel.

file
opened on the
number of characters

With the exception of FILIN, all the functions return 1 to indicate a
successful
completion of
the operation, or 0 to indicate a failure.
FILIN returns a negative value to indicate a failure to
complete
its
operation,
or a positive value (possibly zero) to indicate the number
of characters read.
All of the routines take a logical
channel
number as a
parameter.
(This
is not guaranteed to correspond to any logical unit number of
the underlying file system).
The channel number should be within the
range
of -1
to
the maximum number of channels supported by EZIO,
normally the range [-1, 0, 1, 2] (see Section Z.3.S).
Channel -1 is reserved for terminal operations.
All calls using
this
channel do a minimum of buffering, and use operating-system primitives
for communicating with the terminal (if such exist).

Z.3.1

The FILOPN Routine

This routine call requires four parameters.
The
first specifies a
logical
channel
that the
file
is
to
be opened on.
The second
parameter specifies the length of the file-spec string.
The third
is
a
character-string pointer to the file-spec (constructed by CH$PTR or
equivalent).
The last parameter specifies either 0 or 1
to
indicate
that the file is to be opened for input or output respectively.

Z-2

Easy-to-Use I/O Package (EZIO)
FUNCTIONAL DESCRIPTION
For example, to open a file for output whose file-spec was dynamically
constructed:
FILOPN( 1,

.NAMLEN, CH$PTR(FILNAM), 1)

The value returned by the routine is 1 if the file was opened
and
subsequent
I/O can be done to its channel;
0 otherwise.
A return
value of 0 usually indicates that either the file
is not present,
there was an error in the syntax of the file-spec, or the file could
not be accessed in the specified mode.
The following conventions apply to programs containing
file-specs that may be transported to other systems:

"hard

coded"

File names should consist of a maximum of six characters, and
contain only the characters A-Z
(upper or lower case is
permitted, but lower will be converted to upper) and 0-9.

File types (extensions) should consist of a maximum of three
characters, and contain only the characters A-Z and 0-9.
Also, they should follow the file name and be separated
from
the file name by a period.
(The same rule applies to case as
for file names.)

Hard coded device names should be avoided since they differ
across operating systems.
The default device is disk for I/O
to channels 0 through 2.
All I/O to channel -1 will go
to
the terminal.

Account information (e.g., PPNs or directory
not be specified if a program is to be fully
In all implementations, the default is to use
established as the default when EZIO is first
the logged in directory).

names)
should
transportable.
the directory
invoked (e.g.,

An example of a transportable file-spec is:
UP LIT ( 'F I LE . EXT'

)

Note that all of the above can be avoided if the program asks the user
to enter
his file
rather
than storing them as static data in the
module.
The user can then type in a file-spec in the host system's
own syntax because EZIO uses the system file-spec parser in all
implementations except TOPS-IO (where the parser is PIP like) •
For all implementations, the character string specifying the file-spec
should
not exceed a length of 127 characters.
However, there may be
other restrictions for specific operating systems.
Z-3

Easy-to-Use I/O Package (EZIO)
FUNCTIONAL DESCRIPTION
Z.3.2

The FILIN Routine

This routine call requires three parameters.
The first specifies
the
logical
channel associated with the file to be read from.
The second
parameter specifies the maximum number of characters that will
fit
into the destination string.
The last parameter is a character-string
pointer to the string that will rpceive the data read in.
The value of the routine is -1 if a read beyond
the end-of-file was
attempted.
-2
is returned if any I/O error occured.
Otherwise, an
integer value greater than -1 is returned to indicate the number of
characters transferred to the destination string.
For example, to read a line of text from the file opened on channel
and to put it in string BUFFR:
LEN

= FILIN( 1,

80, CH$PTR(BUFFR)

);

In this example, the variable LEN is set with the number of characters
actually put in the string at BUFFR.
A "line of text" is a string of ASCII characters delimited
according
to
the host file system's conventions.
Any delimiting factors (i.e.,
length field, vertical motion characters, etc) will act as a
stream
"break" and will be stripped on input.
On output, the format expected
by the system's principal editors will be used.
NOTE
On some systems, there is more than one
way to delimit a line of text, and an
effort has been made to use the methods
of the principal editors in each case.

Z.3.3

The FILOUT Routine

This routine call has
three parameters.
The first specifies the
logical channel associated with the file to be written on.
The second
parameter specifies the number of characters that will be transferred
to
the file.
The last parameter is a character string pointer to the
string that is to be written.
For example, to write a line from string TITLE to
channel 2:
FILOUT( 2,

.TITLIN, CH$PTR(TITLE)

Z-4

);

the

file

open

Easy-to-Use I/O Package (EZIO)
FUNCTIONAL DESCRIPTION
Of course, if there were any doubt that the operation might not
complete
successfully,
an
IF statement could be used to check the
indicating
success and 0
return value of the call;
the value
I
indicating failure.
The string is output as a line of text.
That
is to
say,
the host
system's conventions are
used
to output the string so that it will
appear as one line when printed.
(Some systems delimit lines with
CRLF,
9thers store it as a counted string.) In all cases, EZIO should
be able to read files that it creates.

Z.3.4

The FILCLS Routine

This routine call has one parameter,
which
associated with the file to be closed.

the

logical

channel

The FILCLS routine ensures that all EZIO buffers containing data are
written out before informing the file system that all data transfers
to/from the file are complete.
For example:
F' I LC LS ( -1);

Of course, the call could be included in a condition~l
expression to
determine whether the operation succeeded or failed (e.g., the case of
not enough disk space) •

Z.3.5

Restrictions

There are no logical
restrictions
in the
EZIO package.
However,
because
EZIO is dependent on them, the restrictions of the underlying
file systems and of BLISS apply to all
programs using
the
EZIO
package.
There are physical constraints on the number of EZIO channels that can
be open at anyone time.
The maximum as distributed is three plus
channel -1 for terminal I/O.
The reason is to reduce the number of
buffers and tables within EZIO.
NOTE
The maximum number of channels that can
be concurrently opened is controlled by
the compile-time literal MAXCHANS
in
most of the implementations.
The user
may change this parameter to change the
number of channels to his/her liking.
Z-5

Easy-to-Use I/O Package (EZIO)
FUNCTIONAL DESCRIPTION
Z.3.6

Example

This example program prints a file on the terminal:
MODULE LISTER (MAIN = LSTR)
1+
This program asks for a filename, opens the named file,
and copies the file to the terminal.
1--

BEGIN
EXTERNAL ROUTINE
F ILOPN,
FILC LS,
FILOUT,
FILIN;
OWN
BUF

EZ 10 open
Ezro Close
EZIO Output
EZrO Input

1 Holds one line of text
VECTOR[CH$ALLOCATION(120)];

MACRO
MSGS(S)
FILOUT(-l,

%CHARCOUNT(S), CH$PTR(UPLIT(S)))

ROUTINE LSTR
BEGIN
LOCAL
LEN,
PTR;

Length of string
Pointer to buf

Open the TTY. Note: no filespec
F I LO PN ( -1, 0, 0, 0);
PTR = CH$PTR(BUF);
MSG('Enter file name');
LEN = FILIN(-l, 60, .PTR);
Open the file on channel

Get pointer
Prompt
Get file name

IF NOT FILOPN (0, • LEN, • PTR, 0)
THEN
BEGIN
MS G ( '0 pen fa i 1 ed . ' ) ;
RETURN;
END;

Z-6

Op en fa i 1 ed •

Easy-to-Use I/O Package (EZIO)
FUNCTIONAL DESCRIPTION
Process each line
WHILE 1 DO
BEGIN
LEN = F I LIN (0, 120, • PT R) i
IF • LEN EQL -1
THEN
EXITLOOPi
FILOUT (-1, • LEN, • PTR) i
END;

End of file
Output the string

F ILC LS (0) ;
MSG ( 'DONE' ) ;
END;
END
ELUDOM

Z.4

LOADING EZIO WITH USER PROGRAM

The procedures shown below describe the steps necessary to
load
EZIO
with a
user
program on each system.
These examples assume that the
user's object program is in a file named TEST which has the proper
file type or extension for the system in question.

Z.4.1

EZIOFC - File Services 11

(RSX-IIM)

Run the Task Builder:
MCR>TKB TEST=TEST,EZIOFC,EISLIB
The TEST to the left of the equal sign is the name of the
task-image
file.
'l'he TEST to the right of the equal sign is
the object module of the main program.
EZIOFC is the object
module of Ezro.
And EISLIB is the EIS BLISS-16 library of
runtime routines.

When TKB
program:

finishes,

give

MCR>RUN TEST

Z-7

the

run

command

invoke

the

Easy-to-Use I/O Package (EZIO)
LOADING EZIO WITH USER PROGRAM
Z.4.2

EZIORT - RT-ll

For RT-ll, simply use the DCL command EXECUTE:
.EXECUTE TEST,EZIORT,EISLIB

Z.4.3

EZI010 - TOPS-10

After your program has been compiled with BLISS-36,
EXECUTE command:

use

the

TOPS-10

.EXECUTE TEST.REL,BLI:EZI010
Note that a library file does not have
generates a load request automatically) .

Z.4.4

specified

(BLISS-36

EZI020 - TOPS-20

After your program has been compiled by BLISS-36
(with the /TOPS-20
compilation switch, if necessary), simply use the EXECUTE command:
@EXECUTE TEST,BLI:EZI020
Note that a library file does not have
generates a load request automatically) •

Z.4.5

specified

EZIOVX - VAX/VMS

After your program has been compiled with BLISS-32,
LINK command, as follows:
$ LINK

Z.5

(BLISS-36

use

the

VAX/VMS

TEST,SYS$LIBRARY:EZIOVX

PACKAGING

EZIO is distributed as several files:
EZIOFC for a Files-ll based
system, EZIORM for a RMS-ll based file system, EZIORT for programs
that run under RT-ll, EZIOVX for the VAX/VMS operating system,
EZI010
for TOPS-10 and EZI020 for TOPS-20.

Z-8

Easy-to-Use I/O Package (EZIO)
PACKAGING
EZIOFC, EZIORM and EZIORT are to be compiled using BLISS-16.
EZIOVX
must
be compiled using BLISS-32.
And EZIOIO and EZI020 must be
compiled with BLISS-36 using
the /TOPSIO
and /TOPS20
switches
respectively.
Some of the EZIO sources have REQUIRE statements.
These require the various system-interface modules also distributed in
the
BLISS Library,
which must be present in order to successfully
modify the sources.

Z-9

INDEX

$ADDRESS field-type, 2-7
usage guidelines, 2-8
$ALIGN, 2-2
usage, 2-13
$BIT field-type, 2-6
$BITS(n) field-type, 2-6
$BYTE
f ield- type, 2-7
See al so BYTE
$BYTES vs. $STRING usage, 2-21
$BYTES(n) field-type, 2-7
$CONTINUE, 2-2
usage, 2-14
$DESCRIPTOR(class) field-type,
2-7
usage guidelines, 2-10
$DIST INCT, 2-2
usage, 2-15
$FIELD declaration
example of, 2-3
general form of, 2-5
usage rules, 2-6
$FIELD keyword, 2-2
$field-types, 2-2
$FIELD SET SIZE, 2-2
usage, i=12
$INTEGER field-type, 2-7
$LITERAL, 2-2
usage, 2-15
$LONG INTEGER field-type, 2-7
$OVERLAY, 2-2
usage, 2-14
$POINTER field-type, 2-7
usage guidelines, 2-8
$REF DESCRIPTOR field-type, 2-7
$SHORT INTEGER field-type, 2-7
$SHOW,-2-2
$SIXBIT(n) field-type, 2-8
$STR APPEND macro
completion codes, A-6
definition of, A-4
$STR ASCII macro
definition of, A-7
$STR BINARY macro
completion codes, A-II
definition of, A-9

$STR COMPARE macro
completion codes, A-13
definition of, A-12
$STR CONCAT macro
definition of, A-14
$STR COPY macro
completion codes, A-18
definition of, A-16
$STR DESC INIT macro
completIon codes, A-22
definition of, A-21
examples of, 6-3
$STR DESCRIPTOR macro
definition of, A-19
examples of, 6-2
$STR EQL macro
completion codes, A-25
definition of, A-23
$STR FORMAT macro
definition of, A-26
$STR GEQ macro
completion codes, A-31
definition of, A-29
$STR GTR macro
completion codes, A-34
definition of, A-32
$S'I'R LEQ macro
completion codes, A-37
definition of, A-35
$STR LSS macro
completion codes, A-40
definition of, A-38
$STR NEQ macro
completion codes, A-43
definition of, A-41
$STR SCAN macro
completion codes, A-47
definition of, A-44
$STRING vs. $BYTES usage, 2-21
$STRING(n) field-type, 2-7
usage guidelines, 2-11
$SUB BLOCK(len) field-type, 2-7
usage guidelines, 2-9
$S UB FIELD, 2-2
$TINY INTEGER field-type, 2-7
$XPO_BACKUP macro

Index-l

completion codes, A-49
definition of, A-48
example of, 3-14
$XPO CLOSE macro
completion codes, A-52
definition of, A-51
examples of, 3-12
$XPO DELETE macro
completion codes, A-55
definition of, A-54
examples of, 3-13
$XPO DESC IN IT macro
completTon codes, A-60
definition of, A-59
examples of, 7-3
$XPO DESCRIPTOR macro
definition of, A-57
examples of, 7-2
$XPO ERROR
standard message device, 3-22
$XPO FREE MEM macro, 4-2
completIon codes, A-62
definition of, A-61
$XPO GET macro
completion codes, A-65
definition of, A-63
examples of, 3-15
$XPO GET MEM macro, 4-2
definition of, A-67
$XPO INPUT, 3-11
standard input device, 3-22
$XPO lOB macro
definition of, A-70
examples of, A-70
$XPO lOB INIT macro
completion codes, A-72
definition of, A-7l
$XPO OPEN macro
completion codes, A-77
definition of, A-73
examples of, 3-11
$XPO OUTPUT
standard output device, 3-22
$XPO PARSE SPEC macro
completion codes, A-80
definition of, A-79
use of, 3-26
$XPO PUT macro
completion codes, A-82
definition of, A-8l

examples of, 3-16
$XPO PUT MSG macro
completion codes, A-85
definition of, A-84
example of, 5-1
$XPO RENAME macro
completion codes, A-89
definition of, A-86
examples of, 3-13
$XPO SPEC BLOCK macro, 3-26
detinitTon of, A-90
examples of, A-90
$XPO TEMPORARY
temporary work file, 3-22
$XPO TERMINATE macro
definition of, A-9l
example of, 5-3
$XPO xxxx macro calls
format of, 3-10
Action routines
I/O, 3-28
memory management, 4-4
put-message, 5-3
Addresses vs. pointers, 2-8,
3-17
ALIGN - See $ALIGN
APPEND option, 3-7, 3-12
Asterisk character (*)
See Wild-card character, 3-26
Automatic file concatenation,
3-6
Automatic program termination,
5-2
BACKUP function, 3-4
BACKUP macro call
see $XPO BACKUP
Backup operation
explanation of, 3-4
Binary descriptor, 7-1
BINARY mode, 3-6
GET example, 3-16
PUT example, 3-17
Block size, fixed, 3-8
BLOCK structures, transportable
difficulties with, 2-1
efficiency considerations,
2-22
example of, 2-3

Index-2

problem areas, 2-20
Boundary alignment
by de f a ul t, 2 -1 2
efficiency considerations,
2-22
BOUNDED descriptor, 6-7, 7-7
BYTE alignment keyword, 2-13

problem areas, 2-20
DECnet links, 3-8
Default action routines
for I/O, 3-28
memory management, 4-5
put-message, 5-3
Default file specification, 3-9
Defaulting technique
Caveats
for file-specs, 3-23
on file-spec parsing, 3-26
Defaults
file-type for BACKUP, 3-14
on use of STREAM mode, 3-6
for descriptor class, 6-2, 7-2
on use of UNITS (I/O), 3-6
Character string
for file specifications, 3-8
See String
for NEW RELATED, 3-13
Character-string fields
DELETE macro call
see $XPO DELETE
coding of, 2-21
Descriptor-usage, 3-11,
Classes of descriptors, 6-4, 7-4
See also Descriptors
3-15 to 3-17, 3-20
Descriptors
CLOSE function, 3-4
CLOSE macro call
BOUNDED, 6-6, 7-6
classes of, 6-2, 7-1
see $XPO CLOSE
Completion-codes
details, 6-4, 7-4
typical uses, 6-8
I/O, 3-22, 3-27
usage rules for, 6-6, 7-6
program termination, 5-4
compile-time initialization of,
put-message, 5-1, 5-3
Concatenated input files, 3-6
6-2, 7-2
Concatenation of strings, logical,
creation of, 6-2, 7-2
DYNAMIC, 6-6, 7-6
A-14
DYNAMIC BOUNDED, 6-6, 7-6
CONTINUE - See $CONTINUE
Conversion
FIXED, 6-6, 7-6
initialization of, 7-3
ASCII to ASCII, A-26
introduction to, 6-1, 7-1
binary to ASCII, A-7
run-time initialization of,
logical string concatenation,
6-3
A-14
typical uses of, 6-8
Conversion pseudo-functions
UNDEFINED, 6-6, 7-6
definition of
DISTINCT - See $DISTINCT
$STR ASCII, A-7
$STR-CONCAT, A-14
DYNAMIC descriptor, 6-7, 7-7
Dynamic memory, 4-1
$STR=FORMA'I', A-26
DYNAMIC BOUNDED descriptor,
Data descriptors, 6-1, 7-1
6-7, 7-7
See also Descriptors
Editing of strings, A-26
Data parameter formats, A-2
End of file (EOF)
Data structures, transportable
on concatenated input, 3-6
difficulties with, 2-1
Error correction, I/O, 3-28
efficiency considerations,
Error message generation, 5-1
2-22
example of, 2-3
FAILURE parameter, 3-10
field positioning, 2-12
Failure-action routines
literal definition, 2-14

Index-3

I/O, 3-28
File-spec resolution
memory management, 4-4
detailed discussion of, 3-23
FATAL severity level, 5-2
general description, 3-8
FIELD - See $FIELD
introduction, 3-4
Field al ignment
rules for, 3-24
by default, 2-12
FILL parameter, memory,
efficiency considerations,
4-2 to 4-3
FIXED descriptor, 6-7, 7-7
2-22
FIELD declaration, standard, 2-2
Freeing memory
examples of, 4-3
Field positioning, 2-12
Field positioning features
r ul e fo r, 4-4
FULLWORD alignment keyword, 2-13
$ALIGN, 2-13
Fullword, definition of, 2-5
$CONTINUE, 2-14
$OVERLA Y, 2-14
Field-names
GET macro call
see $XPO GET
lOB, 3-19
Field-type usage guidelines
Get operations
$ADDRESS, 2-8
concatenated input files, 3-7
$DESCRIPTOR, 2-10
in BINARY mode, 3-5
$ PO IN T ER , 2 - 8
in RECORD mode, 3-5
$STRING, 2-11
in STREAM mode, 3-5
$SUB BLOCK, 2-9
Getting memory, examples, 4-2
Field-Type, nontransportable
$SIXBIT(n), 2-8
I/O action routines, 3-28
Field-types, transportable, 2-6
I/O capabilities
FIELD SET SIZE - See $FIELD SET SIZE concatenated input files, 3-6
File backup operation, 3-4 get and put
File concatenation, input, 3-6
BINARY mode, 3-6
File specification
in general, 3-5
default, 3-9
RECORD mode, 3-6
primary, 3-9
STREAM mode, 3-6
related, 3-9
I/O completion codes, 3-22, 3-27
resultant, 3-9
I/O control block - See "lOB"
File specifications
I/O control blocks
concatenated input files, 3-6
description of, 3-18
defaults for, 3-8, 3-23
introduction to, 3-2
parsing of, 3-26
I/O devices, standard, 3-22
processing of, 3-23
I/O functions, summary of, 3-3
remembered, 3-4
I/O macros, 3-9
resolution of, 3-8, 3-23
common parameters, 3-10
rules for resolution, 3-24
examples of, 3-15
File-copy coding example, 3-21
general format, 3~10
File-level capabilities, 3-3
I/O routine exa~ple, 3-21
File-level functions
I/O services
BACKUP, 3-4
characteristics, 3-2
CLOSE, 3-4
file-level capabilities, 3-3
OPEN, 3-4
implementation, 3-2
summary of, 3-3
input/output capabilities, 3-5
File-level macros
introduction, 3-1
examples of, 3-11
keyword macros, 3-2

Index-4

linking with program, 3-2
I/O transportability, 3-1
Input & output devices, 3-8
standard error, 3-22
standard input, 3-22
standard output, 3-22
Input file concatenation, 3-6
INPUT option, default, 3-8
Input/Output - See "I/O"
Interactive terminals, 3-8
lOB (control block)
creation of, 3-18
description of, 3-18
field names, 3-2
fields
function of, 3-19
usage example, 3-20 to 3-21
initialization of, 3-19
introduction to, 3-2
lOB keyword parameter, 3-10
IOB$G 2ND CODE field, 3-28
IOB$G=COMP_CODE field, 3-27
Keyword parameters, I/O, 3-10
examples of use, 3-20
LIBRARY declaration, 3-2
LINK command example, 3-2
LITERAL - See $LITERAL
Literal-defining features
$DISTINC'l', 2-14
$LITERAL, 2-14
Macro calls
definitions of, A-4, A-19,
A-57
general format for I/O, 3-10
Macros
See $STR xxxx
See $XPO-xxxx
Memory management
action routines, 4-4
introduction, 4-1
routine values, 4-4
Miscellaneous services, 5-1
Mode keywords, I/O, 3-5
NEW_RELATED default, 3-13
Notation for macro definitions,
A-I

OPEN function, 3-4
OPEN macro call
see $XPO 0 PEN
Opening
concatenated input files, 3-6
defa ul ts, 3-8
for both input and output, 3-8
interactive terminal, 3-11
output files, 3-7
Output files, opening of, 3-7
OUTPUT option, 3-7
OVERLAY - See $OVERLAY
OVERWRITE option, 3-7
Parameter keywords, I/O, 3-10
Physical block size, fixed, 3-8
Placeholder $SUB BLOCK usage,
2-9
Pointers vs. addresses, 2-8,
3-17
Primary file specification, 3-9
Program
brief example, 1-5
Program termination
automatic, 5-2
requested, 5-3
Prompted read operation, 3-15
PUT macro call
see $XPO PUT
Put operations
in BINARY mode, 3-5
in RECORD mode, 3-5
in STREAM mode, 3-5
Put-Message function, 5-1
RECORD mode, 3-6
GET example, 3-15
PUT example, 3-16
RECORD SIZE parameter, 3-8
Related file specification, 3-9
Releasing memory
rule for, 4-4
REMEMBER file-close option,
3-4 to 3-5
REMEMBER option, 3-12 to 3-14
Remembered file specifications,
3-4
RENAME macro call
see $XPO RENAME
Resultant file specification,

Index-5

3-9
Routine values
I/O, 3-27
memory management, 4-4

see Data structures
Transportable field-types, 2-6
see also Field-type
Transportable I/O services, 3-1

UNDEFINED descriptor, 6-6, 7-6
Sample program
brief, 1-5
UNIT alignment keyword, 2-13
Usage guidelines
SEQUENCE NUMBER parameter, 3-17
$XPO BACKUP macro, A-49
SEQUENCED attribute, 3-5, 3-12,
$XPO-CLOSE macro, A-52
3-22
Sequenced file
$XPO=PUT macro, A-82
PUT example, 3-17
USER parameter, 3-11
SEVERITY parameter
Wild-card character (*), 3-26
put-message, 5-2
WORD alignment keyword, 2-13
Spaceholder $SUB BLOCK usage,
2-9
STREAM mode, 3-6
XPO$ NORMAL
caveat regarding, 3-6
completion code, 3-27
GET example, 3-15
XPO$ TERMINATE code, 5-3
PUT example, 3-16
XPO$FAILURE routine, 3-28, 4-5,
String concatenation, logical,
5-3
A-14
XPO$FM FAILURE routine, 4-5
String conversion
XPO$GM-FAILURE routine, 4-5
see also Conversion
XPO$IO-FAILURE routine, 3-28
String conversion pseudo-functions XPO$PM-FAILURE routine, 5-3
definition of
XPORT I/O devices
$STR ASCII, A-7
standard, 3-22
$STR-CONCA'l', A-14
XPORT I/O facilities - See "I/O"
$STR-FORMAT, A-26
String descriptors, 6-1
See also Descriptors
String editing, A-26
String parameter formats, A-2
Structures - See Data structures
Sub-fields - See $SUB FIELD
Sub-structures - See $SUB BLOCK
SUCCESS parameter, 3-11 Success-action routines
I/O, 3-28
memory management, 4-4
Syntax notation, A-I
Temporary files, 3-23
Terminal I/O, 3-22
Termination function, 5-3
Transportability problem areas,
2-20
Transportable BLOCK structures
see BLOCK structures
Transportable data structures

XPORT Programmer's Guide
AA-J201A-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 •

CI)

o
c

"5o

Did you find errors in this manual?
page number.

If so, specify the error and the

CI)
ell

CI)

a..

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify) ________________________________________

Name

Da te _________________

Organization ____________________________________
Street _____________________________________________________________________
Ci ty____________________ S ta te ___________ zip Code _____________
or
Country

-I

Do Not Tear - Fold Here and Tape
No Postage
Necessary
if Mailed in the
United States

~DmDDmD

I
I

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK 1-3/ J3-5
DIGITAL EQUI'PMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

-- -

Do Not Tear - Fold Here

-I

I
I