PL/I Useful Stuff

ADDR -- Built-in function

Returns a pointer value identifying the location of x.
>>--ADDR(x)-------------------------------------------------------------><
Example: P = ADDR(TABLE);
ALL -- Built-in function
Returns bit string (with length of longest element of array) resulting
from logical AND of all the elements of array x.
>>--ALL(x)--------------------------------------------------------------><
Example: IF ALL(LIST) THEN CALL SUB;

AREA -- Attribute
Reserves storage (in bytes) for the area. Default size is 1000 bytes.
>>--AREA----------------------------------------------------------------><
+-(--*--)-------------------------------------
+-(--expression-----------------------------)-+
+-REFER--(--variable--)-+
Example: DECLARE MC AREA(4095);
ASSEMBLER (ASM) -- Option of OPTIONS Attribute
Specifies that entry point is in an assembler routine.
Example: DECLARE ENTB ENTRY OPTIONS(ASM);
ATTENTION (ATTN) -- Condition
Occurs in conversational mode when programmer causes an attention interruption from the
terminal or when
SIGNAL ATTENTION is executed.
>>--ATTENTION-----------------------------------------------------------><
Example: ON ATTENTION CALL ATTPACK;

BACKWARDS -- Attribute
Causes the (implied) RECORD SEQUENTIAL INPUT tape file to be accessed in reverse order.

>>--BACKWARDS-----------------------------------------------------------><
Example: DECLARE TAPE FILE INPUT BACKWARDS...;

BASED -- Attribute
Specifies that the actual area of storage is identified by locator values. A based variable can be
used to refer
to variables of any storage class; it can also control its own storage by means of ALLOCATE and
FREE
statements.
>>--BASED---------------------------------------------------------------><
+-(--locator-reference--)-+
Example: DECLARE REC CHAR(30) BASED(P);

BYADDR -- Option of OPTIONS Option

Specifies that the argument or parameter is passed or received by the address.
Example: EXTR: PROC(A,B) OPTIONS(BYADDR);
DCL (A,B) FLOAT;

BYVALUE -- Option of OPTIONS Option

Specifies that the argument or parameter is passed or received by the value (contents).
Example: EXTR: PROC(P,Q) OPTIONS(BYVALUE);
DCL (P,Q) POINTER;

CEIL -- Built-In Function

Determines smallest integer greater than or equal to x.
>>--CEIL--(--x--)-------------------------------------------------------><
Example: DECLARE ST CHAR(CEIL(LST/2));

CHAR -- Built-In Function

Converts x to character string of length y. If y is omitted, the length is determined according to
the rules for
type conversion.
>>--CHAR--(--x------------)---------------------------------------------><

+-,--y-+
Example: CALL BC(SUBSTR(CHAR(B3,10),10,1));

CHARGRAPHIC (CHARG) -- Option of PROCEDURE and BEGIN Statement

When in effect, all character string assignments are assumed to be mixed-character
assignments.
Example: CH:PROCEDURE CHARGRAPHIC;
BEGIN CHARGRAPHIC;

COBOL -- Option of OPTIONS Option

Specifies that the entry point is to be invoked only by a COBOL routine.
Example: C:PROCEDURE(X,Y,Z) OPTIONS(COBOL);

CONDITION (COND) -- Attribute

Specifies that the associated identifier is a condition name.
>>--CONDITION-----------------------------------------------------------><
Example: DECLARE X COND;

CONTROLLED (CTL) -- Attribute

Specifies that storage is controlled by ALLOCATE and FREE statements. Declared name refers
to current
generation only.
>>--CONTROLLED----------------------------------------------------------><
Example: DECLARE PROFIT CTL;
...ALLOCATE PROFIT;

CURRENTSTORAGE (CSTG) -- Built-In Function

Returns the size in bytes of the storage currently occupied by the variable x.
>>--CURRENTSTORAGE--(--x--)---------------------------------------------><
Example: I = CURRENTSTORAGE(X);

DATAFIELD -- Built-In Function

Returns a character string giving contents of data field responsible for raising of NAME condition.

>>--DATAFIELD-----------------------------------------------------------><
+-(--)-+
Example: ON NAME(INFILE) PUT SKIP
EDIT('UNKNOWN:', DATAFIELD) (A);

