11-1-1

PL/I
Language
Reference Manual

Copyright @ 1983

	Digital Research
		P.O. Box 579
	160 Central Avenue
Pacific Grove, CA 93950
		(408) 649-3896
	TWX 910 360 5001

All Rights Reserved

1--l
COPYRIGHT

Copyright (D 1983 by Digital Research. All rights
reserved. No part of this publication may be
reproduced, transmitted, transcribed, stored in a
retrieval system, or translated into any language or
computer language, in any form or by any means,
electronic, mechanical, magnetic, optical, chemical,
manual or otherwise, without the prior written
permission of Digital Research, Post Office Box 579,
Pacific Grove, California, 93950.

DISCLAIMER

Digital Research makes no representations or
warranties with respect to the contents hereof and
specifically disclaims any implied warranties of
merchantability or fitness for any particular
purpose. Further, Digital Research reserves the
right to revise this publication and to make changes
from time to time in the content hereof without
obligation of Digital Research to notify any person
of such revision or changes.

TRADEMARKS

CP/M is a registered trademark of Digital Research.
PL/I-80 and PL/I-86 are trademarks of Digital
Research. SP/k is a trademark of the University of
Toronto. IBM is a registered trademark of
International Business Machines, Incorporated.
Digital Equipment Corporation is a registered
trademark of Digital Equipment Corporation. Z80 is
a registered trademark of Zilog, Inc. Intel is a
registered trademark of Intel Corporation.
Microsoft is a registered trademark of Microsoft
Incorporated.

The PL/I Language Reference Manual was prepared
using the Digital Research TEX Text Formatter and
printed in the United States of America.

			First Edition:	October 1982
		Second Edition:	June 1983
Foreword

Digital Research PL/I is a complete software development system for
both applications and system programming. Digital Research has
implemented PL/I for both 8-bit and 16-bit microprocessors. At the
source-code level, the 16-bit implementations are upward compatible
with the 8-bit implementations. Appendix A contains a complete list
of the differences among the various implementations. This manual
describes the PL/I language which is common to all implementations.

Digital Research PL/I runs under any of the Digital Research family
of operating systems. It also runs under the IBM8 Personal Ccmputer
Disk Operating System Version 1.1. This manual assumes you are
already familiar with your operating system, and mimimizes
references to any specific system.

The PL/I Language Reference Manual is the formal specification of
the PL/I programming language. This manual is primarily intended to
be a reference document and is therefore not tutorial in nature.
Some previous programming experience with PL/I or with another
language is assumed.

The Language Reference Manual describes the overall structure and
organization of PL/I source programs in the form of blocks and
procedures. There is also a specification of the character set of
the language, rules governing the formation of identifiers,
constants, delimiters, operators, and comments.

This manual explains the various PL/I data types including arrays
and structures, the rules governing conversion between data types,
and the rules governing the scope of data declarations. Assignments
and expressions, sequence control, run-time memory management, and
1/0 processing are also described.

There is a complete description all of the PL/I built-in functions
including arithmetic, mathematical, string, conversion, condition,
and miscellaneous functions.

Finally, the manual also describes the internal representation of
data in the various implementations, and conventions for
interfacing PL/I programs with programs written in assembly
language.
Table of Contents

I		introduction

1.1		Documentation Set.

1.2		Notation . . . . . . . . . . . . .

2		Program Structure

2.1		High-level Organization . . . . . . . . . . . . . 2-1
2.2		Blocks . . . . . . . . . . . . . . . . . . . . . . 2-2

2.3		Internal vs. External Blocks . . . . . . . . . . .	2-5
2.4		Scope of Variables . . . . . . . . . . . . . . . .	2-6
2.5		Procedure Blocks . . . . . . . . . . . . . . . . .	2-9
2.6		The CALL Statement . . . . . . . . . . . . . . . .	2-10
2.7		The RETURN Statement . . . . . . . . . . . . . . .	2-10
2.8		Arguments and Parameters . . . . . . . . . . . . .	2-11
2.9		The PROCEDURE Statement . . . . . . . . . . . . .	2-13

2.10		Low-level Organization . . . . . . . . . . . . . . 2-15

2.11		The Character Set . . . . . . . . . . . . . . . . 2-16

2.12		Identifiers . . . . . . . . . . . . . . . . . . . 2-17
2.13		Constants . . . . . . . . . . . . . . . . . . . . 2-18

2.14		Delimiters and Separators . . . . . . . . . . . . 2-18

2.14.1		Spaces . . . . . . . . . . . . . . . . . .	2-19
2.14.2		operators . . . . . . . . . . . . . . . .	2-19
2.14.3		Special Characters . . . . . . . . . . . .	2-20
2.14.4		Comments . . . . . . . . . . . . . . . . .	2-21

2.15		Preprocessor Statements . . . . . . . . . . . . . 2-22

2.15.1		The %INCLUDE Statement . . . . . . . . . . 2-22
2.15.2		The %REPLACE Statement . . . . . . . . . . 2-22

v
Table of Contents
	(continued)

3	Data Types and Attributes

3.1	Arithmetic Data . . . . . . . . . . . . . . . . .	3-1

	3.1.1	FIXED BINARY . . . . . . . . . . . . . . .	3-2
	3.1.2	FLOAT BINARY . . . . . . . . . . . . . . .	3-2
	3.1.3	FIXED DECIMAL . . . . . . . . . . . . . . .	3-3
3.2	String		Data . . . . . . . . . . . . . . . . . . .	3-4
	3.2.1	Character-string Data . . . . . . . . . . .	3-5
	3.2.2	Bit-string Data . . . . . . . . . . . . . .	3-5

3.3	Control Data		Items . . . . . . . . . . . . . . . .	3-6
	3.3.1	LABEL		Data . . . . . . . . . . . . . . . .	3-7
	3.3.2	ENTRY		Data . . . . . . . . . . . . . . . .	3-9
3.4	POINTER Data . . . . . . . . . . . . . . . . . . .	3-11
3.5	FILE Data . . . . . . . . . . . . . . . . . . . .	3-11

3.6	The DECLARE Statement	. . . . . . . . . . . . . . 3-11

3.7	Multiple Declarations	. . . . . . . . . . . . . . 3-12

3.8	Default Attributes . . . . . . . . . . . . . . . . 3-13

4	Data Conversion

4.1	Arithmetic Conversions . . . . . . . .

4.2	Arithmetic Conversion Functions . . . . . . . . . 	4-6

4.2.1	The		BINARY BIF . . . . . . . . . . . . . .	4-6
4.2.2	The		DECIMAL BIF . . . . . . . . . . . . . .	4-7
4.2.3	The		DIVIDE BIF . . . . . . . . . . . . . .	4-7
4.2.4	The		FIXED BIF . . . . . . . . . . . . . . .	4-7
4.2.5	The		FLOAT BIF . . . . . . . . . . . . . . .	4-8

4.3	String Conversions . . . . . . . . . . . . . . . .	4-8

4.3.1	Arithmetic to Bit-string Conversion . . . . 	4-9
4.3.2 Arithmetic to Character Conversion . . . . 4-9
4.3.3 Bit-string to Arithmetic Conversion . . . . 4-10
4.3.4 Bit to Character-string Conversion . . . . 4-11
4.3.5 Character to Arithmetic Conversion . . . . 4-11
4.3.6 Character to Bit-string Conversion . . . . 4-12

vi
Table of Contents
	(continued)

5		Data Aggregates

5.1		Array Declarations . . . . . . . . . . . . . . . . 	5-1

5.2		Array References . . . . . . . . . . . . . . . . . 	5-3

5.3		Initializing Array Elements . . . . . . . . . . . 	5-5

5.4		Arrays in Assignment Statements . . . . . . . . . 	5-7

5.5		Structures . . . . . . . . . . . . . . . . . . . .	5-8

5.6		Mixed Aggregates . . . . . . . . . . . . . . . . . 5-11

5.7		Mixed Aggregate Referencing

6		Assigronents and Expressions

6.1		The Assignment Statement

6.2		Expressions . . . . . . .

6.2.1		Prefix Expressions . . . . . . . . . . . . 6-1
6.2.2		Infix Expressions . . . . . . . . . . . . . 6-2

6.3		Precedence of Operators . . . . . . . . . . . . . 	6-2

6.4		Concatenation . . . . . . . . . . . . . . . . . . 	6-3

6.5		Relational Operators . . . . . . . . . . . . . . . 	6-3

6.6		Bit-string Operators . . . . . . . . . . . . . . . 	6-5

6.7		Exponentiation . . . . . . . . . . . . . . . . . .	6-5
6.8		Pseudo-variables . . . . . . . . . . . . . . . . .	6-6
	6.8.1		Character SUBSTR . . . . . . . . . . . . .	6-6
	6.8.2		Bit SUBSTR . . . . . . . . . . . . . . . .	6-7
6.8.3		UNSPEC . . . . . . . . . . . . . . . . . .	6-8
Table of Contents
	(continued)

7	Storage Management

7.1	Storage Classes . . . . . . . . . . . . . . . . .	7-1

7.1.1 The AUTOMATIC Storage Class
7.1.2 The BASED Storage Class . .
7.1.3 The PARAMETER Storage Class
7.1.4 The STATIC Storage Class . . . .

The ALLOCATE Statement . . . . . . . . . . . . . .	7-5
Multiple Allocations . . . . . . . . . . . . . . .	7-5

The FREE Statement . . . . . . . . . . . . . . . .	7-7

7.5	The NULL BIF . . . . . . . . . . . . . . . . . . . 	7-8

7.6	The ADDR BIF . . . . . . . . . . . . . . . . . . . 	7-9

7.7	Storage Sharing . . . . . . . . . . . . . . . . . 	7-9

7.8	Programming Considerations . . . . . . . . . . . . 7-10

8	Sequence Control

8.1	The Simple DO Statement
8.2	The Controlled DO Statement

8.2.1 The DO WHILE Statement . . .
8.2.2 The DO REPEAT Statement . . .
8.2.3 The DO REPEAT WHILE Statement
8.2.4 The DO BY WHILE Statement . .

8.3	The IF Statement . . . . . . . . . . . . . .
8.4	The STOP Statement . . . . . . . . . . . . . . . .
8.5	The GOTO Statement . . . . . . . . . . . . . . . .

8.6	The Nonlocal GOTO Statement . . . . . . . . . . . 	8-8

viii
Table of Contents
(continued)

9		Condition Processing

9.1		The ON Statement . . . . . . . . . . . . . . . . .	9-1
9.2		The SIGNAL Statement . . . . . . . . . . . . . . .	9-4
9.3		The REVERT Statement . . . . . . . . . . . . . . .	9-4
9.4		The ERROR Condition . . . . . . . . . . . . . . .	9-4
9.5		Arithmetic Error Conditions . . . . . . . . . . .	9-6
9.6		The ONCODE BIF . . . . . . . . . . . .
9.7		Default ON-units . . .
9.8		1/0 Conditions . . . . . . .

10		Input/Output Processing

10.1		The OPEN Statement . . . . . . . . . . . . . . . . 10-1

10.2		Establishing File Attributes . . . . . . . . . . . 10-5

10.3		The CLOSE Statement . . . . . . . . . . . . . . . 10-8

10.4		The File Parameter Block . . . . . . . . . . . . . 10-9

10.5		1/0 Conditions . . . . . . . . . . . . . . . . . . 10-10

10.5.1		The ENDFILE Condition . . . . . . . . . . 10-10
10.5.2		The UNDEFINEDFILE Condition . . . . . . . 10-10
10.5.3		The KEY Condition . . . . . . . . . . . . 10-10
10.5.4		The ENDPAGE Condition . . . . . . . . . . 10-11
10.5.5		Default 1/0 ON-units . . . . . . . . . . . 10-11

10.6		1/0 Condition BIFs . . . . . . . . . . . . . . . . 10-11
	10.6.1 The ONFILE Function . . . . . . . . . . . 10-12
	10.6.2 The ONKEY Function . . . . . . . . . . . . 10-12
	10.6.3 The PAGENO Function . . . . . . . . . . . 10-12
	10.6.3 The LINENO Function . . . . . . . . . . . 10-12

10.7		Predefined Files SYSIN and SYSPRINT . . . . . . . 10-12
10.8		1/0 Categories . . . . . . . . . . . . . . . . . . 10-13
	10.8.1		STREAM 1/0 . . . . . . . . . . . . . . . . 10-13
	10.8.2		RECORD 1/0 . . . . . . . . . . . . . . .. 10-13

ix
Table of Contents
	(continued)

11	Stream 1/0

11.1	LIST-directed 1/0 . . . . . . . . . . . . . . . .	11-2
	11.1.1	The GET LIST Statement . . . . . . . . .	11-3
	11.1.2	The PUT LIST Statement . . . . . . . . .	11-3
11.2	Line-directed 1/0 . . . . . . . . . . . . . . . .	11-4

11.2.1	The READ Varying Statement . . . . . . . 11-4
11.2.2	The WRITE Varying Statement . . . . . . . 11-5

11.3	EDIT-directed 1/0 . . . . . . . . . . . . . . . . 11-6

11.3.1	The Format List . . . . . . . . . . . . . 11-6
11.3.2	Data Format Items . . . . . . . . . . . . 11-6
11.3.3	Control Format Items . . . . . . . . . . 11-9
11.3.4	Remote Format Items . . . . . . . . . .. 11-10
11.3.5	The FORMAT Statement . . . . . . . . . . 11-11
11.3.6	The Picture Format Item	. . . . . . . . . 11-11
11.3.7	The GET EDIT Statement	. . . . . . . . . 11-19
11.3.8	The PUT EDIT Statement	. . . . . . . .. 11-19

12	Record 1/0

12.1	The READ Statement . . . . . . . . . . . . . . . 12-1

12.2	The READ with KEY Statement . . . . . . . . . . . 12-1

12.3	The READ with KEYTO Statement . . . . . . . . . . 12-2

12.4	The WRITE Statement . . . . . . . . . . . . . . . 12-2

12.5	The WRITE with KEYFROM Statement . . . . . . . . 12-2

13	Built-in Functions

13.1	Arithmetic Functions . . . . . . . . . . . . . . 13-1

13.2	Mathematical Functions . . . . . . . . . . . . . 13-1

13.3	String-handling Functions . . . . . . . . . . . . 13-2

13.4	Conversion Functions . . . . . . . . . . . . . . 13-3

13.5	Condition-handling Functions . . . . . . . . . . 13-3

x
Table of Contents
	(continued)

13.6		Miscellaneous Functions . . . . . . . . .

13.7		List of Built-in Functions

14		Summary of PL/1 Statements

14.1		The ALLOCATE Statement . . . . . . . . . . . . . 14-1

14.2		The ASSIGNMENT Statement . . . . . . . . . . . . 14-1

14.3		The BEGIN Statement . . . . . . . . . . . . . . . 14-1

14.4		The CALL Statement . . . . . . . . . . . . . . . 14-1

14.5		The CLOSE Statement . . . . . . . . . . . . . . . 14-1

14.6		The DECLARE Statement	(for scalar variables)	14-1
14.7		The DECLARE Statement	(for array variables)	14-2
14.8		The DECLARE Statement	(for structure variables)	14-2

14.9		The DECLARE Statement (for ENTRY data) . . . . .	14-2
14.10		The FREE Statement . . . . . . . . . . . . . . .	14-3
14.11		The DO Statement . . . . . . . . . . . . . . . .	14-3
14.12		The END Statement . . . . . . . . . . . . . . .	14-3
14.13		The FORMAT Statement . . . . . . . . . . . . . .	14-3
14.14		The FREE Statement . . . . . . . . . . . . . . .	14-4

14.15			The	GET EDIT Statement . . . . . . . . . . . . .	14-4
14.16			The	GET LIST Statement . . . . . . . . . . . . .	14-4
14.17			The	GOTO Statement . . . . . . . . . . . . . . .	14-4
14.18			The	IF Statement . . . . . . . . . . . . . . . .	14-4
14.19			The	%INCLUDE Statement . . . . . . . . . . . . .	14-5
14.20			The	NULL Statement . . . . . . . . . . . . . . .	14-5

xi
Table of Contents
(continued)

14.21		The	ON Statement . . . . . . . . . . . . . . . .	14-5
14.22		The	OPEN Statement . . . . . . . . . . . . . . .	14-5
14.23		The	PROCEDURE Statement . . . . . . . . . . . .	14-6
14.24		The	PUT EDIT Statement . . . . . . . . . . . . .	14-6
14.25		The	PUT LIST Statement . . . . . . . . . . . . .	14-6

14.26		The READ Varying Statement . . . . . . . . . . . 14-6
14.27		The READ Statement . . . . . . . . . . . . . . . 14-6
14.28		The READ with KEY Statement . . . . . . . . . .14-7

14.29		The READ with KEYTO Statement . . . . . . . . . 14-7

14.30		The	%REPLACE Statement . . . . . . . . . . . . .	14-7
14.31		The	RETURN Statement . . . . . . . . . . . . . .	14-7
14.32		The	REVERT Statement . . . . . . . . . . . . . .	14-7
14.33		The	SIGNAL Statement . . . . . . . . . . . . . .	14-8
14.34		The	STOP Statement . . . . . . . . . . . . . . .	14-8

14.35		The WRITE Varying Statement . . . . . . . . . . 14-8

14.36		The WRITE Statement . . . . . . . . . . . . . . 14-8

14.37		The WRITE with KEYFROM Statement . . . . . . . . 14-8

Data Attributes

15.1		ALIGNED . . . . . . . . . . . . . . . . . . . . . 15-1
15.2		AUTOMATIC . . . . . . . . . . . . . . . . . . . . 15-1

15.3		BASED . . . . . . . . . . . . . . . . . . . . . .	15-1
15.4		BINARY . . . . . . . . . . . . . . . . . . . . .	15-1
15.5		BIT . . . . . . . . . . . . . . . . . . . . . . .	15-2
15.6		BUILTIN . . . . . . . . . . . . . . . . . . . . .	15-2

xii
Table of Contents
(continued)

15.7		CHARACTER . . . . . . . . . . . . . . . . . . . .	15-2
15.8		DECIMAL . . . . . . . . . . . . . . . . . . . . .	15-2
15.9		ENTRY . . . . . . . . . . . . . . . . . . . . . .	15-2
15.10		ENVIRONMENT . . . . . . . . . . . . . . . . . .	15-3

15.11		EXTERNAL . . . . . . . . . . . . . . . . . . . .	15-3
15.12		FILE . . . . . . . . . . . . . . . . . . . . . .	15-3
15.13		FIXED . . . . . . . . . . . . . . . . . . . . .	15-3
15.15		INITIAL . . . . . . . . . . . . . . . . . . . .	15-4
15.16		LABEL . . . . . . . . . . . . . . . . . . . . .	15-4
15.17		PARAMETER . . . . . . . . . . . . . . . . . . .	15-4
15.18		POINTER . . . . . . . . . . . . . . . . . . . .	15-4
15.19		RETURNS . . . . . . . . . . . . . . . . . . . .	15-4
15-20		STATIC . . . . . . . . . . . . . . . . . . . . .	15-5
15-21		VARIABLE . . . . . . . . . . . . . . . . . . . .	15-5
15.22		VARYING . . . . . . . . . . . . . . . . . . . .	15-5

1-1

xiii
Appendixes

A	Implementation Notes . . . . . . . . . . . . . . . . . . 	A-1

A.1	DRI PL/I vs. PL/I Subset G . . . . . . . . . . . . 	A-1

A.2	Differences between PL/I-80 and PL/I-86 . . . . . . 	A-3

A.3	PL/I Running Under DOS . . . . . . . . . . . . . . 	A-5

A.4	Summary of Differences . . . . . . . . . . . . . . 	A-5

B	Internal Data Representation . . . . . . . . . . . . . . 	B-1

B.1	FIXED BINARY Representation . . . . . . . . . . . . 	B-1

B.2	FLOAT BINARY Representation . . . . . . . . . . . . 	B-2

B.2.1	Single-precision . . . . . . . . . . . . . . B-2
B.2.2	Double-precision . . . . . . . . . . . . . . B-6

B.3	FIXED DECIMAL Representation . . . . . . . . . . . 	B-8

B.4	CHARACTER Representation . . . . . . . . . . . . . 	B-8

B.5	BIT Representation . . . . . . . . . . . . . . . . 	B-9

B.6	POINTER . . . . . . . . . . . . . . . . . . . . . B-10

B.7	ENTRY and LABEL Data . . . . . . . . . . . . . . . B-10

B.8	File Constant Representation . . . . . . . . . . . B-10

B.9	Aggregate Storage . . . . . . . . . . . . . . . . . B-11

C	Interface Conventions . . . .

C.1	Parameter Passing Using a Parameter Block

C.2	Returning Values in Registers or on the Stack . . . 	C-6

C.2.1 Returning FIXED BINARY Data . . . . . . . . C-6
C.2.2 Returning FLOAT BINARY Data . . . . . . . . C-7
C.2.3 Returning FIXED DECIMAL Data . . . . . . . . c-7
C.2.4 Returning CHARACTER Data . . . . . . . . . . C-8
C.2.5 Returning BIT Data . . . . . . . . . . . . . C-8
C.2.6 Returning POINTER Variables . . . . . . . . C-8
C.2.7 Returning ENTRY and LABEL Variables . . . . C-9

C.3	Direct Operating System Function Calls . . . . . . C-12

Xiv
Appendixes
(continued)

*		Compiler Options . . . . . . . .

*		Error Messages and Condition Codes . . . . . . . . . . . E-1
E.1 PL/I-80 R1.4 and PL/I-86 R1.0 . . . . . . . . . . . E-2
E.2 PL/I-86 Rl.l and PL/1-86 R1.0 under DOS . . . . . . E-19
E.3 Condition Categories and Codes . . . . . . . . . . E-19

*		ASCII and Hexadecimal Conversions . . . . . . . . . . . F-1

*		PL/I Bibliography . . . . . . . . . . . . . . . . . . . G-1

*		Glossary . . . . . . . . . . . . . . . . . . . . . . . . H-1

xv
Tables, Figures and Listings

Tables

2-1.	PL/I Symbols . . . . . . . . . . . . . . . . .	2-16
2-2.	PL/I Operators . . . . . . . . . . . . . . . .	2-20
2-3.	Special Character Delimiters and Separators . .	2-21
3-1.	PL/I Float Binary Numbers . . . . . . . . . . .	3-3
3-2.	Bit-String Constant Formats . . . . . . . . . .	3-6
4-1.	Common Operand Types in Mixed Operand
	Expressions	4-3
4-2.	PL/I BIFs for C.n,,;,;i~n*B;t'we;n*A;i'th~,~ic ;nd'
	Nonarithmetic Data Types . . . . . . . . . . .	4-8
4-3.	Character to Arithmetic Conversion . . . . . .	4-11
6-1.	PL/I Operator Precedence . . . . . . . . . . .	6-2
6-2.	PL/I Bit-String Operators . . . . . . . . . . .	6-5
9-1.	Arithmetic Error Condition . . . . . . . . . .	9-6
10-1.	External Device Names . . . . . . . . . . . . .	10-3
10-2.	PL/I implied Attributes . . . . . . . . . . . .	10-5
10-3.	Valid File Attributes for each 1/0 Statement .	10-6
10-4.	PL/I Valid File Atributes . . . . . . . . . . .	10-7

11-1.	Stream 1/0 Naming Conventions . . . . . . . . . 11-2
11-2.	Picture Format Characters . . . . . . . . . . . 11-12
11-3.	Picture Output Characters . . . . . . . . . . . 11-14
11-4.	Picture Edited Output . . . . . . . . . . . . . 11-17
11-5.	Picture Edited Output . . . . . . . . . . . .. 11-18

A-1.	Built-in Functions Not Implemented . . . . . .	A-2
A-2.	Summary of Implementation Differences . . . . .	A-6
D-1.	PL/I Compiler options . . . . . . . . . . . . .	D-1
E-1.	General Errors . . . . . . . . . . . . . . . .	E-2
E-2.	Compiler Errors . . . . . . . . . . . . . . . .	E-4
E-3.	Run-time Errors . . . . . . . . . . . . . . . .	E-14
E-4.	PL/I Condition Categories and Subcodes . . . . E-20

Figures

2-1.	Begin and Procedure Blocks . . . . . . . . . .	2-4
2-2.	Internal and External Blocks . . . . . . . . .	2-6
2-3.	Subroutine and Function Invocation . . . . . .	2-10
2-4.	Actual and Formal Parameters . . . . . . . . .	2-11

xvi
Tables, Figures and Listings
(continued)

5-1.		Two-dimensional Array . . . . . . . . . . . . .	5-2
5-2.		Array Element References . . . . . . . . . . .	5-4
5-3.		Array Initialization . . . . . . . . . . . . .	5-5
5-4.		Hierarchy of Structure Levels . . . . . . . . .	5-10
5-5.		Hierarchy of Structure Levels . . . . . . . . .	5-11
5-7a.		An Array of Structures . . . . . . . . . . . .	5-12
5-7b.		A Structure of Arrays . . . . . . . . . . . . .	5-13
7-1.		Multiple Allocations of a Based Variable . . .	7-6
7-2.		Linked List . . . . . . . . . . . . . . . . . .	7-8
8-1.		Forms of the DO Statement . . . . . . . . . . .	8-1
8-2.		Forms of the DO WHILE Statement . . . . . . . .	8-3
8-3.		The DO REREAT Statement . . . . . . . . . . . .	8-4
8-4.		The DO REPEAT WHILE Statement . . . . . . . . .	8-4
8-5.		The DO BY WHILE Statement . . . . . . . . . . .	8-6
9-1.		On-unit Activation . . . . . . . . . . . . . .	9-3
11-1.		Picture Specification Recognizer . . . . . .	. 11-13
B-1.		FIXED BINARY Representation . . . . . . . . . .	B-2
B-2.		PL/I-80 Single-precision Floating Point Format	B-2
B-3.		IEEE Single-precision Floating Point Format . .	B-4
B-4.		Double-precision Floating Point Format . . . .	B-6
B-5.		Bit-string Data Representation . . . . . . . .	B-10
C-1.		PL/I Parameter Passing Mechanism . . . . . . .	C-1
F-1.		ASCII Symbols . . . . . . . . . . . . . . . . .	F-1
F-2.		ASCII Conversion Table . . . . . . . . . . . .	F-2

Listings

B-1.		Floating-point Format Conversion Procedure	B-6
C-1.		The DTEST Program . . . . . . . * ' ' * *	C-3
C-2.		DIV2.ASM Assembly Language Program (8080)	C-4
C-3.		DIV2.A86 Assembly Language Program (8086) . . .	C-5
C-4.		DTEST Output (Abbreviated) . . . . . . . . . .	C-6
C-5.		The FDTEST Program . . . . . . . . . . . . . .	C-9
C-6.		FDIV2.ASM Assembly Language Program . . . . . .	C-10
C-7.		FDIV2.A86 Assembly Language Program . . . . . .	C-11

xvii
Section 1
Introduction

Digital Research PL/I is an implementation of PL/I for
microcomputers that use the 8080, 8086, 8088, or similar processor.
It is formally based on American National Standard X3.74 PL/I
General Purpose Subset (Subset G) . Subset G has the formal
structure of the full PL/I language, but in some ways it is a new
language and in many ways an improved language compared to full
PL/I.

PL/I Subset G is easy to learn and use. It is a highly portable
language because its design usually ensures hardware independence.
It is also more efficient and cost effective. Programs written in
PL/I Subset G are easier to implement, document, and maintain.

1.1 Documentation Set

The PL/I Language Reference Manual presents a detailed but concise
description of the PL/I programming language. It is not a tutorial
on how to program in PL/I; rather, it is a functional description of
the language, its syntax, and semantics. This manual is a reference
document that supplements Digital Research's PL/I Language
Programmer's Guide.

The PL/I Language Programmer's Guide includes sample programs that
illustrate many of the features of PL/I, as well as the mechanical
aspects of compiling and linking programs. If you have not
programmed in PL/I before, read the Programmer's Guide first, while
cross-referencing specific topics in the Reference Manual. If you
are already an experienced PL/I programmer, you might want to read
the Reference Manual only.

The PL/I Language Command Summary lists all the PL/I keywords and
statement forms, data attributes, and error messages. It also
contains a summary of the commands for the compiler.

1-1
PL/I Reference Manual	1.2 Notation

1.2 Notation

The following notational conventions appear throughout this
document:

Words in capital letters are PL/I keywords.

Words in lower-case letters or in a combination of lower-case
letters and digits separated by a hyphen represent variable
information for you to select. These words are described or
defined more explicitly in the text.

Example statements are given in lower-case.

The vertical bar I indicates alternatives.

JK represents a blank character.

Square brackets [] enclose options.

Ellipses (. . . ) indicate that the immediately preceding item can
occur once, or any number of times in succession.

	Except for the special characters listed above, all other
punctuation and special characters represent the actual
occurrence of those characters.

	Within the text, the symbol CTRL represents a control
character. Thus, CTRL-C means control-C. In a PL/I source
program listing or any listing that shows example console
interaction, the symbol - represents a control character.

	The acronym BIF means built-in function.

	Everything that you type at the keyboard and that appears on
the screen is in colored type.

End of Section 1

1-2
	Section 2
Program Structure

2.1 High-level organization

The following statements comprise every PL/I program:

		Structural statements
		Declarative statements
		Executable statements

Structural statements define distinct, logical units within a
program and therefore determine the overall, high-level
organization. When a program runs, control always flows from one of
these logical units to another. Logical units can contain other
logical units; they can be nested. Structural statements also
determine the hierarchical structure of a program where some logical
units are subordinate to others.

Declarative statements determine the environment of a logical unit.
The environment is simply the names and attributes of variables that
are available or active in a logical unit. Declarative statements
specify the context of variables that can be legally manipulated in
a logical unit.

Executable statements are statements that perform some action. Both
structural statements and declarative statements serve only to
create a context for executable statements. All executable
statements fall into one of the following categories:

		Assignment statements that assign the value of an expression or
constant to a variable.

		Condition handling statements that allow a program to intercept
and recover from run-time errors.

		1/0 statements that control the flow of data to and from 1/0
devices.

		Memory management statements that manipulate storage.

		Null statements that perform no action but function as
placeholders.

		Preprocessor statements that execute at compile time and
manipulate external source files.

		Sequence control statements that transfer the flow of control
between logical units.

2-1
PL/I Reference Manual	2.2 		Blocks

where proc-name identifies the procedure, and statement-1 through
statement-n are any PL/I statements constituting the body of the
block. Section 2.9 describes the PROCEDURE statement.

Note: the proc-name for the END statement is optional, but if
included it must match the proc-name for the PROCEDURE statement.

The essential difference between a BEGIN block and a PROCEDURE block
is how they receive control when the program is running. Control
flows into a BEGIN block in the usual sequential manner. At this
point, the block becomes active. When control transfers,
programmatically, outside the block, or its corresponding END
statement executes, the block terminates.

PL/I skips PROCEDURE blocks during the usual execution sequence, and
they receive control only when invoked (see Section 2.5). Figure 2
1 illustrates the block concept.

1-11

2-3
PL/I Reference Manual	2.3		Internal vs. External Blocks

2.3		Internal vs. External Blocks

Each block is characterized as either internal or external depending
on its relationship with other blocks. An internal procedure is one
that is contained in an encompassing block. An external procedure
is separate from other blocks. The procedure is not contained
(nested) in any other block. Thus, the main procedure is always an
external procedure.

A PL/I program can have one or more external procedures that contain
nested internal procedures or blocks. Each external procedure can
be separately compiled and linked together to form a runnable
program. One of the external procedures forming the program must be
the main procedure.

In Figure 2-2 (a) , blocks Pl, P2, and P3 are all external but the
BEGIN block is internal to P3. In Figure 2-2 (b) , Pl is the external
block, and P2, P3, and the BEGIN block are all internal. The main
procedure has the form:

proc-name:
PROCEDURE OPTIONS(MAIN);

Statement. or Blocks

END [proc-name];

2-5
PL/I	Reference Manual	2.3	Internal vs. External Blocks
	Pl:		Pi.
	PROCEDURE OPTIONS(MAIN);		PROCEDURE OPTIONS(MAIN);

-END P1,

P2:			P2:
	PROCEDURE,			PROCEDURE;
END P21			END P2;
P3:		P3:
	PROCEDURE;		PROCEDURE;
	BEGIN,				BEGIN;
	END.				END;

-END P3;

END P3:	-END P1,

A 	B

Figure 2-2. Internal and External Blocks

The PL/I Language Programmer's Guide contains specific examples of
program structure and how you can separately compile, link, and load
external procedures.

2.4	Scope of Variables

The scope of a variable is the set of blocks in which the variable
is known. Variables can be either local or external relative to a
block in which they appear.

2-6
PL/I Reference Manual	2.4		Scope of Variables

When you declare a variable in a block, you can reference it in that
block or any contained block. The variable is said to be local to
that block because you cannot reference it outside the block where
you declare it. In a contained block, a reference to a variable
declared in a containing block is called an up-level reference.

The following example illustrates the concept of scope:

Pl:
procedure;
declare
(a,b) fixed binary(7);
a = 2;	/* a is local to Pl
b = 3;	/* b is local to Pl
P2:
	procedure;
	declare
	b fixed binary(7);
	b = 2;		/* b is local to P2
	a = a*b; /* b here is b in P2, not b in P1
end P2;
put list (a,b);

end Pl;

PL/I creates a new variable b in block P2 because it is a declared
variable in that block. The PUT LIST statement is outside P2;
therefore, the value of the variable b of Pl is 3. Because there is
no declaration for the identifier a in P2, a is an up-level
reference to the variable a declared in Pl, and the assignment
statement in P2 changes its value. Thus, this code sequence
produces the values 4 and 3.

Any variable declared as EXTERNAL is known to all blocks in which it
is declared as EXTERNAL and in all contained blocks unless
redeclared without the EXTERNAL attribute. Two declarations of the
same variable name denote separate storage locations unless both
specify the EXTERNAL attribute.

2-7
PL/I Reference Manual	2.4	Scope of Variables

Pl:
procedure;
declare
z fixed binary external;

P2:
procedure;
declare
z fixed binary external;

P3:
begin;
declare
z float binary; /* not external

	-end;
	-end P3;
	end P2;
	end Pl;

In this code sequence, the variable z in Pl and P2 refers to the
same external variable, but variable z in P3 is a local variable and
is distinct from the external variable z.

2-8
PL/I Reference Manual	2.4		Scope of Variables

Pl:
procedure options(main);
declare x float binary;

begin;
declare x fixed;

end;

P2:
procedure;
declare x character(10) varying;

end P2;

end Pl;

In this code sequence, the scope of x is limited to each block in
which it is declared. Although the name is identical in each
declaration, the compiler treats each one as a completely different
variable with its own data type, and stores them in different memory
locations.

2.5 Procedure Blocks

In PL/I , there are two types of procedures: subroutines and
functions. Both types perform a specific task and are logically
separate from the rest of the program. Both types can execute the
same sequence of code one or more times without duplicating the code
at each occurrence.

You invoke or call a subroutine and, optionally, pass data items to
it in an argument list. The subroutine then manipulates the data
and, optionally, returns it to the invoking procedure. Control
resumes at the statement immediately following the invocation.

A function is a procedure that manipulates data items and then
returns a single value. You invoke a function by referencing its
function name and argument list in an expression. Control passes to
the function that performs its task and then returns a single value
that replaces the function reference. Control then resumes at the
point of reference.

2-9
PL/I Reference Manual	2.6	The CALL Statement

2.6 The CALL Statement

The CALL statement has the general form:

CALL proc-name((sub-l,...,sub-n)] [(argument-list)];

where sub-1 through sub-n are optional subscripts that are required
only when proc-name is a subscr ipted entry var iable (Section 3. 3. 2) ,
and argument-list represents the arguments passed to the procedure.
Figure 2-3 illustrates the invocation of subroutines and functions.

SUBROUTINE INVOCATION: 	FUNCTION INVOCATION:
'~T' 1E El '~T' E El

CALL NAME	ARGUMENT-LIST	NAME 	ARGUMENT-LIST

Figure 2-3. Subroutine and Function Invocation

example: 	example:

call print_header;	point = 3.14/sin(A);
call compute(base_pay,overtime);	put list (Sum(X'Y));

2.7	The RETURN Statement

The RETURN statement returns control to the point in the calling
block immediately following the procedure invocation. It also
returns a value if the procedure is a function procedure.
The RETURN statement has the form:
RETURN [(return-exp)];

where return-exp is the function value the procedure returns to the
calling point. When necessary, PL/I converts the attributes of the
returned value to conform to the attributes specified in the RETURNS
attribute of the procedure statement. (See Section 4.1.)

The RETURN statement ends the procedure block that contains it. If
the main procedure has the RETURNS attribute, PL/I returns control
to the operating system.
The following are some examples of RETURN statements:

return;
return (X**2);
return (F(A,(B)));
PL/I Reference Manual	2.8 Arguments and Parameters

2.8 Arguments and Parameters

The data items you pass to a procedure are called the arguments,
while the data items expected by a procedure and defined in the
PROCEDURE statement, are called the parameters. Upon invocation of
a procedure block, PL/I pairs each argument with its corresponding
parameter. Figure 2-4 illustrates this concept.

I	ARGUMENT-LIST

CALL COMPUTE 		+ C), R/2,3.14);

PARAMETER-LIST

COMPUTE: PROCEDURE (X,Y,Z);

END COMPUTE;

Figure 2-4. Arguments and Parameters

When you pass the argument by reference, the argument and
corresponding parameter share storage. In this case, any changes
made to the parameter in the invoked procedure change the value of
argument of the invoking block.

When you pass the argument by value, the argument and parameter do
not share storage. In this case, PL/I passes a copy of the argument
to the invoked procedure, so that any changes to the parameter
affect only the copy, not the argument's value.

The following example program illustrates parameter passing.

A:
procedure;
declare
ACTUAL		fixed binary,
DUMMY		fixed binary;

call X(ACTUAL);
call X((DUMMY));

procedure (FORMAL);
declare FORMAL fixed binary;
FORMAL = 3;
end X;
end A;

2-11
PL/I Reference Manual	2.8 Arguments and Parameters

PL/I passes ACTUAL by reference. Therefore, the assignment
statement in the procedure X changes the value of ACTUAL throughout
the program. PL/I passes DUMMY by value. Thus the procedure only
changes a copy of the value inside the procedure.

PL/I passes arguments by reference when the data attributes of the
argument are the same as the data attributes of the parameter. PL/I
passes an argument by value when it is one of the following:

*		a constant
		an entry name
		an expression consisting of variable references and operators
		a variable reference enclosed in parentheses
		a function invocation
		a variable reference whose data type does not match that of the
parameter

In the latter case, PL/I converts the argument to the data type,
precision, and scale factor of the parameter. The following program
illustrates this concept:

A:
procedure;
declare
X character(7),
	(Y,Z) fixed binary;
	call p(X,(Y),Z);

p:
procedure(A,B,C);
declare
A character(7),
B fixed binary,
C float binary;

A = 'Digital';
B = 100;
C = 2.5E2;
end p;
-end A;

The CALL statement sends the procedure three arguments X, Y, and Z
corresponding to the three parameters A, B, and C. PL/I passes the
first argument by reference because it matches the parameter, and
the second argument by value because it occurs as an expression.
PL/I converts the third argument to the FLOAT binary data type and
passes it by value.

2-12
PL/I Reference Manual	2.9		The PROCEDURE Statement

2.9		The PROCEDURE Statement

In PL/I, you can define a procedure with a PROCEDURE statement at
any point in a program. However, for readability you should place
all procedures together in a single section at the beginning or the
end of the main program. The main program is a single-procedure
definition.

The PROCEDURE statement identifies the entry point to the procedure,
delimits the beginning of the procedure block, defines the parameter
list, and gives the attributes of the returned value for functions.
The procedure can consist of a sequence of one or more statements
including the corresponding END statement that ends the procedure
definition. The END statement can also be the exit point of the
procedure, although embedded RETURN statements can appear within the
procedure body.

The PROCEDURE statement has the general form:

proc-name:		PROCEDURE[(parameter-list)]
	[OPTIONS(option .... )] [RETURNS(attribute-list)]
	[RECURSIVE];

where parameter-list are the parameters for the procedure which you
must declare within the procedure body at the principle block level.
A parameter can be any of the following:

a scalar variable
an array
	9 a major structure
	but cannot have the attributes:

STATIC
AUTOMATIC
BASED
o		EXTERNAL

OPTIONS(option,...) defines a list of one or more of the options
MAIN, STACK(b), or EXTERNAL.

e		The MAIN option identifies the procedure as the first procedure
to receive control when the program begins execution.

a		The STACK(b) option sets the size of the run-time stack to the
number of bytes specified by b. The default value is 512
bytes.

*		The EXTERNAL option identifies the procedure as an externally
compiled procedure. The EXTERNAL option in a procedure heading
makes the procedure accessible outside the module. It is often
useful to group separately compiled procedures into a single
compilation, where the procedures reference the same global
data. According to the Subset G standard, you must compile

2-13
PL/I Reference Manual	2.9	The PROCEDURE Statement

each subroutine separately, and duplicate the global data area
in each compilation. You can then combine the individual
modules using the linkage editor to produce the object module.

The following procedure shows an example of using the EXTERNAL
option:

module:
procedure;
declare
1		global_data static,
	2 a field character(20) varying initial(''),
	2 b field fixed initial(O),
	2 c field float initial(O);
Eset-a:
procedure (c) options(external);
declare c character(20) varying;
a field = c;
end-set a;
set-b:
procedure (x) options(external);
declare x fixed;
b field = x;
Eend-set b;
Eset-c:
procedure (y) options(external);
declare y float;
c field = y;
end-set-c;
sum:
procedure returns(float) options(external);
return (b-field + c-field);
Eend sum;
display:
procedure options(external);
put skip list(a-field,b-field,c-field);
Eend display;
end module;

2-14
PL/I Reference manual	2.9		The PROCEDURE Statement

This code defines five external procedures: set a, set b, set c,
The
sum, and display. These procedures are then accessed in
following code sequence:

call-ext:
procedure options(main);
declare
set a entry (character(20) varying),
set b entry (fixed),
set c entry (float),
sum returns(float),
display entry;
call set a('Johnson,JI);
call set-b(25);
call set-c(5.50);
put skip list(sumo);
call displayo;
end call-ext;

These two modules, when compiled separately and linked together,
form a single, runnable program.

		The RETURNS attribute for a function procedure gives the
attributes of the value returned by the function.

		The RECURSIVE attribute indicates that the procedure can
activate itself, either directly or indirectly.

2.10 Low-level Organization

The low-level organization of PL/I source text includes a
specification of the character set and the rules for forming
identifiers, both keywords and declared names, operators, constants,
delimiters, and comments.

PL/I is a free-format language. The source program consists of a
sequence of ASCII characters that make up lines delimited by
carriage return characters. You can enter the source text without
regard for column position or specific line format. However, the
source text is easier to read and comprehend if you follow some
basic formatting rules:

		Place only one statement on a line.

		Use indentation to show the nesting level of blocks and DO
groups.

2-15
PL/I Reference Manual	2.10	Low-level Organization

You can create the PL/I source program using any suitable text
editor.

Note:	all PL/I source programs must have the filetype PLI.

2.11	The Character Set

The PL/I character set consists of both upper- and lower-case
letters, numeric digits, and other symbols. Table 2-1 shows the
symbols recognized by PL/I and briefly describes their use.

Table 2-1. PL/1 Symbols

Symbol	Meaning
		equal sign (assignment)
	+	plus sign (addition)
		minus sign (subtraction)
		asterisk (multiplication)
		slash (division)
		left parenthesis	(delimiter)
		right parenthesis	(delimiter)
		comma (separator)
		period (name qualifier)
	%	percent symbol (INCLUDE or REPLACE prefix)
		apostrophe (string delimiter)
		semicolon (statement terminator)
		colon (separator for ENTRY or LABEL constant)
		circumflex (logical Not symbol)
		tilde (alternative Not symbol)
	&	ampersand (logical And symbol)
		vertical bar (logical Or symbol)
		exclamation mark	(alternative Or symbol)
		backslash (alternative Or symbol)
	>	right angle bracket (greater than)
	<	left angle bracket (less than)
		break or underscore (for readablity in identifiers)
		dollar sign (valid character in identifiers)
	?	question mark (valid character in identifiers)
PL/I Reference Manual	2.12 		Identifiers

2.12		Identifiers

An identifier is a string of from one to thirty-one characters that
are either letters, digits, or the underscore. The first character
must be a letter. PL/I always represents letters internally in
upper-case. Therefore, two identifiers that differ only in case
represent the same identifier.

PL/I allows the question mark character to be embedded in
identifiers to allow access to external system entry points.

Note: you should avoid embedded question marks to maintain upward
compatibility with full language implementation.

Every identifier in the source text of a PL/I program must be either
a keyword or a declared name. Keywords are those identifiers that
have a special meaning in PL/I when used in a specific context.
Examples of keywords are the names of built-in functions,
statements, and data attributes. The following is a list of all the
keywords. The PL/I Language Command Summary contains a complete
list of keywords with brief explanations.

A	ABS	ACOS	ADDR
ALIGNED	ALLOCATE		ASCII	ASIN
ATAN	ATAND	AUTO	AUTOMATIC
B	Bl	B2	B3
B4	BASED	BEGIN	BIN
BINARY	BIT	BOOL	BUILT-IN
BY	CALL	CEIL	CHAR
CHARACTER		CLOSE	COLLATE	COLUMN
Cos	COSD	DCL	DEC
DECIMAL	DECLARE	DIM	DIMENSION
DIRECT	DIVIDE	DO	E
EDIT	ELSE	END	ENDFILE
ENDPAGE	ENTRY	ENV	ENVIRONMENT
ERROR	EXP	EXT	EXTERNAL
F	FILE	FIXED	FIXEDOVERFLOW
FLOAT	FLOOR	FOFL	FORMAT
FREE	FROM	GET	GO TO
GOTO	HBOUND	IF	INCLUDE
INDEX	INIT	INITIAL	INTO
KEY	KEYED	KEYFROM	KEYTO
LABEL	LBOUND	LENGTH	LINE
LINENO	LINESIZE		LIST	LOG
LOG2	LOG10	MAIN	MAX
MIN	MOD	NULL	OFL
ON	ONCODE	ONFILE	ONKEY
OPEN	OPTIONS	OUTPUT	OVERFLOW
PAGENO	PAGESIZE		POINTER	PRINT
PROC	PROCEDURE		PTR	PUT

2-17
PL/I Reference Manual	2.12 	Identifiers

R	RANK	READ	RECORD
RECURSIVE	REPEAT	REPLACE	RETURN
RETURNS	REVERT	ROUND	SEQUENTIAL
SET	SIGN	SIGNAL	SIN
SIND	SINH	SKIP	SQRT
STACK	STATIC	STOP	STREAM
SUBSTR	SYSIN	SYSPRINT	TAB
TAN	TAND	TANH	THEN
TITLE	TO	TRANSLATE	TRUNC
UNDEFINEDFILE	UNDF	UNDERFLOW	UFL
UNSPEC	UPDATE	VAR	VARIABLE
VARYING	VERIFY	WHILE	WRITE
X	ZERODIVIDE

Declared names are identifiers whose use or meaning you define in a
DECLARE statement (Section 3.6). A keyword can appear in a
declaration as a user-defined identifier. The meaning of the
identifier depends on how and where it appears. PL/I determines the
meaning in context. For example, INDEX is a keyword because it is
the name of a PL/I built-in function. However, in the context of
the declaration,

	declare index fixed binary;
	index is a declared name and not a keyword.

2.13	Constants

Constants are text items that have a fixed literal meaning which can
not change when the program runs. In PL/I, the basic constants are
the following:

 arithmetic (Example: 3674-799
 character string (Exam le: 'Ada Lovelace'
 bit string (Example: T0010110'B

2.14	Delimiters and Separators

Separate items, such as identifiers, must be distinguishable. PL/I
recognizes certain characters as delimiters and separators.

Usually, delimiters enclose one or more text items while separators
mark the end of one item and the beginning of another. In PL/I,
each identifier and arithmetic constant must be preceded and
followed by one or more delimiters or separators. Delimiters can be
either spaces, operators, or certain special characters.

2-18
PL/I Reference Manual	2.14		Delimiters and Separators

2.14.1		Spaces

In PL/I, a space can be either a blank, or a tab character (CTRL-I)
PL/I ignores any carriage return, line-feed, or carriage return,
line-feed sequence that is embedded in a string constant. For
example, the assignment statement,

string = 'WHEN YOU HAVE A VERY LONG STRING LIKE THISf PL/I ALLOWS
YOU TO PUT SOME OF IT ON ANOTHER LINE';

assigns the specified character string to the variable string. Any
blanks or tabs that follow ALLOWS or precede YOU TO PUT are included
in the string.

2.14.2		Operators

An operator is a symbol for a mathematical or logical operation.
There are four types of operators in PL/I as shown in Table 2-2.

Note: operators that consist of two characters, such as >=, are
called composite operators and must not be separated by blanks or
tabs.

2-19
PL/I Reference Manual	2.14	Delimiters and Separators

Table 2-2. PL/I Operators

Symbol			Meaning
		Arithmetic Operators
	+	addition or prefix plus
		subtraction or prefix minus
		multiplication
		division
		exponentiation
		Comparison Operators

>	greater than
> or ->	not greater than
	>=	greater than or equal to
		equal to
or		not equal to
	<=	less than or equal to
	<	less than
< or		not less than

Bit-string Operators

or		Logical Not
	&	Logical And
	or ! or	Logical Or
		The String Operator
or !! or concatenate

2.14.3	Special Characters

Table 2-3 shows the special characters that can also function as
delimiters or separators in PL/I. Subsequent sections of the manual
contain examples of their use.

2-20
PL/I Reference Manual	2.14		Delimiters and Separators

Table 2-3. Special Character Deliniters and Separators

Chara ter	Function

A colon follows ENTRY and LABEL constants.

A semicolon terminates statements.

A comma separates elements of a list.

A period separates items in a qualified
name.

A single apostrophe is a delimiter for the
specification of character and bit-string
constants.

The arrow is a composite operator
consisting of the minus sign and the right
angle bracket. It is a separator in a
pointer qualified reference.

An equal sign is a separator in an
assignment statement.,

Left parenthesis.

Right parenthesis. A left parenthesis
together with a right parenthesis is used
to enclose lists and extents, define the
order of evaluation of expressions, and
separate keywords -from statements and
option names.

2.14.4		Comments

Comments provide documentary text in a PL/I source program.		The
compiler ignores comments, so you can place them wherever a
delimiter is appropriate. Precede a comment by the composite pair
/* and end the comment by the reverse composite pair	For
example,

get list(name); /* read the name

2-21
PL/I Reference Manual	2.15	Preprocessor Statements

2.15	Preprocessor Statements

PL/I allows modification of the source program or inclusion of
external source files at compile time through the use of
preprocessor statements. Preprocessor statements are identified by
a leading % symbol before the keyword:

INCLUDE	or 	REPLACE

2.15.1	The %INCLUDE Statement

The %INCLUDE statement copies PL/I source text from an external file
at compile time. The statement is useful for filling in a structure
declaration or format list. The %INCLUDE statement has the form:

%INCLUDE 'filespec';

where filespec designates the file to copy into the source program.
Filespec must be a standard file specification, [d: J filename [. typ] ,
and must be enclosed in single apostrophes. If there is no drive
specification, PL/I assumes the drive containing the source program.
When the compiler encounters the %INCLUDE statement in the source
file, it begins reading the file specified by %INCLUDE. When the
compiler reaches the end of the %INCLUDE file, it resumes reading
the original source file.

The following code sequence is an example of the %INCLUDE statement:

f:
procedure;
declare a fixed binary;
%include 'struc.lib';
declare c float;

end f;

The compiler includes the source text from the file struc.lib at the
point of the %INCLUDE statement.

Note:	PL/I does not allow nested %INCLUDE statements.

2.15.2	The %REPLACE Statement

The %REPLACE statement allows you to program with named constants.
The %REPLACE statement has the form:

%REPLACE identifier BY constant;

The compiler replaces every occurrence of the given identifier in
the source text with the specified constant. The constant can be a
signed or unsigned arithmetic constant, a bit string, or a character

2-22
