PL/I Reference Manual	11.3		EDIT-directed 1/0

the scale factor. The F format ignores leading and trailing blanks.
If the field contains only blank characters, the F format reads the
value zero.

	Input Value	Format	Input Result
	IM2fO b16	F(5)	0
	12f- 6 lzr	F(4)	-6
	13.09	F(5)	14

With PUT EDIT, the F format converts the data item to FIXED DECIMAL,
and then uses d to specify the scale factor of the output value. If
d is omitted, the scale factor is zero. The F format rounds the
output value unless the variable has precision 15. The F format
suppresses leading zeros except for one immediately to the left of
the decimal point.

Value	Format	Output Result
	0	F(5,1)	1&0. 0
	-27	F(5,1)	-27.0
	.39	F(6,2)	bhO.39

11.3.3 Control Format Items

Control format items are used for line, page, and space placement.
PL/I processes control format items as they are encountered in the
format-list, and ignores any items that remain after the input-list
or output-list is exhausted. PL/I supports the following control
format items.

COLUMN(nc)

This item moves the format pointer to column nc in the input or
output data stream. With GET EDIT, COLUMN ignores those characters
passed over by positioning the format pointer to column nc. If the
current column position is less than nc, the format pointer moves to
column position nc. If the current column position is greater than
nc, the pointer first moves to the next line, and then moves to the
new column position nc. If nc exceeds the rightmost position on the
line, the format pointer moves to the first column of the new line.
With GET EDIT, movement of the format pointer discards input
characters.

With PUT EDIT, COLUMN writes blanks in the process of positioning to
column nc. Also, if the current position is greater than nc, the
run-time system outputs a linemark, then outputs blanks until it
reaches column nc of the new line. If nc exceeds line size, the
run-time system writes a linemark and sets the column position to 1.

11-9
PL/I Reference Manual	11.3	EDIT-directed 1/0

LINE(ln)

This item applies only to PRINT files and specifies the line number
of the next data item to be written. The constant ln must be
greater than zero. If the current line number is equal to ln,
LINE(ln) has no effect. If the current line number is less than ln,
then the run-time system outputs linemarks until the current line
number equals ln. PL/I signals the ENDPAGE condition if sufficient
linemarks are issued to exceed the current page size.

PAGE

This item is used only with PRINT files and it causes the run-time
system to write a pagemark, increment the page number by one, and
set the line number and column position to 1.