DATETIME -- Built-In Function

Returns a current date in character-string form, yyyymmddhhmmssttt, for year, month, day, hour,
minute,
second, and millisecond.
>>--DATETIME------------------------------------------------------------><
+-(--)-+
DEFINED (DEF) -- Attribute
Specifies that the defined variable is to occupy all or part of the same storage as the designated
base variable
>>--DEFINED----reference------------------------------------------------><
+-(--reference--)-+
Example: DECLARE A(8,8,8), D(2,2,2) DEFINED A;
EMPTY -- Built-In Function
Returns an area of zero extent and can be used to free all allocations of based variables in an
area variable.
>>--EMPTY---------------------------------------------------------------><
+-(--)-+
Example: TABLE = EMPTY;
FETCH -- Statement
Loads the named procedure.
<-,--------------+
>>--FETCH----entry-constant----;----------------------------------------><
Example: PROG: PROCEDURE;
FETCH PROGA;

IGNORE -- Option of READ Statement

Ignores n records in input file.
>>--IGNORE--(--expression--)--------------------------------------------><
Example: READ FILE(AU) IGNORE(N);

INDEX -- Built-In Function

Returns the starting position of the string y within string x; returns 0 if y not present in x.
>>--INDEX--(--x--,--y--)------------------------------------------------><
Example: IF INDEX(REC,'DUP') = 0 THEN....;

INTERNAL (INT) -- Attribute

Indicates variable known only within declared block and within contained blocks.
+-INTERNAL-----------------------------+
>>----EXTERNAL----------------------------------------------------------><
+-(--environment-name--)-+
Example: DECLARE A CHARACTER(6) INT;

KEY -- Option of READ, DELETE, REWRITE, or UNLOCK Statement

Identifies which record is processed.
>>--KEY--(--expression--)-----------------------------------------------><
Example: READ FILE(TAX) KEY('AU65') INTO(ALA);

LABEL -- Attribute
Specifies an identifier as label variable. Optimization is aided by including a list of label
constants that the
variable can take as values.
>>--LABEL---------------------------------------------------------------><
<-,--------------+
+-(----label-constant----)-+
Example: DECLARE DOG LABEL (D1,D2);

LOCATE -- Statement
Causes allocation of a based variable in an output buffer and transmission of previous output
buffer, if
necessary.
>>--LOCATE--based-variable--FILE--(--file-reference--)------------------->
>-------------------------------------------------------------------;---><
+-SET--(--pointer-reference--)-+ +-KEYFROM--(--expression--)-+
Example: LOCATE RECORD SET(Q) FILE(PATIENT);

MOD -- Built-In Function

