home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
kermit.columbia.edu
/
kermit.columbia.edu.tar
/
kermit.columbia.edu
/
archives
/
ibmtsonih.zip
/
tsnalpdoc.txt
< prev
next >
Wrap
Text File
|
1986-12-18
|
121KB
|
3,714 lines
# LIST CC UNN REM 112
,FONT 1 27 9
,PRINT 100
,END
1************************************************************
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* ALP: Assembly Language Preprocessor *
* *
* User's Guide *
* *
* *
* Computer Center Branch *
* Division of Computer Research and Technology *
* National Institutes of Health *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
* *
************************************************************
Version 6.19 5/10/88
1
1 Level 2 Software Support
(Revised November 1986)
This software product, or a certain portion of it, has been
assigned Level 2 support status. The Level 2 designation is made
by the Computer Center for any of three reasons: First, an
entire software product may be designated Level 2 if it is in
test status, or the Center determines that rapid problem
resolution and long-term product availability can not be ensured
with the vendor support available. Second, an interface to
specific peripheral hardware devices (e.g., terminals or
plotters) will receive Level 2 support, even if the remainder of
the product is designated Level 1. Third, an interface to
processors not at the NIH Computer Utility (e.g., microprocessors
or other computer installations) will receive Level 2 support,
even if the remainder of the product is designated Level 1.
If a hardware device/terminal is not specifically mentioned in
the documentation for this product, no interface to it is
supported (even as Level 2). While unsupported devices may
sometimes function with the interfaces provided, any problems
encountered are wholly the user's responsibility. This support
policy is necessary in order to provide services for the large
number of devices (e.g., terminals, plotters, microprocessors)
commonly owned/used by end users. It is not practical for the
NIH Computer Center to be familiar with the hardware
characteristics of the myriad devices that can take advantage of
these services.
Users of this product should be fully aware that Level 2 software
support provides documentation, non-critical Programmer Trouble
Report (PTR) service, and limited INTERFACE preannouncement of
changes, but does not guarantee continued availability or
conversion assistance if this software is discontinued by the
vendor or the Computer Center.
In addition, no Programmer Assistance and Liaison (PAL) Unit
consulting will be available on questions pertaining to the use
of or problems with software receiving Level 2 support. The
Computer Center will accept PTRs for problems if they are
accompanied by all of the documentation necessary for diagnosis
and resolution. When the Computer Center staff member
responsible for the problem area described in a PTR for a product
receiving Level 2 support receives all pertinent documentation on
the problem, the staff member will frequently act as a technical
guide with the burden of the work remaining with the user.
Resolving or circumventing problems with software receiving Level
2 support may require resources (e.g., hardware/terminals or
source code) that are not available to the Computer Center staff.
Since the Computer Center is often completely unfamiliar with the
specific devices/terminals involved, the vendor may be the sole
source of vital information required for problem resolution or
circumvention. For this reason, the "Critical" designation for
PTRs is not applicable and will be disregarded by the Center.
Once a PTR and all supporting documentation is received by the
Computer Center, the work to get a resolution is a mutual effort
of the user, the Computer Center and the author or vendor for
products designated to receive Level 2 support. Since the
Computer Center must rely on the cooperation/interest of the
1vendor/developer of a product, it is possible that some problems
may never be resolved.
The effects of this reduced support from the Computer Center
should be thoroughly considered before incorporating any software
receiving Level 2 support into critical applications. It must be
stressed that the proper functioning or long-term availability of
software receiving Level 2 support cannot be guaranteed by the
Computer Center.
The following chart outlines Computer Center services available
for software receiving Level 2 support. For further information
on Levels of software and how to submit PTRs, see the appropriate
section of the Computer Center Users Guide. If questions remain
on this policy, contact the PAL Unit Consulting Desk of the NIH
Computer Center.
SERVICE LEVEL 2 SOFTWARE SUPPORT
CONSULTING (PAL DESK)
a) personal visit No
b) telephone No
(Users will have to rely
on technical documentation
provided by the Computer
Center and their own
resources)
PROGRAMMER TROUBLE REPORT (PTR) Yes
"CRITICAL" PTR DESIGNATION No
REFUNDS Yes
DOCUMENTATION Yes
TRAINING Resources
permitting
SOFTWARE MAINTENANCE
a) Currency maintained with respect Resources
to new versions and facilities permitting
b) Formal change testing (Test Job No
Stream)
c) Informal change testing Yes
d) Guarantee of orderly, fully No
documented conversion if product
is discontinued
e) Preannouncement in INTERFACE of Resources
all new facilities permitting
f) Preannouncement in INTERFACE of Resources
changes which cause old versions permitting
of programs to function
incorrectly or differently
g) Preannouncement in INTERFACE of Yes
discontinuance of support or changes
in support status (Level)
h) Preventive and corrective fixing Resources
by Computer Center staff permitting
1
Table of Contents
I. Introduction . . . . . . . . . . . . . . . . . . . . . . 1
II. The ALP Language . . . . . . . . . . . . . . . . . . . . 3
Input format . . . . . . . . . . . . . . . . . . . . . 3
Comment convention . . . . . . . . . . . . . . . . . . 3
Statement differentiation . . . . . . . . . . . . . . . 4
Compound statements . . . . . . . . . . . . . . . . . . 5
Predicates . . . . . . . . . . . . . . . . . . . . . . 6
III. ALP Statements . . . . . . . . . . . . . . . . . . . . . 8
Conditional and alternative statements (IF). . . . . . 8
Loop statements (DO). . . . . . . . . . . . . . . . . . 9
Case selection (CASE). . . . . . . . . . . . . . . . . 14
Predicate selection (SELECT). . . . . . . . . . . . . . 16
Loop control mechanisms (EXIT and NEXT) . . . . . . . . 18
Branching (GOTO and RGOTO). . . . . . . . . . . . . . . 20
Control of base register assignment (USE) . . . . . . . 21
Inline data (DATA) . . . . . . . . . . . . . . . . . . 22
Conditional assembly (ASM) . . . . . . . . . . . . . . 23
Including ALP code in macros (MACRO) . . . . . . . . . 26
Reversion to BAL (BAL) . . . . . . . . . . . . . . . . 28
Block Comments (COMMENT). . . . . . . . . . . . . . . . 29
Listing format control (TITLE,SUBTITLE,EJECT,SPACE) . . 30
IV. Non-Control Extensions . . . . . . . . . . . . . . . . . 32
V. The Implementation of ALP . . . . . . . . . . . . . . . 34
VI. ALP Syntax . . . . . . . . . . . . . . . . . . . . . . . 35
VII. ALP Readability Macros . . . . . . . . . . . . . . . . . 39
VIII. Macros for Environment Enhancement . . . . . . . . . . . 41
AREA and AREAEND . . . . . . . . . . . . . . . . . . . . 42
DEBLANK . . . . . . . . . . . . . . . . . . . . . . . . 45
EDIT . . . . . . . . . . . . . . . . . . . . . . . . . . 47
EXI . . . . . . . . . . . . . . . . . . . . . . . . . . 49
MCLC, MMVC, MNC, MOC and MXC . . . . . . . . . . . . . . 51
MFC . . . . . . . . . . . . . . . . . . . . . . . . . . 52
MTC . . . . . . . . . . . . . . . . . . . . . . . . . . 53
MTR . . . . . . . . . . . . . . . . . . . . . . . . . . 54
MTRT . . . . . . . . . . . . . . . . . . . . . . . . . . 55
MZC . . . . . . . . . . . . . . . . . . . . . . . . . . 56
DF . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
SF . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
TF . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
ZF . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
1
OSCALL . . . . . . . . . . . . . . . . . . . . . . . . . 61
OSENTER . . . . . . . . . . . . . . . . . . . . . . . . 62
OSEXIT . . . . . . . . . . . . . . . . . . . . . . . . . 63
OSSETUP . . . . . . . . . . . . . . . . . . . . . . . . 64
OPENP . . . . . . . . . . . . . . . . . . . . . . . . . 66
CBDELINK . . . . . . . . . . . . . . . . . . . . . . . . 67
CBDLINKH . . . . . . . . . . . . . . . . . . . . . . . . 69
CBDLINKT . . . . . . . . . . . . . . . . . . . . . . . . 70
CBLINK . . . . . . . . . . . . . . . . . . . . . . . . . 72
CBLINKH . . . . . . . . . . . . . . . . . . . . . . . . 73
CBLINKT . . . . . . . . . . . . . . . . . . . . . . . . 74
IX. ALP Coding Hints . . . . . . . . . . . . . . . . . . . . 75
X. Sample Program . . . . . . . . . . . . . . . . . . . . . 76
XI. Using ALP at NIH . . . . . . . . . . . . . . . . . . . . 80
XII. References . . . . . . . . . . . . . . . . . . . . . . . 82
1 - 1 -
I. INTRODUCTION
The choice of the proper vehicle -- assembly language or
higher-level language -- for writing so-called "systems programs"
is a subject of constant debate (1,2). With a few notable
exceptions (3,4), the trend has been toward continued use of
assembly languages, generally those provided by vendors of
computer systems. Fortunately, the field is now well enough
explored that most assemblers are relatively powerful,
incorporating macro or preprocessor facilities such as symbolic
substitution, conditional assembly, etc. Given the architecture
of most currently-available hardware and the orientation of
assemblers toward that hardware, very little has been done to
provide sophisticated control or data structures. Considering
that until fairly recently this was also the case even for
compiler-level languages, perhaps it is not too surprising.
For better or worse, systems being implemented at the
assembly language level have -- inevitably -- grown in size and
complexity. This is one of the major factors (along with the
desire to work in terms closer to the nature of the application
being developed) that led to the evolution of higher-level
languages. It has also fostered the investigation of more
powerful tools for building systems whose implementation is
constrained, for one reason or another, to the use of assembly
language. The various approaches taken have included more
powerful macro facilities, compilers for languages which can be
straightforwardly and efficiently translated (some into object
code, others into assembly source), highly-optimized compilers
which attempt to relieve the concerns about staying close to the
underlying hardware, and preprocessors which provide capabilities
similar to those available with macro systems but with increased
flexibility. It is a tool of this last type which will be
described below.
Our search for a means of making assembly language
programming easier began in the first place because we were faced
with a large project which we had already decided would be done
in assembly language. This was due to the environment in which
the end result would operate, efficiency considerations, and the
lack of any reasonable alternative, as well as experience with
previous versions of the system. It was obvious, though, that
features not provided by the available assemblers would greatly
improve both the speed with which the project could proceed and
its eventual maintenance and enhancement. The most realistic
goal was to provide better control structures, perhaps assembly
language's most serious deficiency. In addition, we sought to
improve the overall reliability of the new system by minimizing
the chances of certain types of coding and logic errors which are
encouraged by the scarcity of good control structures and the
consequent requirement for explicit branching, labels, etc.
Hence some form of "structured" programming technique seemed to
be indicated.
1 - 2 -
For reasons of practicality, we preferred to use something
already developed and in use. A preprocessor (AL) which provided
many of the features we were looking for had been developed by
Edward C. Haines at MITRE, and we decided to use that as a base
(portions of this document are taken from the original reference
(5)). The salient features of AL were that it provided:
. "predicates" for condition testing
. an "IF ... THEN ... ELSE ..." structure
. "WHILE ... DO ..." and "DO ... UNTIL ..."
. a "COUNT" statement for iterative loops
. a conditional branching capability
in addition, it allowed:
. free-form input, with label and statement delimiters
. comments
. transparent use of regular assembly language
After acquiring the source for AL and examining it, we made
a number of enhancements. These include:
. extension of predicates to allow grouping
. generalization of the loop control structures into
.. DO-WHILE / WHILE-DO
.. DO-UNTIL / UNTIL-DO
.. DO-FOR / FOR-DO (replacing AL's "COUNT")
.. DO-FOREVER / FOREVER-DO (replacing AL's "LOOP")
. addition of CASE and SELECT statements
. generalization of explicit branching to allow
.. GOTO (replacing AL's "BIF")
.. RGOTO (for register form of branch)
. improved loop controls
.. EXIT
.. NEXT
. local control of base register assignment for DSECTs
through USE
. access to conditional assembly facilities through the
ASM statements
. support for ALP code in macros through the MACRO statement
. substitution of '<'/'>' and 'BEGIN'/'END' for AL's use of
parentheses as compound statement delimiters
. recording of nesting level and display on listing
. automatic indentation according to nesting level
. provision for title and subtitle control as well as eject
and space
. allowance for presence of macro variables (i.e. those
beginning with "&") in operand fields
. acceptance of macro and sequence symbols as labels
. limited optimization of internally-generated branches
Fortunately, AL proved to be a reasonable basis for
expansion. Our task would have been far greater had we been
forced to start from scratch.
1 - 3 -
II. THE ALP LANGUAGE
Following sections will describe each ALP statement in some
detail. A syntax description in augmented BNF is contained in
section VI.
INPUT FORMAT
+____________
ALP resembles PL/I in some respects. Programs are composed
of statements, separated by semi-colons (';'). Source code may
be entered in free form in columns 1-72 (columns 73-80 should
contain some sort of sequence information). The program must be
terminated with an "END" statement (i.e. "END;"). Labels are
delimited by a colon (':'), and multiple labels may appear on a
single statement. Otherwise, labels obey assembler conventions.
That is, they must be one to eight characters in length, consist
of 'A'-'Z', '0'-'9', '$', '@', or '#', and begin with 'A'-'Z',
'$', '@', or '#'.
In order to allow for sequence symbols, set symbols, and
labels into which macro variables are to be substituted, '.',
'&', '(', and ')' are also allowed. Ampersands should be doubled
in order to prevent confusion with the AND operator.
Examples:
program:
S1; S2; S3; END;
labeling:
LABEL: S;
L1: L2: S;
.SEQ: AGO .SEQ2;
&&CHAR: SETC 'ABC';
X&&Y(2)Z: DC H'0';
COMMENT CONVENTION
+__________________
Like PL/I, ALP allows comments wherever a blank is legal.
However, the delimiting mechanism is quite different. ALP
comments begin with a percent sign ('%') and are terminated by
the end of the input line.
Examples:
LA R1,2; % THIS IS A COMMENT
Block comments are also supported, see section III.
1 - 4 -
STATEMENT DIFFERENTIATION
+_________________________
There are two types of ALP statements, which, unless stated
otherwise will be treated equivalently in the rest of this
document. The first type consists of those beginning with
keywords meaningful to ALP, which it processes. The second
consists of those which ALP does not recognize and passes on to
the assembler on the assumption that they are BAL statements or
macro calls.
In the latter type, the usual assembler conventions about
operand fields apply, with three changes:
1. Comments must be entered as described above -- a blank
signals only the end of the field, not the start of comments
as well.
2. If an ampersand ('&') is to appear in an operand other than
inside a quoted string, it must be doubled to distinguish it
from ALP's predicate conjunction operator (see below). For
example:
LA REG,&&CON;
LA REG,=C'&STRING';
3. Since ALP input is free form, the only place special
continuation is required is when operand fields must be
split across line boundaries. In such cases, end the first
part of the field with an underscore -- it will be continued
with the next non-blank character (ignoring any intervening
comments) and the underscore will be discarded. If a quoted
string must be broken, end the first part with a
quote-underscore pair and continue with a quote on the next
line. The underscore, any intervening blanks, and the two
extra quotes will be discarded. For example:
TPUT MESSAGE,_
LENGTH;
and
DC C'THIS IS A LONG CONSTANT '_
'WHICH WILL BE CONTINUED';
1 - 5 -
COMPOUND STATEMENTS
+___________________
Simple statements may be combined into compound statements
by enclosing them in angle brackets ("<" and ">") or
"BEGIN"-"END" symbols and separating them with semicolons.
Examples:
<S1; S2; S3>
BEGIN
S1;
S2;
S3;
END
Spacing is irrelevant, except that there must be a delimiter
(such as a blank) following the "BEGIN" and preceding the "END".
Also, there is no semicolon required preceding the "END" or ">".
However, a semicolon must follow a compound statement wherever
one is required after a simple statement.
Although "BEGIN"-"END" and "<"-">" are generally inter-
changeable, special consideration must be taken in two cases:
1) An "END" bracket must never be labeled. An acceptable
equivalent is a labeled null statement preceding the
terminating bracket. For example:
BEGIN
statement;
statement;
label: ;
END
2) If the final statement in a group of statements to be
bracketed has no operands, a semicolon must precede the
terminating "END" or the "<"/">" form must be used to prevent
the "END" from being mistaken for an operand on the statement.
1 - 6 -
PREDICATES
+__________
The concept necessary for most control structures is that
of predicate. A predicate is a sequence of statements that
produces a truth value. On the System/370, testing of truth
conditions is accomplished by setting a condition code (with
an instruction such as a comparison) and then conditionally
branching on the status of the condition code. The
instructions that set the condition code are sometimes, but not
often, what people logically want to think of as the
predicate. The execution of conditional branches is almost
always not what people want to think about (cf Dijkstra(6)).
In ALP, a simple predicate is a sequence of instructions
(possibly empty) that defines a condition code setting. A
predicate is then a Boolean combination of simple predicates
involving the operators '&' ("AND"), '|' ("OR"), and '^' ("NOT").
The conditional branches (and unconditional branches where
necessary) are implied by the control statements. The programmer
is, for the most part, freed from worrying about what condition
code value(s) will be set and how to test them.
*****************************************************************
A number of macros have been provided to improve the
readability of ALP programs and to provide additional information
for ALP's use in determining condition tests, etc. They will be
used freely in the examples that follow: see sections VII and
VIII for complete information. Note that use of these macros is
not required.
*****************************************************************
Examples:
simple predicate:
<CLI BUFFER,C'*'>
<L R15,RETCODE; RZ R15>
predicate:
^<CLI BUFFER,C' '>
<CLC WORD,=C'ERROR'> & <RNP R15> | <TM EBITS,X'80'>
<<CLC WORD,=C'ERROR'> & <RNP R15>> | <TM EBITS,X'80'>
Grouping is such that a&b|c&d is interpreted as a&(b|(c&d));
there is no operator precedence, but grouping of predicates in
angle brackets is allowed. IF, DO, etc. should not be used
within a predicate because they introduce uncertainty in the
condition actually being tested. The way in which predicates are
evaluated does not always insure that all instructions in the
predicate are executed. Thus, care should be taken that
processing does not depend on the execution of all instructions
in a predicate involving Boolean combinations of simple
predicates.
1 - 7 -
The appropriate condition code test is determined from the
op-code of the last statement of the predicate; if the name is
not recognized, the default is '=' (equal, or zero). The test
can be explicitly specified by using a special statement of the
form:
CC ccstring
where ccstring is composed of characters from the set
0 = E Z 1 L M 2 P H 3 O N ^
These are used as in the form of the extended mnemonics of
the assembler except that they specify the "truth" condition (as
opposed to the branch condition) and any combination of
characters is allowed.
Since equality is the appropriate truth condition for most
predicates, only non-standard cases are coded into the
preprocessor. These are: OPENP (NZ), TF (NZ), TM (NZ), TS (NZ),
TRT (NZ), RM (M), RZ (Z), RP (P), RMZ (NP), RMP (NZ), RZP (NM),
RNM (NM), RNZ (NZ), RNP (NP), RNMZ (P), RNMP (Z), RNZP (M).
1 - 8 -
III. ALP STATEMENTS
CONDITIONAL AND ALTERNATIVE STATEMENTS
+______________________________________
Conditional and alternative statements are provided by the
IF-THEN-ELSE statement. Its format is:
IF predicate THEN statement ELSE statement
where the "ELSE" clause is optional.
Examples:
IF <LH R2,0(R1); RP R2> THEN STH R2,BLKSIZE;
at assembly time would appear (subject to label differences) as:
LH R2,0(R1)
LTR R2,R2
BNP @0001
STH R2,BLKSIZE
@0001 ----
IF <L R2,0(,R3); RZ R2>
THEN LA R3,1
ELSE LA R3,2;
would generate:
L R2,0(R3)
LTR R2,R2
BNZ @0001
LA R3,1
B @0002
@0001 LA R3,2
@0002 ----
NOTE: If a simple statement without operands (such as an
operand-less machine op-code or macro call) comprises the
predicate or the "THEN" clause in an "IF ... THEN ... ELSE"
construct, it must be enclosed in '<'/'>' bracketing symbols to
prevent the following keyword ('THEN' or 'ELSE') from being
interpreted as an operand of the statement.
*****************************************************************
Note that ALP-generated labels begin with a commercial "at-sign"
('@'). Labels generated outside macro definitions will consist
of an at-sign followed by a four-digit decimal integer (e.g.
@0001). Labels generated inside a macro (see the discussion of
support for ALP code in macros) will involve a special symbol so
that multiple invocations of the macro will not generate
duplicate labels (e.g. @&@001).
*****************************************************************
1 - 9 -
LOOP STATEMENTS
+_______________
There are four sets of loop-producing statements:
. DO-WHILE and WHILE-DO
. DO-UNTIL and UNTIL-DO
. DO-FOR and FOR-DO
. DO-FOREVER and FOREVER-DO
The two forms differ in the position of the test which
terminates the loop: whether it comes after (as in the first
form) or before (as in the second) the body of the loop. The
format of the first set is:
WHILE predicate DO statement
or
DO statement WHILE predicate
Examples:
WHILE ^<CR R3,R11> DO <MVI 0(R3),C' '; AI R3,1>;
generates:
@0001 CR R3,11
BE @0002
MVI 0(R3),C' '
LA R3,1(,R3)
B @0001
@0002 ----
DO <MVI 0(R3),C' '; AI R3,1> WHILE ^<CR R3,R11>;
generates:
@0001 MVI 0(R3),C' '
LA R3,1(,R3)
CR R3,R11
BNE @0001
1 - 10 -
The DO-UNTIL set is similar to the DO-WHILE set except that
the "sign" of the test is reversed. Its format is:
DO statement UNTIL predicate
or
UNTIL predicate DO statement
Examples:
DO <LR R1,R2; L R2,0(,R1); LA R2,0(,R2)>
UNTIL <C ADR,EADR(R2); CC H>;
translates to:
@0001 LR R1,R2
L R2,0(,R1)
LA R2,0(,R2)
C ADR,EADR(R2)
BNH @0001
@0002 ----
UNTIL <C ADR,EADR(R2); CC H>
DO <LR R1,R2; L R2,0(,R1); LA R2,0(,R2)>;
generates:
@0001 C ADR,EADR(R2)
BH @0002
LR R1,R2
L R2,0(,R1)
LA R2,0(,R2)
B @0001
@0002 ----
1 - 11 -
A simple loop counting mechanism is provided by the DO-FOR
set. The number of times the loop is to be executed is
determined by the value of a specified register (set by a
previous statement) on entry to the loop. The register is
decremented once per cycle until it is zero. The format is:
DO statement FOR register
or
FOR register DO statement
Examples:
DO <IC R1,0(R11); BAL R9,PCHAR; AI R11,1> FOR R12;
translates to:
@0001 IC R1,0(R11)
BAL R9,PCHAR
LA R11,1(,R11)
BCT R12,@0001
FOR R12 DO <IC R1,0(R11) ; BAL R9,PCHAR; AI R11,1>;
generates:
LTR R12,R12
BNP @0002
@0001 IC R1,0(R11)
BAL R9,PCHAR
LA R11,1(,R11)
BCT R12,@0001
@0002 ----
1 - 12 -
The last of the loop control structures are also the
simplest: a "do-once" structure and an infinite loop, with
responsibility for escaping from it placed on the programmer.
The format of the "do-once" is:
DO statement
This form is useful where the statement is a compound one
containing EXIT statements (described in a later section), which
permit escape from the compound statement. Similarly, a NEXT
statement (see below) occurring in such a compound statement will
cause control to be transfered to the start of the statement.
The format of the infinite loop is:
DO statement FOREVER
or
FOREVER DO statement
Examples:
DO <AI R2,1> FOREVER;
and
FOREVER DO <AI R2,1>
both translate to:
@0001 LA R2,1(,R2)
B @0001
1 - 13 -
The WHILE-DO/DO-WHILE, UNTIL-DO/DO-UNTIL, and FOR-DO/DO-FOR
constructs, as well as the "do-once" form, may also be followed
by an optional "THEN statement". This allows the specification
of action to be taken if and only if control "falls through" the
DO (e.g. when the register specified in a FOR-DO construct
becomes zero), but not if control is transfered via an EXIT
statement. FOREVER-DO/DO-FOREVER cannot take a THEN clause.
Example:
DO BEGIN
...
EXIT;
...
END
THEN BEGIN
...
END;
NOTE: Introduction of THEN as part of the DO construct requires
care in the nesting of statements under certain circumstances.
Nesting of DO's within DO's can cause confusion of THEN's in the
same way that nesting of IF's can cause confusion of ELSE's. In
either case bracketing symbols must be used to prevent attaching
the dependent clause to the inner statement instead of the outer.
1 - 14 -
CASE SELECTION
+______________
The CASE statement permits the selection of an action
designated by the value of a register. Its format is:
CASE register MAX expression MIN expression;
case-label: statement;
...
ENDCASE
The case to be executed is designated by the contents of the
specified register. This index must be a multiple of four
greater than or equal to zero and be contained in a register
other than register zero. A maximum value (used to generate a
branch table, but not checked at execution time) is required, and
may be any valid previously defined assembler expression which
evaluates to a multiple of four greater than the minimum value.
A minimum value (also used to generate the branch table) is
optional, has a default value of 0, and may be any valid
previously defined assembler expression. The case to be executed
is designated by the value of the "case-label" assigned to it.
Each such label consists of an assembler expression, two
expressions separated by the keyword "THRU", or a series of these
two types separated by commas. As shown above, the case label is
separated from the statement making up the case by a colon. If
duplicate or overlapping case labels are specified, the last one
takes precedence. This allows a default action to be defined
which will take effect if a case is specified for which a
statement was not otherwise provided. If a default action is not
provided, a program check (invalid op-code) will occur if a case
is specified for which no statement was entered.
Example:
CASE R15 MAX 16;
0: ;
4,16: LA R15,4;
8 THRU 12: LA R15,8;
ENDCASE;
translates to:
B @0001(R15)
@0001 B @0002
B @0003
B @0004
B @0004
B @0003
@0003 LA R15,4
B @0002
@0004 LA R15,8
@0002 ----
1 - 15 -
The CHECK option may be used in a CASE statement to specify
that the minimum and maximum values are to be checked. An ELSE
clause may be added after the ENDCASE to specify the action to be
taken for an out of bounds value. If no ELSE clause is used, an
operation exception will occur for an invalid value.
Example:
CASE R15 MAX 16 MIN 4 CHECK;
4,16: LA R15,4;
8 THRU 12: LA R15,8;
ENDCASE
ELSE ABEND 1234,DUMP;
translates to:
C R15,=A(4)
BL @0004
C R15,=A(16)
BH @0004
B @0001-4(R15)
@0001 B @0002
B @0003
B @0003
B @0002
@0002 LA R15,4
B @0005
@0003 LA R15,8
B @0005
@0004 ABEND 1234,DUMP
@0005 ----
The CASE statement may also have a THEN clause which
functions in the same manner as for the DO statement. The THEN
clause must follow an ELSE clause, if present.
1 - 16 -
PREDICATE SELECTION
+___________________
The SELECT statement is analogous to the CASE statement in
that it allows the selection of an action designated by the
validity of a specified condition. In the CASE statement this
condition is the equality of the specified register to a value
given in the "case-label". In the SELECT statement the condition
is the truth of one or more predicates which take the place of
CASE "case-label"s. The format is:
SELECT;
predicate: statement;
...
ENDSEL
Execution of the statement is as follows: each predicate is
evaluated in turn and, if true, its associated statement is
executed. The sequential nature of this process means that the
execution of a selected statement can influence the truth of a
predicate forming the selection-label on a later statement. For
example:
LI R1,1;
SELECT;
<C R1,=F'1'>: <LI R1,2>;
<C R1,=F'2'>: <LI R1,3>;
ENDSEL;
As in the previous example, multiple elements of the selection
list may be executed in turn. The SELECT FIRST form of the
construct specifies that only the first statement for whose
predicate is true will be executed, and no others "below" it --
regardless of the fact that their predicates may also be true.
Applying this option to the example above:
LI R1,1;
SELECT FIRST;
<C R1,=F'1'>: <LI R1,2>;
<C R1,=F'2'>: <LI R1,3>;
ENDSEL;
In this case, only the first selected case ("LI R1,2") would be
executed, since no other predicates would be tested.
1 - 17 -
An additional option, applicable to SELECT FIRST form only,
allows specification of an action to be performed if no predicate
in the selection-list is true. Its form is as follows:
SELECT FIRST;
predicate: statement;
...
ENDSEL
ELSE statement
Example:
LI R1,0;
SELECT FIRST;
<C R1,=F'1'>: <LI R1,2>;
<C R1,=F'2'>: <LI R1,3>;
ENDSEL
ELSE LI R1,4;
A THEN clause may also be appended to a SELECT statement.
The statement following THEN is executed if control "falls
through" to the end of the statement but not if an EXIT statement
is used. For example;
SELECT FIRST;
<C R1,=F'1'>: <LI R1,2>;
<C R1,=F'2'>: <LI R1,3>;
ENDSEL
ELSE LI R1,4
THEN MH R1,=H'10000';
NOTE: Although the effect of the SELECT FIRST ... ELSE is
easily obtained with IF-THEN-ELSEs, the SELECT construct is
generally more readable, and may clarify the processing being
carried out.
1 - 18 -
LOOP CONTROL MECHANISMS
+_______________________
In order to reduce the necessity for coding explicit
branches, ALP provides ways to escape from and reenter a control
structure. The first is the EXIT statement, whose complete form
is:
EXIT FROM label IF predicate
where the "FROM label" and "IF predicate" clauses are optional.
Examples:
EXIT;
EXIT FROM BLOCK1;
EXIT IF <RP 15>;
EXIT FROM BLOCK1 IF <RP 15>;
NOTE: If both are specified, the FROM clause must precede the IF
clause.
When used inside a loop construct (DO-WHILE, etc.), EXIT
causes control to be transfered to the first instruction
following the loop (bypassing any THEN clause). The EXIT
statement may also be used inside a CASE or SELECT statement to
terminate execution of the case.
An EXIT without a FROM clause causes a transfer of control
to the first instruction immediately following the construct
containing the EXIT. An EXIT followed by a FROM clause causes a
transfer of control to the first instruction following the
construct whose label is specified in the FROM clause. Both
forms may be modified by the IF clause to provide both
conditional and unconditional EXITs.
Examples: (target labels are shown only for reference)
BLOCK1: DO BEGIN
...
BLOCK2: DO BEGIN
...
EXIT; % TO TARGET1
...
EXIT FROM BLOCK1; % TO TARGET2
...
END;
TARGET1: ...
...
END;
TARGET2: ...
FOREVER DO BEGIN
LA R2,1(,R2);
EXIT IF <CR R2,R3>;
MVI 0(R2),C'*';
END;
1 - 19 -
In an analogous manner, the NEXT statement,
NEXT OF label IF predicate
causes transfer of control, conditionally or unconditionally, to
the point at which the next iteration of the construct named by
"label" begins (e.g. to the "BCT" in a "FOR" structure). If no
OF clause is specified, the next iteration of the innermost loop
is begun. In a CASE or SELECT statement, a NEXT causes a
transfer of control back to the point of case selection.
Examples:
WHILE <L R2,0(,R2); CR R2,R3; CC NE>
DO <NEXT IF RZ R5; AI R4,1>;
CASE R15 MAX 8;
0: ;
4: <NEXT IF LTR R3,R3; CALL ERROR>;
8: CALL ERROR2;
ENDCASE;
SELECT;
<C R2,=F'1'>: <LI R2,2; NEXT>;
<C R2,=F'2'>: <AI R2,1>;
ENDSEL;
BLOCK1: DO BEGIN
BLOCK2: DO BEGIN
...
NEXT; % NEXT ITERATION OF BLOCK2
...
NEXT OF BLOCK1; % NEXT ITERATION OF BLOCK1
...
END WHILE <CR R2,R3>;
END WHILE <RP R1>;
NOTE: If an EXIT or NEXT statement occurs in the THEN clause of
a DO, CASE or SELECT statement, it applies to the containing
statement.
NOTE: It is possible to code statements like:
IF predicate THEN EXIT;
However, this causes less efficient code to be generated than if
the EXIT statement had been used in the form
EXIT IF predicate;
Hence the latter form is recommended. This is equally true for
the NEXT statement.
1 - 20 -
BRANCHING
+_________
The final control statement, an admission of our failure to
write completely structured programs, is an explicit branch. Its
format is:
GOTO label IF predicate
A branch-register form is also available:
RGOTO register IF predicate
where the "IF" clauses in both forms are optional.
Examples:
GOTO X;
translates to:
B X
RGOTO REG;
generates:
BR REG
GOTO X2 IF <TM 0(R1),X'40'>;
generates:
TM 0(R1),X'40'
BNZ X2
RGOTO REG2 IF <SI R3,1; RZ R3>;
generates:
BCTR R3,0
LTR R3,R3
BZR REG2
NOTE: "GOTO/RGOTO ... IF ..." generates more efficient code
than "IF ... THEN GOTO/RGOTO ...", and is therefore preferable
(even though the latter may be easier to think of).
1 - 21 -
CONTROL OF BASE REGISTER ASSIGNMENT FOR DSECTS
+______________________________________________
Control of base register assignment for DSECTs through USING
and DROP assembler statements, while not difficult, is frequently
not easy to relate to the processing being performed. ALP's USE
statement allows explicit use of a data structure for the
duration of a single statement -- simple or compound -- and
automatically provides the appropriate USING and DROP directives.
Its format is:
USE register AS dsect-name IN statement
Example:
USE R12 AS MSGBLK IN L R11,MSGLEN;
translates to:
USING MSGBLK,R12
L R11,MSGLEN
DROP R12
Multiple "register AS dsect-name" units may be specified,
using commas as separators.
Example:
USE R1 AS PARMBLK1, R2 AS PARMBLK2 IN BEGIN
L R3,PARM1;
L R4,PARM2
END;
generates:
USING PARMBLK1,R1
USING PARMBLK2,R2
L R3,PARM1
L R4,PARM2
DROP R1,R2
1 - 22 -
INLINE DATA
+___________
The DATA statement may be used to branch around data values
which are included with executable code for purposes of clarity.
The general form is
DATA statement
Examples:
DATA CON: DC F'99'
translates to
B @0001
CON DC F'99'
@0001 ...
DATA BEGIN
CONS:
DC F'99';
DC F'999';
END
translates to
B @0001
CONS DC F'99'
DC F'999'
@0001 ...
1 - 23 -
CONDITIONAL ASSEMBLY
+____________________
While it is, of course, possible to use the assembler's
conditional assembly facilities in a straightforward way, it is
often more convenient to have ALP generate the necessary sequence
symbols, take care of isolation of labels generated within
conditional assembly blocks, and so on. The ASM statements
provide these capabilities. The most often used ASM statement is
the ASM IF:
ASM IF (condition) THEN statement ELSE statement
where the "ELSE" clause is optional.
Examples:
ASM IF ('&TYPE' EQ 'EMPTY') THEN statement;
translates to:
AIF (NOT ('&TYPE' EQ 'EMPTY')).@0001
statement
.@0001 ANOP
ASM IF (&&V EQ &&X) THEN statement1 ELSE statement2;
generates:
AIF (NOT (&V EQ &X)).@0001
statement1
AGO .@0002
.@0001 ANOP
statement2
.@0002 ANOP
NOTE: If "statement1" in the "... THEN ... ELSE ..." form is a
simple statement without operands (e.g. a macro call without
operands, an assembler op-code without operands, etc.) then it
should be bracketed with '<'/'>' symbols to prevent the 'ELSE'
from being interpreted as an operand of the statement.
1 - 24 -
Most other ALP statements are available in the ASM form in an
analogous way.
. ASM WHILE (condition) DO statement THEN statement
. ASM UNTIL (condition) DO statement THEN statement
. ASM DO statement WHILE (condition) THEN statement
. ASM DO statement UNTIL (condition) THEN statement
. ASM DO statement THEN statement
. ASM FOREVER DO statement
. ASM DO statement FOREVER
. ASM CASE set-expression;
case-list: statement;
...
ENDCASE
THEN statement
. ASM CASE set-expression;
case-list: statement;
...
ENDCASE
ELSE statement
THEN statement
. ASM SELECT;
(condition): statement;
...
ENDSEL
THEN statement
. ASM SELECT FIRST;
(condition): statement;
...
ENDSEL
THEN statement
. ASM SELECT FIRST;
(condition): statement;
...
ENDSEL
ELSE statement
THEN statement
. ASM FOR seta-variable FROM seta-expression BY seta-expression
TO seta-expression DO statement THEN statement
. ASM DO statement FOR seta-variable BY seta-expression
TO seta-expression THEN statement
. ASM EXIT
. ASM EXIT FROM sequence-symbol
. ASM EXIT IF (condition)
. ASM EXIT FROM sequence-symbol IF (condition)
. ASM NEXT
. ASM NEXT OF sequence-symbol
. ASM NEXT IF (condition)
. ASM NEXT OF sequence-symbol IF (condition)
. ASM GOTO sequence-symbol
. ASM GOTO sequence-symbol IF (condition)
1 - 25 -
Notable points are
. "condition" represents a valid SETB expression.
. the THEN clause is optional with all statements except ASM IF.
. FROM, BY and TO are provided with ASM FOR to define the limits
of the loop. The defaults are 1, 1 and infinity, respectively.
If negative numbers are used, they must be written as
"0-number", in honor of the assembler restriction on unary
operators. FROM is not valid with ASM DO FOR.
. The selection value in the ASM CASE statement may also be a
SETC expression in quotes. If this is done, the case
identifiers must also be SETC expressions in quotes.
. MAX and MIN are not used with ASM CASE.
. There is no ASM RGOTO statement.
. ASM IF may also be written as ASMIF for compatability with
earlier versions.
1 - 26 -
INCLUDING ALP CODE IN MACROS
+____________________________
Although macros are frequently used for describing data
structures or for small common code segments containing little or
no control structure, this is not always the case. In such
instances it is desirable to write them in ALP in order to
continue to maintain consistency and preserve the goals of using
a structured language. ALP's MACRO statement allows the
definition of assembler macros which may contain ALP constructs.
Its format is:
MACRO macro-label: macro-name macro-operands;
GBLx and LCLx declarations
macro-body
MEND
where:
macro-label is the (optional) label to be placed on
the first statement of the macro, and is of the form
&&identifier
macro-name is the name of the macro
macro-operands is an (optional) operand field which
names the symbolic operands of the macro, in the form
&&identifier,&&identifier,...
Example:
MACRO &&LABEL: ZAP &&P1,&&P2;
GBLA &&X;
COPY NAMES;
&&LABEL: IF <RP &&P1> THEN <ZR &&P1>
ELSE <LCR &&P2,&&P1>;
MEND;
generates
MACRO
&LABEL ZAP &P1,&P2
GBLA &X
COPY NAMES
LCLC &@
&@ SETC '&SYSNDX'
&LABEL LTR &P1,&P1
BNP @&@001
SR &P1,&P1
B @&@002
@&@001 LCR &P2,&P1
@&@002 ...
NOTE: The doubling of ampersands ('&') is necessary, as
described in section II, to prevent confusion with the predicate
operator "AND".
1 - 27 -
All GBLx and LCLx declarations and any COPY statements which
copy in such statements must be grouped immediately after the
MACRO header. This is because a local set symbol must be defined
so that ALP-generated labels do not result in duplicate labels if
a macro is invoked more than once. Assembler restrictions
require that all set symbol declarations precede other
statements, and ALP picks the point at which to define its own
set symbol by detecting the first statement which is not a GBLx,
LCLx, or COPY. Another consequence of this is that a COPY which
copies in executable code MUST be preceded by a dummy statement
of some sort to prevent premature generation of the ALP local set
symbol. For example:
MACRO EXAMPLE;
GBLA &&X;
; % TO FOOL ALP
COPY CODE; % TO COPY IN EXECUTABLE CODE
MEND;
ALP may also be used to process macros to be stored in assembler
macro libraries. To facilitate this, ALP will pass through
unchanged any ./ control cards which occur in the input stream.
Thus, output from ALP may be passed directly to IEBUPDTE.
1 - 28 -
REVERSION TO BAL
+________________
While most assembler code can be written within the
framework of ALP, it may occasionally be necessary to revert to
BAL mode. The ALP statement "BAL;" will cause the preprocessor
to enter a transparency mode, in which card images are simply
copied from the input stream to the output stream. BAL mode is
terminated when "ALP;" appears as the first non-blank symbol on a
line. Any text beyond the "BAL;" on the same line is ignored.
The format of the statement is:
BAL;
bal-code
ALP;
Examples:
BAL;
MACRO
&L ADD &A,&B,&C
L 15,&A
A 15,&B
ST 15,&C
MEND
ALP;
BAL;
IF &L1,&L2
ALP;
1 - 29 -
BLOCK COMMENTS
+______________
The comment statement is an alternate way of including a
large block of comments in an ALP program. All lines following a
"COMMENT;" statement are ignored. Normal processing is resumed
when "ALP;" appears as the first non-blank character on a line.
The advantage of COMMENT over normal comments is that WYLBUR's
ALIGN and JUSTIFY commands may be used since there are no
extraneous characters on the comment lines.
Example:
COMMENT;
Normally a long-winded explanation of some part of the
program would appear here.
ALP;
1 - 30 -
LISTING FORMAT CONTROL
+______________________
Several conventions were adopted to allow control of the
SYSPRINT listings of both ALP and the assembler. These are as
follows:
. The indentation of each line is automatically adjusted to be 3
times the nesting level at the start of the line. The nesting
level is the number of unterminated BEGIN, <, CASE, SELECT and
MACRO statements.
. Blank lines are ignored by ALP, and may thus be used to format
input source. They are not passed on to the assembler, and
hence have no effect on its output.
. If ALP is being used in conjunction with the assembler, a
post-processor extracts location counter values from the
assembler listing and adds them to the ALP listing. In order
for this process to work properly, the input lines must be
sequence numbered in ascending order in columns 73 through 80.
Special care must be taken with COPY statements outside of
macros as they will disrupt the sequencing. Sequence fields of
all blanks or all zeroes are ignored. The IEBUPDTE statement
./ NUMBER NEW1=0,INCR=0 may be used to cause sequence numbers
of all zeroes to be placed in a COPY module.
. ALP provides limited support for the assembler directive SPACE.
The ALP listing is arbitrarily spaced up two lines, and the
SPACE and its operands (if any -- no checking for validity is
performed) are passed on to the assembler.
. ALP processes the EJECT assembler directive by causing a page
eject and passing the EJECT (and any operands -- no checking is
done) on to the assembler.
. ALP accepts the assembler directive TITLE. The operands are
stored for printing at the top of each page, and with the TITLE
op-code are passed on to the assembler. No validity checking
is performed, but there should be only one operand -- a quoted
string. If a label is present, it is also passed to the
assembler. Note that there is an assembler requirement that
only one such "deck name" be present in any assembly. The
default title is a standard ALP heading.
. ALP supports a SUBTITLE statement. The operands, which should
consist of a single quoted string, are stored for printing at
the top of each page immediately below the current title. The
SUBTITLE is converted to a TITLE directive and passed with its
operands to the assembler. The default subtitle is a blank
line.
. ./ (IEBUPDTE) control cards cause a page eject.
1 - 31 -
NOTE: SPACE, EJECT, TITLE, and SUBTITLE are all treated as
regular assembly language statements -- no special notice is
taken that they also influence formatting of the source listings.
Hence some care must be taken in their placement in the source.
For example,
IF predicate THEN BEGIN
statements
END
ELSE
EJECT;
BEGIN
statements
END;
will cause the EJECT to form the body of the ELSE clause and not
the desired BEGIN-END block. It is also not permissible to
separate CASE or SELECT components with format control
statements.
1 - 32 -
IV. NON-CONTROL EXTENSIONS
Some non-control extensions are provided by ALP in an attempt
to improve the conceptual environment in which one programs at
the assembly language level. There are several notions that are
fairly well established in the machine instruction set and the
basic assembly language. These include word, halfword, byte, and
register operations. A very important data type not directly
covered is the bit. Bit operations are adequately handled by
byte instructions, but what is missing is a clear identification
that one is dealing with bits. AL provided three 'extended
mnemonics', TB, SB, and ZB for test bit, set bit, and zero bit.
These allowed writing code as if the machine had instructions
with byte and bit addressing rather than having to think about
the appropriate mask to use with a particular kind of
instruction. However, there were several problems with this
approach, and we decided that the ability to use symbolic masks,
etc. was more important. Hence these macros appear in a
modified form or not at all.
A very important set of instructions in the 360/370 are the
byte string instructions. Unfortunately, the notion provided at
the BAL level is rather poor. One problem is that the length
field in the instruction is one less than the effective length.
Another problem is that the BAL format confuses the length field
with the base register field of the first operand. This latter
problem is solved by separating out the length field. AL
provided the MOVE instruction instead of MVC and the COMP
instruction instead of CLC; these names also emphasize the
importance and generality of these instructions rather than
confusing one with "logical character". Since ALP provides
extended macros for more than just MVC and CLC, we elected to use
mnemonics closer to the original ones. Note that these extended
facilities provide more than just modification of the format.
Certain other operations are clarified with appropriate
mnemonics. For example: ZR (for Zero Register), RP, RZ, etc.
for Register Plus, Zero, and so on (all generate an LTR but imply
different condition code tests), and ZI (for Zero Immediate -- an
NI with 255-bitvalue mask). Macros useful in ALP for
clarification purposes are listed below. Not all are actually
required (see the end of section II for those that are built into
the translator), but all have been found useful. Note that some
AL macros have been changed or replaced, and others (due to our
own preferences) discarded.
1 - 33 -
AI - Add Immediate
CI - Compare Immediate
CIL - Compare Immediate Logical
DI - Divide Immediate
LI - Load Immediate
LQS - Load Quoted String
LT - Load and Test
MI - Multiply Immediate
RM - Register Minus
RMP - Register Minus or Plus
RMZ - Register Minus or Zero
RNM - Register Not Minus
RNMP - Register Not Minus or Plus
RNMZ - Register Not Minus or Zero
RNP - Register Not Plus
RNZ - Register Not Zero
RNZP - Register Not Zero or Plus
RP - Register Plus
RZ - Register Zero
RZP - Register Zero or Plus
SI - Subtract Immediate
Z - Zero
ZB - Zero Byte
ZH - Zero Halfword
ZHB - Zero High Byte
ZHBR - Zero High Byte Register
ZI - Zero Immediate
ZR - Zero Register
EXI - Execute immediate
EDIT - Generate edit mask and ED/EDMK instruction
MCLC - Multiple Compare Logical Characters
MMVC - Multiple Move Characters
MNC - Multiple AND Characters
MOC - Multiple OR Characters
MXC - Multiple Exclusive-OR Characters
MFC - Multiple Fill Characters
MTR - Multiple Translate
MTRT - Multiple Translate and Test
MZC - Multiple Zero Characters
DF - Define Flags
SF - Set Flags
TF - Test Flags
ZF - Zero Flags
DEBLANK - Deblank a string
OPENP - Check for successful open
See sections VII and VIII for further information on
these macros.
1 - 34 -
V. THE IMPLEMENTATION OF ALP
ALP has been implemented as a preprocessor to the standard
OS/360 assembler, using macros within the assembler in some
instances to enhance readability. The preprocessor is written in
PL/I using recursive descent, and is approximately 3100 lines
long. The post-processor for extracting location counter values
is also written in PL/I and is approximately 365 lines long.
ALP, the assembler and the post-processor are usually
invoked in sequence by a small control program, allowing the two
tasks to be executed as one job step. Cataloged procedures (see
section XI) have been developed for using ALP.
1 - 35 -
VI. ALP SYNTAX
Notation
Non-terminal symbols are lower case identifiers (which may
include a "dash")
Terminal symbols are either upper case identifiers or special
symbols enclosed in quotation marks
-> means "is defined as"
| indicates alternatives
" " means must be entered as is
( ) indicates an optional occurrence (0 or 1 times)
( )* indicates multiple optional occurrences (0 or more times)
< > indicates a required selection of one of the enclosed
alternatives
< >* indicates a required selection of one or more of the
enclosed alternatives
Some non-terminals are left undefined. Their meaning should be
obvious from their names.
1 - 36 -
program -> statements ";" END ";"
statements -> statement (";" statement)*
statement -> (label ":")* <compound-statement | simple-statement>
compound-statement -> "<" statements ">"
| BEGIN statements END
simple-statement -> if | case | select | loop | goto | exit | next
| mapping | data | conditional-assembly | macro
| format-control | bal | cc | bal | comment
if -> IF predicate THEN statement (ELSE statement)
case -> CASE register-id (case-option)* ";"
case-list
ENDCASE
(ELSE statement)
(THEN statement)
case-option -> MAX expression
| MIN expression
| CHECK
case-list -> <case-label-list ":" statement ";">*
case-label-list -> case-label ("," case-label)*
case-label -> expression (THRU expression)
select -> SELECT (FIRST) ";"
selection-list
ENDSEL
(ELSE statement)
(THEN statement)
selection-list -> <predicate ":" statement ";">*
loop -> <WHILE | UNTIL> predicate DO statement (THEN statement)
| DO statement <WHILE | UNTIL> predicate (THEN statement)
| FOR register-id DO statement (THEN statement)
| DO statement FOR register-id (THEN statement)
| DO statement (THEN statement)
| FOREVER DO statement
| DO statement FOREVER
goto -> <GOTO | RGOTO> target (IF predicate)
exit -> EXIT (FROM label) (IF predicate)
1 - 37 -
next -> NEXT (OF label) (IF predicate)
mapping -> USE register AS dsect-id ("," register AS dsect-id)*
IN statement
data -> DATA statement
conditional-assembly -> asm-if | asm-case | asm-select | asm-loop
| asm-goto | asm-exit | asm-next
asm-if -> ASM IF setb-expression THEN statement (ELSE statement)
asm-case -> ASM CASE set-expression ";"
asm-case-list
ENDCASE
(ELSE statement)
(THEN statement)
asm-case-list -> <asm-case-label-list ":" statement ";">*
asm-case-label-list -> asm-case-label ("," asm-case-label)*
asm-case-label -> set-expression (THRU set-expression)
asm-select -> ASM SELECT (FIRST) ";"
asm-selection-list
ENDSEL
(ELSE statement)
(THEN statement)
asm-selection-list -> <setb-expression ":" statement";">*
asm-loop -> ASM <WHILE | UNTIL> setb-expression
DO statement (THEN statement)
| ASM DO statement <WHILE | UNTIL> setb-expression
(THEN statement)
| ASM FOR seta-variable (FROM seta-expression)
(BY seta-expression) (TO seta-expression)
DO statement (THEN statement)
| ASM DO statement FOR seta-variable (BY seta-expression)
(TO seta-expression) (THEN statement)
| ASM DO statement (THEN statement)
| ASM FOREVER DO statement
| ASM DO statement FOREVER
asm-goto -> ASM GOTO sequence-symbol (IF setb-expression)
asm-exit -> ASM EXIT (FROM sequence-symbol) (IF setb-expression)
asm-next -> ASM NEXT (OF sequence-symbol) (IF setb-expression)
macro -> MACRO (macro-label) macro-name (macro-operands)
macro-label -> "&&"label":"
macro-operands -> "&&"identifier (",&&"identifier)*
1 - 38 -
format-control -> EJECT
SPACE ( integer )
TITLE "'" title "'"
SUBTITLE "'" subtitle "'"
bal -> BAL;
bal-segment
ALP;
comment -> COMMENT;
text
ALP;
cc -> CC condition-code-string
condition-code-string -> <N | "^" | 0 | "=" | E | Z | 1 | L | M |
2 | P | H | 3 | O>*
predicate -> ("^")* <statement | "<" predicate ">">
| predicate "&" predicate
| predicate "|" predicate
comment -> "%" text "end-of-line"
1 - 39 -
VII. ALP READABILITY MACROS
In the description that follows,
r is a register
a is any relocatable expression that is valid in an
instruction
c is a constant
Macro Name Code Generated
AI r,c Add Immediate LA r,c(,r)
AI 0,c Add Immediate AL 0,=A(c)
CI r,c Compare Immediate C r,=A(c)
CIL r,c Compare Immediate CL r,=A(c)
Logical
DI r,c Divide Immediate D r,=A(c)
LI r,c Load Immediate LA r,c
LQS rx,ry,'str' Load Quoted String LA rx,=C'str'
LA ry,length
LT r,a Load and Test L r,a
LTR r,r
MI r,c Multiply Immediate MH r,=AL2(c)
RM r Register Minus LTR r,r
RMP r Register Minus or Plus LTR r,r
RMZ r Register Minus or Zero LTR r,r
RNM r Register Not Minus LTR r,r
RNMP r Register Not Minus LTR r,r
or Plus
RNMZ r Register Not Minus LTR r,r
or Zero
RNP r Register Not Plus LTR r,r
RNZ r Register Not Zero LTR r,r
RNZP r Register Not Zero LTR r,r
or Plus
1 - 40 -
RP r Register Plus LTR r,r
RZ r Register Zero LTR r,r
RZP r Register Zero or Plus LTR r,r
SI r,1 Subtract Immediate BCTR r,0
SI r,2 Subtract Immediate BCTR r,0
BCTR r,0
SI r,c Subtract Immediate SL r,=A(c)
Z r,a Zero SR r,r
ST r,a
Z ,a Zero XC a(4),a
ZB r,a Zero Byte SR r,r
STC r,a
ZB ,a Zero Byte MVI a,0
ZH r,a Zero Halfword SR r,r
STH r,a
ZH ,a Zero Halfword XC a(2),a
ZHB a Zero High Byte MVI a,0
ZHBR r Zero High Byte Register LA r,0(,r)
ZHBR 0 Zero High Byte Register N 0,=XL4'00FFFFFF'
ZI a,c Zero Immediate NI a,255-(c)
ZR r Zero Register SR r,r
1 - 41 -
VIII. Macros for Environment Enhancement
Conventions
Macro operands are described using the following terms:
cexpr4 - denote expressions which evaluate to a constant
to be held in 4 bits
cexpr8 - denote expressions which evaluate to a constant
to be held in 8 bits
relexpri - denotes a relocatable expression that is valid as
a storage address in an instruction
symbol - an identifier acceptable to the assembler
reg - any register
preg - any register except 0
1 - 42 -
AREA, AREAORG and AREAEND - Define a structured storage area
+ ____________________________________________________________
AREA and AREAEND are used to define an area of storage which is
structured into smaller named components. AREA begins the
definition, DSs and DCs follow, and AREAEND terminates the
definition.
AREAORG is used to ORG back to the start of the area so that
fields may be overlaid. The length of the area will be the
maximum attained.
<symbol> AREA alignment<,DSECT=NO>
symbol symbol
The name of the total storage area. The length attribute
will be correctly set.
alignment X,H,F,D,0X,0H,0F,0D
Specifies the boundary alignment for the area. Default
is X (byte alignment).
DSECT=NO
Indicates that the area is not to be a DSECT.
<symbol> AREAEND <alignment>
symbol symbol
A symbol which is to be EQUed to the length of the area.
alignment X,H,F,D,0X,0H,0F,0D
Specifies the boundary alignment for the end of the area.
Default is what was specified in the AREA macro.
1 - 43 -
<symbol> AREAORG <alignment>
symbol symbol
A symbol which is to be EQUed to the current length of
the area.
alignment X,H,F,D,0X,0H,0F,0D
Specifies boundary alignment for the end of this overlay
of the area. Default is what was specified in the AREA
macro.
NOTE:
Area definitions may be nested. DSECT=NO is implied at the
inner levels.
EXAMPLE:
WA AREA F
WATEMP DS F
WABYTE DS X
WAHALF DS H
WASIZE AREAEND
1 - 44 -
EXAMPLE:
WA AREA F
WATEMP DS F
WA2 AREA D
WABYTE DS X
WAHALF DS H
WA2SIZE AREAEND
WAHALF2 DS H
WASIZE AREAEND
generates
WA DSECT
WATEMP DS F
WA2 DS OD
WABYTE DS X
WAHALF DS H
DS OD
WA2SIZE EQU *-WA2
WAHALF2 DS H
DS OF
WASIZE EQU *-WA
prevsect CSECT
where "prevsect" is the previous CSECT name
1 - 45 -
DEBLANK - Deblank a string
+ __________________________
The DEBLANK macro removes leading and/or trailing blanks from a
string.
<symbol> DEBLANK loc-reg,len-reg<,work-reg><,TYPE=symbol>
<,NULL=NO><,ZERO=NO><,LABEL=symbol><,FILL=char>
<,FILADDR=byte>
loc-reg preg
Specifies the starting address of the string to be
deblanked.
len-reg reg
Specifies the length of the string to be deblanked.
After the termination of the macro, this register will
contain the new length of the deblanked string.
work-reg preg
Provides a work register to be used in the search. More
efficient code may be generated if this register is
provided.
TYPE=symbol LEFT, RIGHT, or BOTH
Specifies elimination of leading (LEFT) or trailing
(RIGHT) blanks, or both (BOTH). Default is RIGHT.
NULL=NO
The NO condition specifies that the resulting string will
never be 0. More efficient code may be generated if this
option is specified.
ZERO=NO
The NO condition specifies that the value in the len
register will never be 0. More efficient code may be
generated if this option is specified.
1 - 46 -
LABEL=symbol relexpri
The location to receive control if the resulting string
has a length of zero.
FILL=char cexpr8
Used to specify a character other than blank to be
stripped.
FILADDR=byte relexpri
Used to specify the location of the character to be
stripped. May not be used with FILL.
RETURNS:
loc-reg = location of deblanked string
len-reg = length of deblanked string
1 - 47 -
EDIT - Generate edit mask and ED/EDMK instruction
+ _________________________________________________
EDIT is used to create both an appropriate mask string or editing
numeric data and the ED or EDMK instruction to perform the
requested operation.
<symbol> EDIT to-field,from-field<,to-length><,from-length>
<,CALC=NO><,DIGITS=n><,MARK=YES>
to-field relexpri or (preg)
The address of the field to contain the edited source
digits. It must be an even number of bytes in length.
from-field relexpri or (preg)
The address of the field containing the source digits to
be EDITed to the to-field. It must contain sufficient
digits to satisfy the implicit (or explicit) length of
the to-field.
to-length cexpr4
An explicit specification of the length of the to-field.
It must be specified if the to-field is presented in
base-displacement form. If specified it will override
the implicit length for the to-field.
from-length cexpr4
An explicit specification of the length of the
from-field. It must be specified if the from-field is
specified in base-displacement form. If specified it
overrides the implicit length for the from-field.
CALC=NO
Indicates that the addresses specified are to be used
exactly as is for the from- and to-fields in the
generated ED or EDMK instruction. If not specified the
macro will calculate the offset in the from-field to use
in the ED or EDMK instruction.
1 - 48 -
DIGITS=n cexpr4
Specifies the minimum number of significant digits to be
produced.
MARK=YES
Indicates that an EDMK instruction should be generated.
Register 1 will then point to the first significant
character in the edited field. If the field does not
produce a significatn digit, register 1 will point to the
low order character of the edited field.
1 - 49 -
EXI and EXORG - Execute immediate
+ _________________________________
EXI permits the instruction to be executed by an EX instruction
to be coded at the same place in the source program.
<symbol> EXI ex-reg,opcode,operand1,operand2,<DECR=YES>,
<INCR=YES>
ex-reg reg
The register to be used as the first operand of the EX
instruction.
opcode valid assembler opcode
Operation code of the instruction to be executed.
operand1
The first operand of the instruction to be executed.
operand2
The second operand of the instruction to be
executed.
DECR=YES
Specifies that the register is to be decremented by one
before the EX instruction.
INCR=YES
Specifies that the register is to be incremented by one
after the EX instruction. The condition code is not
affected.
1 - 50 -
NOTES:
1. The opcode to be executed may not be a macro unless it is
one of the following: MCLC, MMVC, MNC, MOC, MTC, MTR,
MTRT, MXC, MZC. When one of these is used, N=1 and a
length of zero are forced.
2. An EXORG must be included within addressable range in
order to assemble the instructions to be executed.
3. If an instruction occurs more than once, EXORG will
assemble only one copy.
1 - 51 -
Extended Length Facilities
+ __________________________
These macros generate inline code to provide extended length
facilities. These macros provide an optional N=count operand to
allow the writer to specify the exact number of instructions to
be generated. If N=count is not present, and the length
operand is an unsigned integer or a SETA symbol, then as many
instructions as are required for the specified length will be
generated. If N=count is not present and the length operand is
not an unsigned integer or SETA symbol, then one instruction is
generated.
MCLC, MMVC, MNC, MOC, and MXC
<symbol> opcd oper1,oper2,length<,N=count><,ZERO=NULL>
opcd MCLC, MMVC, MNC, MOC, or MXC
oper1 relexpri or (preg)
The address of the 1st operand.
oper2 relexpri or (preg)
The address of the 2nd operand.
length
The number of bytes affected.
N=count unsigned integer or SETA symbol
The number of instructions to be generated.
ZERO=NULL
Specifies that no instructions are to be generated if len
is zero. Normally a single instruction would be
generated.
1 - 52 -
MFC - Fill a field
+ __________________
The MFC macro will fill a field with the specified charater.
<symbol> MFC loc,len<,FILL=char><,N=count><,ZERO=NULL>
loc relexpri or (preg)
The address of the field to be filled.
len
The length of the field to be filled.
FILL=char cexpr8
The character to fill the field with. Default is
blank (C' ')
N=count unsigned integer or SETA symbol
The number of instructions to be generated.
ZERO=NULL
Specifies that no instructions are to be generated if len
is zero.
1 - 53 -
MTC - Test a field
+ __________________
MTC tests a field for all zero (or other specified value) bytes.
<symbol> MTC loc,len<,FILL=char><,N=count><,ZERO=NULL>
loc relexpri or (preg)
Address of field to be tested.
len
Length of field.
FILL=char cexpr8
The character to be tested for. Default is 0.
N=count unsigned integer or SETA symbol
Number of instructions to be generated.
ZERO=NULL
Specifies that no test is to be performed if len is zero.
The condition code will be set to zero in that case.
NOTE:
If FILL is not specified, OC instructions are generated to
test the field for zeros. If FILL is specified, CLC
instructions are generated, even if FILL=0 is specified.
1 - 54 -
MTR - Translate a field
+ _______________________
MTR translates a field using a specified translate table.
<symbol> MTR loc,table,len<,N=count><,ZERO=NULL>
loc relexpri or (preg)
Location of field to be translated.
table relexpri or (preg)
Location of translate table.
len
Length of field.
N=count unsigned integer or SETA symbol
Number of TR instructions to be generated.
ZERO=NULL
Specifies that no instructions are to be generated if len
is zero.
1 - 55 -
MTRT - Translate and test a field
+ _________________________________
MTRT performs a translate-and-test on a field.
<symbol> MTRT loc,table,len<,N=count><,ZERO=NULL>
loc relexpri or (preg)
Location of field.
table relexpri or (preg)
Location of translate-and-test table.
len
Length of field.
N=count unsigned integer or SETA symbol
Number of instructions to be generated.
ZERO=NULL
Specifies that no translate and test is to be performed
if len is zero. The condition code is set to zero in
that case.
1 - 56 -
MZC - Clear a field
+ ___________________
The MZC macro will clear a field to all X'00's.
<symbol> MZC loc,len<,N=count><,ZERO=NULL>
loc relexpri or (preg)
The address of the field to be zeroed.
len
The length of the field to be zeroed.
N=count unsigned integer or SETA symbol.
The number of instructions to be generated.
ZERO=NULL
Specifies that no instructions are to be generated if len
is zero.
1 - 57 -
DF - Define flags
+ _________________
DF is used to define one or more flag bits and optionally assign
initial values.
<symbol> DF flag-name,...<INIT=(flag-name,...)>
flag-name symbol
The name of the flag to be defined. Any number of flags
may be specified. If more than 8 are specified, more than
1 byte will be reserved.
INIT=(flag-name,...) list of symbols
Specifies flags which are to be initially 1 (on).
1 - 58 -
SF - Set flags
+ ______________
SF is used to turn on one or more flags defined with DF.
<symbol> SF flag-name,...
flag-name symbol
The name of a flag to be turned on (set to 1). Up to 8
flags may be specified; all must reside in the same byte.
1 - 59 -
TF - Test flags
+ _______________
TF is used to test one or more flags defined with DF.
<symbol> TF flag-name,...
flag-name symbol
The name of a flag to be tested. Up to 8 flags may be
specified; all must reside in the same byte.
RETURNS:
CC = Z all tested flags off
O all tested flags on
M some on, some off
1 - 60 -
ZF - Zero flags
+ _______________
ZF is used to turn off one or more flags defined with DF.
<symbol> ZF flag-name,...
flag-name symbol
The name of a flag to be cleared. Up to 8 flags may be
specified; all must reside in the same byte.
1 - 61 -
OSCALL - Pass control to an OS-type subroutine
+ ______________________________________________
The OSCALL macro will pass control to a specified subroutine
using OS calling conventions.
<symbol> OSCALL routine<,A><,R1=parm><,R0=parm>
<,R15=parm>
routine relexpra or vsymbol or (preg)
The address of the subroutine to be called.
A
The address specified in the routine parameter is a
relexpra.
R1=parm addrla
A parameter to be passed in register 1.
R0=parm addrla
A parameter to be passed in register 0.
R15=parm addrla
A parameter to be passed in register 15.
NOTE:
Register 15 is loaded with the entry point address unless
R15=parm is specified
1 - 62 -
OSENTER - Generate OS entry code
+ ________________________________
The OSENTER macro will generate proper OS entry linkage code.
<symbol> OSENTER <(reg1,reg2),...><,ENTRY=NO>
<,BASE=NO><,SAVE=area><,PACK=YES>
<,FORWARD=YES><,ID=identification>
reg1,reg2 regs
Registers to be saved in STM form. Any number of
parenthesized pairs may be specified. If reg2 is the same
as reg1, then reg2 and the parentheses may be omitted.
ENTRY=NO
Requests that an ENTRY point not be generated.
BASE=NO
Requests that a base register not be established.
SAVE=area relexpri
The address of the users register save area.
PACK=YES
Registers are to be stored packed at 12 bytes after the
start of the save area.
FORWARD=YES
Specifies that the forward linking of save areas is to be
performed. Normally only backward linking is done.
ID=identification symbol or string or *
Specifies an identifying character string to be assembled
4 bytes after the entry point. * indicates that the entry
name (or the CSECT name if there is no entry name) is to
be used.
NOTES:
1. The base register is BASER (see OSSETUP).
2. If SAVE=area is not specified, then no new save area will
be established.
3. The generated code does not depend on register 15 being
loaded with the entry point address unless
ID=identification is specified.
1 - 63 -
OSEXIT - Generate OS return code
+ ________________________________
The OSEXIT macro will generate proper OS exit linkage code.
<symbol> OSEXIT <(reg1,reg2)...>,<,SAVE=area><,LTR=reg>
<,PACK=YES><,RC=value><,FLAG=YES>
reg1,reg2 registers
Registers to be restored in LM format. Any number of
parenthesized pairs may be specified. When reg2 is the
same as reg1, reg2 and the parentheses may be omitted.
SAVE=area relexpri
The address of the program's register save area.
LTR=reg reg
Requests that an LTR reg,reg be performed to set the
condition code upon return.
PACK=YES
Must be specified if PACK=YES was coded on the
corresponding OSENTER macro.
RC=value valuela
Specifies a return code to be loaded into register 15.
FLAG=YES
Specifies that X'FF' is to be placed into the high-order
byte of word 4 of the save area after the registers are
restored.
NOTE:
If SAVE=area is not specified, then the registers are
restored from the area pointed to by register 13. Note that
SAVE=0(SAVER) and SAVE=0(13) are perfectly acceptable.
1 - 64 -
OSSETUP - Set up OS linkage environment
+ _______________________________________
The OSSETUP macro, used once at the start of the program (after
macro definitions, but before any code or EQUs), defines register
names and optionally defines certain OS control blocks.
symbol OSSETUP <REGS=option><,DCB=YES>
<,R15=name><,R14=name><,R13=name><,BASER=name>
<,R1=name><,R0=name>
symbol 1-8 characters (required)
CSECT name for the module.
REGS=option PLI or NO
PLI is used to request PL/I compatible register
definitions. NO specifies that register definitions
should not be included.
DCB=YES
Define OS DCB DSECT.
R15=name symbol
Name to be used by OSENTER, OSEXIT and OSCALL to refer to
register 15. Default is RCR.
R14=name symbol
Name to be used by OSENTER, OSEXIT and OSCALL to refer to
register 14. Default is RTNR.
R13=name symbol
Name to be used by OSENTER, OSEXIT and OSCALL to refer to
register 13. Default is SAVER.
BASER=name symbol
Register to be loaded by OSENTER as a base register.
Default is BASER.
R1=name
Name to be used by OSENTER, OSEXIT and OSCALL to refer to
register 1. Default is VR1.
R0=name
Name to be used by OSENTER, OSEXIT and OSCALL to refer to
register 0. Default is VR0.
1 - 65 -
NOTE:
Register definitions are as follows:
Default PLI
Register Absolute name Symbolic name Symbolic name
0 R0 VR0 VR0
1 R1 VR1 VR1
2 R2 XRA, LOWR XRA,HIGHR
3 R3 XRB XRB
4 R4 XRC XRC
5 R5 XRD XRD
6 R6 XRE XRE
7 R7 XRF XRF
8 R8 XRG XRG
9 R9 XRH XRH
10 R10 XRI XRI
11 R11 XRJ BASER,HIGHR
12 R12 BASER, HIGHR GCBR
13 R13 SAVER SAVER
14 R14 RTNR RTNR
15 R15 RCR RCR
LOWR and HIGHR are for use with OSENTER and OSEXIT when
specifying registers to be saved and restored.
1 - 66 -
OPENP - Check for successful open
+ _________________________________
The OPENP macro will check DCBOFLGS to see if the DCB was opened
successfully.
<symbol> OPENP dcb-addr
dcb-addr relexpri
The address of the DCB to be checked.
RETURNS:
If the DCB was opened successfully, the condition code will
be set to a non-zero value.
NOTE:
The DCBD macro must be included in the assembly.
1 - 67 -
CBDELINK - Remove control block from linked list
+ ________________________________________________
CBDELINK is used to remove a control block from a linked list of
similar control blocks.
<symbol> CBDELINK prev-reg,del-reg,work-reg,HEAD=loc
<,TAIL=loc>,NEXT=dsect-loc
<,BACK=dsect-loc>
<,CB=dsect-name><,ZOT=YES>
prev-reg preg
Register must contain a pointer to the control block which
immediately preceeds the one to be removed. Should
contain zero if removing from the beginning of the list.
del-reg preg
Register must contain a pointer to the control block to be
removed from the list.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list. Contains zero when the list is
empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
1 - 68 -
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
ZOT=YES
Indicates that the NEXT and BACK fields in the control
block being removed should be set to zero.
1 - 69 -
CBDLINKH - Remove control block from head of linked list
+ ________________________________________________________
CBDLINKH is used to remove the first control block from a linked
list of similar control blocks.
<symbol> CBDLINKH del-reg,work-reg,HEAD=loc<,TAIL=loc>
NEXT=dsect-loc<,BACK=dsect-loc>
<,CB=dsect-name><,ZOT=YES>
del-reg preg
Register must contain a pointer to the first control block
in the linked list.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list. Contains zero when the list is
empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
ZOT=YES
Indicates that the NEXT and BACK fields in the control
block being removed should be set to zero.
1 - 70 -
CBDLINKT - Remove control block from tail of a linked list
+ __________________________________________________________
CBDLINKT is used to remove the last control block from a linked
list of similar control blocks.
<symbol> CBDLINKT prev-reg<,del-reg>,work-reg,head=loc
<,TAIL=loc>,NEXT=dsect-loc
<,BACK=dsect-loc><,CB=dsect-name>
<,ZOT=YES>
prev-reg preg
Register must contain a pointer to the control block which
immediately preceeds the one to be removed. Should
contain zero if removing from the beginning of the list.
del-reg preg
Register must contain a pointer to the control block to be
removed from the list. Required only if ZOT=YES is
specified.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list. Contains zero when the list is
empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
1 - 71 -
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
ZOT=YES
Indicates that the NEXT and BACK fields in the control
block being removed should be set to zero.
1 - 72 -
CBLINK - Add control block to linked list
+ _________________________________________
CBLINK is used to add a control block anywhere in a linked list
of similar control blocks.
<symbol> CBLINK after-reg,new-reg,work-reg,HEAD=loc
<,TAIL=loc>,NEXT=dsect-loc,
<,BACK=dsect-loc><,CB=dsect-id>
after-reg preg
Register containing a pointer to the control block after
which the new control block is to be added. Should
contain zero if the new control block is to be first in
the list.
new-reg preg
Register must contain a pointer to the control block to be
added.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list. Contains zero when the list is
empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
1 - 73 -
CBLINKH - Add a control block at the head of a linked list
+ __________________________________________________________
CBLINKH is used to add a control block at the start of a linked
list of similar control blocks.
<symbol> CBLINKH new-reg,work-reg,HEAD=loc<,TAIL=loc>,
NEXT=dsect-loc<,BACK=dsect-loc>
<,CB=dsect-id>
new-reg preg
Register must contain a pointer to the control block to be
added.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list. Contains zero when the list is
empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block which in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
1 - 74 -
CBLINKT - Add control block at the tail of a linked list
+ ________________________________________________________
CBLINKT is used to add a control block at the end of a linked
list of similar control blocks.
<symbol> CBLINKT new-reg,work-reg,HEAD=loc,TAIL=loc,
NEXT=dsect-loc<,BACK=dsect-loc>
<,CB=dsect-id>
new-reg preg
Register must contain a pointer to the control block to be
added.
work-reg preg
A work register.
HEAD=loc relexpri
Location of a word which contains a pointer to the first
element in the list. Contains zero when the list is
empty.
TAIL=loc relexpri
Location of a word which contains a pointer to the last
element in the list Contains zero when the list is empty.
NEXT=dsect-loc symbol
Name of the word defined in a DSECT for the control block
which points to the next control block in the list.
Contains zero for the last element in the list.
BACK=dsect-loc symbol
If present, indicates a doubly-linked list (forward and
backward pointers). Name of the word defined in a DSECT
for the control block which points to the preceeding
control block in the list. Contains zero for the first
element in the list.
CB=dsect-id symbol
The name of the DSECT for the control block. Omit if the
control block is defined with EQUs instead of a DSECT.
1 - 75 -
IX. ALP CODING HINTS
1. Use indentation to indicate the nesting level. The ALP
listing shows the current nesting level to the left of each
input line. It is increased by BEGIN, <, CASE, SELECT, ASM
CASE, ASM SELECT and MACRO and is reduced by END, >, ENDCASE,
ENDSEL and MEND. With WYLBUR, tabs can be set every few
positions (say 3) and each line indented by the number of
tabs equal to its nesting level.
2. Avoid using explicit branching or "GOTOs". The ALP control
structures show intent much more clearly.
3. Use the readability and environment macros -- they make the
intent of a program much clearer.
4. Use the assembler USING statement for "global" base registers
and the ALP USE statement for "local" base registers.
5. Using symbolic register names makes a program easier to
understand. Name registers according to function. The
OSSETUP macro provides one possible set of names.
6. Never use two names for the same register in a single section
of code.
7. Always use RGOTO instead of BR and GOTO instead of B (if you
must use explicit branching).
1 - 76 -
X. SAMPLE PROGRAM
The following problem is taken from an actual class for beginning
assembly language programmers.
Given: 50 full words in core, each containing a fixed-point
(binary) value. The instructor will give you this data
(in the form of DC statements) and describe the necessary
JCL. The first constant will be labeled NUMBERS.
Task: You are to determine the number of positive constants,
the number of negative constants and the number of zero
constants, as well as the sum of each of these. Store
the five computed values into core and output them via a
core dump. JFDUMP will be described in class. Computing
the sums will not result in overflow.
1 - 77 -
Assembly Language Solution:
// EXEC ASMHCOMP
//COMP.SYSIN DD *
PROB1 START 0
SAVE (14,12),,*
BALR 10,0
USING *,10
LA 12,SAVE
ST 13,4(12)
ST 12,8(13)
LR 13,12
LA 2,50 MAX TIMES THRU
SR 3,3 ZERO INDEX REG
SR 4,4 # OF POS VALUES
SR 5,5 # OF NEG VALUES
SR 6,6 # OF ZERO VALUES
TOP L 7,NUMBERS(3) GET VALUE
LTR 7,7 SET CC
BP POS POSITIVE
BM NEG NEGAGIVE
LA 6,1(,6) BUMP ZERO CTR
GOBACK LA 3,4(,3) BUMP POINTER
BCT 2,TOP KEEP GOING
STM 4,6,NUMS SAVE RESULTS
JFDUMP START=PROB1,END=NUMS+12
L 13,4(13) GO BACK
RETURN (14,12),RC=0
POS LA 4,1(,4) BUMP COUNTER
L 8,POSNUM GET # OF POS
AR 8,7 ADD TO IT
ST 8,POSNUM SAVE IT BACK
B GOBACK KEEP GOING
NEG LA 5,1(,5) BUMP COUNTER
L 8,NEGNUM GET NUMBER
AR 8,7 ADD TO IT
ST 8,NEGNUM RESTORE IT
B GOBACK KEEP GOING
SAVE DC 18F'0' SAVE AREA
NUMBERS DC 2F'8,1,1,0,2,-2,0,3,-3,0,4,-4,0,5,-5,0,6,-6,0,7,-7,0,8,-8,0'
POSNUM DC F'0' POSITIVE VALUE
NEGNUM DC F'0' NEGATIVE VALUE
NUMS DS 3F COUNTERS
END
// EXEC ASMHLKGO
//GO.SYSUDUMP DD SYSOUT=A
1 - 78 -
ALP Solution (without macros):
// EXEC ALPHCOMP
//COMP.SYSIN DD *
PROB1: START 0;
SAVE (14,12),,*;
BALR 10,0; USING *,10;
LA 12,SAVE; ST 13,4(,12); ST 12,8(,13);
LR 13,12;
LI 2,50; % NUMBER OF TIMES THRU
SR 3,3; % CLEAR INDEX REGISTER
SR 4,4; % NUMBER OF POS VALUES
SR 5,5; % NUMBER OF NEG VALUES
SR 6,6; % NUMBER OF ZERO VALUES
DO BEGIN
L 7,NUMBERS(3); % GET VALUE
IF <LTR 7,7; CC Z> THEN LA 6,1(,6) % ZERO VALUE
ELSE IF <CC P> THEN BEGIN % POSITIVE VALUE
LA 4,1(,4); % BUMP COUNTER
L 8,POSNUM; AR 8,7; ST 8,POSNUM; % COMPUTE SUM
END
ELSE BEGIN % NEGATIVE VALUE
LA 5,1(,5); % BUMP COUNTER
L 8,NEGNUM; AR 8,7; ST 8,NEGNUM; % COMPUTE SUM
END;
LA 3,4(,3); % BUMP POINTER
END FOR 2;
STM 4,6,NUMS; % SAVE RESULTS
JFDUMP START=PROB1,END=NUMS+12;
L 13,4(,13);
RETURN (14,12),RC=0;
SAVE: DC 18F'0'; % SAVE AREA
NUMBERS: DC 2F'8,1,1,0,2,-2,0,3,-3,0,4,-4,0,5,-5,0,6,-6,'_
'0,7,-7,0,8,-8,0';
POSNUM: DC F'0'; % POSITIVE VALUE
NEGNUM: DC F'0'; % NEGATIVE VALUE
NUMS: DS 3F;
END;
// EXEC ALPHLKGO
//GO.SYSUDUMP DD SYSOUT=A
1 - 79 -
ALP Solution (with macros):
// EXEC ALPHCOMP
//COMP.SYSIN DD *
PROB: TITLE 'CLASS PROBLEM 1';
PROB1: OSSETUP;
SUBTITLE 'MAIN PROGRAM';
OSENTER (RTNR,HIGHR),SAVE=SAVE,FORWARD=YES;
LI XRA,50; % NUMBER OF TIMES THRU
ZR XRB; % CLEAR INDEX REGISTER
ZR XRC; % NUMBER OF POS VALUES
ZR XRD; % NUMBER OF NEG VALUES
ZR XRE; % NUMBER OF ZERO VALUES
DO BEGIN
L XRG,NUMBERS(XRB); % GET NUMBER
IF <RZ XRG> THEN AI XRE,1 % ZERO VALUE
ELSE IF <CC P> THEN BEGIN % POSITIVE VALUE
AI XRC,1; % BUMP COUNTER
L XRH,POSNUM; AR XRH,XRG; ST XRH,POSNUM; % COMPUTE SUM
END
ELSE BEGIN % NEGATIVE VALUE
AI XRD,1; % BUMP COUNTER
L XRH,NEGNUM; AR XRH,XRG; ST XRH,NEGNUM; % COMPUTE SUM
END;
AI XRB,4; % BUMP POINTER
END FOR XRA;
STM XRC,XRE,NUMS; % SAVE RESULTS
JFDUMP START=PROB1,END=NUMS+12;
OSEXIT (RTNR,HIGHR),RC=0,SAVE=SAVE;
SUBTITLE 'CONSTANTS AND WORK AREA';
SAVE: DC 18F'0'; % SAVE AREA
NUMBERS: DC 2F'8,1,1,0,2,-2,0,3,-3,0,4,-4,0,5,-5,0,6,-6,'_
'0,7,-7,0,8,-8,0';
POSNUM: DC F'0'; % POSITIVE VALUE
NEGNUM: DC F'0'; % NEGATIVE VALUE
NUMS: DS 3F;
END;
// EXEC ALPHLKGO
//GO.SYSUDUMP DD SYSOUT=A
1 - 80 -
XI. USING ALP AT NIH
. The following procedures are available and conform to NIH
conventions:
ALP Procedure Corresponding Assembler Procedure
+ _____________ _________________________________
ALPHCOMP ASMHCOMP
ALPHOBJ ASMHOBJ
ALPHCOMF ASMHCOMP
ALPHOBJF ASMHOBJ
ALPHPRE None
ALPHLKGO ASMHLKGO
ALPHLDGO ASMHLDGO
ALPHLKSM ASMHLKSM
ALPHLKMM ASMHLKMM
ALPHCALL ASMHCALL
ALPHLOOK ASMHLOOK
All symbolic parameters are the same.
. Normally, ALPHCOMP and ALPHOBJ produce only the ALP listing.
However, if ASMLIST='' is specified on the EXEC statement, the
assembler listing will be produced as well.
. ALPHCOMF and ALPHOBJF differ from ALPHCOMP and ALPHOBJ in that
the assembler listing is placed on microfiche. Some additional
symbolic parameters are provided to facilitate this:
MFID=name Required. Specifies a 1-8
character name to be used to
insure uniqueness of the DSNAME
on the microfilm tape. Should
begin with registered initials.
MFNAME='dsname' Optional. Specifies the name of
a data set containing PTFORM
control records. A default
suitable for most applications
is included.
MFSTOR=unit Optional. Specifies unit name
for the PTFORM control data
set. Default is MFSTOR=FILE.
MFDISK=volume Optional. Specifies the volume
on which the PTFORM control
data set resides.
1 - 81 -
. The procedure ALPHPRE may be used to perform ALP preprocessing
without assembling the result. Normally, only the ALP listing
is produced. However, if ASMLIST='' is specified on the
EXEC statement the generated assembly code will be listed as
well.
. Problems or questions concerning ALP should be forwarded to the
PAL Unit, Computer Center, DCRT, Building 12A, Room 1017,
accompanied by a PTR (Programmer Trouble Report) and all
necessary computer runs. This is currently the only method of
support for this product.
1 - 82 -
XII. REFERENCES
1. Fletcher, J. G. et al., "On The Appropriate Language
For System Programming", SIGPLAN Notices Vol. 7, No. 7,
(July 1972),28-32.
2. Lang, C. A., "Languages for Writing System Programs",
in "Software Engineering Techniques". NATO Science
Committee 101-106, April 1970.
3. Lyle, L. M., "A Hierarchy of High Order Languages for
Systems Programming", SIGPLAN Notices Vol. 6, No. 9,
(October 1971), 73&77.
4. Du Bois, P. J. et al., "The LRLTRAN Language As Used
in the FROST and FLOE Time-Sharing Operating Systems",
SIGPLAN Notices Vol. 6, No. 9, (October 1971), 92-104.
5. Haines, E. C., "AL: A Structured Assembly Language",
M72-81, The MITRE Corp., Bedford, Mass., April 1972. Also
SIGPLAN Notices Vol. 8, No. 1, (January 1973), 15-20.
Also SIGPLAN Notices Vol. 8, No. 4, (April 1973), 16-21.
6. Dijkstra, E. W., "GO TO Statement Considered Harmful",
"Communications of the ACM", Vol. 11, No. 3, (March 1968),
147-148.
1
COMMENT FORM
Is the ALP User's Guide YES NO
Clear? __ __
Well Organized? __ __
Complete? __ __
Accurate? __ __
Suitable for the beginner? __ __
Suitable for the advanced user? __ __
Comments:________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
Please give page references where appropriate. If you wish a
reply, include your name and mailing address.
Send to: NIH
DCRT
Computer Center
Technical Information Office
Bldg. 12A, Rm. 1017
Bethesda, Maryland 20892
,SEPARATOR