SKIP[(nl)l

This item specifies the number of linemarks (nl) to be skipped or
written. If omitted, n1 defaults to 1. The run-time system sets
the column position to 1.

With GET EDIT, nl is the number of linemarks to skip before moving
to the next format item. The run-time system discards the first
line, if the program executes a SKIP(l) as the first format item
immediately following an explicit or implicit OPEN operation.
SKIP(O) is undefined for input streams.

With PUT EDIT, nl is the number of linemarks to be written. If the
page size is exceeded in the process of writing linemarks in a PRINT
file, the run-time system signals the ENDPAGE condition and, upon
return from the ON-unit, stops processing the SKIP operation.

X(sp)

This item advances the format pointer sp positions in the input or
output data stream. With GET EDIT, sp is the number of characters
to be advanced. The run-time system ignores linemarks, and
continues the operation on the next line. With PUT EDIT, sp is the
number of blanks to be written. If the end of the line is reached,
the run-time system writes a linemark, and the blank fill operation
continues on the next line.

11.3.4	Remote Format Items

The remote format item uses the format-list of a FORMAT statement in
place of the format item. The remote format item has the form:

R(format-label)

where the format-label is the label constant preceding a FORMAT

11-10
PL/I Reference Manual	11.3		EDIT-directed 1/0

put edit(a,b,c) (r(elsewhere));

11.3.5		The FORMAT Statement

The FORMAT statement defines a remote format item, and has the
general form:

format-label: FORMAT(format-list);

where the format-label is the label constant corresponding to the
FORMAT, and the format-list is a list of format items analogous to
those described in the previous section. For example, the FORMAT
statement:

	Ll: format(a(5), f(6,2),skip(3),a(2));
	is referenced as a remote format by the statement:

get edit (a,b,c) (r(Ll));

11.3.6		The Picture Format Item

The picture data format item is used on output to edit numeric data
in fixed-point decimal form. The value resulting from such an edit
is a character string whose form is determined by the numeric value
and the Picture specification in the picture format item.
The following is the form of a Picture format item:

P'picspec'

where picspec is a char acter-str ing constant describing the Picture
specification.

The Picture format item can appear in a PUT EDIT statement like any
other data format item.

Picture		Syntax

The character-string constant that describes the Picture
specification must consist of one or more special characters as
shown in Table 11-2.
PL/I Reference Manual	11.3	EDIT-directed 1/0

Table 11-2. Picture Format Characters

Character		Purpose
	$ +	S	static or drifting characters
	* Z		conditional digit characters
	9		digit character
	V		decimal point position character
	/ ,	: B	insertion characters
	CR DB		credit and debit characters

These characters must satisfy certain rules of syntax. Insertion
characters can occur anywhere in a valid Picture specification, with
the exception that they must not separate the characters of either
Picture character pair, CR and DB.

If all insertion characters of a Picture specification are removed,
the resulting string must be acceptable to the nondeterministic,
finite-state machine recognizer illustrated in Figure 11-1. That
is, it must be possible beginning with the START node to trace
through this diagram to ACCEPT, where transitions across an edge are
allowed if the edge is unlabeled, or if the edge is labeled by the
next character in the Picture specification.

The following character string constants define valid Picture
specifications:

'BB$***,***V.99BBI

'$----,999V.99BCR'

99: 99: 99

I:BBB$SSSS,SSS.VSSBBB:l

11-12
PL/I Reference Manual	11.3		EDIT-directed 1/0

U
U

U
M-T-U.
6

AN

F_

Figure 11-1. Picture Specification Recognizer

11-13
PL/I Reference Manual	11.3 EDIT-directed 1/0

Picture Semantics

The types of Picture characters appearing in the specification
determine how a Picture specification edits a numeric value into a
character-string value.

In the Picture specification, certain characters occur as either
static or drifting characters. These characters are

dollar sign
plus sign
minus sign
upper-case S

Such a character is static if it appears only once in the Picture
specification; otherwise, it is drifting. If it is drifting, all
its occurrences except for one correspond to conditional digit
positions.

In either case, these Picture characters, together with the sign of
the numeric value, determine an output character that occupies one
position in the output. These output characters are shown in Table
11-3.

Table 11-3. Picture Output Characters

Sign	Static/Drifting Characters
	S + $
POS	+ + 'b' $
neg	'b' $

If the Picture character is static, the output character appears in
the corresponding position of the output.

If the Picture character is drifting, then the output character
appears exactly one position to the left of the first nonzero digit
over which the Picture character drifts, or in the last position
over which it drifts. All other occurrences of the drifting
character are replaced by spaces, corresponding to the suppression
of a zero digit in the numeric value.

The * and Z Characters

The characters * and Z are called conditional digit Picture
characters or zero suppression characters. Each such character in
the Picture specification is associated with a digit in the numeric
value.

11-14
PL/I Reference Manual	11.3 EDIT-directed 1/0

If the digit is a zero, the output character is an * or a blank. If
the digit is nonzero, the output is the digit character.

The B, /, ., :, and , Characters

The Picture characters B, /, .' :, and , are called insertion
characters. B is the space insertion character. The : is not an
insertion character defined in the ANSI Standard, but is added in
PL/I to display numeric data that represents time.

PL/I outputs insertion characters in the corresponding output
position, unless the insertion character occurs in the field of a
drifting character, or zero suppression character. If the insertion
character occurs in the field of a drifting or zero suppression
character that causes the suppression of numeric digits, then PL/I
suppresses the insertion character following the preceding rules.

Note: in some PL/I implementations, B is an unconditional
insertion character that always causes a space in the corresponding
position of the output. According to the ANSI Standard, such a
space in the output can be overwritten by a drifting character or,
*, the zero suppression character.

The 9 Character

The Picture character 9 specifies that the corresponding digit in
the numeric value occurs in the corresponding position of the
output. Thus, 9 is an unconditional digit position.

The V character

The V character establishes the correspondence between digits in the
numeric value and the numeric digit positions in the Picture
specification. This character only specifies the position where
integral digits end and fractional digits begin. Thus, the V
character specifies the alignment of the Picture specification to
the numeric value.

If you omit the V character, PL/I assumes that all the digit
positions implied by the Picture specification refer to integral
digit positions. Any fractional digits in the numeric value do not
appear in the result.

Note: the V Picture character is the only character that does not
correspond to a character position in the result. Thus, the length
of the resulting string equals the length of the Picture
specification if V is omitted, but is one character less if V
appears.

11-15
PL/I Reference Manual	11.3	EDIT-directed 1/0

The V character also affects the suppression of characters. PL/I
never suppresses fractional digits unless it suppresses all of the
digits.

Beyond the V character PL/I turns OFF suppression if it is ON. As a
result, PL/I does not suppress any insertion character occurring
beyond the V Picture character, such as a decimal point, unless it
suppresses everything.

The CR and DB Characters

The character pairs CR and DB, represent credit and debit. They act
as sign characters. If either of them appear in the Picture
specification, and if the sign of the numeric value is negative,
then the specified pair occurs in the result. If the numeric value
is positive, then the positions corresponding to these character
pairs are replaced by two spaces.

Default Rules

If the numeric value is zero and if the Picture specification does
not contain a 9 Picture character, then the resulting output is all
*s if the Picture character * occurs at all. Otherwise, the output
is all spaces. This rule takes precedence over the other rules.

If the sign of the numeric value is negative, and if the Picture
specification does not contain any of the characters S,	CR, or
DB, then PL/I signals a conversion error, ERROR(l).

Each Picture specification implies a precision and scale factor for
the numeric value in the result according to the following rules:

	Insertion characters and the character pairs CR and DB have no
effect on precision and scale factor.

	The precision of the result equals one less than the number of
static/drifting characters; or the number of zero suppression
characters, plus the number of 9 characters.

	The scale factor of the result is zero if no V occurs.

	If V occurs, the scale factor of the result equals the number
of drifting characters, the number of zero suppression
characters, or the number of 9 characters occurring after the V
character.

The examples shown in Tables 11-4 and 11-5 illustrate some of the
rules involving the use of Picture data format items.

11-16
PL/I Reference Manual	11.3		EDIT-directed 1/0

Table 11-4. Picture Edited Output

	Value		picspec		Result
	0.00	BB$***,***V.99BB	$*******.Oo
	0.01	BB$***,***V.99BB	$*******.Ol
	0.25	BB$***,***V.99BB	$*******.25
	1.50	BB$***,***V.99BB	$******1.50
	12.34	BB$***,***V.99BB	$*****12.34
	123.45	BB$***,***V.99BB	$****123.45
	1234.56	BB$***,***V.99BB	$**1,234.56
	12345.67	BB$***,***V.99BB	$*12,345.67
	123456.78	BB$***,***V.99BB	$123,456.78
	0.00	$$$$$B$$$V.99		$.00
	0.01	$$$$$B$$$V.99		$.01
	0.25	$$$$$B$$$V.99		$.25
	1.50	$$$$$B$$$V.99		$1.50
	12.34	$$$$$B$$$V.99		$12.34
	123.45	$$$$$B$$$V.99		$123.45
	1234.56	$$$$$B$$$V.99	$1		234.56
	12345.67	$$$$$B$$$V.99	$12		345.67
	123456.78	$$$$$B$$$V.99	$123		456.78
	0.00	99/99/99	00/00/00
	0.01	99/99/99	00/00/00
	0.25	99/99/99	00/00/00
	1.50	99/99/99	00/00/02
	12.34	99/99/99	00/00/12
	123.45	99/99/99	00/01/23
	1234.56	99/99/99	OP/12/35
	12345.67	99/99/99	01/23/46
	123456.78	99/99/99	12/34/57
	0.00
	0.01
	0.25
	1.50			*******2
	12.34			******12
	123.45			****1:23
	1234.56			***12:35
	12345.67			*1:23:46
	123456.78			12:34:57

	0.00	....		1+++.V++/
	0.01	....		F+++.V++/	+01/
	0.25	.........	V++/		+25/
	1.50	.........	V++/		+1.50/
	12.34	.........	V++/		+12.34/
	123.45	.........	V++/		+123.45/
	1234.56	.........	V++/	/	+1,234.56/
	12345.67	.........	V++/	/ +12,345.67/
	123456.78	.........	V++/	/+123,456.78/

11-17
PL/I Reference Manual	11.3	EDIT-directed 1/0

Table ILI-5. Picture Edited Output

	Value			picspec	Output	Result
	0.00	S***B***.V**
	-0.01	S***B***.V**
	0.25	S***B***.V**		+********25
	-1.50	S***B***.V**		-******1.50
	12.34	S***13***.V**		+*****12.34
	-123.45	S***B***.V**		-****123.45
	1234.56	S***B***.V**		+**l 234.56
	-12345.67	S***B***.V**		-*12 345.67
	123456.78	S***B***.V**		+123 456.78
	0.00	$SSSSBSSSV.SS
	-0.01	$SSSSBSSSV.SS		$	-.01
	0.25	$SSSSBSSSV.SS		$	+.25
	-1.50	$SSSSBSSSV.SS		$	-1.50
	12.34	$SSSSBSSSV.SS		$	+12.34
	-123.45	$SSSSBSSSV.SS		$	-123.45
	1234.56	$SSSSBSSSV.SS		$ +1 234.56
	-12345.67	$SSSSBSSSV.SS		$ -12 345.67
	123456.78	$SSSSBSSSV.SS		$+123	456.78
	0.00	***.***S
	-0.01	***.***S
	0.25	***.***S
	-1.50	***.***S
	12.34	***.***S		*****12+
	-123.45	***.***S		****123
	1234.56	***.***S		**1.235+
	-12345.67	***.***S		*12.346
	123456.78	***.***S		123.457+
	0.00	$***,***V**CR
	-0.01	$***,***V**CR		$*******OICR
	0.25	$***,***V**CR		$*******25
	-1.50	$***,***V**CR		$******150CR
	12.34	$***,***V**CR		$*****1234
	-123.45	$***,***V**CR		$****12345CR
	1234.56	$***,***V**CR		$**1,23456
	-12345.67	$***,***V**CR		$*12,34567CR
	123456.78	$***,***V**CR		$123,45678
	0.00		....f+++.V++/
	-0.01	.........	V++/	ol/
	0.25	....	1+++.v++/	+25/
	-1.50	....	r+++.V++/	1.50/
	12.34	....	F+++.V++/	+12.34/
	-123.45	....	r+++.v++/	123.45/
	1234.56	.........	V++/	/	+1.234.56/
	-12345.67	....	F+++.v++/	/	12,345.67/
	123456.78	....		1+++.V++/	/+123,456.78/

11-18
PL/I Reference Manual	11.3		EDIT-directed 1/0

11.3.7		The GET EDIT Statement

The GET EDIT statement reads data using a format-list. The GET EDIT
statement has the form:

GET [FILE(file-id)] [SKIP[(nl)]]
EDIT(input-list)(format-list);

You can specify the options FILE or SKIP, in any order. EDIT must
appear last. If you do not specify the FILE option, PL/I assumes
file(SYSIN).

The GET EDIT statement reads data items from the input stream into
the variables given in the input-list until the input-list is
exhausted or the end-of-file is reached. The GET EDIT statement
pairs each input-list item with the next sequential format-list
item, applying control format items as they are encountered in the
process. If the GET EDIT statement exhausts the input-list before
the end of the format-list, remaining format items are ignored. If
the GET EDIT statement exhausts the format-list before the end of
the input-list, the format-list is reprocessed from the beginning

11.3.8		The PUT EDIT Statement

The PUT EDIT statement writes output data items according to a
format list. The PUT EDIT statement has the form:

PUT [FILE(file-id)] [SKIP[(nl)ll [PAGE]
EDIT(output-list)(format-list);

You can specify the options, FILE, SKIP, or PAGE, in any order.
EDIT must appear last. If you do not specify the FILE option, PL/I
assumes the file(SYSPRINT).

The PUT EDIT statement pairs output expressions from the output list
with format items from the format-list. The PUT EDIT statement also
applies any control format items encountered during this process.
The PUT EDIT statement ignores unprocessed format items at the end
of the statement. If the PUT EDIT statement encounters the end of
the output-list during processing, the format list restarts from the
beginning.

End of Section 11

11-19
Section 12
Record 1/0

Record files contain binary data that PL/I transmits to or from an
external device without conversion. There are two kinds of RECORD
files:

		SEQUENTIAL, where PL/I accesses the records in the order they
appear in the file.

		DIRECT, where PL/I randomly accesses the records through keys.

In the following discussion of RECORD 1/0 statements, file - id is a
file variable or file constant; x is a scalar, or connected
aggregate data type that does not have the attributes CHARACTER
VARYING, and k is a FIXED BINARY key value or variable.

12.1		The READ Statement

The READ statement reads fixed or variable length RECORD files. The
READ statement has the form:

READ FILE(file-id) INTO(x);

If you do not use the OPEN statement to open the file, the READ
statement performs an implicit OPEN with the attributes RECORD,
SEQUENTIAL, and INPUT.

The READ statement reads the number of bytes determined by the
length of x. If you open the file with the ENVIRONMENT option
specifying the size of the fixed-length record, the READ statement
reads the amount of data according to the declared record size. If
the length of x does not match the declared record size, the READ
statement either pads x with zero-bits or truncates it on the right.

12.2		The READ with KEY Statement

The READ statement with the KEY option directly accesses individual
records in a file. The READ with KEY statement has the form:

READ FILE(file-id) INTO(x) KEY(k);

where k is a FIXED BINARY expression that defines the relative
record to access. Key values start at zero, and continue until the
key value multiplied by the f ixed-record length reaches the capacity
of the disk.

If you do not use the OPEN statement to open the file, the READ with
KEY statement performs an implicit OPEN with the attributes RECORD,
INPUT, DIRECT, and KEYED. PL/I does not allow the READ with KEY
statement to access variable length records.

12-1
PL/I Reference Manual	12.3	The READ with KEYTO Statement

12.3	The READ with KEYTO Statement

The READ statement with the KEYTO option extracts key values from an
input file during sequential access. The program can save the key
values in memory or in another file, and subsequently perform direct
access on the records of the input file using the key values.

The READ with KEYTO statement has the form:

READ FILE(file-id) INTO(x) KEYTO(k);

where k is a FIXED BINARY variable assigned to the relative record
number of the record being read.

If you do not use the OPEN statement to open the file, the READ with
KEYTO statement performs an implicit OPEN with the attributes
RECORD, INPUT, SEQUENTIAL, and KEYED.

12.4	The WRITE Statement

The WRITE statement writes data from memory to the external data set
without conversion. The WRITE statement has the form:

WRITE FILE(file-id) FROM(x);

If you do not use the OPEN statement to open the file, the WRITE
statement performs an implicit open with the attributes RECORD,
OUTPUT, and SEQUENTIAL.

The output record size is exactly the length of x. If you open the
file with the ENVIRONMENT option specifying the fixed-length record
size, the WRITE statement writes the amount of data according to the
declared record size. If the length of x does not match the
declared record size, the WRITE statement either pads x with zero
bits or truncates it on the right.

12.5	The WRITE with KEYFROM Statement

The WRITE with KEYFROM statement directly accesses a file for
output. The WRITE with KEYFROM statement has the form:

WRITE FILE(file-id) FROM(x) KEYFROM(k);

where k denotes a FIXED BINARY expression yielding a key value that
PL/I treats like the READ with KEY option shown in Section 12.2.

If you do not use the OPEN statement to open the file, the WRITE
with KEYFROM statement performs an implicit OPEN with the attributes
RECORD, DIRECT, OUTPUT, and KEYED.

End of Section 12

12-2
Section 13
Built-in Functions

A built-in function (BIF) is a computational subroutine provided as
part of the PL/I Run-time Subroutine Library (RSL). You can use a
BIF reference as a user-defined function reference.

You do not have to declare the name of a BIF. If you redeclare the
name of a BIF in the program, you cannot reference it as a BIF
within the scope of that declaration. However, you can use a BIF in
a contained block by redeclaring the name with the attribute
BUILTIN.

PL/I built-in functions are divided into the following categories:

 Arithmetic	* Conversion
 Mathemetical	* Condition Handling
 String Handling		* Miscellaneous

13.1		Arithmetic Functions

The arithmetic functions are

ABS		FLOOR	MOD	TRUNC
CEIL		MAX	ROUND
DIVIDE		MIN 	SIGN

The arithmetic BIFs return information about the attributes of
specified arithmetic values, and perform common arithmetic
calculations.

13.2		mathematical Functions

The mathematical functions are

ACOS		Cos	LOG	SIND	TAND
ASIN		COSD	LOG2	SINH	TANH
ATAN		COSH	LOG10	SQRT
ATAND		EXP	SIN 	TAN

The mathematical BIFs perform mathematical calculations in floating
point arithmetic. The mathematical functions include

*		the most commonly used trigonometric functions and their
inverses

*		base 2, base e (natural) , and base 10 (common) , logarithmic
functions

13-1
PL/I Reference Manual	13.2	Mathematical Functions

 the natural exponent function

 hyperbolic sin and cos functions

 the square root function

Each of these functions accepts a single FLOAT BINARY argument and
returns a FLOAT BINARY result. The precision of the result depends
on the precision of the argument. If the argument is single
precision, the result is single-precision. If the argument is
double-precision, the result is double-precision. If the argument
is an expression containing operands of different precisions, PL/I
first performs conversion according to the rules stated in Section
4.2.

You can also specify a argument that is not FLOAT BINARY, but PL/I
automatically converts it.

All of the function subroutines, with the exception of SQRT, use
algorithms based on the Chebyshev polynomial approximations. The
SQRT function subroutine is based on Newton's method.

Typically these algorithms scale the given argument into a finite
interval, usually -1 <= X <= 1, and then evaluate the Chebyshev
approximation using an appropriate recurrence relation. The
greatest source of error in these routines results from the
truncation of significant digits during the scaling process. Except
for this, the subroutines have an average accuracy of 7 significant
decimal digits for single-precision, 15 digits for double-precision.

13.3 String-handling Functions

The string-handling functions are

* BOOL
 COLLATE
 COPY
 INDEX
 LENGTH
 REVERSE
 SEARCH
 SUBSTR
o TRANSLATE
o TRIM
o VERIFY

The string-handling BIFs perform character-string and bit-string
manipulation.

13-2
PL/I Reference Manual	13.4		Conversion Functions

13.4		Conversion Functions

The conversion functions are

*		ASCII
e		BINARY
	BIT
	CHARACTER
	DECIMAL
o		FIXED
	FLOAT
	RANK
	UNSPEC

The conversion BIFs convert data from one type to another. PL/I
uses these functions internally to perform automatic conversion.

13.5		Condition-handling Functions

The condition-handling functions are

9 ONCODE
* ONFILE
e ONKEY

The condition-handling BIFs return information about conditions
signaled by the run-time system. These functions do not have
parameters and return a value only when executed in an ON-unit. The
ON-unit . can be entered when the specified condition is
programmatically signaled, or as the result of an interrupt caused
by the occurrence of the specified condition.

13.6		Miscellaneous Functions

The miscellaneous BIFs are

ADDR
DATE
DIMENSION
HBOUND
LBOUND
LINENO
LOCK
NULL
PAGENO
TIME
UNLOCK

13-3
PL/I Reference Manual	13.6	Miscellaneous Functions

The miscellaneous BIFs return information about based variables,
date and time, the current line number and page number of a file,
information about array dimensions, and provide the ability to lock
and unlock individual records within a file.

13.7	List of Built-in Functions

The following sections describe the specific format, parameter
attributes, purpose, and properties of each built-in function.

ABS

Category:	Arithmetic
Format:	ABS(X)

Parameters:	X can be any arithmetic expression.

Result:	Returns the absolute value of X.
Algorithm:	If X >= 0 then return X, otherwise return -X.

Result type:	Same as X.

Examples:	ABS(-100) returns 100
	AB(18.78) returns 18.78

13-4
PL/I Reference Manual	13.7		List of Built-in Functions

ACOS

Category:		Mathematical
Format:	ACOS(X)
Parameter:		X is an arithmetic expression, -1 <= X <= 1.
Result:	Returns the arc cosine of X; for example, ACOS(X) is
	the angle in radians, whose cosine is X such that 0
	<= ACOSW <= PI.

Result type:		FLOAT BINARY.

Algorithm:		ACOS(X) equals PI/2 - ASIN(X).
Error
Condition:		If X is not in the interval -1 <=X <= 1 the run-time
	system signals the ERROR(3) condition.
Examples:		ACOS(O.866) returns 5.236490E-01
	ACOS(O.86603) returns 5.235897302627563E-001
		ADDR

Category:		Miscellaneous
Format:	ADDR(X)
Parameter:		X is a reference to a variable with connected
	storage.
Result:	Returns a pointer that identifies the storage
	location of the variable X.

Result type: 		POINTER
PL/I Reference Manual	13.7	List of Built-in Functions

ASCII

Category:	Conversion
Format:	ASCII(I)
Parameter:	I is a FIXED BINARY expression.
Result:	Returns a single character whose position in the
	ASCII collate sequence corresponds to I (see
	Appendix F for ASCII codes).

Result type: 	CHARACTER(l)

Algorithm:	ASCII(1) equals SUBSTR(COLLATEorMOD(I.128)+1,1).
Remark:	ASCII (I) is the inverse function of RANK (I) ; that is,
	ASCII (Rank(C))=C, for any character C.
Examples:	ASCII(88) returns Ixf
	ASCII(40) returns I('
		ASIN
Category:	Mathematical
Format:	ASIN(X)
Parameter:	X is an arithmetic expression, -1 <= X <= 1.
Result:	Returns the arc sine of X; for example, ASIN(X) is
	the angle in radians, whose sine is X, such that -
	PI/2 <= ASIN(X) <= PI/2

Result type:	FLOAT BINARY

Algorithm:	Chebyshev polynomial approximation
Error
Condition:	If X is not in the interval -1 <= X <= 1, the run
	time system signals the ERROR(3) condition.
Examples:	ASIN(O.866) returns 1.0471462E+00
	ASIN(O.86603) returns 1.047206282615661E+000
		13-6
PL/I Reference Manual	13.7		List of Built-in Functions

ATAN

Category:		Mathematical
For-mat:	ATAN(X)
Parameter:		X is any arithmetic expression.
Result:	Returns the arc tangent of X; for example, ATAN (X) is
	the angle in radians, whose tangent is X, such that
	-PI/2 <= ATAN(X) <= PI/2

Result type:		FLOAT BINARY

Algorithm:		Chebyshev polynomial approximation

Examples:		ATAN(O.577) returns 5.23336OOE-01
	ATAN(O.57735) returns 5.235985517501830E-001

ATAND

Category:		Mathematical
Format:	ATAND(X)
Parameter:		X is any arithmetic expression.
Result:	Returns the arc tangent of X in degrees; for example,
	the angle, in degrees, whose tangent is X, such that
	-90 <= ATAND(X) <= 90

Result type:		FLOAT BINARY

Algorithm:		ATAND(X) equals 180/PI * ATAN(X)

Examples:		ATAND(O.577) returns 2.9984940E+01
	ATAND(O.57735) returns 2.999998664855957E+001

13-7
PL/I Reference Manual	13.7	List of Built-in Functions

BINARY

Category:	Conversion
Format:	BINARY (X [,p
Parameter:	X is an arithmetic expression, or a string expression
	that can be converted to an arithmetic value. If X
	is DECIMAL with a nonzero scale factor, then p must
	be given, where p is an integer constant that
	specifies the precision of the result.
Result:	Returns a BINARY arithmetic value equivalent to X.
Result type:	If X is FLOAT BINARY, the result is FLOAT BINARY;
	otherwise it is FIXED BINARY.
Examples:	If x = 12.675 FIXED DECIMAL(6,3)

then

BINARY(X,15) returns 12

BINARY(12.675,15) returns 1.2000000E+01

BIT

Category:	Conversion
Format:	BIT(S[,Ll)
Parameter:	S is an arithmetic or string expression. L is a
	positive FIXED BINARY expression.
Result:	Converts S to a bit string of length L when L is
	specified. Otherwise, it converts S to a bit string
	whose length is determined by the conversion rules
	in Section 4.3.3.
Result type:	BIT
Examples:	BIT(3,8) returns 00000110
	BIT(-4,16) returns 0000100000000000
		13-8
PL/I Reference Manual	13.7		List of Built-in Functions

BOOL

Category:		String
Format:	BOOL(X,Y,Z)
Parameters:		X is a bit expression.
	Y is a bit expression.
	Z is a bit-string constant, four-bits long.
Result:	Returns a Boolean function on X and Y, specified by
	the bit-string constant Z as follows. Let
	Zl,Z2,Z3,Z4 be the bit values in Z, reading left to
	right. Then bit values A,B and the four-bit string
	Z determine the Boolean function BOOL(A,B,Z):

A		B		BOOL(A,B,Z)
0		0		Zi
0		1		Z2
1		0		Z3
1		1		Z4

This then induces the function BOOL(X,Y) on bit
strings X and Y as follows. If X and Y do not have
the sane length, the shorter string is padded on the
right with zero-bits until they have the same
length. Then BOOL(X,Y,Z) is defined to be the bit
string whose Nth bit is obtained from the preceding
table by letting A be the Nth bit of X and B the Nth
bit of Y.

Result type:		BIT(n) where n equals MAX(LENGTH(X)ILENGTH(Y)).
Examples:		BOOL(10011'B,'0101'B,'1001'B) returns '1001'B
	BOOL('01011'B,'11'B,11001'B) returns '01100'B

13-9
PL/I Reference Manual	13.7	List of Built-in Functions

CEIL

Category:	Arithmetic
Format:	CEIL(X)
Parameter:	X is any arithmetic expression.
Result:	Returns the smallest integer >= to X.
Algorithm:	-FLOOR(-X)

Result type:	An integer value of the same type as X.

Examples:	CEIL(7.9) returns 8
	CEIL((5/3)) returns 2
		CHARACTER
Category:	Conversion
Format:	CHARACTER(S[,Ll)	___'N'
Parameter:	S is an arithmetic or string expression, L is a
	positive FIXED BINARY expression.
Result:	S is converted to a character string of length L when
	L is specified; otherwise, S is converted to a
	character string whose length is determined by the
	conversion rules of Section 4.

Result type: 	CHARACTER

Examples:	If x = -13.25

then

CHARACTER(X,10) returns VX-13.25

CHARACTER(2*(3+7)-6,10) returns VO(VOW14

13-10
PL/I Reference Manual	13.7		List of Built-in Functions

COLLATE

Category:		String
Format:	COLLATEO

Parameters: 		None

Result:	Returns a character string of length 128 consisting
	of the set of characters in the ASCII character set
	in ascending order. (The ASCII character set is
	given in Appendix C.)

Result type: 		CHARACTER(128)

Note: in PL/I-86 V1.2, COLLATEO returns a character string of
length 256.

COPY

Category:		String
Format:	COPY(S,I)

Parameters:		S is a character string expression
I is a FIXED BINARY expression

Result:	Returns I copies of S. concatenated together.
	If I <= 0, COPY returns a null string.

Result Type: 		CHARACTER

Examples:		COPY('*1,80) returns a CHARACTER(80) value
containing 80 asterisk characters.

13-11
PL/I Reference Manual	13.7	List of Built-in Functions

Cos

Category:	Mathematical
Format:	COS(X)
Parameter:	X is an arithmetic expression.
Result:	Returns the cosine of X in radians.
Result type:	FLOAT BINARY
Algorithm:	Chebyshev polynomial approximation
Examples:	COS(3.1415/3.0) returns 5.000267465490945E-001

COSD

Catfc
	_jo=.	Mathematical
Format: COSD(X)
Parameter: X is an arithmetic expression
Result: Returns the cosine of X in degrees.
Result type: FLOAT BINARY
Algorithm: COSD(X) equals COS(X*PI/180)
Examples: COSD(O.500) returns 9.9996180E-01
		COSD(O.50000) returns 9.999617934226980E-001

13-12
PL/I Reference Manual	13.7		List of Built-in Functions

COSH

Category: 		Mathematical

Format: 	COSH(X)

Parameter:		X is an arithmetic expression.

Result:	Returns the hyperbolic cosine of X.

Result type:		FLOAT BINARY

Algorithm:		COSH(X) equals (EXP(X) + EXP(-X))/2

Examples:		COSH(2-75) returns 7.8532790E+00
	COSH(2.75000) returns 7.853279590606689E+000

DATE

Category:		Miscellaneous
Format:	DATEO

Parameters: 		None

Result:	Returns a character string representing the date in
	the form, YYMMDD where
	YY is the current year (00-99)
	MM is the current month (00-12)
	DD is the current day of the month (00-31)

Result Type: 		CHARACTER(6)

Examples:		DATEO	returns '8303251

Remarks:	Only available if supported by operating system.
If not supported, DATE returns blanks.

13-13
PL/I Reference Manual	13.7	List of Built-in Functions

DECIMAL

Category:	Conversion
Format:	DECIMAL(X[,p[,qll)
Parameter:	X is an arithmetic or string expression that can be
	converted to an arithmetic value.
	p is an integer constant, 1 <= p <= 15.
	q is an integer constant, 0 <= q <= p.
Result:	Converts X to a DECIMAL value. p and q are optional
	but when specified represent the precision and scale
	factor, respectively. If only p is given, q is
	assumed to be zero. If neither p nor q is given,
	then the precision and scale factor of the result
	are determined by the rules for conversion given in
	Section 4.3.2.

Result type:	FIXED DECIMAL

Examples:	DECIMAL(125,6,2) returns 125.00

DIMENSION

Category:	Miscellaneous
Format:	DIMENSION(X,N) I DIM(X,N)

Parameters:	X is an array variable; N is a positive integer
expression.

Result:	Returns a positive integer representing the extent of
	the Nth dimension of the array referenced by X.

Result type:	FIXED BINARY

13-14
PL/I Reference Manual	13.7		List of Built-in Functions

DIVIDE

Category:		Arithmetic
Format:	DIVIDE(X,Y,p) or DIVIDE(X,Y,p,q)

Parameters:		X and Y are arithmetic expressions.

Result:	Returns the quotient of X divided by Y, with the
	constants p, precision of the result, and q, scale
	factor. q assumed to be zero if not included. If X
	and Y are FIXED BINARY, q must be omitted or equal
	to zero.

Result type:		The common arithmetic type of X and Y.

Examples:		DIVIDE(189.07,37.56,15,5) returns 5.03381
	DIVIDE(296,49,15) returns 6
	DIVIDE(233.456e2,1.19el,24) returns 1.9710920E+02

EXP

Category:		Mathematical
Format:	EXP(X)
Parameter:		X is an arithmetic expression.
Result:	Returns the value of e to the power X, where e is the
	base of the natural logarithm.

Result type:		FLOAT BINARY

Algorithm:		Chebyshev polynomial approximation.

Examples:		EXP(5.13) returns 1.6901700E+02
	EXP(5.13333) returns 1.695808563232421E+002

13-15
PL/I Reference Manual	13.7	List of Built-in Functions

FIXED

Category:	Conversion
Format:	FIXED(X[,p[,qll)
Parameters:	X is an arithmetic expression or string expression
	that can be converted to an arithmetic value.
	p is an integer constant.
	q is an integer constant.
Result:	Converts X to a FIXED arithmetic value. p and q are
	optional but when specified determine the precision
	and scale factor of the result. If only p is given,
	then q is assumed to be zero. If neither p nor q is
	given, then the precision and scale factor are
	determined by the conversion rules in Section 4.
Result type:	If X is FIXED DECIMAL or CHARACTER, the result is
	FIXED DECIMAL. Otherwise, it is FIXED BINARY.
Examples:	If s = '01010010'b

then

FIXED(S,8) returns 82
FIXED(s,24) returns 8.2000000E+01

FLOAT

Category:	Conversion
Format:	FLOAT(X[rpl)
Parameter:	X is an arithmetic or string expression that can be
	converted to an arithmetic value. p is an optional
	positive integer constant.
Result:	Converts X to a FLOAT arithmetic value. p is
	optional but, when given, determines the precision
	of the result. If p is not given, the precision is
	determined by the conversion rules in Section 4.
Result type:	FLOAT BINARY
Examples:	If y = 4589 FIXED BINARY(15)

then

FLOAT(Y,24) returns 4.5890000E+03

13-16
PL/I Reference Manual	13.7		List of Built-in Functions

FLOOR

Category: 		Arithmetic

Format: 	FLOOR(X)

Parameter:		X is any arithmetic expression.

Result:	Computes the greatest integer <= X.

Result type:		An integer value of the same type as X.

Examples:		FLOOR(7.9) returns 7
	FLOOR((5/3))	returns 1
		HBOUND
Category:		Miscellaneous
Format:	HBOUND(X,N)

Parameters:		X is an array variable, N is a positive integer
expression.

Result:	Returns the upper bound of the Nth dimension of the
	array variable X.

Result type:		FIXED BINARY

13-17
PL/I Reference Manual	13.7	List of Built-in Functions

INDEX

Category:	String
Format:	INDEX(X,Y[,Il)

Parameters:	X and Y are string expressions of the same type,
either bit or character. The optional third
argument, I, is an integer expression. If only two
arguments are given, the third argument defaults to
1.

Result:	Returns an integer value indicating the position of
	the leftmost occurrence of the string Y in the
	string X, starting the scan fron position I in X.
	If X or Y is null or if Y does not occur in X. INDEX
	returns the value zero.

Result type:	FIXED BINARY

Examples:	INDEX(11234567891,'7') returns 8
INDEX(IABAB',IABI,2) returns 3

LBOUND

Category:	miscellaneous
Format:	LBOUND(X,N)

Parameters:	X is an array variable, N is a positive integer
expression.

Result:	Returns the lower bound of the Nth dimension of the
	array referenced by X.

Result type:	FIXED BINARY

13-18
PL/I Reference Manual	13.7		List of Built-in Functions

LENGTH

Category:		String
FormaL	LENGTH(X)
Parameter:		X is a string expression, either bit or character.
Result:	Returns the number of characters or bits in the
	string X. If X has the attribute VARYING, LENGTH(X)
	returns the current length of X.

Result type:		FIXED BINARY

Examples:		LENGTH('Himalayan') returns 9
LENGTH(") returns 0

LINKNO

Category:		Miscellaneous
Format:	LINENO(F)
Parameter:		F is a file value.
Result:	Returns the current line number of the file
	referenced by F. The file must have the PRINT
	attribute.

Result type:		FIXED BINARY

13-19