Returns the smallest positive value, R, such that: (x-R)/y=n where n is an integer. If x is
positive, result is
remainder from x/y.
>>--MOD--(--x--,--y--)--------------------------------------------------><
Example: SUBSTR(SED,MOD(X,256) = SEE;

NAME -- Condition
Raised during a data-directed GET FILE statement when an invalid identifier occurs in the data
stream.
>>--NAME--(--file-reference--)------------------------------------------><
Example: ON NAME(INFILE) PUT SKIP
EDIT('UNKNOWN:', DATAFIELD)(A);

OFFSET -- Attribute
Specifies that the variable identifies a location relative to the start of an area.
>>--OFFSET--------------------------------------------------------------><
+-(--area-variable--)-+
Example: DECLARE DATA AREA(50),
(L1,L2) OFFSET(DATA);

ONFILE -- Built-In Function

Gives name of file for which I/O condition was raised.
>>--ONFILE--------------------------------------------------------------><
+-(--)-+
Example: ON CONVERSION BEGIN;
IF ONFILE='INFILE' THEN...;
END;

ONLOC -- Built-In Function

Gives name of entry point to PROCEDURE in which the ON-condition was raised.
>>--ONLOC---------------------------------------------------------------><
+-(--)-+
Example: ON NAME BEGIN;
IF ONLOC='SORT' THEN ...;
END;

ORDER -- Option of PROCEDURE or BEGIN Statement

Specifies no relaxation of language rules to assist optimization of a block.
Example: E:PROCEDURE OPTIONS(MAIN) ORDER;

PLICKPT -- Built-In Subroutine

Allows you to take a checkpoint for later restart.
<-,--------+
>>--PLICKPT--(----argument----)-----------------------------------------><

PLIDUMP -- Built-In Subroutine

Allows you to obtain a formatted dump of selected parts of storage used by your program.
<-,--------+
>>--PLIDUMP--(----argument----)----

PLIREST -- Built-In Subroutine

Allows you to restart program execution.
>>--PLIREST---------

PLIRETC -- Built-In Subroutine

Allows you to set a return code that can be examined by the program, system, or subsystem that
invoked this
PL/I program or by another PL/I procedure via the PLIRETV built-in function.
>>--PLIRETC--(--return-code--)------

PLIRETV -- Built-In Function

Returns value set by CALL PLIRETC statement or returned by COBOL or ASSEMBLER routine.
>>--PLIRETV-------------------------------------------------------------><
+-(--)-+
Example: I = PLIRETV();
See the Language Environment for MVS & VM Programming Guide for other services that can
set the value returned by this built-in function.

PLISRTA -- Built-In Subroutine

Allows you to use DFSORT to sort an input file to produce a sorted output file.
<-,--------+
>>--PLISRTA--(----argument----)--

POINTER (PTR) -- Built-In Function

Returns a pointer value that identifies, in area y, a generation originally identified by the offset x.
>>--POINTER--(--x--,--y--)----------------------------------------------><
Example: G = POINTER(DISP,TAB);

POSITION (POS) -- Attribute

Specifies beginning of DEFINED string within base string.
>>--POSITION--(--expression--)------------------------------------------><
Example: DECLARE B CHAR(3) DEFINED C POS(3);

PROD -- Built-In Function

Returns product of all the elements of array x.
>>--PROD--(--x--)-------------------------------------------------------><
Example: PRODUCT = PROD(TABLE);

RECORD -- Condition
Raised if size of record and variable do not correspond.
>>--RECORD--(--file-reference--)----------------------------------------><
Example: ON RECORD(NEWINFO) BEGIN;
...END;

RECURSIVE -- Option of PROCEDURE Statement

Allows procedure to be invoked recursively.
Example: POW:PROCEDURE RECURSIVE;
...;
CALL POW;
...;
END POW;

REDUCIBLE (RED) -- Attribute for PROCEDURE or ENTRY Statement

If specified, it is checked for syntax errors, and the implied attribute ENTRY is applied. It is
otherwise ignored.
Example: D:PROC(FUNC, STR) REDUCIBLE;
DECLARE E ENTRY REDUCIBLE;

REENTRANT -- Option of OPTIONS Option

Allows a procedure to be reactivated when already active in another MVS task.
Example: E:PROCEDURE OPTIONS(REENTRANT);

REORDER -- Option of PROCEDURE or BEGIN Statement

Specifies relaxation of language rules to allow optimization of block.
Example: P:PROCEDURE REORDER;
...END;

REPEAT -- Option of DO Statement

Specifies value assigned to the control variable before each repetition of the DO-group.
Example: DO I = 1 REPEAT 2*I...; END;
DO PTR1=HEAD REPEAT PTR1->FWD
WHILE(PTR1=NULL()); ...END;

REPEAT -- Built-In Function

Returns the string x concatenated with itself y times.
>>--REPEAT--(--x--,--y--)-----------------------------------------------><
Example: A = REPEAT(STR,2);
(e.g., if STR='10'B then A='101010'B);

RETCODE -- Option of the OPTIONS Attribute

Specifies that, on return from a non-PL/I routine, the return code (in register 15) is saved. It can
be accessed
using the PLIRETV built-in function.
Example: DECLARE ASSEM OPTIONS(RETCODE)

RETURN -- Statement
Terminates execution of its procedure. For a function procedure, an expression must be
included.
>>--RETURN------------------------;-------------------------------------><
+-(--expression--)-+
Example: RETURN;
RETURN(2*P+Q);
RETURNS -- Attribute/Option of PROCEDURE or ENTRY Statement
Specifies data attributes of a returned value.
<-----------+
>>--RETURNS--(----attribute----)----------------------------------------><
Example: DECLARE A ENTRY RETURNS(FIXED);
F:PROCEDURE RETURNS(FIXED);
SAMEKEY -- Built-In Function
Returns '1'B if record accessed on a VSAM data set is followed by another record with the same
key.
>>--SAMEKEY--(--x--)----------------------------------------------------><
Example: IF SAMEKEY(INFILE) THEN ...;

SET -- Option of READ, ALLOCATE, or LOCATE Statement

Specifies the locator variable that is to identify a new generation of a based variable.
>>--SET--(--pointer-reference--)----------------------------------------><
Example: DECLARE VAL BASED;
ALLOCATE VAL SET (P);

SIGN -- Built-In Function

Returns sign of expression(x) as binary 1 if x>0, 0 if x=0, -1 if x<0.
>>--SIGN--(--x--)-------------------------------------------------------><
Example: DO X = 0 BY SIGN(A - B) TO SIGN(A - B) * 10;

SIZE -- Condition/Condition Prefix

Raised when high-order digits are lost on assignment or during an arithmetic or I/O operation.
>>--SIZE----------------------------------------------------------------><

Example: ON SIZE P = Q;

SNAP -- Option of ON Statement

Lists all currently active blocks and statements most recently executed.
>>--ON--condition--------------SYSTEM--;--------------------------------><
+-SNAP-+ +-ON-unit---+
Example: ON FIXEDOVERFLOW SNAP BEGIN...;

STATIC -- Attribute
Specifies storage is allocated before execution and remains allocated throughout execution.
>>--STATIC--------------------------------------------------------------><
Example: DECLARE TABLE (6,6) STATIC;

STORAGE (STG) -- Built-In Function

Returns the size in bytes of the storage required by the specified variable.
>>--STORAGE--(--x--)----------------------------------------------------><
Example: I = STORAGE(X);

STRING -- Built-In Function/Pseudovariable

Refers to all elements of aggregate x as a single string.
>>--STRING--(--x--)-----------------------------------------------------><
Example: DECLARE (ST(5),CS) CHARACTER(10) VAR;
CX=STRING(ST);
STRINGRANGE (STRG) -- Condition/Condition Prefix
Raised if values of arguments to SUBSTR reference are improper.
>>--STRINGRANGE---------------------------------------------------------><
Example: STRG:SUBSTR(S1,I,J) = SUBSTR(S2,I,J);
STRINGSIZE (STRZ) -- Condition/Condition Prefix
Raised when a string is assigned to a shorter string.
>>--STRINGSIZE----------------------------------------------------------><
Example: (STRINGSIZE):A = B||C;

SUBSCRIPTRANGE (SUBRG) -- Condition/Condition Prefix

Raised when subscript value is outside dimensions of array.
>>--SUBSCRIPTRANGE------------------------------------------------------><
Example: ON SUBRG PUT DATA (I,J);
SUM -- Built-In Function
Gives sum of all elements of array x.
>>--SUM--(--x--)--------------------------------------------------------><
Example: T = SUM(TABLE);

SYSTEM -- Option of ON Statement

Specifies standard system action for interrupt.
>>--ON--condition--------------SYSTEM--;--------------------------------><
+-SNAP-+ +-ON-unit---+
Example: ON ERROR SNAP SYSTEM;
SYSTEM -- Option of DECLARE Statement
Specifies standard defaults are to be taken.
<-,----------------------------------------------+
>>--DECLARE---------------name-----------------------------------;------><
+-level-+
<-----------+ +-SYSTEM-+
+---attribute---+
Example: DECLARE X(5) SYSTEM;

TASK -- Attribute
Specifies that identifier is task name and can be used to determine or modify relative priority of
task, using
PRIORITY built-in function/pseudovariable.
>>--TASK----------------------------------------------------------------><
Example: DECLARE TX TASK;
PRIORITY(TX)=1;

TASK -- Option of the CALL Statement

Specifies that invoked procedure is a subtask.

>>--TASK----------------------------------------------------------------><
+-(--task-reference--)-+
Example: CALL PROCA TASK(T1);
TITLE -- Option of OPEN Statement
Identifies data set associated with a file.
Example: OPEN FILE(W) TITLE('SUPER');
TRANSLATE -- Built-In Function
Translates source string x according to replacement string y and z. If z is omitted, string
containing all
possible characters (in ascending order) is assumed.
>>--TRANSLATE--(--x--,--y------------)----------------------------------><
+-,--z-+
Example: W = TRANSLATE (W,NEWCHARS,OLDCHARS);

TRANSMIT -- Condition
Raised by a permanent I/O transmission error.
>>--TRANSMIT--(--file-reference--)--------------------------------------><
Example: ON TRANSMIT (PAYROLL)...;

TRUNC -- Built-In Function

Truncates value of x to FLOOR(x) if x>0, CEIL(x) if x<0.
>>--TRUNC--(--x--)------------------------------------------------------><
Example: S = TRUNC(B);

UNALIGNED (UNAL) -- Attribute

Specifies mapping of data element is the next byte and independent of alignment requirement of
data type.
>>----ALIGNED-----------------------------------------------------------><
+-UNALIGNED-+
Example: DECLARE 1 A UNAL, 2 (B CHAR(3),C);

UNDEFINEDFILE (UNDF) -- Condition

Raised if file named cannot be opened.

>>--UNDEFINEDFILE--(--file-reference--)---------------------------------><
Example: ON UNDF(MASTER) GO TO STOPRUN;

UNDERFLOW (UFL) -- Condition/Condition Prefix

Raised when exponent of floating-point number is less than implementation minimum.
>>--UNDERFLOW-----------------------------------------------------------><
Example: ON UNDERFLOW...;

UPDATE -- Attribute
Specifies that file is used for both input and output.
+-INPUT--+
>>--+-OUTPUT-+----------------------------------------------------------><
+-UPDATE-+
Example: DECLARE F FILE UPDATE...;

VARIABLE -- Attribute
Identifies associated item to be a variable. Can be specified only for file, entry, or label
variables.
>>--VARIABLE------------------------------------------------------------><
Example: DECLARE G FILE VARIABLE;

VERIFY -- Built-In Function

Indicates the position in string x of the first character or bit that is not in string y. If all characters
in x are
contained in y, result is zero.
>>--VERIFY--(--x--,--y--)-----------------------------------------------><
Example: IF VERIFY(NAME,ALPHABET) THEN...;
The string function concatenates all the elements in an array or a structure into a single
character or bit string element.
The base and scale for picture are implicitly Dec & Fix resp.
Unlike a structure all elements in an array have identical attributes.
The string option may appear in a get or put stmt in place of the file option. String option causes
internal data movement. It may be used to convert character data to coded arithmetic data.

An argument is passed to a subroutine procedure from a calling procedure. A parameter is the

name used within the called procedure to represent the value that is passed to it.
Date and time are functions for which there are no arguments.
The case structure maybe implemented by a series of if stmts or by the select group.
One purpose of open stmt is to specify additional file attributes at open time.
Count built-in fn returns the no. of data items that were transmitted during the last get or put
operation in a given file.
Based variables would be used instead of the defined attrib to accomplish the fn of overlay
defining when the identifiers do not have the same base, scale or precision.
Processing data directly in a buffermwithout moving data into work storage area is termed as
locate mode.
The null form of the ON stmt indicates that if the specified condition occurs, no action should be
taken and execution should continue as if the cond had not been raised.
Begin blocks are needed when more than one Pli stmts needs to be executed in an On unit.
ON Conditions:
Conversion: bit specified character encountered.
Fixed overflow: when max precision exceeded.
Overflow: mag of floating pt exceeds max.
Underflow: mag of floating pt exceeds min.
Size: when exceeds declared precision.
Name: raised during a data directed get file stmt when an invalid identifier occurs in the data
stream.
Subscriptrange: raised whenever there is a reference to an element outside the boundaries of
an array.
Transmit: arises when malfunction of hardware device takes place.
Stringsize: raised when a string is assigned to a shorter atring
Buit-in fns for On units:
Oncode: determines the type of interrupt that caused the on unit to become active.
Onloc: determines the entry point of the procedure in which condition was raised.
Onchar/onsource: determines the char and source field that caused the conversion condition to
be raised.
Con, Var declared with the external attribute have static storage class initialised only once before
execution of pgm.
Direction of transmission for flat files are input/output/update.
The entry attrib allows compiler to generate coding to convert one or more arguments to conform
to the attribute of the corresponding parameters.
Return stmt is used to terminate a function.
Returns is a method of specifying the attrib of a returned value.

When a procedure invokes itself it is said to be recursive.