| 3.0/B MARCH 1974 |
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, meaningful 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.
PART I. THE ASSEMBLY LANGUAGE UNDER ASSIST
SECTION I: INTRODUCTION
Compatibility
Macro Instructions
The Assembler Program
SECTION 2: GENERAL INFORMATION
Symbols
General Restrictions on Symbols
Location Counter References
Literals
Literal Pool
Expressions
SECTION 3: ADDRESSING -- PROGRAM SECTIONING AND LINKING
USING -- Use Base Register
CONTROL SECTIONS
Control Section Location Assignment
FIRST CONTROL SECTION
START -- Start Assembly
CSECT -- Identify Control Section
DSECT -- Identify Dummy Section
*EXTERNAL DUMMY SECTIONS (ASSEMBLER F ONLY)
*COM -- DEFINE BLANK COMMON CONTROL SECTION
SECTION 4: MACHINE INSTRUCTIONS
Instruction Alignment and Checking
OPERAND FIELDS AND SUBFIELDS
SECTION 5: ASSEMBLER LANGUAGE STATEMENTS
*OPSYN -- EQUATE OPERATION CODE
DC -- DEFINE CONSTANT
Operand Subfield 3: Modifiers
Operand Subfield 4: Constant
CCW -- DEFINE CHANNEL COMMAND WORD
Listing Control Instructions
TITLE -- IDENTIFY ASSEMBLY OUTPUT
PRINT -- PRINT OPTIONAL DATA
PROGRAM CONTROL INSTRUCTIONS
*ICTL, ISEQ, PUNCH, REPRO
LTORG -- BEGIN LITERAL POOL
Special Addressing Considerations
Duplicate Literals
*COPY -- COPY PREDEFINED SOURCE CODING
SECTION 6: INTRODUCTION TO THE MACRO LANGUAGE
SECTION 7: HOW TO PREPARE MACRO DEFINITIONS
SECTION 8: HOW TO WRITE MACRO-INSTRUCTIONS
SECTION 9: HOW TO WRITE CONDITIONAL ASSEMBLY INSTRUCTIONS
SECTION 10: EXTENDED FEATURES OF THE MACRO LANGUAGE
APPENDIX K: USE OF LIBRARY MACROS
PART II. INPUT/OUTPUT AND DEBUGGING INSTRUCTIONS
INPUT/OUTPUT INSTRUCTIONS - XREAD, XPRNT, XPNCH
CONDITION CODE
CARRIAGE CONTROL
EXAMPLES OF XREAD, XPRNT, XPNCH USAGE
DEBUGGING INSTRUCTION - XDUMP
GENERAL PURPOSE REGISTER DUMP
STORAGE DUMP
EXAMPLES OF XDUMP USAGE
DECIMAL CONVERSION INSTRUCTIONS - XDECI, XDECO
XDECI
XDECO
SAMPLE USAGE OF XDECI
SAMPLE USAGE OF XDECO
HEXADECIMAL CONVERSION INSTRUCTIONS - XHEXI, XHEXO
XHEXI
XHEXO
SAMPLE USAGE OF XHEXI AND XHEXO
LIMIT DUMP INSTRUCTION - XLIMD
SAMPLE USAGE OF XLIMD
OPTIONAL INPUT/OUTPUT INSTRUCTIONS - XGET, XPUT
CONDITION CODE
CARRIAGE CONTROL
EXAMPLES OF XGET AND XPUT USAGE
PART III. ASSIST CONTROL CARDS AND DECK SETUP
A. JOB CONTROL LANGUAGE
B. OPTIONAL PARAMETERS FOR ASSIST
C. DESCRIPTION OF INDIVIDUAL OPTIONS
PART IV. ASSIST OPTIONAL EXTENDED INTERPRETER
A. GENERAL DESCRIPTION OF NEW FEATURES
B. THE XOPC (Assist OPtions Call) DEBUGGING INSTRUCTION
PART V. OUTPUT AND ERROR MESSAGES
A. ASSEMBLY LISTING
1. ASSEMBLY LISTING FORMAT
2. ASSEMBLER ERROR MESSAGES
3. LIST OF ASSEMBLER ERROR MESSAGES
4. ASSEMBLER STATISTICS SUMMARY
B. ASSIST MONITOR MESSAGES
1. HEADING AND STATISTICAL MESSAGES
2. ASSIST MONITOR ERROR MESSAGES
E. OBJECT DECKS AND LOADER MESSAGES
1. OBJECT DECK FORMAT
2. ASSIST LOADER USAGE AND MESSAGES
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.
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 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.
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.
ASSIST allows full use of the location counter *, with the following exceptions:
L 1,=A(*+20)
NAME DC 256AL1(*-NAME)
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.
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.
Use of general expressions is permitted for most statements. Any restrictions are noted under the individual statements.
The first expression (address) in a USING statement must be relocatable.
Multiple control sections are allowed. A program must contain at least one control section.
Control sections may not be intermixed under ASSIST, i.e., all the statements of one control section must be coded before another is begun.
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.
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.
No more than one CSECT may use a given symbol as a name, and statements from different CSECT's may not be interspersed.
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 are not supported, so the commands CXD and DXD are not recognized.
If any statement requires alignment and causes bytes to be skipped, the bytes skipped are NOT necessarily set to hexadecimal zeros.
ASSIST permits the same use of expressions in machine-instruction operand fields as does the standard assembler.
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.
The following modifiers are not permitted by ASSIST: Bit-Length Specification, Scale Modifier, and Exponent Modifier.
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.
No scale or exponent modifiers are allowed, but exponents are accepted within each constant.
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'
only A and V address constants are allowed.
are not allowed.
may not be used in a literal constant if it refers to the location counter. It will be assembled improperly if it does so.
are not allowed.
The CCW is recognized and allocated storage, but is not otherwise assembled. It will be flagged 'NOT CURRENTLY IMPLEMENTED'.
No title may have a symbol in the name field.
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.
ICTL -- INPUT FORMAT CONTROL, ISEQ -- INPUT SEQUENCE CHECKING, PUNCH -- PUNCH A CARD, and REPRO -- REPRODUCE FOLLOWING CARD : are not accepted by ASSIST.
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 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.
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=1 as described in Part III.
COPY statements are not allowed.
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.
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.
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.
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 are not allowed.
There are no changes from the IBM standard.
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.
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.
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 follows the same restriction as AIF: backwards branches are allowed in macros, but not in open code.
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.
There are no changes, except that attributes L', S', and I' are not supported.
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.
CSECT or DSECT statements processed in a macro definition do NOT affect the value for &SYSECT for any subsequent inner macros in that definition.
ASSIST does not accept AGOB or AIFB.
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. 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:
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
The user should be aware of the following when using the macro library facility:
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:
MACRO
IHBERMAC &A,&B,&D,&E,&F,&H
MNOTE 4,'PSEUDO IHBERMAC CALLED: &A,&B,&D,&E,&F,&H'
MEND
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
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.
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).
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.
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
One basic debugging command is provided, called XDUMP. It can be used in two different ways, to print either registers or storage areas:
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* XDUMP1 is the same as XDUMP with no operand.
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.
XDUMP AREA+10,80
XDUMP 8(1,4),100
XDUMP FULLWORD use default value of 4
XDUMP TABL(3),12
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 is generally used to scan a data card read by XREAD. The sequence of actions performed by XDECI is as follows:
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.
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
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
(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 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:
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.
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
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.
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.
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.
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.).
XPUT only requires the first character of the area to be a valid carriage control character, if the output device is the printer.
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.
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.
Depending on the type of ASSIST desired at a given installation, one or two different types of deck setup can be used.
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 1 PARM='option,option....' after ASACG on the EXEC card.
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)
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:
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) // 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.
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
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.
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.
The BATCH option allows multiple jobs to be run in one invocation of ASSIST. It is described in Part III.A. of this manual.
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.
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.
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).
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.
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.
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.
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.
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=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.
This is used to specify the maximum lines per page, and is only enabled if the CPAGE option is turned on.
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.
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.
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.
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.
This provides a default value for the starting ACTR counters in all macros used. It can be overridden by explicit ACTR statements.
This gives a limit on the maximum level of nested macro calls, thus allowing prevention of unwanted recursion in macros.
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.
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.
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.
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:
At steps 3 and 4 the lines remaining count is just carried forward, so that the user gets the benefit of any partial pages.
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).
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=).
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:
saves no pages for dump. Good for debugged programs.
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.
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.
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=.
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= 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.
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 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.
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.
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.
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 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 is the SS option during user execution (see SS above).
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).
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.
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).
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 1 L 0,X 1 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.
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=give the modify and fetch bits for the SD flag. SR= give the modify and fetch bits for the SR flag. Possible values for and are: 0: turn bit off. 1: turn bit on. *: leave bit in previous state.
If an
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.
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.
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.
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:
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.
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.
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
This instruction combines the actions of XOPC instructions 1 and 2. It assumes register usage the same as in XOPC 1.
This instruction disables the Instruction Trace.
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.
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
This instruction combines the actions of the XOPC 5 and XOPC 6 instructions above.
This instruction disables the Storage Modification 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).
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.
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.
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).
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).
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.
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.
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.
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.
This instruction combines the actions of XOPC instructions 16 and 17. Register usage is assumed to be the same as in XOPC 17.
This instruction disables the IECF. This instruction will not have any effect on the IECF 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.
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:
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:
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
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.
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:
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:
The following lists the codes and messages issued by the ASSIST assembler, with further explanations following each message.
The address used in a machine instruction is not aligned to the correct boundary required by the type of instruction used.
A symbol named in an ENTRY statement is either undefined, or is also named in either a DSECT or EXTRN statement.
A symbol named in an EXTRN statement is either defined in the program or is named in an ENTRY statement.
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.
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.
The assembler creates an END card because the user has supplied none before an end-file marker.
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.
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.
An unrecognizable type of constant is specified.
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.
Three or more continuation cards are used, which is illegal, except on macro prototype statements and macro calls.
ASSIST does not permit complex relocatible expressions.
ASSIST allows no more than ten operands in a DC statement.
The assembler requires that any section be coded in one piece. The label flagged has already appeared on a CSECT or DSECT.
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.
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.
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.
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 .
A label is used on a statement not permitting one, such as a CNOP or USING statement.
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.
A constant contains invalid characters for its type, or is specified improperly in some other way.
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.
The field flagged has an unrecognizable value, or is otherwise incorrectly coded. PRINT OF is flagged this way.
The symbol flagged either contains nine or more characters or does not begin with an alphabetic character as is required.
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.
The symbol in the label field has been previously used as a label, or a SET variable has been previously declared.
A relocatable expression is used where an absolute one is required, such as in constant duplication factor or for a register.
A delimiter is expected but not found. For instance, a C-type constant coded with no ending ' is flagged this way.
The version of ASSIST being used does not support the language feature used.
The instruction requires an operand, but it is not specified.
An instruction requiring a label, such as a DSECT, is coded without one.
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.
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.
The START card flagged is coded with one or more statements other than listing controls or comments appearing before it.
The literal constant appears in the receiving field of an instruction which modifies storage. e.g., ST 0,=F'1'
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.
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.
The character flagged is either not in the set of acceptable characters, or is used in an illegal way.
Parentheses are nested more than five deep in an expression.
RElocatable terms or expressions may not be used with either of these operators.
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.
The expression contains more than the legal maximum of 16 terms.
The expression terminates without having enough closing parentheses to balance the opening ones used.
During macro expansion, an extra operand was found, i.e., an extra positional beyond those given in the prototype.
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.
A dimensioned set symbol was used without a dimension, or one which was not dimensioned was written with one.
There was an error in specifying substring notation, sublists, or set symbol dimension.
During macro editing, a SET instruction was found with an obviously Incorrect conversion, as in &I SETA C .
Quotes (apostrophes) are required in character expressions and must always be supplied, but were not.
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.
An operand is used with an incompatible operator. For example, if &C is LCLC, &B LCLB : &B SETB (NOT &C) .
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.
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 .
ASSIST does not support S', I', or L' for macro operands.
A STATEMENT WAS GENERATED HAVING MORE THAN TWO CONTINUATION CARDS .
During expansion of macro 'name', the statement numbered ##### was encountered, but not expanded because it had already been flagged.
The following call to the macro listed caused overflow of storage1 probably due to looping. Use ACTR, MACTR=, or MSTMG= .
This may appear following an entire macro definition, and gives the number of a statement referencing a sequence symbol never defined .
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).
The ACTR count has been exceeded. The ACTR is set by the MACTR option, or by an ACTR statement. This indicates a looping macro .
A subscript is out of range. The offending value is given.
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.
The value could not be converted to arithmetic form.
The value was not 0 or 1.
The value was not '0' or '1', so it could not be converted.
An attribute was used incorrectly.
The subscript has a value greater than the maximum number of fields which can be supplied.
An internal error has occurred inside ASSIST. Please send a deck.
Too much concatenation was done in the statement. Remedy: reduce the complexity of the statement.
The MSTMG limit (total number of statements processed during macro expansion) has been exceeded. Use MSTMG= to increase this.
One of these interrupts was caused by the statement given.
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.
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.
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.
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.
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.
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.
Following the assembly listing, the assembler prints three or four lines of statistical information, as follows:
This notes the total numbers of statements flagged, warning messages, and error messages given during the assembly.
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).
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.
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.
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.
The main control program of ASSIST may issue the following headings and messages during execution:
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).
Following the above heading, the ASSIST monitor prints the contents of the user's EXEC card PARM field, or his $JOB CARD.
This message is issued immediately before the user program is executed, and serves to delimit user output.
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.
This is the last line printed by ASSIST, and the time given includes time for the entire run. Printed only if CHECK/TRP/=2## .
The ASSIST monitor may also issue any of the following messages, which are of the form AM###, and usually indicate errors:
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.
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.
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.
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.
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.
When a user program terminates abnormally, a completion dump is provided for debugging purposes, and contains the following items:
The above header begins the dump.
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:
The three-digit hexadecimal code is followed by a descriptive message. PART IV.D provides a list of the messages and codes.
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.
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.
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.
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.
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.
This type is given for special ASSIST completions. The possible codes and messages are as follows:
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.
The user specified an I= limit on his EXEC card, and this number of instructions has been exceeded. The program was probably looping.
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.
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.
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.
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.
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:
Regardless of the method used to create the input deck, the entire object deck must follow the rules below:
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).
Messages produced by the ASSIST loader are of the form AL###, and include the following messages:
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.
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' 1 and the offending card displayed beginning at the first address given by the XSNAP.
The loader encountered an end-of-file indication or ASSIST control card before finding any TXT cards.
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.
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.
This message follows any of the other messages to note the immediate termination of the loading process.
This page was last modified by Michael Stack on Thursday, January 14, 2010, at 01:53:21 PM CST