ASSIST1-1
3.0/B
ASSIST MARCH 1974
INTRODUCTORY ASSEMBLER USER'S MANUAL
Program&Documentation: John R. Mashey
Project Supervision : Graham Campbell
Computer Science Department - Pennsylvania State University
PREFACE
This manual is the basic reference for the programmer writing
in the Assembler Language for the IBM S/360 computer, using the ASSIST
assembler-interpreter system. ASSIST (Assembler System for Student
Instruction and Systems Teaching) is a small, high-speed, low-overhead
assembler/interpreter system especially designed for use by students
learning assembler language. The assembler program accepts a large
subset of the standard Assembler Language under OS/360, and includes
most common features. The execution-time interpreter simulates the
full 360 instruction set, with complete checking for errors, meaning-
ful diagnostics, and completion dumps of much smaller size than the
normal system dumps.
The first part of this manual describes the assembly language
commands permitted by the ASSIST assembler. In essence, it is a
comparison with the standard Assembly Language, and generally notes
only the omissions or differences from the standard. The reader should
refer to one of the following publications, which the first part of this
manual closely follows (depending on operating system used):
C28-6514 IBM SYSTEM/360 OPERATING SYSTEM ASSEMBLER LANGUAGE
C24-3414 IBM SYSTEM/360 DISK AND TAPE OPERATING SYSTEM ASSEMBLER LANG.
The second section describes input/output, decimal conversion,
hexadecimal conversions, and debugging facilities available to the user
at execution time.
The third part of the manual describes the control cards and
Job Control Language required to assemble and execute a program
under ASSIST. It also notes the various options from the PARM
field which are accepted by the system.
The fourth section gives information concerning the output
from ASSIST, including the assembly listing, the format of the
completion dump produced by an error in program execution, and
a list of all error messages produced during assembly or execution.
It also describes the object decks produced/accepted by ASSIST.
Note: this document is NOT copyrighted.
Note: only major change in documentation from version 2.1
is the inclusion of cross-reference material(XREF)
and the inclusion of the extended interpreter
material.
ASSIST1-2
TABLE OF CONTENTS
PART I. THE ASSEMBLY LANGUAGE UNDER ASSIST................. 1-4
The sections flagged * note that the given language features
are not accepted by ASSIST.
SECTION I: INTRODUCTION.................................... 1-4
Compatibility......................................... 1-4
Macro Instructions.................................... 1-4
The Assembler Program................................. 1-5
SECTION 2: GENERAL INFORMATION............................. 1-5
Symbols............................................... 1-5
General Restrictions on Symbols....................... 1-5
Location Counter References........................... 1-5
Literals.............................................. 1-5
Literal Pool.......................................... 1-5
Expressions........................................... 1-5
SECTION 3: ADDRESSING -- PROGRAM SECTIONING AND LINKING.... 1-6
USING -- Use Base Register............................ 1-6
CONTROL SECTIONS...................................... 1-6
Control Section Location Assignment................... 1-6
FIRST CONTROL SECTION................................. 1-6
START -- Start Assembly............................... 1-6
CSECT -- Identify Control Section..................... 1-6
DSECT -- Identify Dummy Section....................... 1-6
*EXTERNAL DUMMY SECTIONS (ASSEMBLER F ONLY)............ 1-6
*COM -- DEFINE BLANK COMMON CONTROL SECTION............ 1-6
SECTION 4: MACHINE INSTRUCTIONS............................ 1-7
Instruction Alignment and Checking.................... 1-7
OPERAND FIELDS AND SUBFIELDS.......................... 1-7
SECTION 5: ASSEMBLER LANGUAGE STATEMENTS................... 1-7
*OPSYN -- EQUATE OPERATION CODE........................ 1-7
DC -- DEFINE CONSTANT................................. 1-7
Operand Subfield 3: Modifiers......................... 1-7
Operand Subfield 4: Constant.......................... 1-7
CCW -- DEFINE CHANNEL COMMAND WORD.................... 1-8
Listing Control Instructions.......................... 1-8
TITLE -- IDENTIFY ASSEMBLY OUTPUT..................... 1-8
PRINT -- PRINT OPTIONAL DATA.......................... 1-8
PROGRAM CONTROL INSTRUCTIONS.......................... 1-8
*ICTL, ISEQ, PUNCH, REPRO.............................. 1-8
LTORG -- BEGIN LITERAL POOL........................... 1-8
Special Addressing Considerations..................... 1-8
Duplicate Literals.................................... 1-8
*COPY -- COPY PREDEFINED SOURCE CODING................. 1-8
SECTION 6: INTRODUCTION TO THE MACRO LANGUAGE ............. 1-9
SECTION 7: HOW TO PREPARE MACRO DEFINITIONS ............... 1-10
SECTION 8: HOW TO WRITE MACRO-INSTRUCTIONS ................ 1-10
SECTION 9: HOW TO WRITE CONDITIONAL ASSEMBLY INSTRUCTIONS . 1-11
SECTION 10: EXTENDED FEATURES OF THE MACRO LANGUAGE ....... 1-12
ASSIST1-3
PART I. (CONTINUED)
APPENDIX K: USE OF LIBRARY MACROS.......................... 1-12
PART II. INPUT/OUTPUT AND DEBUGGING INSTRUCTIONS........... 2-1
INPUT/OUTPUT INSTRUCTIONS - XREAD, XPRNT, XPNCH............ 2-1
CONDITION CODE........................................ 2-1
CARRIAGE CONTROL...................................... 2-1
EXAMPLES OF XREAD, XPRNT, XPNCH USAGE................. 2-2
DEBUGGING INSTRUCTION - XDUMP.............................. 2-3
GENERAL PURPOSE REGISTER DUMP......................... 2-3
STORAGE DUMP.......................................... 2-3
EXAMPLES OF XDUMP USAGE............................... 2-3
DECIMAL CONVERSION INSTRUCTIONS - XDECI, XDECO............. 2-4
XDECI................................................. 2-4
XDECO................................................. 2-4
SAMPLE USAGE OF XDECI................................. 2-5
SAMPLE USAGE OF XDECO................................. 2-5
HEXADECIMAL CONVERSION INSTRUCTIONS - XHEXI, XHEXO......... 2-6
XHEXI................................................. 2-6
XHEXO................................................. 2-6
SAMPLE USAGE OF XHEXI AND XHEXO....................... 2-7
LIMIT DUMP INSTRUCTION - XLIMD............................. 2-8
SAMPLE USAGE OF XLIMD................................. 2-8
OPTIONAL INPUT/OUTPUT INSTRUCTIONS - XGET, XPUT............ 2-9
CONDITION CODE........................................ 2-9
CARRIAGE CONTROL...................................... 2-9
EXAMPLES OF XGET AND XPUT USAGE....................... 2-10
PART III. ASSIST CONTROL CARDS AND DECK SETUP.............. 3-1
A. JOB CONTROL LANGUAGE.................................... 3-1
B. OPTIONAL PARAMETERS FOR ASSIST.......................... 3-2
C. DESCRIPTION OF INDIVIDUAL OPTIONS....................... 3-4
PART IV. ASSIST OPTIONAL EXTENDED INTERPRETER.............. 4-1
A. GENERAL DESCRIPTION OF NEW FEATURES..................... 4-1
B. THE XOPC (Assist OPtions Call) DEBUGGING INSTRUCTION.... 4-2
PART V. OUTPUT AND ERROR MESSAGES......................... 5-1
A. ASSEMBLY LISTING........................................ 5-1
1. ASSEMBLY LISTING FORMAT............................ 5-1
2. ASSEMBLER ERROR MESSAGES........................... 5-1
3. LIST OF ASSEMBLER ERROR MESSAGES................... 5-2
4. ASSEMBLER STATISTICS SUMMARY....................... 5-10
B. ASSIST MONITOR MESSAGES................................. 5-11
1. HEADING AND STATISTICAL MESSAGES................... 5-11
2. ASSIST MONITOR ERROR MESSAGES...................... 5-12
C. ASSIST COMPLETION DUMP.................................. 5-13
D. COMPLETION CODES........................................ 5-14
E. OBJECT DECKS AND LOADER MESSAGES........................ 5-15
1. OBJECT DECK FORMAT................................. 5-15
2. ASSIST LOADER USAGE AND MESSAGES................... 5-16
PART I. THE ASSEMBLY LANGUAGE UNDER ASSIST
This section deals with the subset of the standard OS/360
Assembler Language accepted be the ASSIST assembler. Because it
follows the standard very closely, the following describes only
those language features which ASSIST omits or treats differently.
The user should generally consult the previously-mentioned publication
for most of the information on the assembler language. The section
headings and sub-headings in this manual are taken from the IBM
publication, and any sections omitted may be assumed to be the same as
the corresponding sections in the IBM manual.
SECTION 1: INTRODUCTION
Compatibility
With a few possible exceptions, any program which assembles
and executes correctly under ASSIST should do so using the standard
OS/360 software, and should produce the same output as under ASSIST.
At most, a change of Job Control Language might be necessary.
The Assembler Program
The assembler program produces a listing of the source program, and
normally creates an object program directly in main memory, while using
no secondary storage, unless requested. An object deck can be punched.
SECTION 2: GENERAL INFORMATION
General Restrictions on Symbols
A symbol may be defined only once in an assembly, i.e., it may
appear in the name field of no more than one instruction. The
same symbol may not be used as a label in two different control
sections, and control sections may not be resumed, the only case
in the standard language allowing the same symbol on more than one
statement.
Location Counter Reference
ASSIST allows full use of the location counter *, with the
following exceptions:
1. The programmer may not refer to the location counter inside
a literal address constant. Thus, the following statement will
produce incorrect results:
L 1,=A(*+20)
2. The programmer may not refer to the location counter in
an A-type address constant having a duplication factor greater
than one, if the reference is made in such a way that the various
duplications of the specified constant have different values.
For instance, under OS/360, the following statement would produce
the values 0,1,...,255, but ASSIST would produce 256 bytes of
zero:
NAME DC 256AL1(*-NAME)
Literals
Literal constants may not contain more than 112 characters,
counting the beginning = and ending delimiter, i.e. may not require
more than two cards when placed in the literal pool.
Literal Pool
Unless otherwise specified by the use of the LTORG instruction,
the literal pool is placed after the program's END card, rather than
at the end of the first control section in the program.
Expressions
Use of general expressions is permitted for most statements.
Any restrictions are noted under the individual statements.
ASSIST1-6
SECTION 3: ADDRESSING -- PROGRAM SECTIONING AND LINKING
USING -- Use Base Register
The first expression (address) in a USING statement must be
relocatable.
CONTROL SECTIONS
Multiple control sections are allowed. A program must contain
at least one control section.
Control Section Location Assignment
Control sections may not be intermixed under ASSIST, i.e.,
all the statements of one control section must be coded before
another is begun.
FIRST CONTROL SECTION
Under ASSIST, the first control section has no properties
different from the other sections, i.e., its initial location
counter value must be relocatable, and it does not normally contain
unassigned literal constants unless it is the only control section.
START -- Start Assembly
The START instruction may be preceded by listing control
instructions and comments cards. The same label may not be used on a
START statement and a later CSECT statement.
CSECT -- Identify Control Section
No more than one CSECT may use a given symbol as a name,
and statements from different CSECT's may not be interspersed.
DSECT -- Identify Dummy Section
No more than one DSECT may use a given symbol as a name, and
statements from different DSECT's may not be interspersed.
EXTERNAL DUMMY SECTIONS (ASSEMBLER F ONLY)
External dummy sections are not supported, so the commands
CXD and DXD are not recognized.
COM -- DEFINE BLANK COMMON CONTROL SECTION
COM is not allowed.
ASSIST1-7
SECTION 4: MACHINE-INSTRUCTIONS
Instruction Alignment and Checking
If any statement requires alignment and causes bytes to be
skipped, the bytes skipped are NOT necessarily set to hexadecimal zeros.
OPERAND FIELDS AND SUBFIELDS
ASSIST permits the same use of expressions in machine-instruction
operand fields as does the standard assembler.
SECTION 5: ASSEMBLER LANGUAGE STATEMENTS
OPSYN -- EQUATE OPERATION CODE is not accepted.
DC -- DEFINE CONSTANT
Multiple operands (up to 10 operands in a single DC statement)
and multiple constants within operands are both permitted. Bytes
skipped to align a DC statement are NOT zeroed.
Operand Subfield 3: Modifiers
The following modifiers are not permitted by ASSIST:
Bit-Length Specification, Scale Modifier, and Exponent Modifier.
Operand Subfield 4: Constant
Fixed-Point Constants -- F and H:
Fixed-point constants may not contain decimal points or exponents
While lengths may range from one to eight bytes, the minimum and maximum
values permitted are those for length 4.
Floating-Point Constants -- E and D:
No scale or exponent modifiers are allowed, but exponents are
accepted within each constant.
Decimal Constants -- P and Z:
If no explicit length is supplied for an operand containing
multiple constants, each of the operands is assembled to the length
of the last constant in the operand, even if truncation is thus
required. For example, under the standard assembler, the following
needs four bytes. Under ASSIST it is assembled into three bytes,
with the second constant truncated:
DC P'0,20,1'
Address Constants: only A and V address constants are allowed.
Complex Relocatable Expressions: are not allowed.
A-type Address Constant: may not be used in a literal constant
if it refers to the location counter. It will be assembled improperly
if it does so.
Y-Type, S-Type, and Q-Type Address Constants: are not allowed.
ASSIST1-8
CCW -- DEFINE CHANNEL COMMAND WORD
The CCW is recognized and allocated storage, but is not otherwise
assembled. It will be flagged 'NOT CURRENTLY IMPLEMENTED'.
Listing Control Instructions
TITLE -- IDENTIFY ASSEMBLY OUTPUT
No title may have a symbol in the name field.
PRINT -- PRINT OPTIONAL DATA
All operands are accepted, but DATA and NODATA have no effect, i.e.
no more than eight bytes of data are ever printed. Any statement
flagged with an error or warning is always printed, even if the
print control is OFF, or NOGEN for generated statements.
PROGRAM CONTROL INSTRUCTIONS
ICTL -- INPUT FORMAT CONTROL, ISEQ -- INPUT SEQUENCE CHECKING,
PUNCH -- PUNCH A CARD, and REPRO -- REPRODUCE FOLLOWING CARD :
are not accepted by ASSIST.
LTORG -- BEGIN LITERAL POOL
Any literals used after the last LTORG are placed after the
END card, instead of at the end of the first control section.
Duplicate Literals:
Duplicate literals are never stored, since the programmer may
not refer to the location counter in a literal A-type address
constant, the only case under the regular system requiring the
storing of duplicate literals.
COPY -- COPY PREDEFINED SOURCE CODING: is not allowed.
ASSIST1-9
SECTION 6: INTRODUCTION TO THE MACRO LANGUAGE
The macro language is a facility which may or may not be included
in a particular version of ASSIST. Also, various levels of the ASSIST
macro processor can be generated, so that the user should check to see
which one(s) are available at his installation. The following
facilities may be available:
BASIC (F) MACRO FACILITY: allows programmer-written macros, compatible
with Assembler(F), but without macro library or open code conditional
assembly.
EXTENDED (G&H) MACRO FACILITY: like BASIC above, but allows certain
features not supported by Assembler F, but allowed by Assemblers G or H.
MACRO LIBRARY: some versions of ASSIST permit system macros to be used
in addition to programmer-written macros. This facility requires the
use of a special comment card (*SYSLIB), as described later.
OPEN CODE CONDITIONAL ASSEMBLY: system assemblers allow the user to
use conditional assembly statements and SET variables outside macros,
i.e., in the open code, or main body of the program. With certain
restrictions as noted, this facility can be supplied if desired.
Finally, in order to use macros at all, the user must supply the
parameter MACRO= , as described in Part III.
THE MACRO DEFINITION
COPY statements are not allowed.
THE MACRO LIBRARY
Certain restrictions exist in ASSIST's processing of system macros.
One or more *SYSLIB cards must follow any programmer-defined macro
definitions. These cards indicate that library search is required, and
must name any macros which are called from the open code later, but have
not been previously mentioned in the programmer-written macros. The
user should consult the appendix USE OF LIBRARY MACROS in this PART.
SYSTEM AND PROGRAMMER MACRO DEFINITIONS
Since ASSIST reads in system macros and edits them upon command of
*SYSLIB cards immediately following programmer macros, they are treated
exactly the same as programmer macros, except that they are not printed
unless requested by the LIBMC option. Errors are attached to correct
statements.
ASSIST1-10
SECTION 7: HOW TO PREPARE MACRO DEFINITIONS
MACRO INSTRUCTION PROTOTYPE
Two formats are allowed for statements, the normal one used by all
other statements, and the alternate one allowed only for macro prototype
and macro call statements. ASSIST does allow macro prototypes and macro
calls to be continued on an indefinite number of cards. When there are
no more than 2 continuation cards, ASSIST is completely compatible with
other assemblers. If the total number of cards in a statement exceeds
3, the following restriction must be followed: every third card in the
statement must use the alternate format, unless it is the last one.
(This is done because ASSIST processes cards in groups of 3). The two
prototypes below illustrate this restriction:
PROTOTYPE ACCEPTED BY ASSEMBLERS F,G, H, VS, BUT NOT ASSIST:
&LABEL LONGPROT &PARM1,&PARM2, PARMS,ALTERNATE FORMAT X
&PARM3,&PARM4,&PARM5, PARMS,ALTERNATE FORMAT X
&PARM6,&PARM7=XXXXXXXX,&PARM8=YYYYYYYY,&PARM9=ZZZZZZZZ,&X
PARM9=A LAST LINE
EQUIVALENT PROTOTYPE, ACCEPTED BY ASSIST:
&LABEL LONGPROT &PARM1,&PARM2, PARMS,ALTERNATE FORMAT X
&PARM3,&PARM4,&PARM5, PARMS,ALTERNATE FORMAT X
&PARM6,&PARM7=XXXXXXXX,&PARM8=YYYYYYYY,&PARM9=ZZZZZZZZ, X
&PARM9=A LAST LINE
Given this restriction, it is best to place any positional parms
early in the list if they may require long values needing continuation.
MODEL STATEMENTS
Variable symbols MAY be used to generate PRINT and END operations .
If the open code feature is allowed, they may also be used to generate
calls to macros at the outer level, but not inside macros.
COPY STATEMENTS
COPY statements are not allowed.
SECTION 8: HOW TO WRITE MACRO-INSTRUCTIONS
There are no changes from the IBM standard.
ASSIST1-11
SECTION 9: HOW TO WRITE CONDITIONAL ASSEMBLY INSTRUCTIONS
All of the conditional assembly instructions may be used inside
macros. They may only be used outside if the version of ASSIST being
used supports it, and there are restrictions in that use in any case.
ATTRIBUTES
ASSIST is a two-pass assembler, performing macro-processing 'on the
fly' during pass 1. As such, it is impossible for it to usually know
the attributes of a symbol, so there are definite restrictions. In
effect, the only attributes are those which can be found by looking just
at a macro call statement by itself. The attributes allowed are:
Attribute Notation
Type T' only values N, O, and U possible
Count K'
Number N'
Thus, Length (L'), Scaling (S'), and Integer (I') attributes are
not supported. The only values for Type are N (Numeric), O (Omitted),
and U (undefined), so that the value is U under ASSIST in many cases
where it would be something else under IBM assemblers.
AIF -- CONDITIONAL BRANCH
IBM assemblers normally assign 4096 as the usual limit for number
of AIF and AGO branches. See ACTR for the way ASSIST handles this.
The sequence symbol named in the AIF may precede or follow the
AIF statement inside macros. Outside macros, it may only follow the
AIF, i.e., only forward branches are allowed. If a branch is taken to
a previously-defined sequence symbol in open code, ASSIST produces an
an error message and ignores the AIF/AGO.
AGO -- UNCONDITIONAL BRANCH
AGO follows the same restriction as AIF: backwards branches are
allowed in macros, but not in open code.
ACTR -- CONDITIONAL ASSEMBLY LOOP COUNTER
ASSIST supports the standard ACTR. However, the default value of
the ACTR counter is set differently, via the MACTR= option supplied by
the user. This has a default value as given in PART III, which is
normally smaller than the IBM value 4096. The MACTR= value is used for
all macro definitions, unless explicitly overridden via ACTR statements.
CONDITIONAL ASSEMBLY ELEMENTS
There are no changes, except that attributes L', S', and I' are not
supported.
ASSIST1-12
SECTION 10: EXTENDED FEATURES OF THE MACRO LANGUAGE
MNOTE -- REQUEST FOR ERROR MESSAGE
The MNOTE statements accepted by ASSIST follow the standard, but
ASSIST effectively ignores the use of severity codes, except that
MNOTE'S with numerical severity codes are printed as errors while ones
with * are printed in another format.
&SYSECT -- Current Control Section
CSECT or DSECT statements processed in a macro definition do NOT
affect the value for &SYSECT for any subsequent inner macros in that
definition.
MACRO DEFINITION COMPATIBILITY
ASSIST does not accept AGOB or AIFB.
APPENDIX K: USE OF LIBRARY MACROS
This section describes the deck layout and use of *SYSLIB cards
when the user desires to use macros from a system library. Brief notes
are given regarding internal workings of macro processing, in order to
help the requirements be more meaningful.
ASSIST performs all macro-processing during the first pass of its
total of two passes across the source program. Macro processing itself
has two stages. During the EDIT stage, macro definitions are read,
scanned, and printed, while tables are built in memory describing them.
The EXPANSION stage is part of the normal first pass of a two-pass
assembler, so that every time a macro call is encountered, the macro
processor expands the call into 0 or more statements, which then act as
though they had been read in the normal way.
For best use of limited memory, ASSIST requires that ALL EDITING
be done before ANY EXPANSION. During editing of programmer macros,
a list is kept of opcodes not yet defined, and these are presumed to
be system macros. Any system macros called by programmer macros are
therefore known to ASSIST, and so it can fetch them from the library.
However, if a system macro is only called at in the open code, there is
no way for ASSIST to know that it will be needed later. Also, it is
desirable that the user specify whether the macro library should be
searched at all, in order to avoid searching the library for a mispelled
opcode name automatically. Thus, a special comments card, *SYSLIB, is
used to inform assist that it should actually perform library search.
The format of the *SYSLIB card is either of the following:
*SYSLIB name1,name2,...... comments
*SYSLIB
The first form gives a list of 1 or more macro names, seprated by
commas, free format. The second form contains no operands at all.
ASSIST1-13
The second form may be used only when all library macros appear in the
user's macro definitions.
The *SYSLIB card should follow all programmer macros (if any), and
must precede any of the statements of the open code, except for comment
and listing control (PRINT, TITLE, EJECT, SPACE) statements. The user
may supply 1 or more *SYSLIB cards, as long as these conditions are
fulfilled, thus allowing some convenience.
When finding any *SYSLIB card in a proper location, ASSIST does
the following:
1. Scans the card, adding any name found there to the list of macro
names. If the name is already in the list, it is totally ignored.
2. Scans the list of macro names. If a macro is not defined, it
searches the macro library for it. If the macro cannot be obtained,
it marks the macro 'searched for', and never looks for it again.
3. If the macro is found during 2, the print control is turned OFF,
unless the user specified LIBMC, in which case the print control is
unchanged. The macro is then read and edited, like a programmer macro.
4. During step 3, the macro being read may refer to other macros not
yet defined, and these are added to the macro list also. The loop of
steps 2,3,4 continues until all macros in the list have either been
found or searched for. Thus, it is possible for a reference to one
macro to cause a number of macros to be fetched from the library. At
this point, print control is restored to its original value, and a list
of undefined macros is produced.
The following gives the overall layout of a program:
..... 0 or more programmer macro definitions, with print control
statements interspersed if desired.
..... 1 or more *SYSLIB cards
..... 0 or more GBLx declarations (if open code cond. asm allowed)
..... 0 or more LCLx declarations "
..... ACTR "
..... open code (main body of program)
The following shows appropriate *SYSLIB use, although the program
itself should not be expected to make sense:
MACRO
PRGMAC1 &ARG
CALL X
MEND
*SYSLIB SAVE WE WILL NEED SAVE MACRO
*SYSLIB RETURN,EQUREGS OTHER MACROS NEEDED
* CALL (USED IN PRGMAC1), IS NOT NEEDED (BUT COULD BE) ABOVE.
USING *,15
SAVE (14,12)
PRGMAC1
RETURN (14,12)
EQUREGS
ASSIST1-14
HINTS ON OPTIMAL USE OF MACRO LIBRARY
The user should be aware of the following when using the macro
library facility:
1. The macro processor is mainly intended to process programmer-
written macros. Among other things, all macro dictionaries and tables
are kept in memory for the sake of speed.
2. Most IBM macros, and many XMACROS, call inner macros, which call
other inner macros, which call others, etc, etc. Thus, calling one
macro from the library may cause many others to be brought in. In
particular, almost every IBM macro calls the macro IHBERMAC to issue
MNOTE statements for any error messages. IHBERMAC contains over 400
statements, with many memory-consuming MNOTEs included.
3. If a macro is referenced, it is fetched from the library, whether
it is actually ever called or not. For example, IHBERMAC is only called
when there is an error, but is always fetched.
4. Given the combination of 1,2,3 above, it is easily possible to
use macros like CALL, SAVE, RETURN, XSAVE, XRETURN, which do not in
themselves seem large, but exceed memory quickly. (CALL, SAVE, RETURN
all use IHBERMAC; XSAVE and XRETURN contain GETMAIN and FREEMAIN to
support the REEN= option, and GETMAIN/FREEMAIN both call IHBERMAC).
Another example is using ASSIST to check out a QSAM program: ask for
OPEN, CLOSE, GET, PUT, and DCB: ASSIST processes these correctly, but
2700 statements are added to the program by the macros and all of the
inner macros. A simple program can easily require 250K bytes of memory
for assembly, given such macros.
Given the above circumstances, care must be taken with the library
facility in order to make efficeient use of it. Given such care, ASSIST
is fast and small enough to check out fairly large programs in a
'reasonable' amount of memory and time. The following are useful tricks
for saving time and space:
1. WRITE REDUCED VERSIONS OF COMMON MACROS, AND PLACE THEM IN A
SPECIAL LIBRARY, TO BE ACCESSED FIRST BY ASSIST. For example, remove the
REEN option from XSAVE/XRETURN, replace IHBERMAC calls by MNOTEs in
CALL, SAVE, RETURN, etc.
2. USE LIBMC OPTION TO EXAMINE LIBRARY MACROS. WRITE DUMMY MACROS TO
KEEP UNUSED ONES FROM BEING FETCHED. For example, if you know that a
given macro will NOT actually be called, write a dummy, like:
MACRO
IHBERMAC &A,&B,&D,&E,&F,&H
MNOTE 4,'PSEUDO IHBERMAC CALLED: &A,&B,&D,&E,&F,&H'
MEND
3. IF NECESSARY, USE THE DISKU OPTION, IF AVAILABLE. The intermediate
text saved between the two passes can be spilled to disk/drum, thus
allowing more space for macro dictionaries, symbol table, etc.
ASSIST2-1
PART II. INPUT/OUTPUT AND DEBUGGING INSTRUCTIONS
ASSIST accepts as special machine instructions some commands
which are handled by OS/360 as macro-instructions. They essentially
permit the user to read and punch cards, print lines, and dump the
contents of his registers and storage areas. They also provide
easy input/output conversions for decimal numbers.
The following table gives the encodings of the special commands of
ASSIST, which use currently undefined opcodes, and ARE SUBJECT TO CHANGE
AT ANY TIME. In some cases, a Mask field is used to differentiate among
different commands using the same opcode. The notation RX-SS under the
columns for OPERAND FORMAT implies that the first four bytes of the
instruction follow standard RX format, with the Mask field giving the
specific type of operation. The third halfword specifies the length,
which is encoded in the same way as are lengths in Shift instructions,
except the length is taken from register 0 if the halfword is all zero .
EXAMPLES: XREAD 0(1,2),100 ==> X'E00120000064'
XPRNT 2(3,4),(1) ==> X'E02340021000'
COMMAND OPCODE MASK LENGTH OPERAND FORMAT
XDECI X'53' - 4 bytes normal RX
XDECO X'52' - 4 bytes normal RX
XDUMP X'E1' - 6 bytes (register form - no operands) - last
five bytes totally ignored.
XDUMP X'E0' 6 6 bytes (storage form) - RX-SS
XGET X'E0' A 6 BYTES RX-SS
XHEXI X'61' - 4 bytes normal RX
XHEXO X'62' - 4 bytes normal RX
XLIMD X'E0' 8 6 bytes RX-SS
XPNCH X'E0' 4 6 bytes RX-SS
XPRNT X'E0' 2 6 bytes RX-SS
XPUT X'E0' C 6 bytes RX-SS
XREAD X'E0' 0 6 bytes RX-SS
XREPL X'A0' - 4 bytes SI - immediate field gives operation
INPUT/OUTPUT INSTRUCTIONS - XREAD, XPRNT, XPNCH
Basic input/output facilities are provided by XREAD (card READer),
XPRNT (line PRiNTer), and XPNCH (card PuNCH). They are written using
the following format:
label XMACRO area,length
label is an optional statement label
XMACRO is XREAD, XPRNT, XPNCH
area is the address in memory to be read or written.
This area may be specified by an RX-type address, i.e., anything
legal as the second operand of a LA instruction, such as:
0(1,2), AREA2+10, CARD+1(3), or =CL30'0 MESSAGE' .
length specifies the number of bytes to be read or written.
This length can range from 1 to the maximum length for the
appropriate device (80 for XREAD,XPNCH, 133 for XPRNT). The length
field may be omitted, in which case the maximum length is used by
default. It may also be specified as a register enclosed in paren-
theses, indicating that the length will be supplied at execution
time from the designated register.
ASSIST2-2
CONDITION CODE
XPRNT and XPNCH do not change the condition code. XREAD sets the
condition code to indicate normal processing or end-of-file as follows:
CC = 0 - a card was read, and length characters placed in user's area
CC = 1 - end-of-file encountered, no more cards can be read (/* found).
CARRIAGE CONTROL
XPRNT requires that the first character of the area be a valid
carriage control character, such as blank (single space), '0' (double
space, and '1' (new page), or any others which are available.
EXAMPLES OF XREAD, XPRNT, XPNCH USAGE
The following section of a program reads in a deck of cards
until an end-of-file (/* card) is found, punches the last 70
characters of each card into the first 70 columns of each card
punched, and prints some number of characters from each card,
where the number + 1 had been previously loaded into register
5 (the + 1 is for the carriage control character). The cards
are double-spaced on the printer.
READLOOP XREAD CARD read card, using omitted length
BNZ NOMORE if CC=1, branch out. BC 4,NOMORE
or BM NOMORE would also work
XPNCH CARD+10,70 punch 70 bytes, explicit length
XPRNT CARD-1,(5) print number of bytes, using
carriage control
B READLOOP go back for next card to be read
NOMORE EQU * branch here when no more cards
..........more program statements..................
DC C'0' carriage control for printing
card, right before CARD
CARD DS CL80 space for card to be read in
The following statements show how the programmer may easily
produce messages and headings for his output, using XPRNT with
literal character constants or related methods:
XPRNT =CL30'1 A HEADING FOR NEW PAGE',30
XPRNT =CL50' SECOND HEADING IMMEDIATELY UNDER FIRST',50
XPRNT MSG,L'MSG LET ASSEMBLER COMPUTE LENGTH
XPRNT MSGX,MSGXL ASSEMBLER COMPUTES LENGTH WITH EQU
MSG DC C'0 THIRD MESSAGE, SINGLE CONSTANT WITH LENGTH'
MSGX DC C' FOURTH MESSAGE, WHICH INCLUDES A SECTION FILLED IN'
DC C' DURING EXECUTION '
MSGNMBR DS CL12 SPACE FOR DECIMAL NUMBER-XDECO
DC C' END OF IT'
MSGXL EQU *-MSGX MSGXL IS SET TO LENGTH OF MESSAGE
ASSIST2-3
DEBUGGING INSTRUCTION - XDUMP
One basic debugging command is provided, called XDUMP. It can
be used in two different ways, to print either registers or storage
areas:
GENERAL PURPOSE REGISTER DUMP
XDUMP
Coding XDUMP with no operands prints the contents of the user's
general purpose registers, in hexadecimal notation. The registers
are preceded by a header line like the following:
BEGIN XSNAP - CALL # AT CCAAAAAA USER REGISTERS
# is the number of calls made to XDUMP so far, for identification.
CCAAAAAA shows the last 32 bits of the user's PSW, in hexadecimal.
CC gives the ILC, CC, and Program Mask at the time of the XDUMP.
AAAAAA gives the address of the instruction following the XDUMP, and
thus can be used to distinguish between the output of different
XDUMP statements. *NOTE* XDUMP , is the same as XDUMP with no operand.
STORAGE DUMP
XDUMP area,length
Coding XDUMP with an address and length produces a dump of a
user storage area, beginning at the address given by area, and
ending at the address area+length. The operands are specified like
those of XREAD, XPRNT, XPNCH, except the length may not specify
a register, but must be an explicit length.
The resulting output includes a header line like the above,
followed by a hexadecimal and alphanumeric dump of the selected
storage area. The storage is printed in lines showing two groups
of four fullwords, preceded by the memory address of the first
word in each line, and followed by the alphanumeric representation
of the 32 bytes on the line, with letters, numbers, and blanks
printed directly, and all other characters translated to periods.
The storage printed is also preceded by a line giving the address
limits specified in the XDUMP.
If the length is omitted, the value 4 is used as a default.
EXAMPLES OF XDUMP USAGE
XDUMP AREA+10,80
XDUMP 8(1,4),100
XDUMP FULLWORD use default value of 4
XDUMP TABL(3),12
ASSIST2-4
DECIMAL CONVERSION INSTRUCTIONS - XDECI, XDECO
To facilitate numeric input/output, ASSIST accepts the commands
XDECI (eXtended DECimal Input), and XDECO (eXtended DECimal Output).
XDECI can be used to scan input cards for signed or unsigned decimal
numbers and convert them to binary form in a general purpose register,
also providing a scan pointer in register 1 to the end of the decimal
number. XDECO converts the contents of a given register to an edited,
printable, decimal character string.
Both instructions follow the RX instruction format, as shown:
XDEC# REG,ADDRESS
where REG is any general purpose register, and ADDRESS is an RX-type
address, such as LABEL, 0(R4,R5), LABEL+3(2).
XDECI
XDECI is generally used to scan a data card read by XREAD. The
sequence of actions performed by XDECI is as follows:
1. Beginning at the location given by ADDRESS, memory is scanned
for the first character which is not a blank.
2. If the first character found is anything but a decimal
digit or plus or minus sign, register 1 is set to the address
of that character, and the condition code is set to 3 (overflow)
to show that no decimal number could be converted. The contents
of REG are not changed, and nothing more is done.
3. From one to nine decimal digits are scanned, and the number
converted to binary and placed in REG, with the appropriate sign.
The condition code is set to 0 (0), 1 (-), or 2 (+), depending
on the value just placed in REG.
4. Register 1 is set to the address of the first non-digit after
the string of decimal digits. Thus REG should not usually be 1.
This permits the user to scan across a card image for any number
of decimal values. The values should be separated by blanks, since
otherwise the scanner could hang up on a string like -123*, unless
the user checks for this himself. I.e. XDECI will skip leading blanks
but will not itself skip over any other characters.
5. During step 3, if ten or more decimal digits are found,
register 1 is set to the address of the first character found
which is not a decimal digit, the condition code is set to 3, and
REG is left unchanged. A plus or minus sign alone causes a similiar
action, with R1 set to the address of the character following
the sign character.
XDECO
XDECO converts the value from REG to printable decimal, with
leading zeroes removed, and a minus sign prefixed if needed. The
resulting character string is placed right-justified in a 12-byte
field beginning at ADDRESS. It can then easily be printed using
an XPRNT instruction. The XDECO instruction modifies NO registers.
ASSIST2-5
SAMPLE USAGE OF XDECI
The following program segment reads a card, and converts one
decimal value of 1-9 digits punched anywhere on the card, placing
this value in general register R0.
XREAD CARD read card into a workarea
XDECI R0,CARD scan and convert the number
XDECI can be used to convert an unknown number of decimal
values from a card. This can be done by punching the values anywhere
on the card, separated by one or more blanks. The last number
on the card is then followed by a $, which indicates the end of
the data values to the program. The following program reads a card
and converts numbers, storing their values in an array for later
use, and stopping when the $ is found.
SR 2,2 zero for index to first word of NUMBERS
XREAD CARD read cardimage into input area
LA 1,CARD intialize R1 as scan pointer register
LOOP XDECI 0,0(,1) scan and convert next number
BO OVER skip if bad number of $ (BC 1,OVER)
ST 0,NUMBERS(2) store legal value into array
LA 2,4(2) increment index value 1 fullword
B LOOP go back for next number
OVER CLI 0(1),C'$' was this delimiter $
BE DONE yes, so branch out
XPRNT =CL30'0*** BAD INPUT ***STOP',30
DONE ...... more instructions ........
NUMBERS DS 20F space for 20 values to be stored
CARD DS CL80 input workarea
SAMPLE USAGE OF XDECO
The following converts register 4 to decimal and prints it.
It assumes a reasonable value in R4, so that the first character
of OUT is a blank for carriage control.
XDECO 4,OUT convert the number
XPRNT OUT,12 print value
..... other assembler statments .....
OUT DS CL12 typical output area
ASSIST2-6
HEXADECIMAL CONVERSION INSTRUCTIONS-XHEXI, XHEXO
(NOTE: Some versions of ASSIST may not provide these instructions)
XHEXI and XHEXO provide easy conversion of hexadecimal numbers
for input and output. The value of a hexadecimal number can be
read from a card using XREAD, converted from character mode to a
hexadecimal number, and the converted number is placed in the specified
general purpose register with XHEXI. XHEXO provides an easy way
to convert internal hexadecimal to an output form that can be
printed using XPRNT.
XHEXI also places the address of the first non-hexadecimal
number in register one, but if more than eight digits are scanned,
the address of the ninth is placed in register 1.
XHEXI
XHEXI REGISTER,ADDRESS
XHEXI, in the general form shown above where REGISTER is any general
purpose register and ADDRESS is anything legal in an RX instruction, is
used to do the following:
1. Beginning at the location ADDRESS, memory is scanned until the
first non-blank character is found.
2. If the first character found is anything but a legal hexa-
decimal character(0-9,A-F), the condition code is set to overflow
and this address is placed in register 1. If the REGISTER is
anything but register 1, its contents remain unchanged.
3. One to eight hexadecimal characters are scanned, the number
converted to hexadecimal, and the result is placed in REGISTER.
The value placed in the register is internal hexadecimal with
leading zeros included and the number is right justified.
4. Register one is set to the address of the first non-hexadecimal
character. With this in mind, the user should not code register one as
REGISTER. This allows you to scan across the card for any number of
character strings. The strings should be separated by blanks. The end
of the string could be flagged with any non-hexadecimal character and a
test could be made after a Branch Overflow (see sample program).
5. If more than eight hex digits are found, register one is set to
the address of the ninth. This allows the user to scan across long
strings of numbers.
XHEXO
XHEXO REGISTER,ADDRESS
XHEXO in the general form shown above converts the value
in REGISTER and places it in a right-justified 8-byte field beginning at
ADDRESS. It can be easily printed using an XPRNT instruction. The XHEXO
instruction modifies NO registers.
ASSIST2-7
SAMPLE PROGRAM USING XHEXI AND XHEXO
This program reads a data card with an unknown number of hexa-
decimal numbers on it. The end of the data is denoted by a '%' punched
after the last number. The numbers are stored after being converted
using XHEXI, and then converted for output using XHEXO.
LA 3,STORAGE WHERE NUMBERS STORED
XREAD CARD,80 READ IN CARD
XPRNT CARD,80 ECHO PRINT
LA 1,CARD ADDRESS OF CARD FOR SCANNING
LOOP XHEXI 2,0(1) CONVERT NUMBER PUT IN 2
BO ILLEGAL CHECK FOR END
XHEXO 2,AREA PUT NUMBER IN OUTPUT AREA
XPRNT REP,28 PRINT CARD AND MESSAGE
ST 2,0(3) STORE NUMBER
LA 3,4(3) INCREASE INDEX
B LOOP GET NEXT NUMBER
ILLEGAL CLI 0(1),C'%' SEE IF END OF STRING
BE DONE YES DONE
XPRNT =CL50' ILLEGAL CHARACTER STOP',50
DONE ....MORE INSTRUCTIONS.....
CARD DC 81C' ' STORAGE FOR CARD
STORAGE DS 20F STORAGE FOR NUMBERS
REP DC C' THE NUMBER IN R2 IS'
AREA DC CL8' ' STORAGE FOR OUTPUT NUMBER
ASSIST2-8
LIMIT DUMP INSTRUCTION - XLIMD
In order to conserve output records when necessary (for instance,
when ASSIST is being used from a remote terminal of any sort), the
XLIMD instruction is provided to enable the user to limit the size of
his completion dump and choose the area to be printed. In general,
it is used to eliminate the user's program code, leaving only his
data areas in the completion dump.
The instruction is coded as follows:
XLIMD area,length
area is the beginning address where the completion dump should start.
The area address is specified by an RX-type address, and must
be within the user program area.
length is the length in bytes of the area the user wishes to be
printed if a completion dump occurs.
Note that the XLIMD instruction format is exactly the same as that
for the instructions XREAD, XPRNT, XPNCH. Thus the length may be
given as a register number, enclosed in parentheses, or may be omitted,
in which case a length of 1 is assumed. If the combined area address
plus the length yields an address greater than the highest user
address, or if the length is 1, the highest user address is used
as an upper limit instead. Thus, storage will be printed to the end
of the user program.
The suggested method of using XLIMD is to place all variables at
the end of the program, then execute an XLIMD with an area address
specifying the first variable desired, and omitting the length. This
will cause the storage to be printed starting at the specfied address
and going to the end of the program.
SAMPLE USAGE OF XLIMD
The following program gives a typical way of using XLIMD.
DUMPTEST CSECT
USING *,15
XLIMD VARIABL1 set dump limit right away
..........
large number of machine instructions
..........
VARIABL1 DS D first variable area
..........
variable areas likely to be required for debugging
..........
END
XLIMD may be executed any number of times during a program, but
it is suggested that it be called early in any large program, if there
is any possiblity that record limits could be exceeded.
ASSIST2-9
OPTIONAL INPUT/OUTPUT INSTRUCTIONS - XGET AND XPUT
These instructions are similar to XREAD/XPRNT/XPNCH,
but are more general, allowing the user to specify any
filename to be read or written. WARNING: not all versions
of ASSIST support these instructions. Also, a particular
version may only support a specific set of file names,
which can differ from installation to installation. It is
advisable to check on local procedures. The instructions
are coded as follows:
label xmacro area,length
label is an optional statement label
xmacro is either XGET or XPUT
area is the address in memory to be read or written.
This area may be specified by an RX-type address, i.e., anything
legal as the second operand of a LA instruction, such as:
0(1,2),AREA2+10,card+1(3), or =CL30'0 MESSAGE' .
length specifies the number of bytes to be read or written.
This length can range from 1 to the maximum length for the
appropriate device (80 for cards, 133 for printer, etc.). The length
field must not be omitted. it may also be specified as a register
enclosed in parentheses, indicating that the length will be supplied
at execution time from the designated register.
If during execution, the length has a value of zero, the
file will be closed.
NOTE: During execution, register 1 must point to an eight byte
character string which is the name of the file to be manipulated.
CONDITION CODE
XGET and XPUT both change the condition code as follows:…
CC=0 - normal input/output occurred
CC=1 - XGET ONLY - end of file occurred
CC=2 shows an error (like invalid data address) which causes
individual operation to be ignored.
CC=3 shows that the file could not be opened (because it is
wrong direction,or DD card missing, or not enough room in
tables, etc.).
CARRIAGE CONTROL
XPUT only requires the first character of the area to be a
valid carriage control character, if the output device is the printer.
CLOSING OF FILE
Performing an XGET or XPUT with a length of zero supplied in any GP
register causes the designated file to be closed, so that it may then
be reread; I.e. LA 1,=CL8'ddname' SR 0,0 XGET area,(0) does close.
ASSIST2-10
EXAMPLE OF XGET AND XPUT USAGE
The following program will read and write a few files
in parallel.
TEST1 CSECT
BALR 12,0
USING *,12
SR 0,0
*
* THIS PROGRAM WILL PROCESS A FEW FILES IN PARALLEL:
*
LOOP LA 1,=CL8'CARD' point to an input file
XGET AREA,80 do the input
BNE DONE branch on endfile,
* file automatically closed
XREAD AREA2,80 do normal input
LA 1,=CL8'PAPER' point to a printer file
XPUT AREA-1,81 do output, note carriage control
LA 1,=CL8'PAPER2' point to other printer file
XPUT AREA2-1,81 do output on other file
B LOOP try again
DONE BR 14 RETURN, IMPLICITLY CLOSE OTHER FILES
DC CL1' '
AREA DS CL80
DC CL1' '
AREA2 DS CL80
END
The extra JCL for the above is as follows:
//DATA.PAPER DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133)
//DATA.PAPER2 DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133)
//DATA.CARD DD *
THIS STUFF IS READ
AT THE SAME TIME AS ANOTHER
FILE IS READ
****** THE LAST CARD *******
//DATA.INPUT DD *
THIS IS THE NORMAL INPUT FILE
AND IS READ AT THE SAME TIME AS ANOTHER FILE
IS READ
********* THE LAST CARD *********
NOTE: a common usage for XGET might be to access files of test
data.
ASSIST3-1
PART III. ASSIST CONTROL CARDS AND DECK SETUP
A. JOB CONTROL LANGUAGE
Depending on the type of ASSIST desired at a given installation,
one or two different types of deck setup can be used.
SINGLE RUN DECK SETUP - NOBATCH
This setup is suitable for individually-submitted jobs, and allows
the most flexibility in job handling. It is as follows:
1) // a JOB card - installation dependent
2) // EXEC ASACG
3) //SYSIN DD *
4) ..... 360 assembler source deck, or ASSIST object deck
5) /*
6) //DATA.INPUT DD *
7) ..... data cards to be read by user program
8) /*
If the programmer has no data to be read, items 6), 7), and 8)
should be omitted. The programmer specifies optional parameters by
adding ,PARM='option,option....' after ASACG on the EXEC card.
BATCH RUN DECK SETUP
This type of run is recommended if a number of jobs is to be given
as a batch to ASSIST, and is best for low overhead. Each separate
program in the batch must be set up as follows:
Col 1 Col 8 Columns 16-80 of card
' ' '
1) $JOB ASSIST list of options, separated by commas. The first
of these may be an account number, which is
ignored by ASSIST. All others are optional.
2) ..... 360 assembler source deck, or ASSIST object deck
3) $ENTRY (this card must be present if user execution is
to occur, regardless of existence of data.)
4) ..... data cards to be read by user program (optional)
If the user desires only an assembly of his program, the $ENTRY
card should be omitted. As many of the above can be included in one
batch submitted to ASSIST, with BATCH and other appropriate parameters
supplied to ASSIST in the invoking PARM field. The batch can be ended
in one of two ways: either an end-of-file indicator, or a card with
the following in columns 1-5: $STOP .
The entire batch of runs is run with whatever enclosing Job
Control Language is required for a given installation by specifying
BATCH in the invoking PARM field. All versions of ASSIST can run BATCH
programs, but not all can run them with the SINGLE RUN DECK SETUP.
A sample BATCH run is given below:
// a JOB card
// EXEC ASACG,PARM='BATCH,other options, if any'
//SYSIN DD *
$JOB ASSIST ACCT1,options
....... more jobs, each beginning with $JOB cards
/* (or a $STOP card)
ASSIST3-2
B. OPTIONAL PARAMETERS FOR ASSIST
ASSIST provides a large number of options to control the actions
it performs. These options are of two types: the first kind show yes/no
values and are coded as a specific name, with or without a preceding NO.
Every option has a default value, and some of the numerical ones have
upper limits which can never be exceeded.
Each parameter can possibly be given values from at most four
different sources, which are as follows:
1. LIMIT/DEFAULT - absolute upper limits on some numerical options,
and default values for some others. (defined inside ASSIST)
2. INVOKING PARM - values for any of the options. (EXEC CARD PARM
field, or PARM supplied by another program calling ASSIST)
**NOTE** this is not available under DOS/360.
3. $JOB CARD PARM - values for some of the options, if desired,
only possible if LIMIT/DEFAULT or INVOKING PARM specified BATCH.
4. DEFAULT - default values for the numerical parameters having upper
limits, only used if values not specified in 2. or 3. (defined
inside ASSIST)
For any assembly-execution-dump cycle of ASSIST (i.e., one program)
the above sources of information are processed in the order given above,
subject to the following rules:
1. Some options can be supplied values only from certain sources.
2. Certain numerical parameters can never be increased beyond any
previous setting from any source. This particularly applies to
time, records, and pages limits.
3. In most cases, if the same option is coded several times in the
same information source, the last value is used, subject to rule 2.
It is possible that some values cannot be reset once set anywhere.
4. DEFAULT values are used only if they are not coded in either the
INVOKING PARM or $JOB cards, i.e., they override only LIMIT/DEFAULT
values. This construct allows for both limit and default values
for the numerical options.
SAMPLE USAGE OF OPTIONAL PARAMETERS
1) // EXEC ASACG,PARM='T=3.5,R=200,NERR=10,RELOC,CMPRS'
2) // EXEC ASACG,PARM='BATCH,CPAGE,T=5,TX=2,P=20,PX=5,RX=315,SSD'
//SYSIN DD *
$JOB ASSIST ACCT#,PD=1,TD=0.05,CMPRS,SS,SSX
(this job crams output onto fewest possible pages)
.............
$JOB ASSIST ACCT#,PD=0,TD=0,RD=0
(this is a debugged program-saves no pages,time,
or records for the dump-gets maximum output).
.............
$JOB ASSIST ACCT#,OBJIN
............. (object deck)
The above examples show a typical single job run and a typical
batch of jobs.
ASSIST3-3
CHARACTERISTICS OF PARAMETERS
The following lists the available options, including the default
values, sources from which each can be specified, and brief notes on
the purpose of each. Each option is described in detail in the next
section. ASSIST can be generated not to allow certain options, and
these are flagged to show whether they can be omitted or not.
KEY
# under FROM column notes that the option CAN be set from the source,
i.e., 1=LIMIT/DEFAULT, 2=INVOKING PARM, 3=$JOB PARM, 4=DEFAULT.
N under N column indicates a numerical parameter which cannot ever
be increased from any previously set value.
O under O column indicates an option which can be omitted from a
particular generation of ASSIST (to save space, for instance).
PARM FROM N O DEFAULT PURPOSE
NAME 1234 VALUE AND USAGE
------------------------------------------------------------------------
ALGN 1234 O ALGN suppress alignment specification errs
BATCH 12 NOBATCH indicate a batched-type run
CMPRS 1234 O NOCMPRS compressed source list,2 cols/page
COMNT 12 O NOCOMNT require percentage of commented cards
CPAGE 12 O NOCPAGE control paging and page counting
DECK 1234 O NODECK punch object deck
DISKU 123 O NODISKU intermediate disk storage used
DUMP= 1234 0 controls type and size of dump
FREE= 12 4096 bytes returned to system for buffers
I= 1234 150000 maximum # instructions for user prog
KP= 1234 O 029 type of keypunch used (026 or 029)
L= 1234 N O 63 maximum lines/page if CPAGE on
LIBMC 1234 O NOLIBMC allow library macros to be printed
LIST 1234 LIST produce source listing of assembly
LOAD 1234 LOAD produce object program and run it
MACRO= 1234 O N allows use and types of macros
MACTR= 1234 N O 200 default value of MACRO ACTR
MNEST= 1234 N O 15 maximum nest level for macro calls
MSTMG= 1234 N O 4000 maximum total macro stmts processed
NERR= 1234 0 maximum # errors permitting execute
OBJIN 1234 O NOOBJIN object deck input rather than source
P= 1234 N O 10 total run page limit if CPAGE on
PD= 1234 N O 1 page limit for dump if CPAGE on
PUNCH 12 O PUNCH select real punch, or print simulated
PX= 1234 N O 5 execution+dump page limit, if CPAGE
R= 1234 N 10000 output record limit (lines+cards)
RD= 1234 N 25 records saved for dump
RELOC 1234 O NORELOC relocate to real address,store-protec
REPL 1234 O NOREPL assembler replacement run
RFLAG= 1234 O 0 replace option flag (only if REPL on)
RX= 1234 N 10000 execution+dump record limit
SS 1234 O NOSS single space assembly (only if CPAGE)
SSD 1234 O NOSSD single space dump (only if CPAGE)
SSX 1234 O NOSSX single space execution(only if CPAGE)
T= 1234 N O 100 total run time, seconds
TD= 1234 N O .1 time in seconds saved for dump
TX= 1234 N O 100 time in seconds for execution+dump
XREF= 1234 O (0,3,3) requests cross-reference
ASSIST3-4
C. DESCRIPTION OF INDIVIDUAL OPTIONS
This section describes each of the options which may be available
under ASSIST. Refer to the previous section for default values and
other information regarding the usage of these options.
ALGN/NOALGN
Use of the NOALGN option allows the user to suppress specification
interrupts caused by improper alignment of operands. This is useful
when using a S/360 computer to simulate a S/370, which may of course use
data on any boundaries for many opcodes. Not every ASSIST allows this.
BATCH/NOBATCH
The BATCH option allows multiple jobs to be run in one invocation
of ASSIST. It is described in Part III.A. of this manual.
CMPRS/NOCMPRS
The CMPRS option (CoMPReSsed output) produces an assembly listing
which is approximately half as long as a standard listing. This is
done by removing the ADDR1 - ADDR2 fields and printing only columns
1-40 of each statement. While the listing produced is not as readable
as the standard one, this option is particularly recommended for remote
terminal usage, since programs are printed nearly twice as fast. It
does, however, increase the amount of dynamic storage required to run.
COMNT/NOCOMNT
The COMNT option causes the machine instructions of the program to
be checked for the presence of comments (4 or more nonblank characters
in the comment field). If less than 80 percent of those statements have
comments, a message is printed and the program is not executed. Some
instructors may require this option on programs to be handed in, and it
is possible that some account numbers may imply this option whether the
programmer codes it or not.
CPAGE/NOCPAGE
If NOCPAGE is used, no limits exist on the number of pages printed,
and lines are printed with whatever carriage controls are specified.
Coding CPAGE enables the usa of the following options: L=, P=, PD=, PX=,
SS, SSD, and SSX, all of which are totally ignored otherwise. Briefly,
a page may be declared to have a maximum number of lines (L=), and
limits given for the pages printed during various stages of a run. The
SS options then allow the maximum number of lines to be printed in a
given number of pages by removing some carriage control characters from
the printed output (such as page and multiple line skips).
DECK/NODECK
Coding DECK causes ASSIST to punch an object deck of the user
program, assuming that the number of errors did not exceed the NERR=
option, that the version of ASSIST in use has a card punch, and that
none of the following options were specified also: NOLOAD,NOPUNCH,OBJIN,
or REPL. The deck punched is described in PART IV.E.1 of this manual.
Note that this option should not be used for large programs, since
every byte of storage of the user program is punched, 56 bytes per card,
even if the storage was reserved by DS or ORG commands. Note that the
deck, while resembling standard S/360 object decks, cannot really be
used for any purpose but to read back into ASSIST later. The user is
also cautioned to be careful about using DECK with the RELOC option.
ASSIST3-5
DISKU/NODISKU
Coding DISKU causes the ASSIST assembler to place the pass1 output
on intermediate disk storage. Pass2 then recovers the pass1 information
from disk to use in the production of object code into ASSIST's dynamic
work area. Assuming ASSIST is generated with the user controlled DISKU
/NODISKU option, it is possible to assemble much larger programs with
ASSIST using the DISKU option. DISKU has no effect when coded with OBJIN
and is compatible with any other combination of parameters.
DUMP=
This option controls the size of the dump printed on any error
termination during program execution. If DUMP=0, a full dump is given.
This includes a PSW, completion code, instruction trace, general-purpose
and floating-point registers, and all contents of the user program's
storage area. If DUMP=1, ASSIST omits the contents of user storage.
FREE=
ASSIST normally acquires the largest single block of space
in its region for a dynamic workarea, then releases part of that
area back to the operating system for buffers and other uses.
The default is 4096 bytes returned, but the value of FREE= is
used if supplied, in case tape input or output is required, or
if extra space is required for the user program. If the value
of FREE= is greater than the total obtained, it is ignored, and
no space is returned. ****NOTE*** THIS OPTION WILL PROBABLY BE NEEDED
BY ANYONE USING BLOCKED INPUT FROM TAPE OR DISK.
I=
This parameter provides a limit on the number of instructions which
which can be executed by the user program during its execution. If this
limit is exceeded during execution, a message and a completion
dump are printed. This is the recommended and most economical
way to prevent infinite loops during user program execution. A limit
for execution time may also be used to terminate loops (TX=).
KP=
KP=26 specifies that an 026 keypunch was used to prepare the job,
while 29 specifies an 029 keypunch. Leading zeroes are permitted, and
any value except 26 implies an 029 keypunch.
L=
This is used to specify the maximum lines per page, and is only
enabled if the CPAGE option is turned on.
LIBMC/NOLIBMC
Coding LIBMC permits macros fetched from libraries to be printed
if desired. Only effecitve when MACRO= is supplied to an ASSIST which
supports macro libraries. See also MACRO=, and APPENDIX K of PART I.
LIST/NOLIST
Coding NOLIST suppresses the printing of the assembly listing, and
can be used for relatively bug-free programs. However, regardless of the
current print status, any statement flagged with an error or warning
message is always printed.
ASSIST3-6
LOAD/NOLOAD
Under most circumstances, a programmer usually wants to execute his
assembler program. If he just wants to check it for errors, but
not execute it, the NOLOAD option can be coded. This will result
in slightly faster assembly times. In addition, it will require
less space in memory, and it may be possible to assemble a program
under NOLOAD that cannot be assembled with the LOAD option.
MACRO=
This option notes whether macro processing is to be done, and if
so, what language facilities are to be allowed. The values allowed are:
MACRO=N NO macro processing: used if error in option
MACRO=F F-level Assembler compatibility (basic facility)
MACRO=G G-level Assembler features added, if available
MACRO=H H-level Assembler features added, if available
If macros or conditional assembly are to be used, the user MUST specify
something other than MACRO=N. See also APPENDIX K of PART I.
MACTR=
This provides a default value for the starting ACTR counters in all
macros used. It can be overridden by explicit ACTR statements.
MNEST=
This gives a limit on the maximum level of nested macro calls, thus
allowing prevention of unwanted recursion in macros.
MSTMG=
This provides a global limit on the total statements processed in
all macro expansions. It is like ACTR, but counts all statements in all
macros, rather than being local to a macro. It can be used to prevent
macro looping which causes storage to be exceeded.
NERR=
This option is used to allow a program to execute even though
there are errors in it. If omitted, the value is assumed to be zero,
i.e., the program is not executed if there are any errors at all in it.
If NERR=10 is used, the program runs if it has 10 errors, but does not
run if there are 11. Note that warning messages are not included in
this count, only actual error messages.
OBJIN/NOOBJIN
Coding OBJIN informs ASSIST that an object deck is being supplied
to it in place of the usual assembler source deck. This is allowed in
every case, unless REPL is coded, in which case OBJIN is ignored. The
format required of the object deck is given in PART IV.E.1.
The ASSIST loader reads the object deck until an end-of-file or
ASSIST control card is found, producing an object program in memory
which is then treated exactly as though the source program had been
just assembled there. The loader also issues various messages of the
form AL###, which are explained in PART IV.E.2. The user should read
all of PART IV.E. before using the OBJIN option, since there are a
number of restrictions which must be noted before using object decks
as input to ASSIST. In general, a single ASSIST-produced deck should
almost always be workable, a single deck produced by the standard
system assembler, or multiple decks of any sort may be usable if they
were created following certain conventions. Decks requiring symbolic
linkage among control sections will definitely NOT run correctly.
ASSIST3-7
P=
This gives the maximum number of pages (with L= lines per page)
which are permitted for a complete job (or from one $JOB card to the
next, if BATCH is used). It is only meaningful if CPAGE is on. The
entire process of page counting (which also involves values of PD= and
PX= ) is summarized as follows:
1. As described in PART III.B, the value of P= is calculated before
ASSIST prints anything for the job. ASSIST prints the beginning of the
header line, followed by the PARM field, or the $JOB card, and then
assembly begins. If the p= value is exceeded during assembly, the job
is halted at that point.
2. If the user program assembles successfully and is to be executed,
a page limit is calculated for execution plus dump. The total for these
two phases is set to the minimum of the PX= option and the number of
pages remaining from before.
3. A temporary limit for user program execution alone is calculated
by subtracting the value of the PD= option, thus reserving that number
of pages for a dump. User program execution occurs, and may be
terminated if the temporary page limit is exceeded.
4. After execution, the PD= value is added to the current pages
remaining counter, and the dump begun. The dump continues until it is
completed or it runs out of pages.
Note A. At steps 3 and 4 the lines remaining count is just carried
forward, so that the user gets the benefit of any partial pages.
Note B. For REPL runs (assembler replacement), step three is performed
twice, once for the replacement program, and once for the program it
assembles (if execution is desired for it). Since a dump of the
replacement program does not occur during the user dump phase, it is
recommended that no pages be saved for it (i.e., PD=0).
Note C. Any process which can be halted by exceeding page count can
also be halted by exceeding record limits (see R=), or time limits (see
T=), and for user program execution, exceeding instruction count limit
(see I=).
PD=
This option specifies the number of pages which should be reserved
for the user completion dump phase. It is effective only if CPAGE is
on, and is used in conjunction with P= and PX= ( see explanation under
P=). Typical values are as follows:
PD=0 saves no pages for dump. Good for debugged programs.
PD=1 even if the program loops printing, this allows enough
information to determine what the program was doing. If SSD
is coded, about 1K of storage can also be seen.
Note that the PD= value does not restrict a dump to that size,
so that the user also gets up to the PX= value for execution plus dump
together, even if the entire amount is used to provide the dump.
PUNCH/NOPUNCH
Use of the NOPUNCH parameter causes the system to print any output
from XPNCH instructions, rather than punching them. Each cardimage is
preceded with the characters ' CARD-->' to distinguish it from other
printed output. This option is useful for testing punching programs.
Versions of ASSIST with no punch treat all attempted punching this way.
ASSIST3-8
PX=
This gives the maximum number of pages for both user program
execution and completion dump phases together. It is effective only if
CPAGE is on. See description under P=.
R=
This value specifies the maximum number of output records (lines
printed + cards punched) allowed for the entire run. Record counting
is always performed, and the entire process resembles that of page
counting (see P=), and occurs in parallel with any page counting. The
parameters R=, and RX= are used just as are P=, PX=, and PD=, with
records substituted for pages. One possible difference is in ASSIST
systems with special record control type 2 (see header description -
PART IV.B.1.a.). In this case, the initial record remaining count is
also determined by the number of records actually left (if this value
can be obtained from the operating system). This value is used rather
than the default value if the user did not specify R= on the EXEC card
or $JOB card. As in Note B. under P=, use RD=0 for replacement runs.
RD=
RD= the number of output records reserved for a user completion dump
It is used in conjunction with R= and RX= in the same way that PD= is
used with P= and PX=. RD=0 is appropriate for well-debugged programs,
and RD=25 is probably the most reasonable value for most runs, as it
saves enough for a partial dump under all conditions.
RELOC/NORELOC
Under NORELOC a user program is assembled with a location counter
beginning either at 0 or the value on a start card, and the program is
executed as though it were actually loaded at whatever addresses are
given on the assembly listing. Maximum debugging checking is provided
by this mode, as the user may not branch, store, or fetch outside the
area of his program.
RELOC in effect inserts a start card at the beginning of the source
program which specifies the actual location in memory at which the user
program will be assembled. When the program is executed, fetch
protection is eliminated, which the execution-time relocation value
of zero, allows the user program to examine any areas of storage in the
computer (for example, to trace system control blocks). RELOC mode is
implied if REPL is coded.
REPL/NOREPL
REPL notes that the user supplies two source programs, of which the
first is a replacement for one of the modules of the ASSIST assembler,
and the second is a test program, to be assembled using the replacement
program. This optional feature is described in detail in the ASSIST
ASSEMBLER REPLACEMENT USER'S GUIDE.
RFLAG
This option specifies an initial value for the replace control
flag, it is meaningful only if REPL is coded, and is described in the
ASSIST ASSEMBLER REPLACEMENT USER'S GUIDE.
ASSIST3-9
RX=
This gives the total number of output records for user program
execution and dump together (see R=). It corresponds to PX= for page
control, and is used in the same way.
SS/NOSS
This option is effective only if CPAGE is on, and is useful for
reducing the number of pages printed for a given number of lines output.
Using SS essentially converts all carriage controls to single space
commands, except for page skips, which become double spaces, and no
spaces, which are unchanged. SS is effective during the assembly phase,
SSX during user program execution, and SSD during a completion dump. The
carriage control conversions are as follows:
'1' (page skip) becomes '0' '+' (overprinting) remains '+'
'-' (triple space) becomes ' ' ' ' (single space) remains ' '
'0' (double space) becomes ' ' any other character becomes ' '
SSD/NOSSD
SSD is the SS option during completion dump (see SS above). Using
SSD allows a partial dump plus 1K of storage to be printed on 1 page.
SSX/NOSSX
SSX is the SS option during user execution (see SS above).
T=
This gives a limit in seconds on the total time allowed for a run.
The handling of the three time limits (T=, TX=, and TD=) is exactly
analogous to that for pages (see P=) and records limits. The values
are coded as integer values of seconds, or with fractional values up to
three digits, thus allowing for millisecond specifications. As shown
in Note B. under P=, TD=0 should be used for replacement runs. The
appropriate times used depend on the model of machine being used, with
the following times being appropriate for student runs on a 360/65:
T=5,TX=5,TD=1.
Some versions of ASSIST may contain NO timing code at all (option
0), and some may contain special option 2. In the latter case, ASSIST
obtains a time remaining estimate from the operating system and uses it
rather than the default if the user specifies no time limit himself.
The user may examine the ASSIST header to determine which type of ASSIST
is being used (see PART IV.B.1.a).
TD=
This supplies the time remaining for a user completion dump, and
should generally be set to a large enough value to permit at least a
partial dump to be given, thus showing the user the instructions being
executed, especially if a loop is occurring. TD=0 is appropriate for
debugged programs, which can then use all possible time for execution.
TX=
This value is the total time in seconds for user program execution
and dump together. It controls time in the same way that PX= controls
pages and RX= controls output records (see P= for description of
the process of control values computation).
ASSIST3-11
XREF=
This option provides a short, but informative cross-reference
listing following the assembly listing. Among other things, it does
distinguish between two types of references. A MODIFY reference is any
one in which a symbol is used in a machine instruction field denoting an
operand to be modified: ST 0,X for example. All other references
are considered FETCH references: B X , L 0,X , DC A(X) . The
cross-reference output shows a symbol, its value, and statement numbers
of referencing statements, with MODIFY references flagged as negative
statement numbers. Conrol of the output is obtained both by the XREF=
option, and by *XREF cards inserted in the source program as desired.
The latter permit explict control of how references are gathered.
A brief note on the XREF mechanism is necessary to make use of the
flexible control provided. During Pass 1 of an assembly, the SD (symbol
Definition) flag is attached to each symbol as it is defined. The flag
consists of two bits (M for Modify and F for Fetch, in that order), and
shows for each symbol what kinds of references may possibly collected.
For example, SD=10 indicates that no Fetch references are ever to be
printed for a specific symbol. The SD flag may be changed during a
program by *XREF cards, so that symbols in different sections of the
program can be treated differently: SD=00 will eliminate all following
symbols completely, until it is changed again.
During Pass 2, a Symbol Reference (SR) flag is used to determine
what types of references are being collected from the code. A reference
to a symbol is logged if and only if the SD bit and the SR bit for the
given type of reference are both on. I.e., if SD=10 for a symbol, SR=11
at the current time, and a fetch reference is made, no reference will be
logged, since the SD Fetch bit is 0. Note that references are only
logged during Pass 2: some symbol references occur only during Pass 1,
and these are ignored, such as sumbols in EQU, ORG, and DC and DS
length modifiers or duplication factors.
The XREF parameter requests a cross-reference, indicates the type
of output produced, and possibly gives initial values to the SD and SR
flags. Two forms are permitted as follows:
XREF=a OR XREF=(a,b,c) WHERE
a: indicates overall control and output format:
=0 no cross-reference is generated.
=2 cross reference is printed, with one symbol per output line.
=3 cross reference is printed, but with minimal output wasted (more
than one symbol may appear on a line- this form is recommended).
b: initial value of SD flag, in decimal corresponding to binary, i.e.
0: 00, 1: 01, 2: 10, 3: 11.
c: initial value of SR flag, same format as b.
Illegal values are ignored, and it is allowable to omit items as
desired, showing this by comma usage: XREF=(2,,2) for example. The
default value is XREF=(0,3,3) so that all that is needed to obtain a
complete listing is to code XREF=2 or XREF=3, as the other values are
not changed or zeroed.
ASSIST3-12
The SR and SD flags may be changed at any time during the program,
by placing *XREF comment cards anywhere in the source program following
the first machine instruction or assembler opcode used (SD options used
before these will work, but SR's will be ignored). The format is:
*XREF one or more blanks OPTION1=value1,OPTION2=value2,.....
The operand(s) may be specified in any order, and if the same
option is used several times, requested actions are performed in order.
The options are:
SD=<M><F> give the modify and fetch bits for the SD flag.
SR=<M><F> give the modify and fetch bits for the SR flag.
Possible values for <M> and <F> are:
0: turn bit off.
1: turn bit on.
*: leave bit in previous state.
If an <F> specification is omitted, this is equivalent to a *.
It is suggested that the user begin by just specifying XREF=2 or 3
and then cutting out unnecessary references later. Although complex,
the facilities allow unwanted output to easily be eliminated. The
following gives as example (assumed to be a large program):
*XREF SD=10 following symbols will have only modify refs.
..... large number of DS and DC statements (global table, for example).
*XREF SD=*1 add modify and fetch references both.
..... more symbols in DSECTS, tables, etc.
*XREF SD=00,SR=10 collect no references to symbols defined from
here on, collect modify references created.
..... section of code referencing tables above.
*XREF SD=11,SR=11 collect all references from following code to
2nd part of table, modify references to first
part, and all references to itself.
..... section of code referencing tables.
ASSIST4-1
PART IV. ASSIST OPTIONAL EXTENDED INTERPRETER
A. DESCRITPION OF NEW FEATURES
The ASSIST Optional Extended Interpreter is a seperate control
section which can replace the original ASSIST interpreter if certain
additional program debugging features are desired. These features
include additional pseudo instructions, extra program statistics,
extra abnormal termination completion information, a facility allowing
the programmer to change machine emulation during execution, an
instruction trace facility, an instruction counting facility and a
larger subset of S360/S370 instructions. The ASSIST interface with
the interpreter (Econtrol Block) has been extended but upwards
compatibility with the entire assist system is maintained.
The ASSIST Optional Extended Interpreter is somewhat larger
and executes slightly slower than the original Assist interpreter.
This is caused by the extensively table-driven nature of the extended
interpreter and the addition of all of the new features.
ASSIST4-2
B. THE XOPC (OPTIONS CALL) DEBUGGING AND ANALYSIS INSTRUCTION
The OPtions Call pseudo-instruction can provide the user
programmer with several functions: 1). Set a type of 'SPIE' in
ASSIST, giving the user the capability to process specified execution
time interrupts, 2). Trace instructions as they are executed, 3). Check
which areas of storage are being modified by which instructions, 4).
Purposely cause an execution time interrupt when a certain number of
instructions have been executed, 5). Control Boundary Alignment
Checking - Turn off and on the allowance of S0C6 alignment interrupts,
and 6). Count and print statistics of the number of instructions
executed between two specified addresses. The flexibility of this
instruction is brought about by its similarity in format to the s360-
s370 Supervisor Call Instruction (SVC).
The XOPC instruction is of the RR type. Its general format
is as follows:
--------------------
| 01 | I1 |
--------------------
0 8 15
The number residing in the second byte of the instruction
controls which specific XOPC instruction will be executed. Up to 256
(0-255) different instructions can be executed using XOPC. However,
at present only 23 XOPC instructions are implemented.
There is very little error checking involved with the inter-
pretation of the XOPC instruction. The condition code is used to tell
the user programmer about XOPC instruction errors and is set during
execution of the instruction as follows:
CC = 0 Instruction is valid
CC = 1 Illegal or Incorrect Argument(s) used.
CC = 3 Specified code number is not implemented.
When a specified XOPC instruction is found to be in error, the condition
code is set as described above, and the instruction execution is
ignored. No other error checking is provided. It should be noted that
XOPC instruction errors cannot cause execution time interrupts
(ABENDS).
Below is a description of the 23 XOPC instructions presently
implemented.
ASSIST4-3
XOPC 0 - SET PSEUDO - SPIE EXIT ADDRESS
This instruction allows the user to set a type of 'SPIE'.
The user specifies an address and the interrupts he wishes to
process in a coded form. When this instruction is executed, Registers
0 and 1 are assumed to contain certain arguments. Register 1 must
contain a user program address (Exit Address) to which control is passed
if any of the specified program interrupts occur. The last 15 bits
(bits 17-31) of Register 0 must contain a code specifying which
interrupts the user wishes to intercept. The first 17 bits of register
0 are ignored. Each of the bit positions 17 to 31 of register 0
correspond to one of the 15 execution time interrupts. A 1 in
one of the bit positions specifies a spie-exit on the corresponding
program interrupt. For example, Bit (17) = 1 specifies a spie-exit on
S0C1, Bit (18) = 1 specifies a spie-exit on S0C2, ......., Bit (31)
= 1 specifies a spie-exit on S0CF. A zero in any of the bit positions
allows the corresponding execution time interrupt to occur as if no
spie had been set.
Example: If register 0 contains the following;
0000 0000 0000 0000 0111 0000 0000 0001
After an XOPC 0 instruction has been executed with register 0 as above,
control will be passed to the address found in register 1 if any of the
following interrupts occur; S0C1, S0C2, S0C3 and S0CF.
If a spie exit address has been given (i.e. This instruction
has been executed) and one of the specified interrupts occurs, the
following actions take place:
1). The current values of user register 0 and 1 are saved.
2). The PSW at interrupt is loaded into registers 0 and 1.
3). The proper interrupt code is inserted into user register
0 (bits 17 thru 31 of the PSW).
4). ASSIST now considers the user in the interrupt processing
state.
5). Control in the user program is passed to the given
interrupt exit address.
It should be noted that when the user is in the Interrupt
Processing State any further interrupt will cause abnormal termination
of the user program. The user will remain in this state until the exec-
ution of an XOPC 21 instruction.
XOPC 0 can be executed an unlimited number of times during
the execution of a program to change the specified exit address or to
change the interrupts to be intercepted. Note, however, that the most
recent execution of XOPC 0 is the one in effect, and cancels all
previous executions.
ASSIST4-4
XOPC 1 - SET ADDRESSES FOR THE INSTRUCTION TRACE FACILITY
This instruction specifies boundary addresses used by the
trace facility. Once enabled the trace facility will give the user a
printed trace of all instructions executed within these two boundary
addresses. When this instruction is executed the lower and upper trace
address limits are assumed to be in registers 0 and 1, respectively.
XOPC 2 - TURN ON THE INSTRUCTION TRACE FACILITY
This instruction enables the trace facility. Prior to the
execution of this instruction the user should have specified two limit
addresses. However, if no limit addresses have been specified, ASSIST
will use the highest and lowest program addresses for the limits.
Below is an example of the trace line printed for each instruction
executed. Assume this instruction is executed causing the following
trace message to be printed:
ADDR INSTRUCTION
00EBE0 STM R0,R10,SAVEAREA
Here is the trace message printed:
TRACE--> INSTR ADDR: 00EBE0 INSTR: 980A 6020
XOPC 3 - SET ADDRESSES (as in XOPC 1) and TURN ON THE
INSTRUCTION TRACE FACILITY
This instruction combines the actions of XOPC instructions 1
and 2. It assumes register usage the same as in XOPC 1.
XOPC 4 - TURN OFF THE INSTRUCTION TRACE FACILITY
This instruction disables the Instruction Trace.
XOPC 5 - SET ADDRESSES FOR THE STORAGE MODIFICATION CHECKING
FACILITY
This instruction specifies address boundaries (high and low)
inside which the Storage Modification Checking Facility will operate.
Once enabled, this facility causes storage between the boundary
addresses to be monitored. If any of this storage is modified, the
length of storage modified and the instruction modifying the storage
will be printed for the user. The register usage upon execution of
this instruction is the same as in XOPC 1 above.
ASSIST4-5
XOPC 6 - TURN ON THE STORAGE MODIFICATION CHECKING FACILITY
This instruction enables the Storage Modification Checking
Facility. Before the execution of this instruction the user should
have specified two boundary addresses. However, if no limit addresses
are specified ASSIST will use the highest and lowest program addresses
(outer limits) for the limit addresses. Below is an example of the
Storage Modification Checking line printed when an instruction modifies
storage. Assume the instruction listed below is executed:
ADDR INSTRUCTION
0001C0 ST R1,SAVE
Here is the line printed assuming the label SAVE has a displacement of
0002C0.
CHECK--> INSTR ADDR: 0001C0 INSTR: 5010 C2C0
MODIFICATION LIMIT ADDRS--> LOW: 0002C0 HIGH: 0002C3
XOPC 7 - SET ADDRESSES (as in XOPC 5) and TURN ON THE
STORAGE MODIFICATION CHECKING FACILITY
This instruction combines the actions of the XOPC 5 and
XOPC 6 instructions above.
XOPC 8 - TURN OFF STORAGE MODIFICATION CHECKING FACILITY
This instruction disables the Storage Modification
Checking Facility.
XOPC 9 - TURN ON BOUNDARY ALIGNMENT CHECKING FACILITY
This instruction turns on boundary alignment checking in
ASSIST. This implies that S0C6 alignment interrupts will be allowed.
The default condition within ASSIST allows Alignment Interrupts to
occur. Thus, this instruction need be executed only after execution
of an XOPC 10 instruction has shut off (disabled) the Boundary
Alignment Checking Facility (see XOPC 10).
XOPC 10 - TURN OFF BOUNDARY ALIGNMENT CHECKING FACILITY
This instruction disables Boundary Alignment checking in
ASSIST. This implies that S0C6 Alignment Interrupts will no longer
be allowed after the execution of this instruction. Thus, the user is
no longer restricted by storage alignments and can fetch and store data
on odd word boundaries.
ASSIST4-6
XOPC 11 - FETCH ASSIST INSTRUCTION COUNTER
The current value of the ASSIST Instruction Counter is put
in user register 0. This instruction should be used in conjunction with
the XOPC 14 instruction described below. The instruction counter
is put into the register in hexidecimal form.
XOPC 12 - EMULATE SYSTEM 360
This instruction causes ASSIST to emulate a system 360. That
is, ASSIST will act as if it is running on an S360 no matter what
machine (S360 or S370) it is really running on. It should be noted
that emulation in ASSIST defaults to S370 (S370 instructions will be
interpreted). After the execution of this instruction however, ONLY
S360 instructions will be interpreted. S370 instructions will cause
user program termination (S0C1).
XOPC 13 - EMULATE SYSTEM 370
This instruction causes ASSIST to emulate a system 370. That
is, ASSIST will act as if it is running on an S370 no matter what
machine (S360 or S370) it is really running on. This instruction
should only be used after the execution of an XOPC 12 instruction as
machine emulation in ASSIST defaults to S370 (i.e.S370 instructions
will be interpreted).
XOPC 14 - SET INTERRUPT COUNT
This instruction allows the user to halt program execution
when the ASSIST instruction counter and the value found in register 0
become equal (i.e. cause a COUNT INTERRUPT). This instruction should be
used in conjunction with the XOPC 11 instruction. Any negative value
found in user register 0 when this instruction is executed will disarm
the count interrupt facility.
Example of Use: The user desires a count interrupt to occur
if 200 instructions are executed from this point on (Note: The ASSIST
instruction counter counts down):
XOPC 11 Load register 0 with current instruction counter
S R0,=F'200' decrement counter by 200
XOPC 14 Set interrupt count 200 instructions from now.
ASSIST4-7
XOPC 15 - SET COUNT EXIT ADDRESS
The value found in user register 0 when this instruction is
executed will be used as an exit address if a count interrupt occurs
(i.e. when the instruction counter becomes equal to the clock
comparator - see XOPC 14). If a count interrupt occurs after this
instruction has been executed, the psw at interrupt will be loaded
into user registers 0 and 1. Execution will then continue beginning
at the given exit address. If no exit address has been specified and
a count interrupt occurs, the program abnormally terminates with
the standard ASSIST instruction limit exceeded error printed.
XOPC 16 - TURN ON THE INSTRUCTION EXECUTION COUNT FACILITY
This instruction enables the INSTRUCTION EXECUTION COUNT
FACILITY. This facility counts each instruction executed between two
limit addresses. It should be realized that upon its initial
execution this instruction will cause ASSIST to allocate a section of
main memory equal in size to that of the user program. If this space
is found to be unavailable, the condition code of the user program is
set to one and the count facility remains disabled. Prior to the
execution of this instruction, the user should have specified two
limit addresses for the count facility (See XOPC 17 below). However,
if two limit addresses were not specified, ASSIST will use the highest
and lowest program addresses for the limit addresses. Note: This
instruction does not clear the instruction counting area. See XOPC
20 for clearing the count area.
XOPC 17 - SET ADDRESSES FOR THE INSTRUCTION EXECUTION
COUNT FACILITY (IECF)
This instruction specifies boundary limit addresses used by
IECF. Once enabled this facility will count the number of executions
of each instruction between the two limit addresses specified by this
instruction. When this instruction is executed the low and high
IECF limit addresses are assumed to be in registers 0 and 1,
respectively.
XOPC 18 - SET ADDRESSES AND TURN ON THE IECF
This instruction combines the actions of XOPC instructions
16 and 17. Register usage is assumed to be the same as in XOPC 17.
XOPC 19 - TURN OFF THE INSTRUCTION EXECUTION COUNT FACILITY
This instruction disables the IECF. This instruction will
not have any effect on the IECF counting area.
ASSIST4-8
XOPC 20 - CLEAR THE INSTRUCTION EXECUTION COUNT FACILITY
COUNTING AREA
This instruction resets the Instruction Execution Count
Facility Counting area to zero. If the IECF has never been enabled in
the user program (i.e. no counting space has been allocated), the
condition code of the user program is set to 1 and this instruction is
ignored. This instruction can be executed an unlimited number of times
to insure accurate instruction counting. Please note that the counter
for each instruction is only a halfword (2 bytes) in length. Executing
one instruction many times could overflow that counter and reset it
to zero.
XOPC 21 - RETURN FROM INTERRUPT PROCESSING CODE
This instruction tells ASSIST that the User Program has com-
pleted any interrupt processing routine (s) and is ready to resume
normal execution of the user program. It causes the following actions
to occur:
1). If the user is not in the interrupt processing state the
condition code is set to 1 and nothing more is done.
2). The address in register 1 is used as the address where
normal execution of the user program will resume. If
register 1 is not modified in the interrupt processing code,
execution of the user program will continue with the
instruction immediately following the instruction that
caused the initial interrupt. Otherwise, the user will be
expected to load register 1 with an appropriate address.
3). User registers 0 and 1 are reloaded with the values they
had when the initial interrupt occurred.
4). Normal execution of the user program is resumed with the
user no longer in the INTERRUPT PROCESSING STATE.
XOPC 22 - DUMP THE INSTRUCTION EXECUTION COUNT FACILITY
STATISTICS
This instruction prints out a statistical report according to
address of the number of instructions counted (within the specified
limit addresses) by the Instruction Execution Count Facility. An
instruction executed 0 times will cause no statistical line to be
printed. Groups of instructions executed the same number of times will
produce one statistical line. This shows the user where his major
loops are and where most of his execution time is being spent. If this
instruction is executed and the count facility has not yet been enabled
at least once in the user program (i.e. no count space has been
allocated), the condition code of the user program is set to one and
this instruction is ignored. As an example consider the following test
program:
ASSIST4-9
ADDR INSTRUCTION COMMENTS
...
...
...
000010 LOWADDR EQU *
000010 LA 0,LOWADDR GET LOW COUNTING ADDRESS
000014 LA 1,HIGHADDR GET HIGH COUNTING ADDRESS
000018 XOPC 18 ENABLE THE COUNT FACILITY
00001A XOPC 20 CLEAR THE COUNT AREA
00001E LA 10,50 GET LOOP VALUE
000022 LOOP LR 1,3 DO GARBAGE FOR COUNTING
000024 AR 4,1 MORE GARBAGE
000028 BCT 10,LOOP LOOP 50 TIMES
00002C XOPC 19 TURN OFF THE COUNTING
00002E XOPC 22 DUMP STATISTICS
000030 HIGHADDR EQU *
...
...
...
The XOPC 22 instruction above would print out the following statistical
report:
STATS--> BEGIN ADDR: 00001E END ADDR: 00001E INSTRUCTION COUNT: 0001
STATS--> BEGIN ADDR: 000022 END ADDR: 000028 INSTRUCTION COUNT: 0050
STATS--> BEGIN ADDR: 00002C END ADDR: 00002C INSTRUCTION COUNT: 0001
A FEW EXTRA NOTES:
It should be noted when using the XOPC instructions that they
are expensive instructions with regard to overhead space and time.
They should be used sparingly and preferably one facility at a time for
best results.
ASSIST5-1
PART V. OUTPUT AND ERROR MESSAGES
A. ASSEMBLY LISTING
1. ASSEMBLY LISTING FORMAT
The assembly listing produced by the ASSIST assembler is essen-
tially the same as that produced by the standard OS/360 assemblers,
with the following minor differences:
a. Error messages are not printed at the end of the assembly
listing, but are printed after the each statement causing the messages.
A scan pointer '$' indicates the column where the error was discovered.
b. No more than four messages are printed for any single source
statement. Some errors cause termination of statement scan, and errors
following in the same statement may not be discovered. However, an
error in a statement does not normally prevent its statement label from
being defined, which is usually the case with the standard assembler.
c. As noted under PRINT in PART I and under NOLIST in PART III,
statements flagged are printed regardless of print status at the time.
d. As noted under PRINT in PART I, no more than eight bytes of
data are printed for a statement, even if PRINT DATA is used.
2. ASSEMBLER ERROR MESSAGES
The assembler produces error messages consisting of an error code
followed by an error description. The code is of the form AS###, with
the value of ### indicating one of three types of errors:
a. Warnings - ### is in range 000-099. These never prevent the
execution of the program, correspond to OS severity code 4, and e have
messages beginning with characters 'W-'.
b. Errors - ### is in range 100-899. Execution is deleted if the
total number of errors exceeds the NERR parameter, as described in PART
III. These correspond to OS severity codes of 8 and 12.
c. Disastrous errors - ### is in range 900-999. Some condition
prevents successful completion of the assembly process. Execution of
the user program may or may not be permitted.
ASSIST5-2
3. LIST OF ASSEMBLER ERROR MESSAGES
The following lists the codes and messages issued by the ASSIST
assembler, with further explanations following each message.
AS000 W-ALIGNMENT ERROR-IMPROPER BOUNDARY
The address used in a machine instruction is not aligned to the
correct boundary required by the type of instruction used.
AS001 W-ENTRY ERROR-CONFLICT OR UNDEFINED
A symbol named in an ENTRY statement is either undefined, or is
also named in either a DSECT or EXTRN statement.
AS002 W-EXTERNAL NAME ERROR OR CONFLICT
A symbol named in an EXTRN statement is either defined in the
program or is named in an ENTRY statement.
AS003 W-REGISTER NOT USED
The register flagged in a DROP statement is not available for use
as a base register at this point in the program. This may be
caused by an error in a USING statement naming the register.
AS004 W-ODD REGISTER USED-EVEN REQUIRED
An odd register is coded in a machine instruction requiring the…
use of an even register for a specific operand. Instructions
which may flagged are Multiply, Divide, Double Shifts, and all
floating point instructions.
AS005 W-END CARD MISSING-SUPPLIED
The assembler creates an END card because the user has supplied
none before an end-file marker.
ASSIST5-3
AS100 ADDRESSIBILITY ERROR
An implied address is used which cannot be resolved into base-
displacement form. No base register is available having the
same relocatability attribute and a value from 0 to 4095 less than
the value of the implied address.
AS101 CONSTANT TOO LONG
Too many characters are coded for the type of constant specified.
This message appears if a literal constant contains more than 112
characters, including the equals sign and delimiters.
AS102 ILLEGAL CONSTANT TYPE
An unrecognizable type of constant is specified.
AS103 CONTINUATION CARD COLS. 1-15 NONBLANK
A continuation card contains nonblank characters in columns 1-15.
This may be caused by an accidental punch in column 72 of the
preceding card.
AS104 MORE THAN 2 CONTINUATION CARDS
Three or more continuation cards are used, which is illegal,
except on macro prototype statements and macro calls.
AS105 COMPLEX RELOCATABILITY ILLEGAL
ASSIST does not permit complex relocatible expressions.
AS106 TOO MANY OPERANDS IN DC
ASSIST allows no more than ten operands in a DC statement.
AS107 MAY NOT RESUME SECTION CODING
The assembler requires that any section be coded in one piece.
The label flagged has already appeared on a CSECT or DSECT.
AS108 ILLEGAL DUPLICATION FACTOR
A duplication factor either exceeds the maximum value of 32,767,
or a duplication factor in a literal constant is not specified by
a decimal term or else has the value zero.
AS109 EXPRESSION TOO LARGE
The value of the flagged expression or term is too large for the
given usage, such as a constant length greater than the maximum
permissible for the type of constant.
AS110 EXPRESSION TOO SMALL
The value of the flagged expression or term is too small for the
given usage, or has a negative value. Coding a V-type constant
with a length of two would generate this message.
ASSIST5-4
AS111 INVALID CNOP OPERAND(S)
The operands of a CNOP have values which are anything but the
legal combinations of values for a CNOP, such as a first operand
greater than the second, an odd value, etc. The only legal value
combinations are 0,4 2,4 0,8 2,8 4,8 6,8 .
AS112 LABEL NOT ALLOWED
A label is used on a statement not permitting one, such as a
CNOP or USING statement.
AS113 ORG VALUE IN WRONG SECTION OR TOO LOW…
The expression in an ORG statement either has a value smaller than
the initial location counter value for the current control
section, or has a relocatibility attribute different from that
of the current control section.
AS114 INVALID CONSTANT
A constant contains invalid characters for its type, or is
specified improperly in some other way.
AS115 INVALID DELIMITER
The character flagged cannot appear in the statement where it does.
This message is used whenever the scanner expects a certain kind of
delimiter to be used, and it is not there.
AS116 INVALID FIELD
The field flagged has an unrecognizable value, or is otherwise
incorrectly coded. PRINT OF is flagged this way.
AS117 INVALID SYMBOL
The symbol flagged either contains nine or more characters or does
not begin with an alphabetic character as is required.
AS118 INVALID OP-CODE
The statement contains an unrecognizable mnemonic op-code, or none
at all. Note that different versions of ASSIST may not accept some
of the possible op-codes. The first heading described in
PART IV.B.1.a describes which op-codes are allowed.
AS119 PREVIOUSLY DEFINED SYMBOL
The symbol in the label field has been previously used as a label,
or a SET variable has been previously declared.
AS120 ABSOLUTE EXPRESSION REQUIRED
A relocatable expression is used where an absolute one is required,
such as in constant duplication factor or for a register.
ASSIST5-5
AS121 MISSING DELIMITER
A delimiter is expected but not found. For instance, a C-type
constant coded with no ending ' is flagged this way.
AS122 FEATURE NOT CURRENTLY IMPLEMENTED
The version of ASSIST being used does not support the language
feature used.
AS123 MISSING OPERAND
The instruction requires an operand, but it is not specified.
AS124 LABEL REQUIRED
An instruction requiring a label, such as a DSECT, is coded
without one.
AS126 RELOCATABLE EXPRESSION REQUIRED
An absolute expression or term is used where a relocatable one is
required by ASSIST, such as in the first operand of a USING.
Also, this message may appear if the final relocatiblity attribute
of the value in an address constant is that of a symbol in a DSECT.
AS127 INVALID SELF-DEFINING TERM
The self-defining term flagged contains an illegal character for
its type, has a value too large for 24 bits to contain, or is
otherwise incorrectly specified.
AS128 ILLEGAL START CARD
The START card flagged is coded with one or more statements other
than listing controls or comments appearing before it.
AS129 ILLEGAL USE OF LITERAL
The literal constant appears in the receiving field of an
instruction which modifies storage. e.g., ST 0,=F'1'
AS130 UNDEFINED SYMBOL
The symbol shown is either completely undefined, or has not been
already defined when it is required to be. Symbols used in ORG
instructions or in constant lengths or duplication factors must be
defined before they are used.
ASSIST5-6
AS131 UNRESOLVED EXTERNAL REFERENCE
The symbol used in a V-type constant is not defined in the
assembly, or is defined but not declared a CSECT or ENTRY. ASSIST
does not link multiple assemblies, so this is an error.
AS132 ILLEGAL CHARACTER
The character flagged is either not in the set of acceptable
characters, or is used in an illegal way.
AS133 TOO MANY PARENTHESIS LEVELS
Parentheses are nested more than five deep in an expression.
AS134 RELOCATABLE EXPRESSION USED WITH * OR /
RElocatable terms or expressions may not be used with either of
these operators.
AS135 SYNTAX
The character flagged is improperly used. This catchall message
is given by the general expression evaluator when it does not find
what is expected during a scan.
AS136 TOO MANY TERMS IN EXPRESSION
The expression contains more than the legal maximum of 16 terms.
AS137 UNEXPECTED END OF EXPRESSION
The expression terminates without having enough closing parentheses
to balance the opening ones used.
THE FOLLOWING MESSAGES ARE ONLY ISSUED DURING MACRO PROCESSING.
AS201 OPERAND NOT ALLOWED
During macro expansion, an extra operand was found, i.e., an extra
positional beyond those given in the prototype.
AS202 STATEMENT OUT OF ORDER
The statement flagged is in an incorrect place in the deck. For
example: LCLx before GBLx, ACTR not after both; GBLx, LCLx, ACTR
in middle of macro definition or open code. *SYSLIB card out of
order, etc. May often be caused by missing MEND card.
AS203 SET SYMBOL DIMENSION ERROR
A dimensioned set symbol was used without a dimension, or one which
was not dimensioned was written with one.
AS204 INVALID NBR OF SUBSCRIPTS
There was an error in specifying substring notation, sublists, or
set symbol dimension.
ASSIST5-7
AS205 ILLEGAL CONVERSION
During macro editing, a SET instruction was found with an obviously
Incorrect conversion, as in &I SETA C .
AS206 MISSING QUOTES IN CHAR EXPR
Quotes (apostrophes) are required in character expressions and must
always be supplied, but were not.
AS207 ILLEGAL OR DUP MACRO NAME
A macro prototype name is either completely illegal, such as having
too many characters, or duplicates the name of a previously given
macro, machine instruction, or assembler instruction.
AS208 OPRND NOT COMPATIBLE WITH OPRTR
An operand is used with an incompatible operator. For example, if
&C is LCLC, &B LCLB : &B SETB (NOT &C) .
AS209 UNDFND OR DUPLICATE KEYWORD
In calling a macro, a keyword is used which does not appear in the
macro prototype. In either defining or calling a macro, a keyword
operand appears twice or more in the list of operands.
AS210 MNEST LIMIT EXCEEDED
The MNEST option provides a maximum limit to the nested depth of
macro calls. This limit has been exceeded. Note that after the
MSTMG limit has been exceeded, the MNEST limit is effectively 0 .
AS211 ILLEGAL ATTRIBUTE USE
ASSIST does not support S', I', or L' for macro operands.
AS212 GENERATED STATEMENT TOO LONG
A STATEMENT WAS GENERATED HAVING MORE THAN TWO CONTINUATION CARDS .
AS217 STMT NOT PROCESSED: PREVIOUS ERROR: STMT/MACRO #####/name
During expansion of macro 'name', the statement numbered ##### was
encountered, but not expanded because it had already been flagged.
AS218 STORAGE EXCEEDED BY FOLLOWING MACRO EXPANSION
The following call to the macro listed caused overflow of storage ,
probably due to looping. Use ACTR, MACTR=, or MSTMG= .
AS220 UNDEFINED SEQUENCE SYMBOL IN STATEMENT #####
This may appear following an entire macro definition, and gives the
number of a statement referencing a sequence symbol never defined .
ASSIST5-8
Any of the following messages describes an error found during the
expansion of statement ##### of macro 'name' . Some messages also add
a descriptive 'value', such as an offending subscript. Note that the
messages below use ## as an abbreviation for the actual output (which is
actually printed by ASSIST in the form STMT/MACRO #####/name).
AS221 ACTR COUNTER EXCEEDED: ##
The ACTR count has been exceeded. The ACTR is set by the MACTR
option, or by an ACTR statement. This indicates a looping macro .
AS222 INVALID SYM PAR OR SET SYMBOL SUBSCRIPT: ## --> value
A subscript is out of range. The offending value is given.
AS223 SUBSTRING EXPRESSION OUT OF RANGE: ## --> value
This is most often caused by the first subscript in a substring
expression having a nonpositive value, or one larger than the size
of the string.
AS224 INVALID CONVERSION, CHAR TO ARITH: ## --> value
The value could not be converted to arithmetic form.
AS225 INVALID CONVERSION, ARITH TO BOOLEAN: ## --> value
The value was not 0 or 1.
AS226 INVALID CONVERSION, CHAR TO BOOLEAN: ## --> value
The value was not '0' or '1', so it could not be converted.
AS227 ILLEGAL ATTRIBUTE USE: ##
An attribute was used incorrectly.
AS228 &SYSLIST SUBSCRIPT OUT OF RANGE: ##
The subscript has a value greater than the maximum number of fields
which can be supplied.
AS229 CALL FRIENDLY ASSIST REPAIRMAN: ##
An internal error has occurred inside ASSIST. Please send a deck.
AS230 INTERNAL CHAR BUFFER EXCEEDED: ##
Too much concatenation was done in the statement. Remedy: reduce
the complexity of the statement.
AS231 MSTMG LIMIT EXCEEDED: ##
The MSTMG limit (total number of statements processed during macro
expansion) has been exceeded. Use MSTMG= to increase this.
AS232 ZERO DIVIDE OR FIXED POINT OVERFLOW: ##
One of these interrupts was caused by the statement given.
ASSIST5-9
AS241 SEQUENCE SYMBOL NOT FOUND
This message immediately follows an AGO or successful AIF in open
code whose sequence symbol could not be found before the END card.
As a result, all of the program between the AIF/AGO and END card is
skipped over.
AS242 BACKWARDS AIF/AGO ILLEGAL
This message appears following an AGO or successful AIF in the open
code which references a previously defined sequence symbol. ASSIST
allows backwards branches only in macros, not in open code.
AS288 MACRO xxxxxxxx COULD NOT BE FOUND
This is issued by the macro library processor when it tries to get
a macro and cannot find it in the library. The macro may be named
on a *SYSLIB card, or referenced by another macro.
AS289 UNABLE TO OPEN MACRO LIBRARY: OPTION CANCELED
This is issued after a *SYSLIB card is encountered, but the macro
library cannot be opened. A SYSLIB DD card is missing or in error.
AS298 GENERATED STMTS OVERWRITTEN
During macro expansion, one or more generated statments were lost
due to internal table management, probably because a statement near
the beginning of a macro generated a long literal constant. One
solution is to insert several comments cards at the beginning of
the macro definition.
AS999 DYNAMIC STORAGE EXCEEDED
ASSIST requires more storage than is available, so the assembly is
halted. This can occur for many reasons. REMEDIES: use the DISKU
option if available, remove comments cards from your program, cut
down on array sizes, etc.
ASSIST5-10
4. ASSEMBLER STATISTICS SUMMARY
Following the assembly listing, the assembler prints three or four
lines of statistical information, as follows:
a.
*** ##### STATEMENTS FLAGGED - ##### WARNINGS, ##### ERRORS
This notes the total numbers of statements flagged, warning
messages, and error messages given during the assembly.
b.
***** NUMBER OF ERRORS EXCEEDS LIMIT OF ##### ERRORS - PROGRAM EXECUTION
DELETED *****
This notes the maximum number of errors permitting execution, and
that the user program will not be executed because the NERR limit
value has been overrun (see PART III regarding NERR).
c.
*** DYNAMIC CORE AREA USED: LOW: ###### HIGH: ###### LEAVING: ######
FREE BYTES. AVERAGE: ###### BYTES/STMT ***
The ASSIST assembler uses memory from the opposite ends of one area
of storage acquired at execution time. The LOW area contains source
statements and generated object code,the HIGH area contains the symbol
and literal tables, and the space remaining indicates how close the
user is to causing a storage overflow. The average core usage printed
includes that used in both LOW and HIGH areas.
d.
*** ASSEMBLY TIME = #.### SECS, ##### STATEMENTS/SEC ***
This notes the total time used by the assembler, along with the
rate of assembly. At PSU, this time includes both CPU time and
I/O charges.
e.
***** EXECUTION DELETED - LESS THAN ## PER CENT OF MACHINE INSTRUCTIONS
HAVE COMMENTS *****
The above message may appear before the core area message, if the
ASSIST has the comment-checking option, and either COMNT was coded,
or was invoked by account number, and the user did not put comments
on the given percentage of machine instruction statements.
ASSIST5-11
B. ASSIST MONITOR MESSAGES
1. HEADINGS AND STATISTICAL MESSAGES
The main control program of ASSIST may issue the following
headings and messages during execution:
a.
*** ASSIST version OF date INSTS/DFP/=### CHECK/TRP/=### OPTS/CCKMR/=###
### PENN STATE UNIV. model - system ***
This heading is the first line printed, and it describes the
facilities in the version of ASSIST being used, as follows:
version,date - version number of this ASSIST, and date it was created.
INS/DFPS/= - describes instruction sets accepted. The digits are 0's
or 1's showing lack or presence of decimal, floating
point, privileged operations, and some S/370 operations
CHECK/TRP/= - describes time, records, and pages checking modes. a 2
for T or R indicates ASSIST can obtain time or records
remaining from system, 0 for T indicates no timing, 0
for P indicates no page checking possible.
OPTS/CCKMR/= - describes availability of major optional features, in
order CMPRS, COMNT, KP=26, MACRO, and REPL. Values of
0 indicate the feature is unavailable. If value for
COMNT is nonzero, it is two digits long and gives the
percentage of comments required. A value of 1 for R
denotes a partial version of the Replace Monitor,
while 2 denotes a complete version with all features .
model - lists the model number of the computer being used.
system - describes operating system being used (such as OS-MVT).
b.
Following the above heading, the ASSIST monitor prints the
contents of the user's EXEC card PARM field, or his $JOB CARD.
c.
*** PROGRAM EXECUTION BEGINNING - ANY OUTPUT BEFORE EXECUTION TIME
MESSAGE IS PRODUCED BY USER PROGRAM ***
This message is issued immediately before the user program is
executed, and serves to delimit user output.
d.
*** EXECUTION TIME = #.### SECONDS ##### INSTRUCTIONS EXECUTED -
##### INSTRUCTIONS/SEC ***
*** FIRST CARD NOT READ: card image
This message is issued immediately after the user program has
been executed, and supplies statistics regarding the execution time and
rate of execution of the user program. The time shown may be slightly
smaller than the actual time, if the completion code given in the dump
is ASSIST = 223 TIME LIMIT EXCEEDED. The second part appears if one or
more data cards were not read by the user program.
e.
*** TOTAL RUN TIME UNDER ASSIST = #.### SECS ***
This is the last line printed by ASSIST, and the time given
includes time for the entire run. Printed only if CHECK/TRP/=2## .
ASSIST5-12
2. ASSIST MONITOR ERROR MESSAGES
The ASSIST monitor may also issue any of the following messages,
which are of the form AM###, and usually indicate errors:
AM001 ASSIST COULD NOT OPEN PRINTER FT06F001:ABORT
This message appears in the system message class data set if
ASSIST is unable to open the DCB for its printer, using DDNAME
FT06F001. This is probably caused by lack of a DD card, or by an
incorrect override of this DDNAME in a catalogued procedure.
AM002 ASSIST COULD NOT OPEN READER SYSIN:ABORT
This message appears in the system message class data set if
ASSIST is unable to open the DCB for the source card reader. The
SYSIN DD * card is probably omitted or mispunched, making an
assembly and execution impossible.
AM003 - STORAGE OVERFLOW BEFORE EXECUTION, EXECUTION DELETED
The user program assembled properly, but there is insufficient
memory remaining to set up control blocks required for execution.
The user should attempt to reduce the amount of storage used by
his program. This message should occur very seldom.
AM004 - NORMAL USER TERMINATION BY RETURN
This message is issued if the user program branches to the address
originally supplied to it as a return address in register 14. If
this message appears, no completion dump is printed.
AM005 - TIME OR RECORDS HAVE BEEN EXCEEDED
This message is printed if the time or record limits have been
exceeded at any time during a job. This message appears after a
completion dump, if there is one.
ASSIST5-13
C. ASSIST COMPLETION DUMP
When a user program terminates abnormally, a completion dump is
provided for debugging purposes, and contains the following items:
1.
ASSIST COMPLETION DUMP
The above header begins the dump.
2.
PSW AT ABEND xxxxxxxx xxxxxxxx COMPLETION CODE type = code message
This line gives the user's Program Status Word, in hexadecimal,
followed by further information concerning the reason for termination.
The type given is one of the following:
a. SYSTEM, indicating that the code given is the same as that given
by OS/360, such as for program interrupts.
b. ASSIST, indicating a completion code which does not necessarily
correspond directly to a code used by OS/360.
The three-digit hexadecimal code is followed by a descriptive message.
PART IV.D provides a list of the messages and codes.
3.
***** TRACE OF INSTRUCTIONS JUST BEFORE TERMINATION: PSW BITS SHOWN ARE
THOSE JUST BEFORE CORRESPONDING INSTRUCTIONS DECODED *****
IM LOCATION INSTRUCTION : IM = PSW BITS 32-39(ILC,CC,MASK) BEFORE
INSTRUCTION EXECUTED AT PROGRAM LOCATION SHOWN
aa bbbbbb cccc cccc cccc (1-10 lines in this format)
The above section in a dump lists up to the last ten instructions
executed before termination, with the last instruction shown usually
causing the termination. Parts aa and bbbbbb make up a user PSW in
each line, and are followed by from one to three halfwords of
instruction, represented by cccc.
4.
** TRACE OF LAST 10 BRANCH INSTRUCTIONS EXECUTED BEFORE TERMINATION: PSW
BITS SHOWN ARE THOSE JUST BEFORE CORRESPONDING INSTRUCTION DECODED **
IM LOCATION INSTRUCTION: IM = PSW BITS 32-39(ILC,CC,MASK) BEFORE
INSTRUCTION EXECUTED AT PROGRAM LOCATION SHOWN
AA BBBBBB CCCC CCCC CCCC (1-10 lines in this format)
The above section of the Assist Completion Dump is only given when
ASSIST Optional Extended Interpreter is in use by the installation. This
section in a dump lists up to the last 10 successful branch instructions
executed before termination.
5.
GP REGISTERS 0/8 1/9 2/10 3/11 4/12
5/13 6/14 7/15
REGS 0-7 (8 groups of 8 hexadecimal digits each)
REGS 8-15 (8 groups of 8 hexadecimal digits each)
FLTR 0-6 (4 groups of 16 hexadecimal digits each)
The above section in a dump displays the contents of the user's
general purpose and floating point registers at the time of termination.
ASSIST5-14
6.
USER STORAGE
CORE ADDRESSES SPECIFIED- xxxxxx TO yyyyyy
zzzzzz (8 groups of 8 hexadecimal digits each) * (32 characters) *
The above section shows the format of a user storage dump. The
beginning and ending addresses are given by xxxxxx and yyyyyy. Each
line shows 32 bytes, beginning at location zzzzzz, grouped into eight
fullwords. Each area is also shown in alphameric form at the right,
with blanks, letters, and digits printed directly, and all other
characters translated to periods.
D. COMPLETION CODES
SYSTEM = 0Cx
This code is given for program interrupts, where x is the
hexadecimal interrupt code. The message given is as shown on page
6 of the IBM System/360 Reference Data card, for interrupts 0-F.
ASSIST = xxx message
This type is given for special ASSIST completions. The possible
codes and messages are as follows:
220 ATTEMPTED READ PAST ENDFILE
After performing an XREAD instruction and receiving an end-of-file
indication, the user has attempted another XREAD, i.e. tried to
read more data cards than existed.
221 INSTRUCTION LIMIT EXCEEDED
The user specified an I= limit on his EXEC card, and this number of
instructions has been exceeded. The program was probably looping.
222 RECORD LIMIT EXCEEDED
The user attempted to print or punch more records than was given by
combination of R, RD, and RX option values. Execution has been
terminated, and at least a partial dump given.
223 TIME LIMIT EXCEEDED
The user program has consumed more execution time than specified by
the values of the T, TD, and TX option values. Execution was
terminated and at least a partial dump given.
224 BRANCH OUT OF PROGRAM AREA
The user program attempted to branch outside of its area. The
only branch outside not flagged this way is a branch to the return
address originally supplied to the user program in register 14.
ASSIST5-15
E. OBJECT DECKS AND LOADER MESSAGES
1. OBJECT DECK FORMAT
ASSIST provides basic facilties for reading (OBJIN) and punching
(DECK) object decks which whose format is a compatible subset of normal
S/360 decks. However, ASSIST does not punch External Symbol Dictionary
(ESD) or Relocation Dictionary (RLD) cards, and ignores them if reading
a deck. Thus, it cannot perform symbolic linkage between modules or
relocate individual address constants. The facility can be useful for
saving assembler utility programs, or for providing efficient running
and good diagnostics for object code from student-written compilers.
Two types of cards are punched and recognized: text cards (TXT),
which supply actual object code, and end cards (END), which supply an
optional entry point address for beginning of execution. The formats
of these cards are described below. ALWAYS lists the characters which
are defintely present, DECK notes those which are punched, and OBJIN
those required for input. The notation IGNORED means that the given
card columns are completely ignored when loading an object deck.
CARD/COLUMNS ALWAYS DECK OBJIN
END CARD
1 ' ' IGNORED
2-4 END - -
5 X'00' IGNORED
6-8 entry address entry address or blanks
9-72 blank IGNORED
73-80 sequence # IGNORED
TEXT CARD
1 ' ' IGNORED
2-4 TXT - -
5 X'00' IGNORED
6-8 beginning address of text code which is on this card
9-10 blanks IGNORED
11 X'00' IGNORED
12 length of object code on card, from X'00' to X'38'
(i.e. 0 to 56 decimal bytes of code).
13-16 blanks IGNORED
17-72 up to 56 bytes of code, to be loaded at given address.
73-80 sequence # IGNORED
Note that the format above resembles the standard, given in:
IBM S/360 OS Assembler (F) Programmer's Guide GC26-3756, Appendix B.
When ASSIST punches an object deck, it punches the entire program
storage, including character 5's which fill any DS or other areas not
having specified code values. Unlike the standard system assemblers,
ASSIST always punches an END card with an entry point address on it,
whether the user specifies an entry point on the source END card or not.
Although it is not possible to perform symbolic linkage of multiple
decks, it is possible to link multiple decks if the user assembles each
of several programs at particular locations known to each other, using
START cards. Deck linkage can then be accomplished by locating a vector
of address constants at the beginning of each assembly, which can then
be used to reference any required areas or modules within that assembly.
Note that this type of procedure will not work if RELOC is used.
ASSIST5-16
2. ASSIST LOADER USAGE AND MESSAGES
The ASSIST loader is called by use of the OBJIN parameter, and
loads object deck cards having the format given on the previous page,
ignoring all cards having neither TXT nor END in columns 2-4. The usual
use for this option is to load a deck previously produced by ASSIST or
possibly by some student-written compiler being tested. However, it is
possible to link decks produced by the standard system assemblers if the
guidelines below are followed:
a. Use no V-type adcons.
b. Any command listed in PART II of this manual (XREAD, XDUMP, etc)
is handled inside ASSIST as a special instruction, using one or
more of the opcodes not already used. If any of these commands
is to be used, equivalent code must be generated.
c. If multiple assemblies are used, the only way to communicate
among them is to assemble each at some fixed location known to
any of the others which reference it in any way.
Regardless of the method used to create the input deck, the entire
object deck must follow the rules below:
a. The address on the first TXT card must be less than or equal to
all other TXT card addresses received. The object code for this
address is placed starting at the first byte of available memory.
b. The difference between the highest address of received object
code and the lowest address cannot exceed the available storage.
c. The entry point address is either the address from the first END
card specifying one (i.e., not blank), or if no such address is
found, then the address found on the first TXT card.
d. The user program cannot modify storage beyond the last code
address, so if it requires more work space, it can specify a TXT
card with zero length and a high enough address to reserve space.
Within the limits above, TXT addresses can occur in any order, and
END cards can appear anywhere (including the first card of the deck).
The user is cautioned to be careful in using the RELOC option with
OBJIN. ASSIST normally computes a relocation factor used to load the
code, which is equal to the lowest actual memory address minus the first
TXT address. After loading the code, if RELOC is used, the relocation
is set to 0, since RELOC-type programs must be run with no execution-
time relocation (so they can reference low-core addresses for instance).
Thus, any deck to be run under RELOC should contain no relocatable-type
address constants of any type, or else should use a START card to create
the same addresses as where the program will be run (which may be hard
to do under general OS-MFT and MVT systems).
ASSIST5-17
Messages produced by the ASSIST loader are of the form AL###,
and include the following messages:
a.
*** AL000 - ASSIST LOADER BEGINS LOAD AT xxxxxx ,USABLE CORE ENDS AT
xxxxxx ***
This message is printed before loading is begun, and gives the
beginning real address at which code can be loaded, and the address of
the first byte beyond the usable area. The entire area mentioned is
filled with character 5's before loading is begun.
*** AL100 - LOAD COMPLETED, USER ADDRESSES: LOW xxxxxx ,HIGH xxxxxx ,
ENTRY xxxxxx , RUN-TIME RELOCATION xxxxxx ***
This message is printed at the end of a successful load. It gives
the low and high addresses in user-relative values (as found in incoming
TXT cards), the entry point address where execution is to begin (again,
in user-relative terms), and the run-time relocation factor. This last
value is used during interpretive execution, and is added to every
program-defined address to obtain an actual address in memory, i.e., as
far as the user program is concerned, it is actually located between the
LOW and HIGH addresses given. If RELOC is used, the relocation factor
will be set to zero, regardless of the relocation factor actually used
to load the program.
The following messages indicate a error in the input deck. Loading
is terminated, and user program execution does not occur. **NOTE** if
either message AL997 or AL998 appears, it will be followed by an XSNAP
labeled 'IMAGE OF INCORRECT OBJECT CARD' , and the offending card
displayed beginning at the first address given by the XSNAP.
*** AL996 - NO TXT CARD RECEIVED ***
The loader encountered an end-of-file indication or ASSIST control
card before finding any TXT cards.
*** AL997 - TXT CARD ADDRESS BELOW 1ST TXT CARD ***
In order to perform relocation from TXT addresses to appropriate
memory addresses, no TXT card can have a lower address than the first
one found. This requirement was not met by the card displayed.
*** AL998 - TXT CARD ADDRESS EXCEEDED STORAGE ***
The area described in message AL000 was not sufficiently large to
hold all of the object code, i.e. the address of at least one byte of
code on the offending card was required to be beyond the end of the
available space.
*** AL999 - LOAD ABORTED ***
This message follows any of the other messages to note the
immediate termination of the loading process.
ASREPLGD-01
3.0/A
June 1973
ASSIST
ASSEMBLER REPLACEMENT USER'S GUIDE
Program&Documentation: John R. Mashey
Project Supervision : Graham Campbell
PSU Computer Science Department
PREFACE
This manual is the key reference source for the programmer who
uses the replacement facility of ASSIST. This facility allows the
programmer to write and test his own versions of certain program
modules which are part of the ASSIST Assembler. The modules which
are replaceable perform a wide variety of functions, thus allowing for
a number of different course assignments covering important segments
of a running 360 Assembler. Among those replacable are modules for
management of the symbol table, base register table, scanning and
covnversion of various constant types, and evaluation of both self-
defining terms and general expressions. The entire replacement
process can be performed with low overhead, in-core, and batched,
while allowing the user program no possible way to damage the rest of
the ASSIST system.
The first part of this manual briefly describes the internal
structure of the ASSIST assembler, and lists the steps in the entire
replacement process. Also included are the overall register and
linkage conventions required of all replacable modules.
The second section describes the additional debugging facilities
available to the writer of a replacement module.
The third section shows the deck setup, Job Control Language,
and PARM options needed to make a replacement run.
The fourth section lists all messages which may be printed by
the ASSIST Replace Monitor during a replacement run.
The reader should be familiar with the following manual:
ASSIST
INTRODUCTORY ASSEMBLER USER'S MANUAL
The above manual gives various information which may be required to
write a program which can be run under ASSIST, and explains the various
messages which may generated (other than Replace Monitor messages).
Note also that this manual is structured similar to the above one.
For replacement of certain of the modules, it may be necessary to
examine the following manual for additional required information:
ASSIST SYSTEM
PROGRAM LOGIC MANUAL
ASREPLGD-02
TABLE OF CONTENTS
PART I. THE ASSIST REPLACEMENT PROCESS.............................. 03
A. OVERVIEW OF THE ASSIST ASSEMBLER................................. 03
B. STEPS IN THE REPLACEMENT PROCESS................................. 04
C. REGISTER AND SUBROUTINE LINKAGE CONVENTIONS...................... 06
PART II. REPLACE MONITOR DEBUGGING AIDS............................. 08
A. THE RFLAG........................................................ 08
B. THE XREPL INSTRUCTION............................................ 09
PART III. JOB CONTROL LANGUAGE AND PARM OPTIONS..................... 09
A. JOB CONTROL LANGUAGE FOR REPLACE RUN............................. 09
B. PARM OPTIONS..................................................... 09
PART IV. REPLACE MONITOR MESSAGES................................... 10
ASREPLGD-03
PART I. THE ASSIST REPLACEMENT PROCESS
A. OVERVIEW OF THE ASSIST ASSEMBLER
The ASSIST Assembler is a section of the entire ASSIST System
which translates a deck of S/360 Assembler Language statements into
object code, in memory. It is made up of approximately 30 control
sections, of which 3 are main control programs. The overall control
program is named MPCON0, which calls the main programs for each of the
two passes in the assembler, and also calls all initialzation and
termination entrypoints for the various other modules in the assembler.
During the first pass, under control of MOCON1, each card in the
input source deck is read, scanned for label and opcode, and processed
partially according to the type of opcode. Each statement is given a
location counter value during this pass, and some types of statements
are completely processed, such as EQU, START, ORG, etc. Each cardimage
and its associated information is then saved into a large dynamic
workarea, until an END card is encountered.
During the second pass, each statement saved in the dynamic area
is retrieved and processed. Several different routines control the
scanning of each statement and production of object code from it. Each
statement's object code, if any, is loaded into memory, and the
statement printed.
Approximately half of the modules of the assembler can be replaced
using the ASSIST Replace Monitor. In general, these modules are
those which are fairly low-level routines, which are not required to
have communication with many other modules, and which generally do
not have to be able to examine variables and flags global to the entire
assembler. They definitely are never required to modify storage outside
the limits of their own storage. These characteristics make it
possible for them to be replaced without requiring a great deal of
knowledge of the internal workings of the ASSIST Assembler.
ASREPLGD-04
B. STEPS IN THE REPLACEMENT PROCESS
1. The programmer writes one control section which is to be assembled
and used as a replacement for the existing one in ASSIST of the same
name. This control section must have the following characteristics:
a. The CSECT and ENTRY names (if any) must be defined and spelled
exactly as the existing ones.
b. Certain replacable modules (such as EVALUT), are permitted to
call existing ASSIST modules. Any module so called can be done
so by listing the module name in an EXTRN statement, then
referencing the module name by use of a V-type address constant.
2. After the user program is assembled and loaded into memory, the
Replace Monitor searches its list of replaceable control sections for
one defined as a csect in the user program. The required entry point
names are found, if possible, in the user program. During this process,
the Replace Monitor modifies certain address constants in the main
control table of the assembler, which will permit it to regain control
every time one of the replaced entry points is called. The messages
labeled AR000, AR001, and AR002 may appear on the listing at this point.
If it cannot find a legally replaceable csect name, the message AR100
is printed, and the replacement process terminated. The latter can also
occur if the user program contains more serious errors than given by the
value of the NERR parameter.
3. VArious functions are performed to initialize the user program for
later execution. These include initializing the user RFLAG to the value
given by the RFLAG= option in the PARM field (see PART III). Then,
instead of executing the user program directly, the ASSIST Assembler is
called to process a test deck, which follows the user program.
4. During the assembly of the test deck, any of the replace program's
entry points may be called. Any such call is intercepted by the Replace
Monitor. Using previously saved information, it supplies the parameter
values to the original ASSIST entry point called, which returns the
correct set of values to be computed by that entry.
At this point, depending on certain bits in the current value of
the user RFLAG, various debugging information may be printed. This may
include the current cardimage being processed, the values of 5 parameter
registers on entry to the Replace Monitor, and their correct values as
returned by the original ASSIST module. These messages have labels
AR051, AR052, AR054, respectively.
5. At this point, a check is made to assure that the entry point
called actually was defined properly by the user. If not, the AR101
message is given, user storage is dumped, and the interception of calls
is terminated. Otherwise, the user registers and counters are prepared,
and the user program executed beginning at the address in his program
given by the called entry point. The user program is not executed
directly, but is interpreted to prevent it from damaging any part of
ASSIST. The user program may thus access storage outside its area, but
may not modify such storage.
ASREPLGD-05
6. The user program is interpreted until it either terminates
normally by returning to the return address supplied to it in R14, or
terminates with some error.
7. If the user program terminated normally, the register values it
returned are checked against the ones returned by the original module.
In some cases, the exact register values do not matter, but any value
definitely wrong is noted. If anything is actually wrong, any debug
information not already printed during step 4 is printed now. Then
the values of the user-returned parameter registers are printed (AR058),
followed by a message flagging the incorrect registers (AR059). The
AR058 message may be printed in any case if the appropriate bit in the
current value of the user RFLAG is turned on. Another bit in the RFLAG
is set if an error has occurred. This bit may be tested by the user
program the next time it is called.
The correct values are placed in the parameter registers, and
control is returned to the program which originally called the replaced
entry point.
8. If the user program did not terminate normally, and the error was
a branch out of the user program, it may be the case that the user
program was attempting to call some other original ASSIST module. The
call is checked to see if it is a legitamate one. If so, the parameter
registers may be printed (AR050), and then checked to make sure they
contain legal values. If they are illegal for any reason, they are
flagged with message AR059, the user program is dumped, and no further
calls are made to user entry points. If the call is legal, the desired
routine is called, and its parameter values placed in the user's
registers, and step 6 is begun once more.
9. Finally, the assembly of the test program is completed, with all
calls having been made to the appropriate entry points of the user
replacement program. Messages AR003 and AR004 are then printed, giving
various statistics about the performace of the user program. These
include the number of times each entry point was called, the total
number of instructions executed by each entry, the number of times the
values returned by the user program were incorrect, the average number
of instructions executed per call, and the percent of the calls which
were handled incorrectly.
10. If the option BATCH was specified, control returns to step 1,
thus allowing different modules to be tested during one run. Otherwise,
ASSIST execution terminates.
ASREPLGD-06
C. REGISTER AND SUBROUTINE LINKAGE CONVENTIONS
1. REGISTER USAGE
The general purpose registers are referred to by two separate sets
of symbols. The first is a set of absolute register equates, the
symbols R0-R15 being used for registers 0-15. In addition, a second set
exists which has more mnemonic meaning. The user is urged to utilize
only symbolic registers in his program, and should thus include any of
the required EQU instructions in his program. In particular, registers
7-11 should be coded using the symbols RA-RE. The additonal symbolic
register equates are as follows:
RW EQU R3 GENERAL WORK REGISTER 1
RX EQU R4 GENERAL WORK REGISTER 2
RY EQU R6 GENERAL WORK REGISTER 3
RZ EQU R6 GENERAL WORK REGISTER 4
RA EQU R7 PARAMETER REGISTER 1
This register is commonly used as a scan pointer register
inside the assembler.
RB EQU R8 PARAMETER REGISTER 2
This register is commonly used to pass a control value to
a subroutine, and on return, almost always contains either
an error code, or a zero to show no errors.
RC EQU R9 PARAMETER REGISTER 3
This register is most often used in the assembler for passing
a 24-bit value (such as the result of an expression or a
self-defining term).
RD EQU R10 PARAMETER REGISTER 4
RE EQU R11 PARAMETER REGISTER 5
Registers RD and RE may be used for subroutines needing more
than two or three arguments, but are more commonly used as
work temporary work registers.
RAT EQU R12 ASSEMBLER TABLE POINTER-READ ONLY
This register points the main assembler table (VWXTABL csect,
AVWXTABL dsect) during an assembly. No subroutine in the
assembler may modify this register.
RSA EQU R13 SAVE AREA POINTER/BASE REG FOR SOME
This register is used to point to an OS/360 save area, for
any subroutine which may call another. Almost all subroutines
use this as a base register if they are not lowest-level
routines.
RET EQU R14 RETURN ADDRESS USED IN CALLS
This is used in subroutine linkage for the return address to
a calling program. This symbol is generally used whenever
subroutine linkage is being set up, while R14 is used when the
register is being used as a temporary work register.
REP EQU R15 ENTRY POINT ADDRESS/OFTEN USED BASE
This register is used to hold the entry point address for all
subroutines in the assembler. Lowest-level routines usually
use this as a base register. In other routines, this may be
used as a local work register, in which case the symbol R15
is normally coded.
ASREPLGD-07
2. LINKAGE CONVENTIONS - THE ASSEMBLER
The linkage conventions inside the ASSIST assembler consist of
a few modifications to the standard OS/360 linkage conventions, which
have been changed mainly to save time and space. The differences are
as follows:
a. Registers R0-R6 (or R0-R2, RW-RZ) are protected across any
calling sequence and must be restored if changed. R14 (RET) must also
be restored if changed before returning.
b.Register R12(RAT) may not be changed by any routine.
c. Registers R7-R11 (RA-RE) are used for parameters and temporary
work registers, and are not protected at all across calls. No routine
ever requires more than five arguments, so these five registers are
sufficient.
d. Except for the above, all normal OS/360 conventions are followed
regarding save area linkage requirements and usage. In general, most
routine only save as many registers as required. Lowest-level routines
use R15 as a base, and do not perfrom save area linkage, other routines
usually use R13 as a base and save area pointer.
e. For replacement runs, the user must include any needed EQU
symbols for registers. Note that all documentation and output produced
by the Replace Monitor refers to registers 7-11 as RA-RE, so that
using these symbols in a replacement program will aid reading the
various diagnostic output produced.
ASREPLGD-08
PART II. REPLACE MONITOR DEBUGGING AIDS
A. THE RFLAG
Communication between the user program and the Replace Monitor
is achieved through the use of the User Replace Flag, called the RFLAG.
This is a two-byte area of storage which may initialized for an entire
run using the RFLAG= option in the PARM field. Certain bits in it
determine which diagnostic messages the Replace Monitor prints when
it intercepts a call to a replaced module. These bits can also be
changed by the user program during execution, thus allowing the user
to obtain additional information when needed. The various bits of the
RFLAG are used as described in the table below.
BYTE BITS DECIMAL BINARY MEANING IF BIT ON (AR### MESSAGE)
------------------------------------------------------------------------
0 0-7 currently unused, user can set or test
for his own purposes.
1 7 1 00000001 print current statement on entry (AR051)
6 2 00000010 print registers RA-RE on entry (AR052)
5 4 00000100 print correct regs RA-RE, on exit (AR054)
from original ASSIST module
4 8 00001000 print registers RA-RE on exit from (AR058)
user replacement module
3 16 00010000 print registers RA-RE if user (AR050)
module calls an original ASSIST module.
1,2 64,32 01100000 reserved for future use
0 128 10000000 is set to 1 when there is an error (AR059)
parameter registers returned by the user
program. Is set to 0 if acceptable.
------------------------------------------------------------------------
Bit 0 of byte 1 can be used to start extra debugging output only
after an error occurs. See the XREPL example for this action.
The entire first byte is reserved for the user program, such as for
additional debugging flag bits for controling the program.
Note that bits 5,6,7 are tested before the call to the user
program. Thus, changing them affects output beginning at the next
call to a user module.
B. THE XREPL INSTRUCTION
The XREPL instruction is an SI format instruction, in which the
immediate field is used to specify a type of action. It is coded as
XREPL ADDR,CODE with CODE meaning as follows:
0 set the RFLAG from the 2-byte area specified by ADDR.
1 fetch the RFLAG into the 2-byte area specified by ADDR.
2 fetch the number of instructions left into the 4-byte area given by
ADDR. This value is decremented each time an instruction is done.
The following gives an example of the use of XREPL:
XREPL MYRFLAG,1 get the value of the RFLAG
TM MYRFLAG+1,128 was there an error last time
BZ *+12 no, don't reset it
OI MYRFLAG+1,8+4+2+1 set all these for debug output
XREPL MYRFLAG,0 reset the RFLAG to new setting
ASREPLGD-09
PART III. JOB CONTROL LANGUAGE AND PARM OPTIONS
A. JOB CONTROL LANGUAGE
The deck setup for a single-job replacement run is as follows:
// a JOB CARD
// EXEC ASACG,PARM='REPL,other options if any'
//SYSIN DD *
.....user-written replacement program.....
END , end card of replacement program
..... user test deck for his replacement program.....
/*
The deck setup for a replace program run under BATCH is:
$JOB ASSIST ACCT#,REPL,other options, if any
..... user-written replacement program
$ENTRY (required to initiate test)
..... user test deck for replacement program
$ENTRY (optional, if user wants assembled test
program to execute also - unlikely)
B. PARM OPTIONS
The following PARM field options are of particular interest to
the user of the replacement facility. (see PART III. of USER'S GUIDE).
REPL required if the run is to be a replacement run rather than
just a normal assembly and execution.
RFLAG=number coded to initialize the value of the RFLAG for the entire
run. The default value is 0.
BATCH may be coded if the user wants to test more than one module,
or more than one version of the same module in the same run.
I=number the instruction count limit specified applies to each call of
a replacement module. It is therefore recommended that this
optional operand be coded, and that its value be fairly small.
ASREPLGD-10
PART IV. REPLACE MONITOR MESSAGES
The following lists the messages which may be produced during a
replace run by the Replace Monitor. Note that all these messages are
printed inline with output produced by other sections of ASSIST. In
particular, Replace Monitor output is embedded in the listing of the
user test program, which can possibly make it difficult to read in some
cases. A helpful procedure is to run the test program by itself under
ASSIST, thus obtaining a listing, then insert a PRINT OFF command at
the beginning. This will remove most of he test program listing.
All Replace Monitor messages are of the form ///AR### message.
The type of message is indicated by the value of ###, as follows:
000-049 - informative or warning messages.
050-099 - debugging output messages,produced during intercepted call.
100-199 - severe error message, causing replacement interception to end.
AR000 REPLACE CSECT: name ///
This message appears immediately after the replace csect has been
assembled, with name being the name of the replacing csect.
AR001 REPLACE ENTRY: name AT LOCATION: xxxxxx ///
If message AR000 appears, each properly defined entry point in the
csect will be listed here with its location xxxxxx in memory. Note
that a csect which can be entered through its csect name is also
listed.
AR002 REPLACE ENTRY: name NOT FOUND AS CSECT OR ENTRY ///
This message may appear with the AR000 and AR001 messages for any
entry or csect name which is required, but either not defined in
the user program or not declared as CSECT or ENTRY. If this entry
name is called during execution, its execution will be terminated
with an AR101 message and storage dump.
AR003 STATISTICS: # INSTRUCTIONS # CALLS # WRONG INSTRS/CALL %WRONG
This message appears after the test program is assembled.
AR004 name : 5 decimal numbers
One of this message appears for each entry point after AR003. It
describes the performance of the named entry point during the run.
AR050 ON CALL TO name REGISTERS RA-RE (values of regs 7-11)
This message may be printed if the RFLAG byte 1 bit 3 is set and
the user program calls some other ASSIST module. It may also be
printed if the user program tries to pass illegal parameter values
to the routine name.
ASREPLGD-11
AR051 ON ENTRY TO name STMT ADDR: xxxxxx -> cardimage
This message is printed before calling the user program, and shows
the current statement being processed, if any. The address of the
cardimage is given by xxxxxx, which corresponds to the first
character following the '>' in the message. The message is
if RFLAG byte 1 bit 7 is set before the call, or if an error
occurs in the user program.
AR052 ON ENTRY TO name REGISTERS RA-RE: (values of 5 registers)
This message displays the 5 parameter registers before the user
program name is called, and is printed if RFLAG byte 1 bit 6 is
on before the user program is called, or if there is an error.
AR054 ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)
This message shows the correct values of the parameter registers
as returned by the original ASSIST module name. It is printed
if RFLAG byte 1 bit 5 is on before call to the module, or if the
user program makes an error.
AR058 ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)
If RFLAG byte 1 bit 4 is on after completion of the user program,
or if there is an error, this message appears, and gives the values
of the parameter registers as returned by the user entry name.
AR059 WARNING: ERROR IN USER REGS: error list
If any of the user registers has an incorrect value, this message
is printed, either following AR050 or AR058, depending on whether
the incorrect value(s) were in a call to another module or in a
return of values to the calling program.
The error list consists of one or more of the following:
R0-R6 when a user program returned, the values in registers
0-6 were not all the same as when it was called.
R12 the user program modified the value of the assembler
table pointer, which is not permitted.
R13 the user did not restore the save area pointer.
$$$$$$$$ The dollar signs indicate a register shown in messages
AR050 or AR058 as incorrect.
If this message appears, RFLAG byte 1 bit 0 is set to 1 for the
next time the user program is called.
AR100 REPLACE CSECT NOT FOUND - REPLACE ABORT ///
This message appears immediately after the assembly of the user
program. None of the allowable csect names were found as a csect
in the user program.
AR101 INVALID ENTRYPOINT NAME: name CALLED. REPLACE ACTION ABORTED ///
If name appeared in an AR002 message and is called, this message
appears, followed by a dump of user storage and the last values of
the user registers.
AR102 USER PROGRAM ABENDED DURING REPLACEMENT ///
Replace action is aborted and a dump given.