, 00001000 ASSIST1-1 00001010 3.0/B 00001020 ASSIST MARCH 1974 00001030 INTRODUCTORY ASSEMBLER USER'S MANUAL 00001040 00001050 Program&Documentation: John R. Mashey 00001060 Project Supervision : Graham Campbell 00001070 Computer Science Department - Pennsylvania State University 00001080 00001090 00001100 PREFACE 00001110 00001120 This manual is the basic reference for the programmer writing00001130 in the Assembler Language for the IBM S/360 computer, using the ASSIST00001140 assembler-interpreter system. ASSIST (Assembler System for Student00001150 Instruction and Systems Teaching) is a small, high-speed, low-overhead00001160 assembler/interpreter system especially designed for use by students00001170 learning assembler language. The assembler program accepts a large00001180 subset of the standard Assembler Language under OS/360, and includes00001190 most common features. The execution-time interpreter simulates the00001200 full 360 instruction set, with complete checking for errors, meaning-00001220 ful diagnostics, and completion dumps of much smaller size than the00001230 normal system dumps. 00001240 00001250 The first part of this manual describes the assembly language00001260 commands permitted by the ASSIST assembler. In essence, it is a00001270 comparison with the standard Assembly Language, and generally notes00001280 only the omissions or differences from the standard. The reader should00001290 refer to one of the following publications, which the first part of this00001300 manual closely follows (depending on operating system used): 00001310 00001320 C28-6514 IBM SYSTEM/360 OPERATING SYSTEM ASSEMBLER LANGUAGE 00001330 00001340 C24-3414 IBM SYSTEM/360 DISK AND TAPE OPERATING SYSTEM ASSEMBLER LANG. 00001350 00001360 The second section describes input/output, decimal conversion,00001370 hexadecimal conversions, and debugging facilities available to the user00001380 at execution time. 00001390 00001400 The third part of the manual describes the control cards and00001410 Job Control Language required to assemble and execute a program00001420 under ASSIST. It also notes the various options from the PARM00001430 field which are accepted by the system. 00001440 00001450 The fourth section gives information concerning the output00001460 from ASSIST, including the assembly listing, the format of the00001470 completion dump produced by an error in program execution, and00001480 a list of all error messages produced during assembly or execution.00001490 It also describes the object decks produced/accepted by ASSIST. 00001500 00001510 Note: this document is NOT copyrighted. 00001520 00001530 Note: only major change in documentation from version 2.100001540 is the inclusion of cross-reference material(XREF) 00001550 and the inclusion of the extended interpreter 00001560 material. 00001570 , 00002000 ASSIST1-2 00002010 TABLE OF CONTENTS 00002020 00002030 PART I. THE ASSEMBLY LANGUAGE UNDER ASSIST................. 1-4 00002040 The sections flagged * note that the given language features 00002050 are not accepted by ASSIST. 00002060 00002070 SECTION I: INTRODUCTION.................................... 1-4 00002080 Compatibility......................................... 1-4 00002090 Macro Instructions.................................... 1-4 00002100 The Assembler Program................................. 1-5 00002110 00002120 SECTION 2: GENERAL INFORMATION............................. 1-5 00002130 Symbols............................................... 1-5 00002140 General Restrictions on Symbols....................... 1-5 00002150 Location Counter References........................... 1-5 00002160 Literals.............................................. 1-5 00002170 Literal Pool.......................................... 1-5 00002180 Expressions........................................... 1-5 00002190 00002200 SECTION 3: ADDRESSING -- PROGRAM SECTIONING AND LINKING.... 1-6 00002210 USING -- Use Base Register............................ 1-6 00002220 CONTROL SECTIONS...................................... 1-6 00002230 Control Section Location Assignment................... 1-6 00002240 FIRST CONTROL SECTION................................. 1-6 00002250 START -- Start Assembly............................... 1-6 00002260 CSECT -- Identify Control Section..................... 1-6 00002270 DSECT -- Identify Dummy Section....................... 1-6 00002280 *EXTERNAL DUMMY SECTIONS (ASSEMBLER F ONLY)............ 1-6 00002290 *COM -- DEFINE BLANK COMMON CONTROL SECTION............ 1-6 00002300 00002310 SECTION 4: MACHINE INSTRUCTIONS............................ 1-7 00002320 Instruction Alignment and Checking.................... 1-7 00002330 OPERAND FIELDS AND SUBFIELDS.......................... 1-7 00002340 00002350 SECTION 5: ASSEMBLER LANGUAGE STATEMENTS................... 1-7 00002360 *OPSYN -- EQUATE OPERATION CODE........................ 1-7 00002370 DC -- DEFINE CONSTANT................................. 1-7 00002380 Operand Subfield 3: Modifiers......................... 1-7 00002390 Operand Subfield 4: Constant.......................... 1-7 00002400 CCW -- DEFINE CHANNEL COMMAND WORD.................... 1-8 00002410 Listing Control Instructions.......................... 1-8 00002420 TITLE -- IDENTIFY ASSEMBLY OUTPUT..................... 1-8 00002430 PRINT -- PRINT OPTIONAL DATA.......................... 1-8 00002440 PROGRAM CONTROL INSTRUCTIONS.......................... 1-8 00002450 *ICTL, ISEQ, PUNCH, REPRO.............................. 1-8 00002460 LTORG -- BEGIN LITERAL POOL........................... 1-8 00002470 Special Addressing Considerations..................... 1-8 00002480 Duplicate Literals.................................... 1-8 00002490 *COPY -- COPY PREDEFINED SOURCE CODING................. 1-8 00002500 00002510 SECTION 6: INTRODUCTION TO THE MACRO LANGUAGE ............. 1-9 00002520 SECTION 7: HOW TO PREPARE MACRO DEFINITIONS ............... 1-10 00002530 SECTION 8: HOW TO WRITE MACRO-INSTRUCTIONS ................ 1-10 00002540 SECTION 9: HOW TO WRITE CONDITIONAL ASSEMBLY INSTRUCTIONS . 1-11 00002550 SECTION 10: EXTENDED FEATURES OF THE MACRO LANGUAGE ....... 1-12 00002560 , 00003000 ASSIST1-3 00003010 00003020 PART I. (CONTINUED) 00003030 APPENDIX K: USE OF LIBRARY MACROS.......................... 1-12 00003060 00003070 PART II. INPUT/OUTPUT AND DEBUGGING INSTRUCTIONS........... 2-1 00003100 00003110 INPUT/OUTPUT INSTRUCTIONS - XREAD, XPRNT, XPNCH............ 2-1 00003120 CONDITION CODE........................................ 2-1 00003130 CARRIAGE CONTROL...................................... 2-1 00003140 EXAMPLES OF XREAD, XPRNT, XPNCH USAGE................. 2-2 00003150 00003160 DEBUGGING INSTRUCTION - XDUMP.............................. 2-3 00003170 GENERAL PURPOSE REGISTER DUMP......................... 2-3 00003180 STORAGE DUMP.......................................... 2-3 00003190 EXAMPLES OF XDUMP USAGE............................... 2-3 00003200 00003210 DECIMAL CONVERSION INSTRUCTIONS - XDECI, XDECO............. 2-4 00003220 XDECI................................................. 2-4 00003230 XDECO................................................. 2-4 00003240 SAMPLE USAGE OF XDECI................................. 2-5 00003250 SAMPLE USAGE OF XDECO................................. 2-5 00003260 00003270 HEXADECIMAL CONVERSION INSTRUCTIONS - XHEXI, XHEXO......... 2-6 00003280 XHEXI................................................. 2-6 00003290 XHEXO................................................. 2-6 00003300 SAMPLE USAGE OF XHEXI AND XHEXO....................... 2-7 00003310 00003320 LIMIT DUMP INSTRUCTION - XLIMD............................. 2-8 00003330 SAMPLE USAGE OF XLIMD................................. 2-8 00003340 00003350 OPTIONAL INPUT/OUTPUT INSTRUCTIONS - XGET, XPUT............ 2-9 00003360 CONDITION CODE........................................ 2-9 00003370 CARRIAGE CONTROL...................................... 2-9 00003380 EXAMPLES OF XGET AND XPUT USAGE....................... 2-10 00003390 00003400 , ASSIST1-4 00004000 00004010 PART III. ASSIST CONTROL CARDS AND DECK SETUP.............. 3-1 00004020 00004030 A. JOB CONTROL LANGUAGE.................................... 3-1 00004040 00004050 B. OPTIONAL PARAMETERS FOR ASSIST.......................... 3-2 00004060 00004070 C. DESCRIPTION OF INDIVIDUAL OPTIONS....................... 3-4 00004080 00004090 PART IV. ASSIST OPTIONAL EXTENDED INTERPRETER.............. 4-1 00004100 00004110 A. GENERAL DESCRIPTION OF NEW FEATURES..................... 4-1 00004120 00004130 B. THE XOPC (Assist OPtions Call) DEBUGGING INSTRUCTION.... 4-2 00004140 00004150 PART V. OUTPUT AND ERROR MESSAGES......................... 5-1 00004160 00004170 A. ASSEMBLY LISTING........................................ 5-1 00004180 1. ASSEMBLY LISTING FORMAT............................ 5-1 00004190 2. ASSEMBLER ERROR MESSAGES........................... 5-1 00004200 3. LIST OF ASSEMBLER ERROR MESSAGES................... 5-2 00004210 4. ASSEMBLER STATISTICS SUMMARY....................... 5-10 00004220 00004230 B. ASSIST MONITOR MESSAGES................................. 5-11 00004240 1. HEADING AND STATISTICAL MESSAGES................... 5-11 00004250 2. ASSIST MONITOR ERROR MESSAGES...................... 5-12 00004260 00004270 C. ASSIST COMPLETION DUMP.................................. 5-13 00004280 00004290 D. COMPLETION CODES........................................ 5-14 00004300 00004310 E. OBJECT DECKS AND LOADER MESSAGES........................ 5-15 00004320 1. OBJECT DECK FORMAT................................. 5-15 00004330 2. ASSIST LOADER USAGE AND MESSAGES................... 5-16 00004340 00004350 00004360 00004370 PART I. THE ASSEMBLY LANGUAGE UNDER ASSIST 00004380 00004390 This section deals with the subset of the standard OS/36000004400 Assembler Language accepted be the ASSIST assembler. Because it00004410 follows the standard very closely, the following describes only00004420 those language features which ASSIST omits or treats differently.00004430 The user should generally consult the previously-mentioned publication00004440 for most of the information on the assembler language. The section00004450 headings and sub-headings in this manual are taken from the IBM00004460 publication, and any sections omitted may be assumed to be the same as00004470 the corresponding sections in the IBM manual. 00004480 00004490 SECTION 1: INTRODUCTION 00004500 00004510 Compatibility 00004520 With a few possible exceptions, any program which assembles00004530 and executes correctly under ASSIST should do so using the standard00004540 OS/360 software, and should produce the same output as under ASSIST.00004550 At most, a change of Job Control Language might be necessary. 00004560 , ASSIST1-5 00005000 00005010 The Assembler Program 00005020 The assembler program produces a listing of the source program, and00005030 normally creates an object program directly in main memory, while using00005040 no secondary storage, unless requested. An object deck can be punched.00005050 00005060 SECTION 2: GENERAL INFORMATION 00005070 00005080 General Restrictions on Symbols 00005090 A symbol may be defined only once in an assembly, i.e., it may00005100 appear in the name field of no more than one instruction. The00005110 same symbol may not be used as a label in two different control00005120 sections, and control sections may not be resumed, the only case00005130 in the standard language allowing the same symbol on more than one00005140 statement. 00005150 00005160 Location Counter Reference 00005170 ASSIST allows full use of the location counter *, with the00005180 following exceptions: 00005190 00005200 1. The programmer may not refer to the location counter inside00005210 a literal address constant. Thus, the following statement will00005220 produce incorrect results: 00005230 00005240 L 1,=A(*+20) 00005250 00005260 2. The programmer may not refer to the location counter in00005270 an A-type address constant having a duplication factor greater00005280 than one, if the reference is made in such a way that the various00005290 duplications of the specified constant have different values.00005300 For instance, under OS/360, the following statement would produce00005310 the values 0,1,...,255, but ASSIST would produce 256 bytes of00005320 zero: 00005330 00005340 NAME DC 256AL1(*-NAME) 00005350 00005360 Literals 00005370 Literal constants may not contain more than 112 characters,00005380 counting the beginning = and ending delimiter, i.e. may not require00005390 more than two cards when placed in the literal pool. 00005400 00005410 Literal Pool 00005420 Unless otherwise specified by the use of the LTORG instruction,00005430 the literal pool is placed after the program's END card, rather than00005440 at the end of the first control section in the program. 00005450 00005460 Expressions 00005470 Use of general expressions is permitted for most statements.00005480 Any restrictions are noted under the individual statements. 00005490 , 00006000 ASSIST1-6 00006010 00006020 SECTION 3: ADDRESSING -- PROGRAM SECTIONING AND LINKING 00006030 00006040 USING -- Use Base Register 00006050 The first expression (address) in a USING statement must be00006060 relocatable. 00006070 00006080 CONTROL SECTIONS 00006090 Multiple control sections are allowed. A program must contain00006100 at least one control section. 00006110 00006120 Control Section Location Assignment 00006130 Control sections may not be intermixed under ASSIST, i.e.,00006140 all the statements of one control section must be coded before00006150 another is begun. 00006160 00006170 FIRST CONTROL SECTION 00006180 Under ASSIST, the first control section has no properties00006190 different from the other sections, i.e., its initial location00006200 counter value must be relocatable, and it does not normally contain00006210 unassigned literal constants unless it is the only control section.00006220 00006230 START -- Start Assembly 00006240 The START instruction may be preceded by listing control00006250 instructions and comments cards. The same label may not be used on a00006260 START statement and a later CSECT statement. 00006270 00006280 CSECT -- Identify Control Section 00006290 No more than one CSECT may use a given symbol as a name,00006300 and statements from different CSECT's may not be interspersed.00006310 00006320 DSECT -- Identify Dummy Section 00006330 No more than one DSECT may use a given symbol as a name, and00006340 statements from different DSECT's may not be interspersed. 00006350 00006360 EXTERNAL DUMMY SECTIONS (ASSEMBLER F ONLY) 00006370 External dummy sections are not supported, so the commands00006380 CXD and DXD are not recognized. 00006390 00006400 COM -- DEFINE BLANK COMMON CONTROL SECTION 00006410 COM is not allowed. 00006420 , 00007000 ASSIST1-7 00007010 00007020 SECTION 4: MACHINE-INSTRUCTIONS 00007030 00007040 Instruction Alignment and Checking 00007050 If any statement requires alignment and causes bytes to be00007060 skipped, the bytes skipped are NOT necessarily set to hexadecimal zeros.00007070 00007080 OPERAND FIELDS AND SUBFIELDS 00007090 ASSIST permits the same use of expressions in machine-instruction00007100 operand fields as does the standard assembler. 00007110 00007160 00007170 SECTION 5: ASSEMBLER LANGUAGE STATEMENTS 00007180 00007190 OPSYN -- EQUATE OPERATION CODE is not accepted. 00007200 00007210 DC -- DEFINE CONSTANT 00007220 Multiple operands (up to 10 operands in a single DC statement)00007230 and multiple constants within operands are both permitted. Bytes00007240 skipped to align a DC statement are NOT zeroed. 00007250 00007260 Operand Subfield 3: Modifiers 00007270 The following modifiers are not permitted by ASSIST: 00007280 Bit-Length Specification, Scale Modifier, and Exponent Modifier.00007290 00007300 Operand Subfield 4: Constant 00007310 Fixed-Point Constants -- F and H: 00007320 Fixed-point constants may not contain decimal points or exponents00007330 While lengths may range from one to eight bytes, the minimum and maximum00007340 values permitted are those for length 4. 00007350 00007360 Floating-Point Constants -- E and D: 00007370 No scale or exponent modifiers are allowed, but exponents are00007380 accepted within each constant. 00007390 00007400 Decimal Constants -- P and Z: 00007410 If no explicit length is supplied for an operand containing00007420 multiple constants, each of the operands is assembled to the length00007430 of the last constant in the operand, even if truncation is thus00007440 required. For example, under the standard assembler, the following00007450 needs four bytes. Under ASSIST it is assembled into three bytes,00007460 with the second constant truncated: 00007470 DC P'0,20,1' 00007480 00007490 Address Constants: only A and V address constants are allowed.00007500 00007510 Complex Relocatable Expressions: are not allowed. 00007520 00007530 A-type Address Constant: may not be used in a literal constant00007540 if it refers to the location counter. It will be assembled improperly00007550 if it does so. 00007560 00007570 Y-Type, S-Type, and Q-Type Address Constants: are not allowed.00007580 , 00008000 ASSIST1-8 00008010 00008020 CCW -- DEFINE CHANNEL COMMAND WORD 00008030 The CCW is recognized and allocated storage, but is not otherwise00008040 assembled. It will be flagged 'NOT CURRENTLY IMPLEMENTED'. 00008050 00008060 Listing Control Instructions 00008070 00008080 TITLE -- IDENTIFY ASSEMBLY OUTPUT 00008090 No title may have a symbol in the name field. 00008100 00008110 PRINT -- PRINT OPTIONAL DATA 00008120 All operands are accepted, but DATA and NODATA have no effect, i.e.00008130 no more than eight bytes of data are ever printed. Any statement00008140 flagged with an error or warning is always printed, even if the00008150 print control is OFF, or NOGEN for generated statements. 00008160 00008170 PROGRAM CONTROL INSTRUCTIONS 00008180 00008190 ICTL -- INPUT FORMAT CONTROL, ISEQ -- INPUT SEQUENCE CHECKING,00008200 PUNCH -- PUNCH A CARD, and REPRO -- REPRODUCE FOLLOWING CARD :00008210 are not accepted by ASSIST. 00008220 00008230 LTORG -- BEGIN LITERAL POOL 00008240 00008250 Any literals used after the last LTORG are placed after the00008260 END card, instead of at the end of the first control section.00008270 00008280 Duplicate Literals: 00008290 Duplicate literals are never stored, since the programmer may00008300 not refer to the location counter in a literal A-type address00008310 constant, the only case under the regular system requiring the00008320 storing of duplicate literals. 00008330 00008340 COPY -- COPY PREDEFINED SOURCE CODING: is not allowed. 00008350 , 00000050 ASSIST1-9 00000100 00000150 SECTION 6: INTRODUCTION TO THE MACRO LANGUAGE 00000200 00000250 The macro language is a facility which may or may not be included00000300 in a particular version of ASSIST. Also, various levels of the ASSIST00000350 macro processor can be generated, so that the user should check to see00000400 which one(s) are available at his installation. The following00000450 facilities may be available: 00000500 00000550 BASIC (F) MACRO FACILITY: allows programmer-written macros, compatible00000600 with Assembler(F), but without macro library or open code conditional00000650 assembly. 00000700 00000750 EXTENDED (G&H) MACRO FACILITY: like BASIC above, but allows certain00000800 features not supported by Assembler F, but allowed by Assemblers G or H.00000850 00000900 MACRO LIBRARY: some versions of ASSIST permit system macros to be used00000950 in addition to programmer-written macros. This facility requires the00001000 use of a special comment card (*SYSLIB), as described later. 00001050 00001100 OPEN CODE CONDITIONAL ASSEMBLY: system assemblers allow the user to00001150 use conditional assembly statements and SET variables outside macros,00001200 i.e., in the open code, or main body of the program. With certain00001250 restrictions as noted, this facility can be supplied if desired. 00001300 00001400 Finally, in order to use macros at all, the user must supply the00001450 parameter MACRO= , as described in Part III. 00001500 00001550 00001600 THE MACRO DEFINITION 00001650 00001700 COPY statements are not allowed. 00001750 00001800 THE MACRO LIBRARY 00001850 00001900 Certain restrictions exist in ASSIST's processing of system macros.00001950 One or more *SYSLIB cards must follow any programmer-defined macro00002000 definitions. These cards indicate that library search is required, and00002050 must name any macros which are called from the open code later, but have00002100 not been previously mentioned in the programmer-written macros. The00002150 user should consult the appendix USE OF LIBRARY MACROS in this PART.00002200 00002250 SYSTEM AND PROGRAMMER MACRO DEFINITIONS 00002300 00002350 Since ASSIST reads in system macros and edits them upon command of00002400 *SYSLIB cards immediately following programmer macros, they are treated00002450 exactly the same as programmer macros, except that they are not printed00002500 unless requested by the LIBMC option. Errors are attached to correct00002550 statements. 00002600 , 00002650 ASSIST1-10 00002700 00002750 SECTION 7: HOW TO PREPARE MACRO DEFINITIONS 00002800 00002850 00002900 MACRO INSTRUCTION PROTOTYPE 00002950 00003000 Two formats are allowed for statements, the normal one used by all00003050 other statements, and the alternate one allowed only for macro prototype00003100 and macro call statements. ASSIST does allow macro prototypes and macro00003150 calls to be continued on an indefinite number of cards. When there are00003200 no more than 2 continuation cards, ASSIST is completely compatible with00003250 other assemblers. If the total number of cards in a statement exceeds00003300 3, the following restriction must be followed: every third card in the00003350 statement must use the alternate format, unless it is the last one.00003400 (This is done because ASSIST processes cards in groups of 3). The two00003450 prototypes below illustrate this restriction: 00003500 00003550 PROTOTYPE ACCEPTED BY ASSEMBLERS F,G, H, VS, BUT NOT ASSIST: 00003600 &LABEL LONGPROT &PARM1,&PARM2, PARMS,ALTERNATE FORMAT X00003650 &PARM3,&PARM4,&PARM5, PARMS,ALTERNATE FORMAT X00003700 &PARM6,&PARM7=XXXXXXXX,&PARM8=YYYYYYYY,&PARM9=ZZZZZZZZ,&X00003750 PARM9=A LAST LINE 00003800 00003850 EQUIVALENT PROTOTYPE, ACCEPTED BY ASSIST: 00003900 &LABEL LONGPROT &PARM1,&PARM2, PARMS,ALTERNATE FORMAT X00003950 &PARM3,&PARM4,&PARM5, PARMS,ALTERNATE FORMAT X00004000 &PARM6,&PARM7=XXXXXXXX,&PARM8=YYYYYYYY,&PARM9=ZZZZZZZZ, X00004050 &PARM9=A LAST LINE 00004100 00004150 Given this restriction, it is best to place any positional parms00004200 early in the list if they may require long values needing continuation.00004250 00004300 MODEL STATEMENTS 00004350 00004400 Variable symbols MAY be used to generate PRINT and END operations .00004450 If the open code feature is allowed, they may also be used to generate00004500 calls to macros at the outer level, but not inside macros. 00004550 00004600 COPY STATEMENTS 00004650 00004700 COPY statements are not allowed. 00004750 00004800 SECTION 8: HOW TO WRITE MACRO-INSTRUCTIONS 00004850 00004900 There are no changes from the IBM standard. 00004950 , 00005000 ASSIST1-11 00005050 00005100 SECTION 9: HOW TO WRITE CONDITIONAL ASSEMBLY INSTRUCTIONS 00005150 00005200 All of the conditional assembly instructions may be used inside00005250 macros. They may only be used outside if the version of ASSIST being00005300 used supports it, and there are restrictions in that use in any case.00005350 00005400 ATTRIBUTES 00005450 00005500 ASSIST is a two-pass assembler, performing macro-processing 'on the00005550 fly' during pass 1. As such, it is impossible for it to usually know00005600 the attributes of a symbol, so there are definite restrictions. In00005650 effect, the only attributes are those which can be found by looking just00005700 at a macro call statement by itself. The attributes allowed are:00005750 00005800 Attribute Notation 00005850 Type T' only values N, O, and U possible 00005900 Count K' 00005950 Number N' 00006000 00006050 Thus, Length (L'), Scaling (S'), and Integer (I') attributes are00006100 not supported. The only values for Type are N (Numeric), O (Omitted),00006150 and U (undefined), so that the value is U under ASSIST in many cases00006200 where it would be something else under IBM assemblers. 00006250 00006300 AIF -- CONDITIONAL BRANCH 00006350 00006400 IBM assemblers normally assign 4096 as the usual limit for number00006450 of AIF and AGO branches. See ACTR for the way ASSIST handles this.00006500 00006550 The sequence symbol named in the AIF may precede or follow the00006600 AIF statement inside macros. Outside macros, it may only follow the00006650 AIF, i.e., only forward branches are allowed. If a branch is taken to00006700 a previously-defined sequence symbol in open code, ASSIST produces an00006750 an error message and ignores the AIF/AGO. 00006800 00006900 AGO -- UNCONDITIONAL BRANCH 00006950 00007000 AGO follows the same restriction as AIF: backwards branches are00007050 allowed in macros, but not in open code. 00007100 00007150 ACTR -- CONDITIONAL ASSEMBLY LOOP COUNTER 00007200 00007250 ASSIST supports the standard ACTR. However, the default value of00007300 the ACTR counter is set differently, via the MACTR= option supplied by00007350 the user. This has a default value as given in PART III, which is00007400 normally smaller than the IBM value 4096. The MACTR= value is used for00007450 all macro definitions, unless explicitly overridden via ACTR statements.00007500 00007550 CONDITIONAL ASSEMBLY ELEMENTS 00007600 00007650 There are no changes, except that attributes L', S', and I' are not00007700 supported. 00007750 , 00007800 ASSIST1-12 00007850 00007900 SECTION 10: EXTENDED FEATURES OF THE MACRO LANGUAGE 00007950 00008000 MNOTE -- REQUEST FOR ERROR MESSAGE 00008050 00008100 The MNOTE statements accepted by ASSIST follow the standard, but00008150 ASSIST effectively ignores the use of severity codes, except that00008200 MNOTE'S with numerical severity codes are printed as errors while ones00008250 with * are printed in another format. 00008300 00008350 &SYSECT -- Current Control Section 00008400 00008450 CSECT or DSECT statements processed in a macro definition do NOT00008500 affect the value for &SYSECT for any subsequent inner macros in that00008550 definition. 00008600 00008650 MACRO DEFINITION COMPATIBILITY 00008700 00008750 ASSIST does not accept AGOB or AIFB. 00008800 00008850 00008900 APPENDIX K: USE OF LIBRARY MACROS 00008950 00009000 This section describes the deck layout and use of *SYSLIB cards00009050 when the user desires to use macros from a system library. Brief notes00009100 are given regarding internal workings of macro processing, in order to00009150 help the requirements be more meaningful. 00009200 00009250 ASSIST performs all macro-processing during the first pass of its00009300 total of two passes across the source program. Macro processing itself00009350 has two stages. During the EDIT stage, macro definitions are read,00009400 scanned, and printed, while tables are built in memory describing them.00009450 The EXPANSION stage is part of the normal first pass of a two-pass00009500 assembler, so that every time a macro call is encountered, the macro00009550 processor expands the call into 0 or more statements, which then act as00009600 though they had been read in the normal way. 00009650 00009700 For best use of limited memory, ASSIST requires that ALL EDITING00009750 be done before ANY EXPANSION. During editing of programmer macros,00009800 a list is kept of opcodes not yet defined, and these are presumed to00009850 be system macros. Any system macros called by programmer macros are00009900 therefore known to ASSIST, and so it can fetch them from the library.00009950 However, if a system macro is only called at in the open code, there is00010000 no way for ASSIST to know that it will be needed later. Also, it is00010050 desirable that the user specify whether the macro library should be00010100 searched at all, in order to avoid searching the library for a mispelled00010150 opcode name automatically. Thus, a special comments card, *SYSLIB, is00010200 used to inform assist that it should actually perform library search.00010250 The format of the *SYSLIB card is either of the following: 00010350 00010400 *SYSLIB name1,name2,...... comments 00010450 *SYSLIB 00010500 00010550 The first form gives a list of 1 or more macro names, seprated by00010600 commas, free format. The second form contains no operands at all.00010650 , 00010700 ASSIST1-13 00010750 00010800 The second form may be used only when all library macros appear in the00010802 user's macro definitions. 00010804 00010806 The *SYSLIB card should follow all programmer macros (if any), and00010850 must precede any of the statements of the open code, except for comment00010900 and listing control (PRINT, TITLE, EJECT, SPACE) statements. The user00010950 may supply 1 or more *SYSLIB cards, as long as these conditions are00011000 fulfilled, thus allowing some convenience. 00011050 00011100 When finding any *SYSLIB card in a proper location, ASSIST does00011150 the following: 00011200 00011250 1. Scans the card, adding any name found there to the list of macro00011300 names. If the name is already in the list, it is totally ignored.00011350 00011400 2. Scans the list of macro names. If a macro is not defined, it00011450 searches the macro library for it. If the macro cannot be obtained,00011500 it marks the macro 'searched for', and never looks for it again.00011550 00011600 3. If the macro is found during 2, the print control is turned OFF,00011650 unless the user specified LIBMC, in which case the print control is00011700 unchanged. The macro is then read and edited, like a programmer macro.00011750 00011800 4. During step 3, the macro being read may refer to other macros not00011850 yet defined, and these are added to the macro list also. The loop of00011900 steps 2,3,4 continues until all macros in the list have either been00011950 found or searched for. Thus, it is possible for a reference to one00012000 macro to cause a number of macros to be fetched from the library. At00012050 this point, print control is restored to its original value, and a list00012100 of undefined macros is produced. 00012150 00012200 The following gives the overall layout of a program: 00012250 00012300 ..... 0 or more programmer macro definitions, with print control00012350 statements interspersed if desired. 00012400 ..... 1 or more *SYSLIB cards 00012450 ..... 0 or more GBLx declarations (if open code cond. asm allowed)00012500 ..... 0 or more LCLx declarations " 00012550 ..... ACTR " 00012600 ..... open code (main body of program) 00012650 00012700 The following shows appropriate *SYSLIB use, although the program00012750 itself should not be expected to make sense: 00012800 00012850 MACRO 00012900 PRGMAC1 &ARG 00012950 CALL X 00013000 MEND 00013050 *SYSLIB SAVE WE WILL NEED SAVE MACRO 00013100 *SYSLIB RETURN,EQUREGS OTHER MACROS NEEDED 00013150 * CALL (USED IN PRGMAC1), IS NOT NEEDED (BUT COULD BE) ABOVE.00013200 USING *,15 00013250 SAVE (14,12) 00013300 PRGMAC1 00013350 RETURN (14,12) 00013400 EQUREGS 00013450 , 00013500 ASSIST1-14 00013550 00013600 HINTS ON OPTIMAL USE OF MACRO LIBRARY 00013650 00013700 The user should be aware of the following when using the macro00013750 library facility: 00013800 00013850 1. The macro processor is mainly intended to process programmer-00013900 written macros. Among other things, all macro dictionaries and tables00013950 are kept in memory for the sake of speed. 00014000 00014050 2. Most IBM macros, and many XMACROS, call inner macros, which call00014100 other inner macros, which call others, etc, etc. Thus, calling one00014150 macro from the library may cause many others to be brought in. In00014200 particular, almost every IBM macro calls the macro IHBERMAC to issue00014250 MNOTE statements for any error messages. IHBERMAC contains over 40000014300 statements, with many memory-consuming MNOTEs included. 00014350 00014400 3. If a macro is referenced, it is fetched from the library, whether00014450 it is actually ever called or not. For example, IHBERMAC is only called00014500 when there is an error, but is always fetched. 00014550 00014600 4. Given the combination of 1,2,3 above, it is easily possible to00014650 use macros like CALL, SAVE, RETURN, XSAVE, XRETURN, which do not in00014700 themselves seem large, but exceed memory quickly. (CALL, SAVE, RETURN00014750 all use IHBERMAC; XSAVE and XRETURN contain GETMAIN and FREEMAIN to00014800 support the REEN= option, and GETMAIN/FREEMAIN both call IHBERMAC).00014850 Another example is using ASSIST to check out a QSAM program: ask for00014900 OPEN, CLOSE, GET, PUT, and DCB: ASSIST processes these correctly, but00014950 2700 statements are added to the program by the macros and all of the00015000 inner macros. A simple program can easily require 250K bytes of memory00015050 for assembly, given such macros. 00015100 00015150 Given the above circumstances, care must be taken with the library00015200 facility in order to make efficeient use of it. Given such care, ASSIST00015250 is fast and small enough to check out fairly large programs in a00015300 'reasonable' amount of memory and time. The following are useful tricks00015350 for saving time and space: 00015400 00015450 1. WRITE REDUCED VERSIONS OF COMMON MACROS, AND PLACE THEM IN A00015500 SPECIAL LIBRARY, TO BE ACCESSED FIRST BY ASSIST. For example, remove the00015550 REEN option from XSAVE/XRETURN, replace IHBERMAC calls by MNOTEs in00015600 CALL, SAVE, RETURN, etc. 00015650 00015700 2. USE LIBMC OPTION TO EXAMINE LIBRARY MACROS. WRITE DUMMY MACROS TO00015750 KEEP UNUSED ONES FROM BEING FETCHED. For example, if you know that a00015800 given macro will NOT actually be called, write a dummy, like:00015850 00015900 MACRO 00015950 IHBERMAC &A,&B,&D,&E,&F,&H 00016000 MNOTE 4,'PSEUDO IHBERMAC CALLED: &A,&B,&D,&E,&F,&H' 00016050 MEND 00016100 00016150 3. IF NECESSARY, USE THE DISKU OPTION, IF AVAILABLE. The intermediate00016200 text saved between the two passes can be spilled to disk/drum, thus00016250 allowing more space for macro dictionaries, symbol table, etc.00016300 , 00001000 ASSIST2-1 00001010 00001020 PART II. INPUT/OUTPUT AND DEBUGGING INSTRUCTIONS 00001030 ASSIST accepts as special machine instructions some commands00001040 which are handled by OS/360 as macro-instructions. They essentially00001050 permit the user to read and punch cards, print lines, and dump the00001060 contents of his registers and storage areas. They also provide00001070 easy input/output conversions for decimal numbers. 00001080 00001090 The following table gives the encodings of the special commands of00001100 ASSIST, which use currently undefined opcodes, and ARE SUBJECT TO CHANGE00001110 AT ANY TIME. In some cases, a Mask field is used to differentiate among00001120 different commands using the same opcode. The notation RX-SS under the00001130 columns for OPERAND FORMAT implies that the first four bytes of the00001140 instruction follow standard RX format, with the Mask field giving the00001150 specific type of operation. The third halfword specifies the length,00001160 which is encoded in the same way as are lengths in Shift instructions,00001170 except the length is taken from register 0 if the halfword is all zero .00001180 EXAMPLES: XREAD 0(1,2),100 ==> X'E00120000064' 00001190 XPRNT 2(3,4),(1) ==> X'E02340021000' 00001200 COMMAND OPCODE MASK LENGTH OPERAND FORMAT 00001220 XDECI X'53' - 4 bytes normal RX 00001230 XDECO X'52' - 4 bytes normal RX 00001240 XDUMP X'E1' - 6 bytes (register form - no operands) - last 00001250 five bytes totally ignored. 00001260 XDUMP X'E0' 6 6 bytes (storage form) - RX-SS 00001270 XGET X'E0' A 6 BYTES RX-SS 00001275 XHEXI X'61' - 4 bytes normal RX 00001280 XHEXO X'62' - 4 bytes normal RX 00001290 XLIMD X'E0' 8 6 bytes RX-SS 00001300 XPNCH X'E0' 4 6 bytes RX-SS 00001310 XPRNT X'E0' 2 6 bytes RX-SS 00001320 XPUT X'E0' C 6 bytes RX-SS 00001325 XREAD X'E0' 0 6 bytes RX-SS 00001330 XREPL X'A0' - 4 bytes SI - immediate field gives operation 00001340 00001350 INPUT/OUTPUT INSTRUCTIONS - XREAD, XPRNT, XPNCH 00001360 00001370 Basic input/output facilities are provided by XREAD (card READer),00001380 XPRNT (line PRiNTer), and XPNCH (card PuNCH). They are written using00001390 the following format: 00001400 00001410 label XMACRO area,length 00001420 00001430 label is an optional statement label 00001440 XMACRO is XREAD, XPRNT, XPNCH 00001460 area is the address in memory to be read or written. 00001480 This area may be specified by an RX-type address, i.e., anything00001490 legal as the second operand of a LA instruction, such as: 00001500 00001510 0(1,2), AREA2+10, CARD+1(3), or =CL30'0 MESSAGE' . 00001520 00001530 length specifies the number of bytes to be read or written.00001540 This length can range from 1 to the maximum length for the00001550 appropriate device (80 for XREAD,XPNCH, 133 for XPRNT). The length00001560 field may be omitted, in which case the maximum length is used by00001570 default. It may also be specified as a register enclosed in paren-00001580 theses, indicating that the length will be supplied at execution00001590 time from the designated register. 00001600 , 00002000 ASSIST2-2 00002010 00002020 CONDITION CODE 00002030 00002040 XPRNT and XPNCH do not change the condition code. XREAD sets the00002050 condition code to indicate normal processing or end-of-file as follows:00002060 00002070 CC = 0 - a card was read, and length characters placed in user's area00002080 00002090 CC = 1 - end-of-file encountered, no more cards can be read (/* found).00002100 00002110 00002120 CARRIAGE CONTROL 00002130 00002140 XPRNT requires that the first character of the area be a valid00002150 carriage control character, such as blank (single space), '0' (double00002160 space, and '1' (new page), or any others which are available.00002170 00002180 EXAMPLES OF XREAD, XPRNT, XPNCH USAGE 00002190 00002200 The following section of a program reads in a deck of cards00002210 until an end-of-file (/* card) is found, punches the last 7000002220 characters of each card into the first 70 columns of each card00002230 punched, and prints some number of characters from each card,00002240 where the number + 1 had been previously loaded into register00002250 5 (the + 1 is for the carriage control character). The cards00002260 are double-spaced on the printer. 00002270 00002280 READLOOP XREAD CARD read card, using omitted length 00002290 BNZ NOMORE if CC=1, branch out. BC 4,NOMORE 00002300 or BM NOMORE would also work 00002310 XPNCH CARD+10,70 punch 70 bytes, explicit length 00002320 XPRNT CARD-1,(5) print number of bytes, using 00002330 carriage control 00002340 B READLOOP go back for next card to be read 00002350 NOMORE EQU * branch here when no more cards 00002360 ..........more program statements.................. 00002370 DC C'0' carriage control for printing 00002380 card, right before CARD 00002390 CARD DS CL80 space for card to be read in 00002400 00002410 The following statements show how the programmer may easily00002420 produce messages and headings for his output, using XPRNT with00002430 literal character constants or related methods: 00002440 00002450 XPRNT =CL30'1 A HEADING FOR NEW PAGE',30 00002460 XPRNT =CL50' SECOND HEADING IMMEDIATELY UNDER FIRST',50 00002470 XPRNT MSG,L'MSG LET ASSEMBLER COMPUTE LENGTH 00002480 XPRNT MSGX,MSGXL ASSEMBLER COMPUTES LENGTH WITH EQU 00002490 MSG DC C'0 THIRD MESSAGE, SINGLE CONSTANT WITH LENGTH' 00002500 MSGX DC C' FOURTH MESSAGE, WHICH INCLUDES A SECTION FILLED IN' 00002510 DC C' DURING EXECUTION ' 00002520 MSGNMBR DS CL12 SPACE FOR DECIMAL NUMBER-XDECO 00002530 DC C' END OF IT' 00002540 MSGXL EQU *-MSGX MSGXL IS SET TO LENGTH OF MESSAGE 00002550 , 00003000 ASSIST2-3 00003010 00003020 DEBUGGING INSTRUCTION - XDUMP 00003030 00003040 One basic debugging command is provided, called XDUMP. It can00003050 be used in two different ways, to print either registers or storage00003060 areas: 00003070 00003080 GENERAL PURPOSE REGISTER DUMP 00003090 00003100 XDUMP 00003110 00003120 Coding XDUMP with no operands prints the contents of the user's00003130 general purpose registers, in hexadecimal notation. The registers00003140 are preceded by a header line like the following: 00003150 00003160 BEGIN XSNAP - CALL # AT CCAAAAAA USER REGISTERS 00003170 00003180 # is the number of calls made to XDUMP so far, for identification.00003190 00003200 CCAAAAAA shows the last 32 bits of the user's PSW, in hexadecimal.00003210 00003220 CC gives the ILC, CC, and Program Mask at the time of the XDUMP.00003230 00003240 AAAAAA gives the address of the instruction following the XDUMP, and00003250 thus can be used to distinguish between the output of different00003260 XDUMP statements. *NOTE* XDUMP , is the same as XDUMP with no operand.00003270 00003280 00003290 STORAGE DUMP 00003300 00003310 XDUMP area,length 00003320 00003330 Coding XDUMP with an address and length produces a dump of a00003340 user storage area, beginning at the address given by area, and00003350 ending at the address area+length. The operands are specified like00003360 those of XREAD, XPRNT, XPNCH, except the length may not specify00003370 a register, but must be an explicit length. 00003380 The resulting output includes a header line like the above,00003390 followed by a hexadecimal and alphanumeric dump of the selected00003400 storage area. The storage is printed in lines showing two groups00003410 of four fullwords, preceded by the memory address of the first00003420 word in each line, and followed by the alphanumeric representation00003430 of the 32 bytes on the line, with letters, numbers, and blanks00003440 printed directly, and all other characters translated to periods.00003450 The storage printed is also preceded by a line giving the address00003460 limits specified in the XDUMP. 00003470 If the length is omitted, the value 4 is used as a default.00003480 00003490 EXAMPLES OF XDUMP USAGE 00003500 00003510 XDUMP AREA+10,80 00003520 XDUMP 8(1,4),100 00003530 XDUMP FULLWORD use default value of 4 00003540 XDUMP TABL(3),12 00003550 , 00004000 ASSIST2-4 00004010 00004020 DECIMAL CONVERSION INSTRUCTIONS - XDECI, XDECO 00004030 00004040 To facilitate numeric input/output, ASSIST accepts the commands00004050 XDECI (eXtended DECimal Input), and XDECO (eXtended DECimal Output).00004060 XDECI can be used to scan input cards for signed or unsigned decimal00004070 numbers and convert them to binary form in a general purpose register,00004080 also providing a scan pointer in register 1 to the end of the decimal00004090 number. XDECO converts the contents of a given register to an edited,00004100 printable, decimal character string. 00004110 Both instructions follow the RX instruction format, as shown:00004120 00004130 XDEC# REG,ADDRESS 00004140 where REG is any general purpose register, and ADDRESS is an RX-type00004150 address, such as LABEL, 0(R4,R5), LABEL+3(2). 00004160 00004170 XDECI 00004180 00004190 XDECI is generally used to scan a data card read by XREAD. The00004200 sequence of actions performed by XDECI is as follows: 00004210 00004220 1. Beginning at the location given by ADDRESS, memory is scanned00004230 for the first character which is not a blank. 00004240 00004250 2. If the first character found is anything but a decimal00004260 digit or plus or minus sign, register 1 is set to the address00004270 of that character, and the condition code is set to 3 (overflow)00004280 to show that no decimal number could be converted. The contents00004290 of REG are not changed, and nothing more is done. 00004300 00004310 3. From one to nine decimal digits are scanned, and the number00004320 converted to binary and placed in REG, with the appropriate sign.00004330 The condition code is set to 0 (0), 1 (-), or 2 (+), depending00004340 on the value just placed in REG. 00004350 00004360 4. Register 1 is set to the address of the first non-digit after00004370 the string of decimal digits. Thus REG should not usually be 1.00004380 This permits the user to scan across a card image for any number00004390 of decimal values. The values should be separated by blanks, since00004400 otherwise the scanner could hang up on a string like -123*, unless00004410 the user checks for this himself. I.e. XDECI will skip leading blanks00004420 but will not itself skip over any other characters. 00004430 00004440 5. During step 3, if ten or more decimal digits are found,00004450 register 1 is set to the address of the first character found00004460 which is not a decimal digit, the condition code is set to 3, and00004470 REG is left unchanged. A plus or minus sign alone causes a similiar00004480 action, with R1 set to the address of the character following00004490 the sign character. 00004500 00004510 XDECO 00004520 00004530 XDECO converts the value from REG to printable decimal, with00004540 leading zeroes removed, and a minus sign prefixed if needed. The00004550 resulting character string is placed right-justified in a 12-byte00004560 field beginning at ADDRESS. It can then easily be printed using00004570 an XPRNT instruction. The XDECO instruction modifies NO registers. 00004580 , 00005000 ASSIST2-5 00005010 00005020 SAMPLE USAGE OF XDECI 00005030 00005040 The following program segment reads a card, and converts one00005050 decimal value of 1-9 digits punched anywhere on the card, placing00005060 this value in general register R0. 00005070 00005080 XREAD CARD read card into a workarea 00005090 XDECI R0,CARD scan and convert the number 00005100 00005110 XDECI can be used to convert an unknown number of decimal00005120 values from a card. This can be done by punching the values anywhere00005130 on the card, separated by one or more blanks. The last number00005140 on the card is then followed by a $, which indicates the end of00005150 the data values to the program. The following program reads a card00005160 and converts numbers, storing their values in an array for later00005170 use, and stopping when the $ is found. 00005180 00005190 SR 2,2 zero for index to first word of NUMBERS 00005200 XREAD CARD read cardimage into input area 00005210 LA 1,CARD intialize R1 as scan pointer register 00005220 LOOP XDECI 0,0(,1) scan and convert next number 00005230 BO OVER skip if bad number of $ (BC 1,OVER) 00005240 ST 0,NUMBERS(2) store legal value into array 00005250 LA 2,4(2) increment index value 1 fullword 00005260 B LOOP go back for next number 00005270 OVER CLI 0(1),C'$' was this delimiter $ 00005280 BE DONE yes, so branch out 00005290 XPRNT =CL30'0*** BAD INPUT ***STOP',30 00005300 DONE ...... more instructions ........ 00005310 NUMBERS DS 20F space for 20 values to be stored 00005320 CARD DS CL80 input workarea 00005330 00005340 00005350 SAMPLE USAGE OF XDECO 00005360 00005370 The following converts register 4 to decimal and prints it.00005380 It assumes a reasonable value in R4, so that the first character00005390 of OUT is a blank for carriage control. 00005400 00005410 XDECO 4,OUT convert the number 00005420 XPRNT OUT,12 print value 00005430 ..... other assembler statments ..... 00005440 OUT DS CL12 typical output area 00005450 00005460 , 00006000 ASSIST2-6 00006010 00006020 HEXADECIMAL CONVERSION INSTRUCTIONS-XHEXI, XHEXO 00006030 (NOTE: Some versions of ASSIST may not provide these instructions) 00006035 00006040 XHEXI and XHEXO provide easy conversion of hexadecimal numbers00006050 for input and output. The value of a hexadecimal number can be00006060 read from a card using XREAD, converted from character mode to a00006070 hexadecimal number, and the converted number is placed in the specified00006080 general purpose register with XHEXI. XHEXO provides an easy way00006090 to convert internal hexadecimal to an output form that can be00006100 printed using XPRNT. 00006110 XHEXI also places the address of the first non-hexadecimal00006120 number in register one, but if more than eight digits are scanned,00006130 the address of the ninth is placed in register 1. 00006140 00006150 XHEXI 00006160 00006170 XHEXI REGISTER,ADDRESS 00006180 00006190 XHEXI, in the general form shown above where REGISTER is any general00006200 purpose register and ADDRESS is anything legal in an RX instruction, is00006210 used to do the following: 00006220 00006230 1. Beginning at the location ADDRESS, memory is scanned until the00006240 first non-blank character is found. 00006250 00006260 2. If the first character found is anything but a legal hexa-00006270 decimal character(0-9,A-F), the condition code is set to overflow00006280 and this address is placed in register 1. If the REGISTER is00006290 anything but register 1, its contents remain unchanged. 00006300 00006310 3. One to eight hexadecimal characters are scanned, the number00006320 converted to hexadecimal, and the result is placed in REGISTER.00006330 The value placed in the register is internal hexadecimal with00006340 leading zeros included and the number is right justified. 00006350 00006360 4. Register one is set to the address of the first non-hexadecimal00006370 character. With this in mind, the user should not code register one as00006380 REGISTER. This allows you to scan across the card for any number of00006390 character strings. The strings should be separated by blanks. The end00006400 of the string could be flagged with any non-hexadecimal character and a00006410 test could be made after a Branch Overflow (see sample program). 00006420 00006430 00006440 5. If more than eight hex digits are found, register one is set to00006450 the address of the ninth. This allows the user to scan across long00006460 strings of numbers. 00006470 00006480 XHEXO 00006490 00006500 XHEXO REGISTER,ADDRESS 00006510 00006520 00006530 XHEXO in the general form shown above converts the value00006540 in REGISTER and places it in a right-justified 8-byte field beginning at00006550 ADDRESS. It can be easily printed using an XPRNT instruction. The XHEXO00006560 instruction modifies NO registers. 00006570 , 00007000 ASSIST2-7 00007010 00007020 00007030 SAMPLE PROGRAM USING XHEXI AND XHEXO 00007040 00007050 This program reads a data card with an unknown number of hexa-00007070 decimal numbers on it. The end of the data is denoted by a '%' punched00007080 after the last number. The numbers are stored after being converted00007090 using XHEXI, and then converted for output using XHEXO. 00007100 00007110 LA 3,STORAGE WHERE NUMBERS STORED 00007120 XREAD CARD,80 READ IN CARD 00007130 XPRNT CARD,80 ECHO PRINT 00007140 LA 1,CARD ADDRESS OF CARD FOR SCANNING 00007150 LOOP XHEXI 2,0(1) CONVERT NUMBER PUT IN 2 00007160 BO ILLEGAL CHECK FOR END 00007170 XHEXO 2,AREA PUT NUMBER IN OUTPUT AREA 00007180 XPRNT REP,28 PRINT CARD AND MESSAGE 00007190 ST 2,0(3) STORE NUMBER 00007200 LA 3,4(3) INCREASE INDEX 00007210 B LOOP GET NEXT NUMBER 00007220 ILLEGAL CLI 0(1),C'%' SEE IF END OF STRING 00007230 BE DONE YES DONE 00007240 XPRNT =CL50' ILLEGAL CHARACTER STOP',50 00007250 DONE ....MORE INSTRUCTIONS..... 00007260 CARD DC 81C' ' STORAGE FOR CARD 00007270 STORAGE DS 20F STORAGE FOR NUMBERS 00007280 REP DC C' THE NUMBER IN R2 IS' 00007290 AREA DC CL8' ' STORAGE FOR OUTPUT NUMBER 00007300 , 00008000 ASSIST2-8 00008010 00008020 LIMIT DUMP INSTRUCTION - XLIMD 00008030 00008040 In order to conserve output records when necessary (for instance,00008050 when ASSIST is being used from a remote terminal of any sort), the00008060 XLIMD instruction is provided to enable the user to limit the size of00008070 his completion dump and choose the area to be printed. In general,00008080 it is used to eliminate the user's program code, leaving only his00008090 data areas in the completion dump. 00008100 00008110 The instruction is coded as follows: 00008120 00008130 XLIMD area,length 00008140 00008150 area is the beginning address where the completion dump should start.00008160 The area address is specified by an RX-type address, and must00008170 be within the user program area. 00008180 00008190 length is the length in bytes of the area the user wishes to be00008200 printed if a completion dump occurs. 00008210 00008220 Note that the XLIMD instruction format is exactly the same as that00008230 for the instructions XREAD, XPRNT, XPNCH. Thus the length may be00008240 given as a register number, enclosed in parentheses, or may be omitted,00008250 in which case a length of 1 is assumed. If the combined area address00008260 plus the length yields an address greater than the highest user00008270 address, or if the length is 1, the highest user address is used00008280 as an upper limit instead. Thus, storage will be printed to the end00008290 of the user program. 00008300 00008310 The suggested method of using XLIMD is to place all variables at00008320 the end of the program, then execute an XLIMD with an area address00008330 specifying the first variable desired, and omitting the length. This00008340 will cause the storage to be printed starting at the specfied address00008350 and going to the end of the program. 00008360 00008370 SAMPLE USAGE OF XLIMD 00008380 The following program gives a typical way of using XLIMD.00008390 00008400 DUMPTEST CSECT 00008410 USING *,15 00008420 XLIMD VARIABL1 set dump limit right away 00008430 .......... 00008440 large number of machine instructions 00008450 .......... 00008460 VARIABL1 DS D first variable area 00008470 .......... 00008480 variable areas likely to be required for debugging 00008490 .......... 00008500 END 00008510 XLIMD may be executed any number of times during a program, but00008520 it is suggested that it be called early in any large program, if there00008530 is any possiblity that record limits could be exceeded. 00008540 , 00010000 ASSIST2-9 00010050 00010100 00010125 OPTIONAL INPUT/OUTPUT INSTRUCTIONS - XGET AND XPUT 00012950 00013000 These instructions are similar to XREAD/XPRNT/XPNCH, 00013050 but are more general, allowing the user to specify any 00013100 filename to be read or written. WARNING: not all versions 00013150 of ASSIST support these instructions. Also, a particular 00013200 version may only support a specific set of file names, 00013250 which can differ from installation to installation. It is 00013300 advisable to check on local procedures. The instructions 00013350 are coded as follows: 00013400 00013450 label xmacro area,length 00013500 00013525 label is an optional statement label 00013550 00013600 xmacro is either XGET or XPUT 00013650 00013700 area is the address in memory to be read or written. 00013750 This area may be specified by an RX-type address, i.e., anything 00013800 legal as the second operand of a LA instruction, such as: 00013850 0(1,2),AREA2+10,card+1(3), or =CL30'0 MESSAGE' . 00013900 00013950 length specifies the number of bytes to be read or written. 00014000 This length can range from 1 to the maximum length for the 00014050 appropriate device (80 for cards, 133 for printer, etc.). The length 00014100 field must not be omitted. it may also be specified as a register 00014150 enclosed in parentheses, indicating that the length will be supplied 00014200 at execution time from the designated register. 00014250 00014275 If during execution, the length has a value of zero, the 00014300 file will be closed. 00014350 00014400 NOTE: During execution, register 1 must point to an eight byte 00014450 character string which is the name of the file to be manipulated. 00014500 00014550 CONDITION CODE 00014600 00014650 XGET and XPUT both change the condition code as follows: 00014700 CC=0 - normal input/output occurred 00014750 CC=1 - XGET ONLY - end of file occurred 00014800 CC=2 shows an error (like invalid data address) which causes 00014850 individual operation to be ignored. 00014855 CC=3 shows that the file could not be opened (because it is 00014900 wrong direction,or DD card missing, or not enough room in 00014925 tables, etc.). 00014930 CARRIAGE CONTROL 00014950 00015000 XPUT only requires the first character of the area to be a 00015010 valid carriage control character, if the output device is the printer. 00015020 00015030 CLOSING OF FILE 00015040 Performing an XGET or XPUT with a length of zero supplied in any GP00015050 register causes the designated file to be closed, so that it may then00015060 be reread; I.e. LA 1,=CL8'ddname' SR 0,0 XGET area,(0) does close. 00015070 , 00015102 ASSIST2-10 00015104 EXAMPLE OF XGET AND XPUT USAGE 00016550 00016600 The following program will read and write a few files 00016650 in parallel. 00016700 00016750 00016800 00016850 TEST1 CSECT 00016950 BALR 12,0 00017000 USING *,12 00017050 SR 0,0 00017100 * 00017150 * THIS PROGRAM WILL PROCESS A FEW FILES IN PARALLEL: 00017200 * 00017250 LOOP LA 1,=CL8'CARD' point to an input file 00017300 XGET AREA,80 do the input 00017350 BNE DONE branch on endfile, 00017400 * file automatically closed 00017425 XREAD AREA2,80 do normal input 00017450 LA 1,=CL8'PAPER' point to a printer file 00017500 XPUT AREA-1,81 do output, note carriage control 00017550 LA 1,=CL8'PAPER2' point to other printer file 00017600 XPUT AREA2-1,81 do output on other file 00017650 B LOOP try again 00017700 DONE BR 14 RETURN, IMPLICITLY CLOSE OTHER FILES 00017750 DC CL1' ' 00017800 AREA DS CL80 00017850 DC CL1' ' 00017900 AREA2 DS CL80 00017950 END 00018100 00018250 00018300 The extra JCL for the above is as follows: 00018350 00018400 //DATA.PAPER DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133) 00018450 //DATA.PAPER2 DD SYSOUT=A,DCB=(RECFM=FA,LRECL=133,BLKSIZE=133) 00018500 //DATA.CARD DD * 00018550 THIS STUFF IS READ 00018600 AT THE SAME TIME AS ANOTHER 00018650 FILE IS READ 00018700 ****** THE LAST CARD ******* 00018750 //DATA.INPUT DD * 00018800 THIS IS THE NORMAL INPUT FILE 00018850 AND IS READ AT THE SAME TIME AS ANOTHER FILE 00018900 IS READ 00018950 ********* THE LAST CARD ********* 00019000 00019100 NOTE: a common usage for XGET might be to access files of test 00019150 data. 00019200 00019250 , 00001000 ASSIST3-1 00001010 00001020 PART III. ASSIST CONTROL CARDS AND DECK SETUP 00001030 00001040 A. JOB CONTROL LANGUAGE 00001050 00001060 Depending on the type of ASSIST desired at a given installation,00001070 one or two different types of deck setup can be used. 00001080 00001090 SINGLE RUN DECK SETUP - NOBATCH 00001100 This setup is suitable for individually-submitted jobs, and allows00001110 the most flexibility in job handling. It is as follows: 00001120 00001130 1) // a JOB card - installation dependent 00001140 2) // EXEC ASACG 00001150 3) //SYSIN DD * 00001160 4) ..... 360 assembler source deck, or ASSIST object deck00001170 5) /* 00001180 6) //DATA.INPUT DD * 00001190 7) ..... data cards to be read by user program 00001200 8) /* 00001210 00001220 If the programmer has no data to be read, items 6), 7), and 8)00001230 should be omitted. The programmer specifies optional parameters by00001240 adding ,PARM='option,option....' after ASACG on the EXEC card.00001250 00001260 BATCH RUN DECK SETUP 00001270 This type of run is recommended if a number of jobs is to be given00001280 as a batch to ASSIST, and is best for low overhead. Each separate00001290 program in the batch must be set up as follows: 00001300 00001310 Col 1 Col 8 Columns 16-80 of card 00001320 ' ' ' 00001330 1) $JOB ASSIST list of options, separated by commas. The first00001340 of these may be an account number, which is 00001350 ignored by ASSIST. All others are optional. 00001360 2) ..... 360 assembler source deck, or ASSIST object deck00001370 3) $ENTRY (this card must be present if user execution is00001380 to occur, regardless of existence of data.) 00001390 4) ..... data cards to be read by user program (optional)00001400 00001410 If the user desires only an assembly of his program, the $ENTRY00001420 card should be omitted. As many of the above can be included in one00001430 batch submitted to ASSIST, with BATCH and other appropriate parameters00001440 supplied to ASSIST in the invoking PARM field. The batch can be ended00001450 in one of two ways: either an end-of-file indicator, or a card with00001460 the following in columns 1-5: $STOP . 00001470 00001480 The entire batch of runs is run with whatever enclosing Job00001490 Control Language is required for a given installation by specifying00001500 BATCH in the invoking PARM field. All versions of ASSIST can run BATCH00001510 programs, but not all can run them with the SINGLE RUN DECK SETUP.00001520 A sample BATCH run is given below: 00001530 00001540 // a JOB card 00001550 // EXEC ASACG,PARM='BATCH,other options, if any' 00001560 //SYSIN DD * 00001570 $JOB ASSIST ACCT1,options 00001580 ....... more jobs, each beginning with $JOB cards 00001590 /* (or a $STOP card) 00001600 , 00002000 ASSIST3-2 00002010 00002020 B. OPTIONAL PARAMETERS FOR ASSIST 00002030 00002040 ASSIST provides a large number of options to control the actions00002050 it performs. These options are of two types: the first kind show yes/no00002060 values and are coded as a specific name, with or without a preceding NO.00002070 Every option has a default value, and some of the numerical ones have00002080 upper limits which can never be exceeded. 00002090 00002100 Each parameter can possibly be given values from at most four00002110 different sources, which are as follows: 00002120 00002130 1. LIMIT/DEFAULT - absolute upper limits on some numerical options,00002140 and default values for some others. (defined inside ASSIST)00002150 2. INVOKING PARM - values for any of the options. (EXEC CARD PARM00002160 field, or PARM supplied by another program calling ASSIST)00002170 **NOTE** this is not available under DOS/360. 00002180 3. $JOB CARD PARM - values for some of the options, if desired,00002190 only possible if LIMIT/DEFAULT or INVOKING PARM specified BATCH.00002200 4. DEFAULT - default values for the numerical parameters having upper00002210 limits, only used if values not specified in 2. or 3. (defined00002220 inside ASSIST) 00002230 00002240 For any assembly-execution-dump cycle of ASSIST (i.e., one program)00002250 the above sources of information are processed in the order given above,00002260 subject to the following rules: 00002270 00002280 1. Some options can be supplied values only from certain sources.00002290 2. Certain numerical parameters can never be increased beyond any00002300 previous setting from any source. This particularly applies to00002310 time, records, and pages limits. 00002320 3. In most cases, if the same option is coded several times in the00002330 same information source, the last value is used, subject to rule 2.00002340 It is possible that some values cannot be reset once set anywhere.00002350 4. DEFAULT values are used only if they are not coded in either the00002360 INVOKING PARM or $JOB cards, i.e., they override only LIMIT/DEFAULT00002370 values. This construct allows for both limit and default values00002380 for the numerical options. 00002390 00002400 SAMPLE USAGE OF OPTIONAL PARAMETERS 00002410 00002420 1) // EXEC ASACG,PARM='T=3.5,R=200,NERR=10,RELOC,CMPRS' 00002430 00002440 2) // EXEC ASACG,PARM='BATCH,CPAGE,T=5,TX=2,P=20,PX=5,RX=315,SSD'00002450 //SYSIN DD * 00002460 $JOB ASSIST ACCT#,PD=1,TD=0.05,CMPRS,SS,SSX 00002470 (this job crams output onto fewest possible pages) 00002480 ............. 00002490 $JOB ASSIST ACCT#,PD=0,TD=0,RD=0 00002500 (this is a debugged program-saves no pages,time, 00002510 or records for the dump-gets maximum output). 00002520 ............. 00002530 $JOB ASSIST ACCT#,OBJIN 00002540 ............. (object deck) 00002550 00002560 The above examples show a typical single job run and a typical00002570 batch of jobs. 00002580 , 00003000 ASSIST3-3 00003010 00003020 CHARACTERISTICS OF PARAMETERS 00003030 00003040 The following lists the available options, including the default00003050 values, sources from which each can be specified, and brief notes on00003060 the purpose of each. Each option is described in detail in the next00003070 section. ASSIST can be generated not to allow certain options, and00003080 these are flagged to show whether they can be omitted or not.00003090 00003100 KEY 00003110 # under FROM column notes that the option CAN be set from the source,00003120 i.e., 1=LIMIT/DEFAULT, 2=INVOKING PARM, 3=$JOB PARM, 4=DEFAULT.00003130 N under N column indicates a numerical parameter which cannot ever00003140 be increased from any previously set value. 00003150 O under O column indicates an option which can be omitted from a00003160 particular generation of ASSIST (to save space, for instance).00003170 PARM FROM N O DEFAULT PURPOSE 00003190 NAME 1234 VALUE AND USAGE 00003200 ------------------------------------------------------------------------00003210 ALGN 1234 O ALGN suppress alignment specification errs00003215 BATCH 12 NOBATCH indicate a batched-type run 00003220 CMPRS 1234 O NOCMPRS compressed source list,2 cols/page00003230 COMNT 12 O NOCOMNT require percentage of commented cards00003240 CPAGE 12 O NOCPAGE control paging and page counting00003250 DECK 1234 O NODECK punch object deck 00003260 DISKU 123 O NODISKU intermediate disk storage used 00003270 DUMP= 1234 0 controls type and size of dump 00003290 FREE= 12 4096 bytes returned to system for buffers00003300 I= 1234 150000 maximum # instructions for user prog00003310 KP= 1234 O 029 type of keypunch used (026 or 029) 00003320 L= 1234 N O 63 maximum lines/page if CPAGE on 00003330 LIBMC 1234 O NOLIBMC allow library macros to be printed 00003350 LIST 1234 LIST produce source listing of assembly00003360 LOAD 1234 LOAD produce object program and run it00003370 MACRO= 1234 O N allows use and types of macros 00003372 MACTR= 1234 N O 200 default value of MACRO ACTR 00003374 MNEST= 1234 N O 15 maximum nest level for macro calls 00003376 MSTMG= 1234 N O 4000 maximum total macro stmts processed 00003378 NERR= 1234 0 maximum # errors permitting execute 00003380 OBJIN 1234 O NOOBJIN object deck input rather than source00003390 P= 1234 N O 10 total run page limit if CPAGE on 00003410 PD= 1234 N O 1 page limit for dump if CPAGE on 00003420 PUNCH 12 O PUNCH select real punch, or print simulated00003430 PX= 1234 N O 5 execution+dump page limit, if CPAGE 00003450 R= 1234 N 10000 output record limit (lines+cards)00003460 RD= 1234 N 25 records saved for dump 00003470 RELOC 1234 O NORELOC relocate to real address,store-protec00003480 REPL 1234 O NOREPL assembler replacement run 00003490 RFLAG= 1234 O 0 replace option flag (only if REPL on)00003500 RX= 1234 N 10000 execution+dump record limit 00003520 SS 1234 O NOSS single space assembly (only if CPAGE)00003530 SSD 1234 O NOSSD single space dump (only if CPAGE)00003540 SSX 1234 O NOSSX single space execution(only if CPAGE)00003550 T= 1234 N O 100 total run time, seconds 00003560 TD= 1234 N O .1 time in seconds saved for dump 00003570 TX= 1234 N O 100 time in seconds for execution+dump 00003580 XREF= 1234 O (0,3,3) requests cross-reference 00003590 , 00004000 ASSIST3-4 00004010 C. DESCRIPTION OF INDIVIDUAL OPTIONS 00004020 00004030 This section describes each of the options which may be available00004040 under ASSIST. Refer to the previous section for default values and00004050 other information regarding the usage of these options. 00004060 00004070 ALGN/NOALGN 00004071 Use of the NOALGN option allows the user to suppress specification00004072 interrupts caused by improper alignment of operands. This is useful00004073 when using a S/360 computer to simulate a S/370, which may of course use00004074 data on any boundaries for many opcodes. Not every ASSIST allows this.00004075 00004076 BATCH/NOBATCH 00004080 The BATCH option allows multiple jobs to be run in one invocation00004090 of ASSIST. It is described in Part III.A. of this manual. 00004100 00004110 CMPRS/NOCMPRS 00004120 The CMPRS option (CoMPReSsed output) produces an assembly listing00004130 which is approximately half as long as a standard listing. This is00004140 done by removing the ADDR1 - ADDR2 fields and printing only columns00004150 1-40 of each statement. While the listing produced is not as readable00004160 as the standard one, this option is particularly recommended for remote00004170 terminal usage, since programs are printed nearly twice as fast. It00004180 does, however, increase the amount of dynamic storage required to run.00004190 00004200 COMNT/NOCOMNT 00004210 The COMNT option causes the machine instructions of the program to00004220 be checked for the presence of comments (4 or more nonblank characters00004230 in the comment field). If less than 80 percent of those statements have00004240 comments, a message is printed and the program is not executed. Some00004250 instructors may require this option on programs to be handed in, and it00004260 is possible that some account numbers may imply this option whether the00004270 programmer codes it or not. 00004280 00004290 CPAGE/NOCPAGE 00004300 If NOCPAGE is used, no limits exist on the number of pages printed,00004310 and lines are printed with whatever carriage controls are specified.00004320 Coding CPAGE enables the usa of the following options: L=, P=, PD=, PX=,00004330 SS, SSD, and SSX, all of which are totally ignored otherwise. Briefly,00004340 a page may be declared to have a maximum number of lines (L=), and00004350 limits given for the pages printed during various stages of a run. The00004360 SS options then allow the maximum number of lines to be printed in a00004370 given number of pages by removing some carriage control characters from00004380 the printed output (such as page and multiple line skips). 00004390 00004400 00004410 DECK/NODECK 00004420 Coding DECK causes ASSIST to punch an object deck of the user00004430 program, assuming that the number of errors did not exceed the NERR=00004440 option, that the version of ASSIST in use has a card punch, and that00004450 none of the following options were specified also: NOLOAD,NOPUNCH,OBJIN,00004460 or REPL. The deck punched is described in PART IV.E.1 of this manual.00004470 Note that this option should not be used for large programs, since00004480 every byte of storage of the user program is punched, 56 bytes per card,00004490 even if the storage was reserved by DS or ORG commands. Note that the00004500 deck, while resembling standard S/360 object decks, cannot really be00004510 used for any purpose but to read back into ASSIST later. The user is00004520 also cautioned to be careful about using DECK with the RELOC option.00004530 , 00005000 ASSIST3-5 00005010 00005020 DISKU/NODISKU 00005030 Coding DISKU causes the ASSIST assembler to place the pass1 output00005040 on intermediate disk storage. Pass2 then recovers the pass1 information00005050 from disk to use in the production of object code into ASSIST's dynamic00005060 work area. Assuming ASSIST is generated with the user controlled DISKU00005070 /NODISKU option, it is possible to assemble much larger programs with00005080 ASSIST using the DISKU option. DISKU has no effect when coded with OBJIN00005090 and is compatible with any other combination of parameters. 00005100 00005110 DUMP= 00005120 This option controls the size of the dump printed on any error00005130 termination during program execution. If DUMP=0, a full dump is given.00005140 This includes a PSW, completion code, instruction trace, general-purpose00005150 and floating-point registers, and all contents of the user program's00005160 storage area. If DUMP=1, ASSIST omits the contents of user storage.00005170 00005180 FREE= 00005190 ASSIST normally acquires the largest single block of space00005200 in its region for a dynamic workarea, then releases part of that00005210 area back to the operating system for buffers and other uses.00005220 The default is 4096 bytes returned, but the value of FREE= is00005230 used if supplied, in case tape input or output is required, or00005240 if extra space is required for the user program. If the value00005250 of FREE= is greater than the total obtained, it is ignored, and00005260 no space is returned. ****NOTE*** THIS OPTION WILL PROBABLY BE NEEDED00005270 BY ANYONE USING BLOCKED INPUT FROM TAPE OR DISK. 00005280 00005290 I= 00005310 This parameter provides a limit on the number of instructions which00005320 which can be executed by the user program during its execution. If this00005330 limit is exceeded during execution, a message and a completion00005340 dump are printed. This is the recommended and most economical00005350 way to prevent infinite loops during user program execution. A limit00005360 for execution time may also be used to terminate loops (TX=).00005370 00005380 KP= 00005390 KP=26 specifies that an 026 keypunch was used to prepare the job,00005400 while 29 specifies an 029 keypunch. Leading zeroes are permitted, and00005410 any value except 26 implies an 029 keypunch. 00005420 00005430 L= 00005450 This is used to specify the maximum lines per page, and is only00005460 enabled if the CPAGE option is turned on. 00005470 00005472 LIBMC/NOLIBMC 00005474 Coding LIBMC permits macros fetched from libraries to be printed00005476 if desired. Only effecitve when MACRO= is supplied to an ASSIST which00005478 supports macro libraries. See also MACRO=, and APPENDIX K of PART I.00005480 00005482 LIST/NOLIST 00005490 Coding NOLIST suppresses the printing of the assembly listing, and00005500 can be used for relatively bug-free programs. However, regardless of the00005510 current print status, any statement flagged with an error or warning00005520 message is always printed. 00005530 , 00000050 ASSIST3-6 00000100 LOAD/NOLOAD 00000450 Under most circumstances, a programmer usually wants to execute his00000500 assembler program. If he just wants to check it for errors, but00000550 not execute it, the NOLOAD option can be coded. This will result00000600 in slightly faster assembly times. In addition, it will require00000650 less space in memory, and it may be possible to assemble a program00000700 under NOLOAD that cannot be assembled with the LOAD option. 00000750 00000752 MACRO= 00000754 This option notes whether macro processing is to be done, and if00000756 so, what language facilities are to be allowed. The values allowed are:00000758 MACRO=N NO macro processing: used if error in option 00000760 MACRO=F F-level Assembler compatibility (basic facility) 00000762 MACRO=G G-level Assembler features added, if available 00000764 MACRO=H H-level Assembler features added, if available 00000766 If macros or conditional assembly are to be used, the user MUST specify00000768 something other than MACRO=N. See also APPENDIX K of PART I. 00000770 00000772 MACTR= 00000774 This provides a default value for the starting ACTR counters in all00000776 macros used. It can be overridden by explicit ACTR statements. 00000778 00000780 MNEST= 00000782 This gives a limit on the maximum level of nested macro calls, thus00000784 allowing prevention of unwanted recursion in macros. 00000786 00000788 MSTMG= 00000790 This provides a global limit on the total statements processed in00000792 all macro expansions. It is like ACTR, but counts all statements in all00000794 macros, rather than being local to a macro. It can be used to prevent00000796 macro looping which causes storage to be exceeded. 00000798 00000800 NERR= 00000850 This option is used to allow a program to execute even though00000900 there are errors in it. If omitted, the value is assumed to be zero,00000950 i.e., the program is not executed if there are any errors at all in it.00001000 If NERR=10 is used, the program runs if it has 10 errors, but does not00001050 run if there are 11. Note that warning messages are not included in00001100 this count, only actual error messages. 00001150 00001200 OBJIN/NOOBJIN 00001250 Coding OBJIN informs ASSIST that an object deck is being supplied00001300 to it in place of the usual assembler source deck. This is allowed in00001350 every case, unless REPL is coded, in which case OBJIN is ignored. The00001400 format required of the object deck is given in PART IV.E.1. 00001450 The ASSIST loader reads the object deck until an end-of-file or00001500 ASSIST control card is found, producing an object program in memory00001550 which is then treated exactly as though the source program had been00001600 just assembled there. The loader also issues various messages of the00001650 form AL###, which are explained in PART IV.E.2. The user should read00001700 all of PART IV.E. before using the OBJIN option, since there are a00001750 number of restrictions which must be noted before using object decks00001800 as input to ASSIST. In general, a single ASSIST-produced deck should00001850 almost always be workable, a single deck produced by the standard00001900 system assembler, or multiple decks of any sort may be usable if they00001950 were created following certain conventions. Decks requiring symbolic00002000 linkage among control sections will definitely NOT run correctly.00002050 , 00002150 ASSIST3-7 00002200 00002250 P= 00002300 This gives the maximum number of pages (with L= lines per page)00002350 which are permitted for a complete job (or from one $JOB card to the00002400 next, if BATCH is used). It is only meaningful if CPAGE is on. The00002450 entire process of page counting (which also involves values of PD= and00002500 PX= ) is summarized as follows: 00002550 1. As described in PART III.B, the value of P= is calculated before00002600 ASSIST prints anything for the job. ASSIST prints the beginning of the00002650 header line, followed by the PARM field, or the $JOB card, and then00002700 assembly begins. If the p= value is exceeded during assembly, the job00002750 is halted at that point. 00002800 2. If the user program assembles successfully and is to be executed,00002850 a page limit is calculated for execution plus dump. The total for these00002900 two phases is set to the minimum of the PX= option and the number of00002950 pages remaining from before. 00003000 3. A temporary limit for user program execution alone is calculated00003050 by subtracting the value of the PD= option, thus reserving that number00003100 of pages for a dump. User program execution occurs, and may be00003150 terminated if the temporary page limit is exceeded. 00003200 4. After execution, the PD= value is added to the current pages00003250 remaining counter, and the dump begun. The dump continues until it is00003300 completed or it runs out of pages. 00003350 Note A. At steps 3 and 4 the lines remaining count is just carried00003400 forward, so that the user gets the benefit of any partial pages.00003450 Note B. For REPL runs (assembler replacement), step three is performed00003500 twice, once for the replacement program, and once for the program it00003550 assembles (if execution is desired for it). Since a dump of the00003600 replacement program does not occur during the user dump phase, it is00003650 recommended that no pages be saved for it (i.e., PD=0). 00003700 Note C. Any process which can be halted by exceeding page count can00003750 also be halted by exceeding record limits (see R=), or time limits (see00003800 T=), and for user program execution, exceeding instruction count limit00003850 (see I=). 00003900 00003950 00004000 PD= 00004050 This option specifies the number of pages which should be reserved00004100 for the user completion dump phase. It is effective only if CPAGE is00004150 on, and is used in conjunction with P= and PX= ( see explanation under00004200 P=). Typical values are as follows: 00004250 PD=0 saves no pages for dump. Good for debugged programs.00004300 PD=1 even if the program loops printing, this allows enough00004350 information to determine what the program was doing. If SSD 00004400 is coded, about 1K of storage can also be seen. 00004450 Note that the PD= value does not restrict a dump to that size,00004500 so that the user also gets up to the PX= value for execution plus dump00004550 together, even if the entire amount is used to provide the dump.00004600 00004650 PUNCH/NOPUNCH 00004700 Use of the NOPUNCH parameter causes the system to print any output00004750 from XPNCH instructions, rather than punching them. Each cardimage is00004800 preceded with the characters ' CARD-->' to distinguish it from other00004850 printed output. This option is useful for testing punching programs.00004900 Versions of ASSIST with no punch treat all attempted punching this way.00004950 , 00005150 ASSIST3-8 00005200 PX= 00005250 This gives the maximum number of pages for both user program00005300 execution and completion dump phases together. It is effective only if00005350 CPAGE is on. See description under P=. 00005400 00005450 R= 00005500 This value specifies the maximum number of output records (lines00005550 printed + cards punched) allowed for the entire run. Record counting00005600 is always performed, and the entire process resembles that of page00005650 counting (see P=), and occurs in parallel with any page counting. The00005700 parameters R=, and RX= are used just as are P=, PX=, and PD=, with00005750 records substituted for pages. One possible difference is in ASSIST00005800 systems with special record control type 2 (see header description -00005850 PART IV.B.1.a.). In this case, the initial record remaining count is00005900 also determined by the number of records actually left (if this value00005950 can be obtained from the operating system). This value is used rather00006000 than the default value if the user did not specify R= on the EXEC card00006050 or $JOB card. As in Note B. under P=, use RD=0 for replacement runs.00006100 00006150 00006200 RD= 00006250 RD= the number of output records reserved for a user completion dump00006300 It is used in conjunction with R= and RX= in the same way that PD= is00006350 used with P= and PX=. RD=0 is appropriate for well-debugged programs,00006400 and RD=25 is probably the most reasonable value for most runs, as it00006450 saves enough for a partial dump under all conditions. 00006500 00006550 00006600 RELOC/NORELOC 00006650 Under NORELOC a user program is assembled with a location counter00006700 beginning either at 0 or the value on a start card, and the program is00006750 executed as though it were actually loaded at whatever addresses are00006800 given on the assembly listing. Maximum debugging checking is provided00006850 by this mode, as the user may not branch, store, or fetch outside the00006900 area of his program. 00006950 RELOC in effect inserts a start card at the beginning of the source00007000 program which specifies the actual location in memory at which the user00007050 program will be assembled. When the program is executed, fetch00007100 protection is eliminated, which the execution-time relocation value00007150 of zero, allows the user program to examine any areas of storage in the00007200 computer (for example, to trace system control blocks). RELOC mode is00007250 implied if REPL is coded. 00007300 00007350 REPL/NOREPL 00007400 REPL notes that the user supplies two source programs, of which the00007450 first is a replacement for one of the modules of the ASSIST assembler,00007500 and the second is a test program, to be assembled using the replacement00007550 program. This optional feature is described in detail in the ASSIST00007600 ASSEMBLER REPLACEMENT USER'S GUIDE. 00007650 00007700 RFLAG 00007750 This option specifies an initial value for the replace control00007800 flag, it is meaningful only if REPL is coded, and is described in the00007850 ASSIST ASSEMBLER REPLACEMENT USER'S GUIDE. 00007900 , 00007950 ASSIST3-9 00008000 00008050 RX= 00008100 This gives the total number of output records for user program00008150 execution and dump together (see R=). It corresponds to PX= for page00008200 control, and is used in the same way. 00008250 00008300 SS/NOSS 00008350 This option is effective only if CPAGE is on, and is useful for00008400 reducing the number of pages printed for a given number of lines output.00008450 Using SS essentially converts all carriage controls to single space00008500 commands, except for page skips, which become double spaces, and no00008550 spaces, which are unchanged. SS is effective during the assembly phase,00008600 SSX during user program execution, and SSD during a completion dump. The00008650 carriage control conversions are as follows: 00008700 '1' (page skip) becomes '0' '+' (overprinting) remains '+'00008750 '-' (triple space) becomes ' ' ' ' (single space) remains ' '00008800 '0' (double space) becomes ' ' any other character becomes ' '00008850 00008900 SSD/NOSSD 00008950 SSD is the SS option during completion dump (see SS above). Using00009000 SSD allows a partial dump plus 1K of storage to be printed on 1 page.00009050 00009100 SSX/NOSSX 00009150 SSX is the SS option during user execution (see SS above).00009200 00009250 00009300 T= 00009350 This gives a limit in seconds on the total time allowed for a run.00009400 The handling of the three time limits (T=, TX=, and TD=) is exactly00009450 analogous to that for pages (see P=) and records limits. The values00009500 are coded as integer values of seconds, or with fractional values up to00009550 three digits, thus allowing for millisecond specifications. As shown00009600 in Note B. under P=, TD=0 should be used for replacement runs. The00009650 appropriate times used depend on the model of machine being used, with00009700 the following times being appropriate for student runs on a 360/65:00009750 T=5,TX=5,TD=1. 00009800 Some versions of ASSIST may contain NO timing code at all (option00009850 0), and some may contain special option 2. In the latter case, ASSIST00009900 obtains a time remaining estimate from the operating system and uses it00009950 rather than the default if the user specifies no time limit himself.00010000 The user may examine the ASSIST header to determine which type of ASSIST00010050 is being used (see PART IV.B.1.a). 00010100 00010150 00010200 TD= 00010250 This supplies the time remaining for a user completion dump, and00010300 should generally be set to a large enough value to permit at least a00010350 partial dump to be given, thus showing the user the instructions being00010400 executed, especially if a loop is occurring. TD=0 is appropriate for00010450 debugged programs, which can then use all possible time for execution.00010500 00010550 00010600 TX= 00010650 This value is the total time in seconds for user program execution00010700 and dump together. It controls time in the same way that PX= controls00010750 pages and RX= controls output records (see P= for description of00010800 the process of control values computation). 00010850 , 00011000 ASSIST3-11 00011010 00011020 XREF= 00011030 00011040 This option provides a short, but informative cross-reference00011050 listing following the assembly listing. Among other things, it does00011060 distinguish between two types of references. A MODIFY reference is any00011070 one in which a symbol is used in a machine instruction field denoting an00011080 operand to be modified: ST 0,X for example. All other references00011090 are considered FETCH references: B X , L 0,X , DC A(X) . The00011100 cross-reference output shows a symbol, its value, and statement numbers00011110 of referencing statements, with MODIFY references flagged as negative00011120 statement numbers. Conrol of the output is obtained both by the XREF=00011130 option, and by *XREF cards inserted in the source program as desired.00011140 The latter permit explict control of how references are gathered.00011150 00011160 A brief note on the XREF mechanism is necessary to make use of the00011170 flexible control provided. During Pass 1 of an assembly, the SD (symbol00011180 Definition) flag is attached to each symbol as it is defined. The flag00011190 consists of two bits (M for Modify and F for Fetch, in that order), and00011200 shows for each symbol what kinds of references may possibly collected.00011210 For example, SD=10 indicates that no Fetch references are ever to be00011220 printed for a specific symbol. The SD flag may be changed during a00011230 program by *XREF cards, so that symbols in different sections of the00011240 program can be treated differently: SD=00 will eliminate all following00011250 symbols completely, until it is changed again. 00011260 00011270 During Pass 2, a Symbol Reference (SR) flag is used to determine00011280 what types of references are being collected from the code. A reference00011290 to a symbol is logged if and only if the SD bit and the SR bit for the00011300 given type of reference are both on. I.e., if SD=10 for a symbol, SR=1100011310 at the current time, and a fetch reference is made, no reference will be00011320 logged, since the SD Fetch bit is 0. Note that references are only00011330 logged during Pass 2: some symbol references occur only during Pass 1,00011340 and these are ignored, such as sumbols in EQU, ORG, and DC and DS00011350 length modifiers or duplication factors. 00011360 00011370 The XREF parameter requests a cross-reference, indicates the type00011380 of output produced, and possibly gives initial values to the SD and SR00011390 flags. Two forms are permitted as follows: 00011400 00011410 XREF=a OR XREF=(a,b,c) WHERE 00011420 00011430 a: indicates overall control and output format: 00011440 =0 no cross-reference is generated. 00011450 =2 cross reference is printed, with one symbol per output line.00011460 =3 cross reference is printed, but with minimal output wasted (more00011470 than one symbol may appear on a line- this form is recommended).00011480 b: initial value of SD flag, in decimal corresponding to binary, i.e.00011490 0: 00, 1: 01, 2: 10, 3: 11. 00011500 c: initial value of SR flag, same format as b. 00011510 00011520 Illegal values are ignored, and it is allowable to omit items as00011530 desired, showing this by comma usage: XREF=(2,,2) for example. The00011540 default value is XREF=(0,3,3) so that all that is needed to obtain a00011550 complete listing is to code XREF=2 or XREF=3, as the other values are00011560 not changed or zeroed. 00011570 , 00012000 ASSIST3-12 00012010 00012020 The SR and SD flags may be changed at any time during the program,00012030 by placing *XREF comment cards anywhere in the source program following00012040 the first machine instruction or assembler opcode used (SD options used00012050 before these will work, but SR's will be ignored). The format is:00012060 00012070 *XREF one or more blanks OPTION1=value1,OPTION2=value2,.....00012080 00012090 The operand(s) may be specified in any order, and if the same00012100 option is used several times, requested actions are performed in order.00012110 The options are: 00012120 00012130 SD= give the modify and fetch bits for the SD flag.00012140 SR= give the modify and fetch bits for the SR flag.00012150 00012160 Possible values for and are: 00012170 00012180 0: turn bit off. 00012190 1: turn bit on. 00012200 *: leave bit in previous state. 00012210 00012220 If an specification is omitted, this is equivalent to a *.00012230 00012240 It is suggested that the user begin by just specifying XREF=2 or 300012250 and then cutting out unnecessary references later. Although complex,00012260 the facilities allow unwanted output to easily be eliminated. The00012270 following gives as example (assumed to be a large program): 00012280 00012290 *XREF SD=10 following symbols will have only modify refs. 00012300 ..... large number of DS and DC statements (global table, for example).00012310 *XREF SD=*1 add modify and fetch references both. 00012320 ..... more symbols in DSECTS, tables, etc. 00012330 *XREF SD=00,SR=10 collect no references to symbols defined from00012340 here on, collect modify references created. 00012350 ..... section of code referencing tables above. 00012360 *XREF SD=11,SR=11 collect all references from following code to00012370 2nd part of table, modify references to first 00012380 part, and all references to itself. 00012390 ..... section of code referencing tables. 00012400 , 00001000 ASSIST4-1 00001010 00001020 PART IV. ASSIST OPTIONAL EXTENDED INTERPRETER 00001030 00001040 A. DESCRITPION OF NEW FEATURES 00001050 00001060 The ASSIST Optional Extended Interpreter is a seperate control00001070 section which can replace the original ASSIST interpreter if certain00001080 additional program debugging features are desired. These features00001090 include additional pseudo instructions, extra program statistics,00001100 extra abnormal termination completion information, a facility allowing00001110 the programmer to change machine emulation during execution, an00001120 instruction trace facility, an instruction counting facility and a00001130 larger subset of S360/S370 instructions. The ASSIST interface with00001140 the interpreter (Econtrol Block) has been extended but upwards00001150 compatibility with the entire assist system is maintained. 00001160 The ASSIST Optional Extended Interpreter is somewhat larger00001170 and executes slightly slower than the original Assist interpreter.00001180 This is caused by the extensively table-driven nature of the extended00001190 interpreter and the addition of all of the new features. 00001200 , 00001210 ASSIST4-2 00001220 00001230 B. THE XOPC (OPTIONS CALL) DEBUGGING AND ANALYSIS INSTRUCTION00001240 00001250 The OPtions Call pseudo-instruction can provide the user 00001260 programmer with several functions: 1). Set a type of 'SPIE' in00001270 ASSIST, giving the user the capability to process specified execution00001280 time interrupts, 2). Trace instructions as they are executed, 3). Check00001290 which areas of storage are being modified by which instructions, 4).00001300 Purposely cause an execution time interrupt when a certain number of00001310 instructions have been executed, 5). Control Boundary Alignment00001320 Checking - Turn off and on the allowance of S0C6 alignment interrupts,00001330 and 6). Count and print statistics of the number of instructions00001340 executed between two specified addresses. The flexibility of this00001350 instruction is brought about by its similarity in format to the s360-00001360 s370 Supervisor Call Instruction (SVC). 00001370 The XOPC instruction is of the RR type. Its general format 00001380 is as follows: 00001390 00001400 -------------------- 00001410 | 01 | I1 | 00001420 -------------------- 00001430 0 8 15 00001440 00001450 00001460 The number residing in the second byte of the instruction 00001470 controls which specific XOPC instruction will be executed. Up to 25600001480 (0-255) different instructions can be executed using XOPC. However,00001490 at present only 23 XOPC instructions are implemented. 00001500 There is very little error checking involved with the inter- 00001510 pretation of the XOPC instruction. The condition code is used to tell00001520 the user programmer about XOPC instruction errors and is set during00001530 execution of the instruction as follows: 00001540 00001550 CC = 0 Instruction is valid 00001560 CC = 1 Illegal or Incorrect Argument(s) used. 00001570 CC = 3 Specified code number is not implemented. 00001580 00001590 When a specified XOPC instruction is found to be in error, the condition00001600 code is set as described above, and the instruction execution is00001610 ignored. No other error checking is provided. It should be noted that00001620 XOPC instruction errors cannot cause execution time interrupts00001630 (ABENDS). 00001640 Below is a description of the 23 XOPC instructions presently 00001650 implemented. 00001660 , 00001670 ASSIST4-3 00001680 00001690 XOPC 0 - SET PSEUDO - SPIE EXIT ADDRESS 00001700 00001710 This instruction allows the user to set a type of 'SPIE'. 00001720 The user specifies an address and the interrupts he wishes to00001730 process in a coded form. When this instruction is executed, Registers00001740 0 and 1 are assumed to contain certain arguments. Register 1 must00001750 contain a user program address (Exit Address) to which control is passed00001760 if any of the specified program interrupts occur. The last 15 bits00001770 (bits 17-31) of Register 0 must contain a code specifying which00001780 interrupts the user wishes to intercept. The first 17 bits of register00001790 0 are ignored. Each of the bit positions 17 to 31 of register 000001800 correspond to one of the 15 execution time interrupts. A 1 in00001810 one of the bit positions specifies a spie-exit on the corresponding00001820 program interrupt. For example, Bit (17) = 1 specifies a spie-exit on00001830 S0C1, Bit (18) = 1 specifies a spie-exit on S0C2, ......., Bit (31)00001840 = 1 specifies a spie-exit on S0CF. A zero in any of the bit positions00001850 allows the corresponding execution time interrupt to occur as if no00001860 spie had been set. 00001870 00001880 Example: If register 0 contains the following; 00001890 00001900 0000 0000 0000 0000 0111 0000 0000 0001 00001910 00001920 After an XOPC 0 instruction has been executed with register 0 as above,00001930 control will be passed to the address found in register 1 if any of the00001940 following interrupts occur; S0C1, S0C2, S0C3 and S0CF. 00001950 If a spie exit address has been given (i.e. This instruction 00001960 has been executed) and one of the specified interrupts occurs, the00001970 following actions take place: 00001980 00001990 1). The current values of user register 0 and 1 are saved. 00002000 00002010 2). The PSW at interrupt is loaded into registers 0 and 1. 00002020 00002030 3). The proper interrupt code is inserted into user register 00002040 0 (bits 17 thru 31 of the PSW). 00002050 00002060 4). ASSIST now considers the user in the interrupt processing 00002070 state. 00002080 00002090 5). Control in the user program is passed to the given 00002100 interrupt exit address. 00002110 00002120 It should be noted that when the user is in the Interrupt 00002130 Processing State any further interrupt will cause abnormal termination00002140 of the user program. The user will remain in this state until the exec-00002150 ution of an XOPC 21 instruction. 00002160 XOPC 0 can be executed an unlimited number of times during 00002170 the execution of a program to change the specified exit address or to00002180 change the interrupts to be intercepted. Note, however, that the most00002190 recent execution of XOPC 0 is the one in effect, and cancels all00002200 previous executions. 00002210 , 00002220 ASSIST4-4 00002230 00002240 XOPC 1 - SET ADDRESSES FOR THE INSTRUCTION TRACE FACILITY00002250 00002260 This instruction specifies boundary addresses used by the 00002270 trace facility. Once enabled the trace facility will give the user a00002280 printed trace of all instructions executed within these two boundary00002290 addresses. When this instruction is executed the lower and upper trace00002300 address limits are assumed to be in registers 0 and 1, respectively.00002310 00002320 00002330 XOPC 2 - TURN ON THE INSTRUCTION TRACE FACILITY 00002340 00002350 This instruction enables the trace facility. Prior to the 00002360 execution of this instruction the user should have specified two limit00002370 addresses. However, if no limit addresses have been specified, ASSIST00002380 will use the highest and lowest program addresses for the limits.00002390 Below is an example of the trace line printed for each instruction00002400 executed. Assume this instruction is executed causing the following00002410 trace message to be printed: 00002420 00002430 ADDR INSTRUCTION 00002440 00EBE0 STM R0,R10,SAVEAREA 00002450 00002460 Here is the trace message printed: 00002470 00002480 TRACE--> INSTR ADDR: 00EBE0 INSTR: 980A 6020 00002490 00002500 00002510 XOPC 3 - SET ADDRESSES (as in XOPC 1) and TURN ON THE00002520 INSTRUCTION TRACE FACILITY 00002530 00002540 This instruction combines the actions of XOPC instructions 1 00002550 and 2. It assumes register usage the same as in XOPC 1. 00002560 00002570 00002580 XOPC 4 - TURN OFF THE INSTRUCTION TRACE FACILITY 00002590 00002600 This instruction disables the Instruction Trace. 00002610 00002620 00002630 XOPC 5 - SET ADDRESSES FOR THE STORAGE MODIFICATION CHECKING00002640 FACILITY 00002650 00002660 This instruction specifies address boundaries (high and low) 00002670 inside which the Storage Modification Checking Facility will operate.00002680 Once enabled, this facility causes storage between the boundary00002690 addresses to be monitored. If any of this storage is modified, the00002700 length of storage modified and the instruction modifying the storage00002710 will be printed for the user. The register usage upon execution of00002720 this instruction is the same as in XOPC 1 above. 00002730 , 00002740 ASSIST4-5 00002750 00002760 XOPC 6 - TURN ON THE STORAGE MODIFICATION CHECKING FACILITY00002770 00002780 This instruction enables the Storage Modification Checking 00002790 Facility. Before the execution of this instruction the user should00002800 have specified two boundary addresses. However, if no limit addresses00002810 are specified ASSIST will use the highest and lowest program addresses00002820 (outer limits) for the limit addresses. Below is an example of the00002830 Storage Modification Checking line printed when an instruction modifies00002840 storage. Assume the instruction listed below is executed: 00002850 00002860 ADDR INSTRUCTION 00002870 0001C0 ST R1,SAVE 00002880 00002890 Here is the line printed assuming the label SAVE has a displacement of00002900 0002C0. 00002910 00002920 CHECK--> INSTR ADDR: 0001C0 INSTR: 5010 C2C0 00002930 MODIFICATION LIMIT ADDRS--> LOW: 0002C0 HIGH: 0002C3 00002940 00002950 00002960 XOPC 7 - SET ADDRESSES (as in XOPC 5) and TURN ON THE00002970 STORAGE MODIFICATION CHECKING FACILITY 00002980 00002990 This instruction combines the actions of the XOPC 5 and 00003000 XOPC 6 instructions above. 00003010 00003020 00003030 XOPC 8 - TURN OFF STORAGE MODIFICATION CHECKING FACILITY00003040 00003050 This instruction disables the Storage Modification 00003060 Checking Facility. 00003070 00003080 00003090 XOPC 9 - TURN ON BOUNDARY ALIGNMENT CHECKING FACILITY00003100 00003110 This instruction turns on boundary alignment checking in 00003120 ASSIST. This implies that S0C6 alignment interrupts will be allowed.00003130 The default condition within ASSIST allows Alignment Interrupts to00003140 occur. Thus, this instruction need be executed only after execution00003150 of an XOPC 10 instruction has shut off (disabled) the Boundary00003160 Alignment Checking Facility (see XOPC 10). 00003170 00003180 00003190 XOPC 10 - TURN OFF BOUNDARY ALIGNMENT CHECKING FACILITY00003200 00003210 This instruction disables Boundary Alignment checking in 00003220 ASSIST. This implies that S0C6 Alignment Interrupts will no longer00003230 be allowed after the execution of this instruction. Thus, the user is00003240 no longer restricted by storage alignments and can fetch and store data00003250 on odd word boundaries. 00003260 , 00003270 ASSIST4-6 00003280 00003290 XOPC 11 - FETCH ASSIST INSTRUCTION COUNTER 00003300 00003310 The current value of the ASSIST Instruction Counter is put 00003320 in user register 0. This instruction should be used in conjunction with00003330 the XOPC 14 instruction described below. The instruction counter00003340 is put into the register in hexidecimal form. 00003350 00003360 00003370 XOPC 12 - EMULATE SYSTEM 360 00003380 00003390 This instruction causes ASSIST to emulate a system 360. That 00003400 is, ASSIST will act as if it is running on an S360 no matter what00003410 machine (S360 or S370) it is really running on. It should be noted00003420 that emulation in ASSIST defaults to S370 (S370 instructions will be00003430 interpreted). After the execution of this instruction however, ONLY00003440 S360 instructions will be interpreted. S370 instructions will cause00003450 user program termination (S0C1). 00003460 00003470 00003480 XOPC 13 - EMULATE SYSTEM 370 00003490 00003500 This instruction causes ASSIST to emulate a system 370. That 00003510 is, ASSIST will act as if it is running on an S370 no matter what00003520 machine (S360 or S370) it is really running on. This instruction00003530 should only be used after the execution of an XOPC 12 instruction as00003540 machine emulation in ASSIST defaults to S370 (i.e.S370 instructions00003550 will be interpreted). 00003560 00003570 00003580 XOPC 14 - SET INTERRUPT COUNT 00003590 00003600 This instruction allows the user to halt program execution 00003610 when the ASSIST instruction counter and the value found in register 000003620 become equal (i.e. cause a COUNT INTERRUPT). This instruction should be00003630 used in conjunction with the XOPC 11 instruction. Any negative value00003640 found in user register 0 when this instruction is executed will disarm00003650 the count interrupt facility. 00003660 Example of Use: The user desires a count interrupt to occur 00003670 if 200 instructions are executed from this point on (Note: The ASSIST00003680 instruction counter counts down): 00003690 00003700 XOPC 11 Load register 0 with current instruction counter 00003710 S R0,=F'200' decrement counter by 200 00003720 XOPC 14 Set interrupt count 200 instructions from now. 00003730 , 00003740 ASSIST4-7 00003750 00003760 XOPC 15 - SET COUNT EXIT ADDRESS 00003770 00003780 The value found in user register 0 when this instruction is 00003790 executed will be used as an exit address if a count interrupt occurs00003800 (i.e. when the instruction counter becomes equal to the clock00003810 comparator - see XOPC 14). If a count interrupt occurs after this00003820 instruction has been executed, the psw at interrupt will be loaded00003830 into user registers 0 and 1. Execution will then continue beginning00003840 at the given exit address. If no exit address has been specified and00003850 a count interrupt occurs, the program abnormally terminates with00003860 the standard ASSIST instruction limit exceeded error printed.00003870 00003880 00003890 XOPC 16 - TURN ON THE INSTRUCTION EXECUTION COUNT FACILITY00003900 00003910 This instruction enables the INSTRUCTION EXECUTION COUNT 00003920 FACILITY. This facility counts each instruction executed between two00003930 limit addresses. It should be realized that upon its initial00003940 execution this instruction will cause ASSIST to allocate a section of00003950 main memory equal in size to that of the user program. If this space00003960 is found to be unavailable, the condition code of the user program is00003970 set to one and the count facility remains disabled. Prior to the00003980 execution of this instruction, the user should have specified two00003990 limit addresses for the count facility (See XOPC 17 below). However,00004000 if two limit addresses were not specified, ASSIST will use the highest00004010 and lowest program addresses for the limit addresses. Note: This00004020 instruction does not clear the instruction counting area. See XOPC00004030 20 for clearing the count area. 00004040 00004050 00004060 XOPC 17 - SET ADDRESSES FOR THE INSTRUCTION EXECUTION00004070 COUNT FACILITY (IECF) 00004080 00004090 This instruction specifies boundary limit addresses used by 00004100 IECF. Once enabled this facility will count the number of executions00004110 of each instruction between the two limit addresses specified by this00004120 instruction. When this instruction is executed the low and high00004130 IECF limit addresses are assumed to be in registers 0 and 1, 00004140 respectively. 00004150 00004160 00004170 XOPC 18 - SET ADDRESSES AND TURN ON THE IECF 00004180 00004190 This instruction combines the actions of XOPC instructions 00004200 16 and 17. Register usage is assumed to be the same as in XOPC 17.00004210 00004220 00004230 XOPC 19 - TURN OFF THE INSTRUCTION EXECUTION COUNT FACILITY00004240 00004250 This instruction disables the IECF. This instruction will 00004260 not have any effect on the IECF counting area. 00004270 , 00004280 ASSIST4-8 00004290 00004300 XOPC 20 - CLEAR THE INSTRUCTION EXECUTION COUNT FACILITY00004310 COUNTING AREA 00004320 00004330 This instruction resets the Instruction Execution Count 00004340 Facility Counting area to zero. If the IECF has never been enabled in00004350 the user program (i.e. no counting space has been allocated), the00004360 condition code of the user program is set to 1 and this instruction is00004370 ignored. This instruction can be executed an unlimited number of times00004380 to insure accurate instruction counting. Please note that the counter00004390 for each instruction is only a halfword (2 bytes) in length. Executing00004400 one instruction many times could overflow that counter and reset it00004410 to zero. 00004420 00004430 00004440 XOPC 21 - RETURN FROM INTERRUPT PROCESSING CODE 00004450 00004460 This instruction tells ASSIST that the User Program has com- 00004470 pleted any interrupt processing routine (s) and is ready to resume00004480 normal execution of the user program. It causes the following actions00004490 to occur: 00004500 00004510 1). If the user is not in the interrupt processing state the 00004520 condition code is set to 1 and nothing more is done. 00004530 00004540 2). The address in register 1 is used as the address where 00004550 normal execution of the user program will resume. If 00004560 register 1 is not modified in the interrupt processing code,00004570 execution of the user program will continue with the 00004580 instruction immediately following the instruction that 00004590 caused the initial interrupt. Otherwise, the user will be 00004600 expected to load register 1 with an appropriate address. 00004610 00004620 3). User registers 0 and 1 are reloaded with the values they 00004640 had when the initial interrupt occurred. 00004650 00004660 4). Normal execution of the user program is resumed with the 00004670 user no longer in the INTERRUPT PROCESSING STATE. 00004680 00004690 00004700 XOPC 22 - DUMP THE INSTRUCTION EXECUTION COUNT FACILITY00004710 STATISTICS 00004720 00004730 This instruction prints out a statistical report according to 00004740 address of the number of instructions counted (within the specified00004750 limit addresses) by the Instruction Execution Count Facility. An00004760 instruction executed 0 times will cause no statistical line to be00004770 printed. Groups of instructions executed the same number of times will00004780 produce one statistical line. This shows the user where his major00004790 loops are and where most of his execution time is being spent. If this00004800 instruction is executed and the count facility has not yet been enabled00004810 at least once in the user program (i.e. no count space has been00004820 allocated), the condition code of the user program is set to one and00004830 this instruction is ignored. As an example consider the following test00004840 program: 00004850 , 00004860 ASSIST4-9 00004870 00004880 ADDR INSTRUCTION COMMENTS 00004890 ... 00004900 ... 00004910 ... 00004920 000010 LOWADDR EQU * 00004930 000010 LA 0,LOWADDR GET LOW COUNTING ADDRESS00004940 000014 LA 1,HIGHADDR GET HIGH COUNTING ADDRESS00004950 000018 XOPC 18 ENABLE THE COUNT FACILITY 00004960 00001A XOPC 20 CLEAR THE COUNT AREA 00004970 00001E LA 10,50 GET LOOP VALUE 00004980 000022 LOOP LR 1,3 DO GARBAGE FOR COUNTING 00004990 000024 AR 4,1 MORE GARBAGE 00005000 000028 BCT 10,LOOP LOOP 50 TIMES 00005010 00002C XOPC 19 TURN OFF THE COUNTING 00005020 00002E XOPC 22 DUMP STATISTICS 00005030 000030 HIGHADDR EQU * 00005040 ... 00005050 ... 00005060 ... 00005070 The XOPC 22 instruction above would print out the following statistical00005080 report: 00005090 00005100 STATS--> BEGIN ADDR: 00001E END ADDR: 00001E INSTRUCTION COUNT: 000100005110 STATS--> BEGIN ADDR: 000022 END ADDR: 000028 INSTRUCTION COUNT: 005000005120 STATS--> BEGIN ADDR: 00002C END ADDR: 00002C INSTRUCTION COUNT: 000100005130 00005140 00005150 A FEW EXTRA NOTES: 00005160 00005170 It should be noted when using the XOPC instructions that they 00005180 are expensive instructions with regard to overhead space and time.00005190 They should be used sparingly and preferably one facility at a time for00005200 best results. 00005210 , 00001000 ASSIST5-1 00001010 00001020 PART V. OUTPUT AND ERROR MESSAGES 00001030 00001040 A. ASSEMBLY LISTING 00001050 00001060 1. ASSEMBLY LISTING FORMAT 00001070 00001080 The assembly listing produced by the ASSIST assembler is essen-00001090 tially the same as that produced by the standard OS/360 assemblers,00001100 with the following minor differences: 00001110 00001120 a. Error messages are not printed at the end of the assembly00001130 listing, but are printed after the each statement causing the messages.00001140 A scan pointer '$' indicates the column where the error was discovered.00001150 00001160 b. No more than four messages are printed for any single source00001170 statement. Some errors cause termination of statement scan, and errors00001180 following in the same statement may not be discovered. However, an00001190 error in a statement does not normally prevent its statement label from00001200 being defined, which is usually the case with the standard assembler.00001210 00001220 c. As noted under PRINT in PART I and under NOLIST in PART III,00001230 statements flagged are printed regardless of print status at the time.00001240 00001250 d. As noted under PRINT in PART I, no more than eight bytes of00001260 data are printed for a statement, even if PRINT DATA is used.00001270 00001280 2. ASSEMBLER ERROR MESSAGES 00001290 00001300 The assembler produces error messages consisting of an error code00001310 followed by an error description. The code is of the form AS###, with00001320 the value of ### indicating one of three types of errors: 00001330 00001340 a. Warnings - ### is in range 000-099. These never prevent the00001350 execution of the program, correspond to OS severity code 4, and e have00001360 messages beginning with characters 'W-'. 00001370 00001380 b. Errors - ### is in range 100-899. Execution is deleted if the00001390 total number of errors exceeds the NERR parameter, as described in PART00001400 III. These correspond to OS severity codes of 8 and 12. 00001410 00001420 c. Disastrous errors - ### is in range 900-999. Some condition00001430 prevents successful completion of the assembly process. Execution of00001440 the user program may or may not be permitted. 00001450 , 00002000 ASSIST5-2 00002010 00002020 3. LIST OF ASSEMBLER ERROR MESSAGES 00002030 00002040 The following lists the codes and messages issued by the ASSIST00002050 assembler, with further explanations following each message. 00002060 00002070 AS000 W-ALIGNMENT ERROR-IMPROPER BOUNDARY 00002080 The address used in a machine instruction is not aligned to the00002090 correct boundary required by the type of instruction used.00002100 00002110 AS001 W-ENTRY ERROR-CONFLICT OR UNDEFINED 00002120 A symbol named in an ENTRY statement is either undefined, or is00002130 also named in either a DSECT or EXTRN statement. 00002140 00002150 AS002 W-EXTERNAL NAME ERROR OR CONFLICT 00002160 A symbol named in an EXTRN statement is either defined in the00002170 program or is named in an ENTRY statement. 00002180 00002190 AS003 W-REGISTER NOT USED 00002200 The register flagged in a DROP statement is not available for use00002210 as a base register at this point in the program. This may be00002220 caused by an error in a USING statement naming the register.00002230 00002240 AS004 W-ODD REGISTER USED-EVEN REQUIRED 00002250 An odd register is coded in a machine instruction requiring the 00002260 use of an even register for a specific operand. Instructions00002270 which may flagged are Multiply, Divide, Double Shifts, and all00002280 floating point instructions. 00002290 00002300 AS005 W-END CARD MISSING-SUPPLIED 00002310 The assembler creates an END card because the user has supplied00002320 none before an end-file marker. 00002330 , 00003000 ASSIST5-3 00003010 00003020 AS100 ADDRESSIBILITY ERROR 00003030 An implied address is used which cannot be resolved into base-00003040 displacement form. No base register is available having the00003050 same relocatability attribute and a value from 0 to 4095 less than00003060 the value of the implied address. 00003070 00003080 AS101 CONSTANT TOO LONG 00003090 Too many characters are coded for the type of constant specified.00003100 This message appears if a literal constant contains more than 11200003110 characters, including the equals sign and delimiters. 00003120 00003130 AS102 ILLEGAL CONSTANT TYPE 00003140 An unrecognizable type of constant is specified. 00003150 00003160 AS103 CONTINUATION CARD COLS. 1-15 NONBLANK 00003170 A continuation card contains nonblank characters in columns 1-15.00003180 This may be caused by an accidental punch in column 72 of the00003190 preceding card. 00003200 00003210 AS104 MORE THAN 2 CONTINUATION CARDS 00003220 Three or more continuation cards are used, which is illegal,00003230 except on macro prototype statements and macro calls. 00003232 00003240 AS105 COMPLEX RELOCATABILITY ILLEGAL 00003250 ASSIST does not permit complex relocatible expressions. 00003260 00003270 AS106 TOO MANY OPERANDS IN DC 00003280 ASSIST allows no more than ten operands in a DC statement.00003290 00003300 AS107 MAY NOT RESUME SECTION CODING 00003310 The assembler requires that any section be coded in one piece.00003320 The label flagged has already appeared on a CSECT or DSECT.00003330 00003340 AS108 ILLEGAL DUPLICATION FACTOR 00003350 A duplication factor either exceeds the maximum value of 32,767,00003360 or a duplication factor in a literal constant is not specified by00003370 a decimal term or else has the value zero. 00003380 00003390 AS109 EXPRESSION TOO LARGE 00003400 The value of the flagged expression or term is too large for the00003410 given usage, such as a constant length greater than the maximum00003420 permissible for the type of constant. 00003430 00003440 AS110 EXPRESSION TOO SMALL 00003450 The value of the flagged expression or term is too small for the00003460 given usage, or has a negative value. Coding a V-type constant00003470 with a length of two would generate this message. 00003480 , 00004000 ASSIST5-4 00004010 00004020 AS111 INVALID CNOP OPERAND(S) 00004030 The operands of a CNOP have values which are anything but the00004040 legal combinations of values for a CNOP, such as a first operand00004050 greater than the second, an odd value, etc. The only legal value00004060 combinations are 0,4 2,4 0,8 2,8 4,8 6,8 . 00004070 00004080 AS112 LABEL NOT ALLOWED 00004090 A label is used on a statement not permitting one, such as a00004100 CNOP or USING statement. 00004110 00004120 AS113 ORG VALUE IN WRONG SECTION OR TOO LOW 00004130 The expression in an ORG statement either has a value smaller than00004140 the initial location counter value for the current control00004150 section, or has a relocatibility attribute different from that00004160 of the current control section. 00004170 00004180 AS114 INVALID CONSTANT 00004190 A constant contains invalid characters for its type, or is00004200 specified improperly in some other way. 00004210 00004220 AS115 INVALID DELIMITER 00004230 The character flagged cannot appear in the statement where it does.00004240 This message is used whenever the scanner expects a certain kind of00004250 delimiter to be used, and it is not there. 00004260 00004270 AS116 INVALID FIELD 00004280 The field flagged has an unrecognizable value, or is otherwise00004290 incorrectly coded. PRINT OF is flagged this way. 00004300 00004310 AS117 INVALID SYMBOL 00004320 The symbol flagged either contains nine or more characters or does00004330 not begin with an alphabetic character as is required. 00004340 00004350 AS118 INVALID OP-CODE 00004360 The statement contains an unrecognizable mnemonic op-code, or none00004370 at all. Note that different versions of ASSIST may not accept some00004380 of the possible op-codes. The first heading described in00004390 PART IV.B.1.a describes which op-codes are allowed. 00004400 00004410 AS119 PREVIOUSLY DEFINED SYMBOL 00004420 The symbol in the label field has been previously used as a label,00004430 or a SET variable has been previously declared. 00004432 00004440 AS120 ABSOLUTE EXPRESSION REQUIRED 00004450 A relocatable expression is used where an absolute one is required,00004460 such as in constant duplication factor or for a register.00004470 00004480 , 00005000 ASSIST5-5 00005010 00005020 AS121 MISSING DELIMITER 00005030 A delimiter is expected but not found. For instance, a C-type00005040 constant coded with no ending ' is flagged this way. 00005050 00005060 AS122 FEATURE NOT CURRENTLY IMPLEMENTED 00005070 The version of ASSIST being used does not support the language00005080 feature used. 00005090 00005100 AS123 MISSING OPERAND 00005110 The instruction requires an operand, but it is not specified.00005120 00005130 AS124 LABEL REQUIRED 00005140 An instruction requiring a label, such as a DSECT, is coded00005150 without one. 00005160 00005170 AS126 RELOCATABLE EXPRESSION REQUIRED 00005180 An absolute expression or term is used where a relocatable one is00005190 required by ASSIST, such as in the first operand of a USING.00005200 Also, this message may appear if the final relocatiblity attribute00005210 of the value in an address constant is that of a symbol in a DSECT.00005220 00005230 AS127 INVALID SELF-DEFINING TERM 00005240 The self-defining term flagged contains an illegal character for00005250 its type, has a value too large for 24 bits to contain, or is00005260 otherwise incorrectly specified. 00005270 00005280 AS128 ILLEGAL START CARD 00005290 The START card flagged is coded with one or more statements other00005300 than listing controls or comments appearing before it. 00005310 00005320 AS129 ILLEGAL USE OF LITERAL 00005330 The literal constant appears in the receiving field of an00005340 instruction which modifies storage. e.g., ST 0,=F'1' 00005350 00005360 AS130 UNDEFINED SYMBOL 00005370 The symbol shown is either completely undefined, or has not been00005380 already defined when it is required to be. Symbols used in ORG00005390 instructions or in constant lengths or duplication factors must be00005400 defined before they are used. 00005410 , 00006000 ASSIST5-6 00006010 00006020 AS131 UNRESOLVED EXTERNAL REFERENCE 00006030 The symbol used in a V-type constant is not defined in the00006040 assembly, or is defined but not declared a CSECT or ENTRY. ASSIST00006050 does not link multiple assemblies, so this is an error. 00006060 00006070 AS132 ILLEGAL CHARACTER 00006080 The character flagged is either not in the set of acceptable00006090 characters, or is used in an illegal way. 00006100 00006110 AS133 TOO MANY PARENTHESIS LEVELS 00006120 Parentheses are nested more than five deep in an expression.00006130 00006140 AS134 RELOCATABLE EXPRESSION USED WITH * OR / 00006150 RElocatable terms or expressions may not be used with either of00006160 these operators. 00006170 00006180 AS135 SYNTAX 00006190 The character flagged is improperly used. This catchall message00006200 is given by the general expression evaluator when it does not find00006210 what is expected during a scan. 00006220 00006230 AS136 TOO MANY TERMS IN EXPRESSION 00006240 The expression contains more than the legal maximum of 16 terms.00006250 00006260 AS137 UNEXPECTED END OF EXPRESSION 00006270 The expression terminates without having enough closing parentheses00006280 to balance the opening ones used. 00006290 00006300 00006310 THE FOLLOWING MESSAGES ARE ONLY ISSUED DURING MACRO PROCESSING. 00006320 00006330 AS201 OPERAND NOT ALLOWED 00006340 During macro expansion, an extra operand was found, i.e., an extra00006350 positional beyond those given in the prototype. 00006360 00006370 00006380 AS202 STATEMENT OUT OF ORDER 00006390 The statement flagged is in an incorrect place in the deck. For00006400 example: LCLx before GBLx, ACTR not after both; GBLx, LCLx, ACTR00006410 in middle of macro definition or open code. *SYSLIB card out of00006420 order, etc. May often be caused by missing MEND card. 00006430 00006440 00006450 AS203 SET SYMBOL DIMENSION ERROR 00006460 A dimensioned set symbol was used without a dimension, or one which00006470 was not dimensioned was written with one. 00006480 00006490 00006495 AS204 INVALID NBR OF SUBSCRIPTS 00006500 There was an error in specifying substring notation, sublists, or00006510 set symbol dimension. 00006520 , 00007000 ASSIST5-7 00007010 00007020 AS205 ILLEGAL CONVERSION 00007030 During macro editing, a SET instruction was found with an obviously00007040 Incorrect conversion, as in &I SETA C . 00007050 00007055 00007060 AS206 MISSING QUOTES IN CHAR EXPR 00007070 Quotes (apostrophes) are required in character expressions and must00007080 always be supplied, but were not. 00007090 00007100 00007110 AS207 ILLEGAL OR DUP MACRO NAME 00007120 A macro prototype name is either completely illegal, such as having00007130 too many characters, or duplicates the name of a previously given00007140 macro, machine instruction, or assembler instruction. 00007150 00007155 00007160 AS208 OPRND NOT COMPATIBLE WITH OPRTR 00007170 An operand is used with an incompatible operator. For example, if00007180 &C is LCLC, &B LCLB : &B SETB (NOT &C) . 00007190 00007200 00007210 AS209 UNDFND OR DUPLICATE KEYWORD 00007220 In calling a macro, a keyword is used which does not appear in the00007230 macro prototype. In either defining or calling a macro, a keyword00007240 operand appears twice or more in the list of operands. 00007250 00007255 00007260 AS210 MNEST LIMIT EXCEEDED 00007270 The MNEST option provides a maximum limit to the nested depth of00007280 macro calls. This limit has been exceeded. Note that after the00007290 MSTMG limit has been exceeded, the MNEST limit is effectively 0 .00007300 00007310 00007320 AS211 ILLEGAL ATTRIBUTE USE 00007330 ASSIST does not support S', I', or L' for macro operands. 00007340 00007345 00007350 AS212 GENERATED STATEMENT TOO LONG 00007360 A STATEMENT WAS GENERATED HAVING MORE THAN TWO CONTINUATION CARDS .00007370 00007380 AS217 STMT NOT PROCESSED: PREVIOUS ERROR: STMT/MACRO #####/name 00007390 During expansion of macro 'name', the statement numbered ##### was00007400 encountered, but not expanded because it had already been flagged.00007410 00007420 AS218 STORAGE EXCEEDED BY FOLLOWING MACRO EXPANSION 00007430 The following call to the macro listed caused overflow of storage ,00007440 probably due to looping. Use ACTR, MACTR=, or MSTMG= . 00007450 00007460 00007470 AS220 UNDEFINED SEQUENCE SYMBOL IN STATEMENT ##### 00007480 This may appear following an entire macro definition, and gives the00007490 number of a statement referencing a sequence symbol never defined .00007500 , 00008000 ASSIST5-8 00008010 00008020 Any of the following messages describes an error found during the00008030 expansion of statement ##### of macro 'name' . Some messages also add00008040 a descriptive 'value', such as an offending subscript. Note that the00008050 messages below use ## as an abbreviation for the actual output (which is00008060 actually printed by ASSIST in the form STMT/MACRO #####/name). 00008065 00008070 00008075 AS221 ACTR COUNTER EXCEEDED: ## 00008080 The ACTR count has been exceeded. The ACTR is set by the MACTR00008090 option, or by an ACTR statement. This indicates a looping macro .00008100 00008110 00008120 AS222 INVALID SYM PAR OR SET SYMBOL SUBSCRIPT: ## --> value 00008130 A subscript is out of range. The offending value is given. 00008140 00008150 AS223 SUBSTRING EXPRESSION OUT OF RANGE: ## --> value 00008160 This is most often caused by the first subscript in a substring00008170 expression having a nonpositive value, or one larger than the size00008180 of the string. 00008190 00008200 00008210 AS224 INVALID CONVERSION, CHAR TO ARITH: ## --> value 00008220 The value could not be converted to arithmetic form. 00008230 00008240 AS225 INVALID CONVERSION, ARITH TO BOOLEAN: ## --> value 00008250 The value was not 0 or 1. 00008260 00008270 AS226 INVALID CONVERSION, CHAR TO BOOLEAN: ## --> value 00008280 The value was not '0' or '1', so it could not be converted. 00008290 00008300 00008310 AS227 ILLEGAL ATTRIBUTE USE: ## 00008320 An attribute was used incorrectly. 00008330 00008340 AS228 &SYSLIST SUBSCRIPT OUT OF RANGE: ## 00008350 The subscript has a value greater than the maximum number of fields00008360 which can be supplied. 00008370 00008380 AS229 CALL FRIENDLY ASSIST REPAIRMAN: ## 00008390 An internal error has occurred inside ASSIST. Please send a deck.00008400 00008410 AS230 INTERNAL CHAR BUFFER EXCEEDED: ## 00008420 Too much concatenation was done in the statement. Remedy: reduce00008430 the complexity of the statement. 00008440 00008450 AS231 MSTMG LIMIT EXCEEDED: ## 00008460 The MSTMG limit (total number of statements processed during macro00008470 expansion) has been exceeded. Use MSTMG= to increase this. 00008480 00008490 AS232 ZERO DIVIDE OR FIXED POINT OVERFLOW: ## 00008500 One of these interrupts was caused by the statement given. 00008510 , 00009000 ASSIST5-9 00009010 00009020 AS241 SEQUENCE SYMBOL NOT FOUND 00009030 This message immediately follows an AGO or successful AIF in open00009040 code whose sequence symbol could not be found before the END card.00009050 As a result, all of the program between the AIF/AGO and END card is00009060 skipped over. 00009061 00009065 00009066 AS242 BACKWARDS AIF/AGO ILLEGAL 00009070 This message appears following an AGO or successful AIF in the open00009080 code which references a previously defined sequence symbol. ASSIST00009090 allows backwards branches only in macros, not in open code. 00009100 00009110 00009120 AS288 MACRO xxxxxxxx COULD NOT BE FOUND 00009130 This is issued by the macro library processor when it tries to get 00009140 a macro and cannot find it in the library. The macro may be named00009150 on a *SYSLIB card, or referenced by another macro. 00009160 00009170 AS289 UNABLE TO OPEN MACRO LIBRARY: OPTION CANCELED 00009180 This is issued after a *SYSLIB card is encountered, but the macro00009190 library cannot be opened. A SYSLIB DD card is missing or in error.00009200 00009210 00009215 AS298 GENERATED STMTS OVERWRITTEN 00009220 During macro expansion, one or more generated statments were lost00009230 due to internal table management, probably because a statement near00009240 the beginning of a macro generated a long literal constant. One00009250 solution is to insert several comments cards at the beginning of00009260 the macro definition. 00009270 00009280 00009290 00009300 AS999 DYNAMIC STORAGE EXCEEDED 00009310 ASSIST requires more storage than is available, so the assembly is00009320 halted. This can occur for many reasons. REMEDIES: use the DISKU00009330 option if available, remove comments cards from your program, cut00009340 down on array sizes, etc. 00009350 , 00007000 ASSIST5-10 00007010 00007020 4. ASSEMBLER STATISTICS SUMMARY 00007030 00007040 Following the assembly listing, the assembler prints three or four00007050 lines of statistical information, as follows: 00007060 00007070 a. 00007080 *** ##### STATEMENTS FLAGGED - ##### WARNINGS, ##### ERRORS 00007090 This notes the total numbers of statements flagged, warning00007100 messages, and error messages given during the assembly. 00007110 00007120 b. 00007130 ***** NUMBER OF ERRORS EXCEEDS LIMIT OF ##### ERRORS - PROGRAM EXECUTION00007140 DELETED ***** 00007150 This notes the maximum number of errors permitting execution, and00007160 that the user program will not be executed because the NERR limit00007170 value has been overrun (see PART III regarding NERR). 00007180 00007190 c. 00007200 *** DYNAMIC CORE AREA USED: LOW: ###### HIGH: ###### LEAVING: ######00007210 FREE BYTES. AVERAGE: ###### BYTES/STMT *** 00007220 The ASSIST assembler uses memory from the opposite ends of one area00007230 of storage acquired at execution time. The LOW area contains source00007240 statements and generated object code,the HIGH area contains the symbol00007250 and literal tables, and the space remaining indicates how close the00007260 user is to causing a storage overflow. The average core usage printed00007270 includes that used in both LOW and HIGH areas. 00007280 00007290 d. 00007300 *** ASSEMBLY TIME = #.### SECS, ##### STATEMENTS/SEC *** 00007310 This notes the total time used by the assembler, along with the00007320 rate of assembly. At PSU, this time includes both CPU time and00007330 I/O charges. 00007340 00007350 e. 00007360 ***** EXECUTION DELETED - LESS THAN ## PER CENT OF MACHINE INSTRUCTIONS 00007370 HAVE COMMENTS ***** 00007380 The above message may appear before the core area message, if the00007390 ASSIST has the comment-checking option, and either COMNT was coded,00007400 or was invoked by account number, and the user did not put comments00007410 on the given percentage of machine instruction statements. 00007420 , 00008000 ASSIST5-11 00008010 00008020 B. ASSIST MONITOR MESSAGES 00008030 00008040 1. HEADINGS AND STATISTICAL MESSAGES 00008050 00008060 The main control program of ASSIST may issue the following00008070 headings and messages during execution: 00008080 00008090 a. 00008100 *** ASSIST version OF date INSTS/DFP/=### CHECK/TRP/=### OPTS/CCKMR/=###00008110 ### PENN STATE UNIV. model - system *** 00008120 This heading is the first line printed, and it describes the00008130 facilities in the version of ASSIST being used, as follows: 00008140 00008150 version,date - version number of this ASSIST, and date it was created.00008160 INS/DFPS/= - describes instruction sets accepted. The digits are 0's00008170 or 1's showing lack or presence of decimal, floating00008180 point, privileged operations, and some S/370 operations00008190 CHECK/TRP/= - describes time, records, and pages checking modes. a 200008200 for T or R indicates ASSIST can obtain time or records00008210 remaining from system, 0 for T indicates no timing, 000008220 for P indicates no page checking possible. 00008230 OPTS/CCKMR/= - describes availability of major optional features, in00008240 order CMPRS, COMNT, KP=26, MACRO, and REPL. Values of00008250 0 indicate the feature is unavailable. If value for00008260 COMNT is nonzero, it is two digits long and gives the00008270 percentage of comments required. A value of 1 for R00008280 denotes a partial version of the Replace Monitor,00008290 while 2 denotes a complete version with all features .00008300 model - lists the model number of the computer being used.00008310 system - describes operating system being used (such as OS-MVT).00008320 00008330 b. 00008340 Following the above heading, the ASSIST monitor prints the00008350 contents of the user's EXEC card PARM field, or his $JOB CARD.00008360 00008370 c. 00008380 *** PROGRAM EXECUTION BEGINNING - ANY OUTPUT BEFORE EXECUTION TIME00008390 MESSAGE IS PRODUCED BY USER PROGRAM *** 00008400 This message is issued immediately before the user program is00008410 executed, and serves to delimit user output. 00008420 00008430 d. 00008440 *** EXECUTION TIME = #.### SECONDS ##### INSTRUCTIONS EXECUTED -00008450 ##### INSTRUCTIONS/SEC *** 00008460 *** FIRST CARD NOT READ: card image 00008465 This message is issued immediately after the user program has00008470 been executed, and supplies statistics regarding the execution time and00008480 rate of execution of the user program. The time shown may be slightly00008490 smaller than the actual time, if the completion code given in the dump00008500 is ASSIST = 223 TIME LIMIT EXCEEDED. The second part appears if one or00008510 more data cards were not read by the user program. 00008520 e. 00008530 *** TOTAL RUN TIME UNDER ASSIST = #.### SECS *** 00008540 This is the last line printed by ASSIST, and the time given00008550 includes time for the entire run. Printed only if CHECK/TRP/=2## .00008560 , 00009000 ASSIST5-12 00009010 00009020 2. ASSIST MONITOR ERROR MESSAGES 00009030 00009040 The ASSIST monitor may also issue any of the following messages,00009050 which are of the form AM###, and usually indicate errors: 00009060 00009070 AM001 ASSIST COULD NOT OPEN PRINTER FT06F001:ABORT 00009080 This message appears in the system message class data set if00009090 ASSIST is unable to open the DCB for its printer, using DDNAME00009100 FT06F001. This is probably caused by lack of a DD card, or by an00009110 incorrect override of this DDNAME in a catalogued procedure.00009120 00009130 AM002 ASSIST COULD NOT OPEN READER SYSIN:ABORT 00009140 This message appears in the system message class data set if00009150 ASSIST is unable to open the DCB for the source card reader. The00009160 SYSIN DD * card is probably omitted or mispunched, making an00009170 assembly and execution impossible. 00009180 00009190 AM003 - STORAGE OVERFLOW BEFORE EXECUTION, EXECUTION DELETED 00009200 The user program assembled properly, but there is insufficient00009210 memory remaining to set up control blocks required for execution.00009220 The user should attempt to reduce the amount of storage used by00009230 his program. This message should occur very seldom. 00009240 00009250 AM004 - NORMAL USER TERMINATION BY RETURN 00009260 This message is issued if the user program branches to the address00009270 originally supplied to it as a return address in register 14. If00009280 this message appears, no completion dump is printed. 00009290 00009300 AM005 - TIME OR RECORDS HAVE BEEN EXCEEDED 00009310 This message is printed if the time or record limits have been00009320 exceeded at any time during a job. This message appears after a00009330 completion dump, if there is one. 00009340 , 00010000 ASSIST5-13 00010010 00010020 C. ASSIST COMPLETION DUMP 00010030 00010040 When a user program terminates abnormally, a completion dump is00010050 provided for debugging purposes, and contains the following items:00010060 1. 00010070 ASSIST COMPLETION DUMP 00010080 The above header begins the dump. 00010090 2. 00010100 PSW AT ABEND xxxxxxxx xxxxxxxx COMPLETION CODE type = code message00010110 This line gives the user's Program Status Word, in hexadecimal,00010120 followed by further information concerning the reason for termination.00010130 The type given is one of the following: 00010140 a. SYSTEM, indicating that the code given is the same as that given00010150 by OS/360, such as for program interrupts. 00010160 b. ASSIST, indicating a completion code which does not necessarily00010170 correspond directly to a code used by OS/360. 00010180 The three-digit hexadecimal code is followed by a descriptive message.00010190 PART IV.D provides a list of the messages and codes. 00010200 00010210 3. 00010220 ***** TRACE OF INSTRUCTIONS JUST BEFORE TERMINATION: PSW BITS SHOWN ARE00010230 THOSE JUST BEFORE CORRESPONDING INSTRUCTIONS DECODED ***** 00010240 00010250 IM LOCATION INSTRUCTION : IM = PSW BITS 32-39(ILC,CC,MASK) BEFORE00010260 INSTRUCTION EXECUTED AT PROGRAM LOCATION SHOWN 00010270 aa bbbbbb cccc cccc cccc (1-10 lines in this format)00010280 00010290 The above section in a dump lists up to the last ten instructions00010300 executed before termination, with the last instruction shown usually00010310 causing the termination. Parts aa and bbbbbb make up a user PSW in00010320 each line, and are followed by from one to three halfwords of00010330 instruction, represented by cccc. 00010340 00010350 4. 00010360 ** TRACE OF LAST 10 BRANCH INSTRUCTIONS EXECUTED BEFORE TERMINATION: PSW00010370 BITS SHOWN ARE THOSE JUST BEFORE CORRESPONDING INSTRUCTION DECODED ** 00010380 00010390 IM LOCATION INSTRUCTION: IM = PSW BITS 32-39(ILC,CC,MASK) BEFORE 00010400 INSTRUCTION EXECUTED AT PROGRAM LOCATION SHOWN 00010410 AA BBBBBB CCCC CCCC CCCC (1-10 lines in this format) 00010420 00010430 The above section of the Assist Completion Dump is only given when 00010440 ASSIST Optional Extended Interpreter is in use by the installation. This00010450 section in a dump lists up to the last 10 successful branch instructions00010460 executed before termination. 00010470 5. 00010510 GP REGISTERS 0/8 1/9 2/10 3/11 4/1200010520 5/13 6/14 7/15 00010530 00010540 REGS 0-7 (8 groups of 8 hexadecimal digits each) 00010550 REGS 8-15 (8 groups of 8 hexadecimal digits each) 00010560 00010570 FLTR 0-6 (4 groups of 16 hexadecimal digits each) 00010580 00010590 The above section in a dump displays the contents of the user's00010600 general purpose and floating point registers at the time of termination.00010610 , 00011000 ASSIST5-14 00011010 00011020 6. 00011030 USER STORAGE 00011040 00011050 CORE ADDRESSES SPECIFIED- xxxxxx TO yyyyyy 00011060 zzzzzz (8 groups of 8 hexadecimal digits each) * (32 characters) *00011070 00011080 The above section shows the format of a user storage dump. The00011090 beginning and ending addresses are given by xxxxxx and yyyyyy. Each00011100 line shows 32 bytes, beginning at location zzzzzz, grouped into eight00011110 fullwords. Each area is also shown in alphameric form at the right,00011120 with blanks, letters, and digits printed directly, and all other00011130 characters translated to periods. 00011140 00011150 D. COMPLETION CODES 00011160 00011170 SYSTEM = 0Cx 00011180 This code is given for program interrupts, where x is the00011190 hexadecimal interrupt code. The message given is as shown on page00011200 6 of the IBM System/360 Reference Data card, for interrupts 0-F.00011210 00011220 ASSIST = xxx message 00011230 This type is given for special ASSIST completions. The possible00011240 codes and messages are as follows: 00011250 00011260 220 ATTEMPTED READ PAST ENDFILE 00011270 After performing an XREAD instruction and receiving an end-of-file00011280 indication, the user has attempted another XREAD, i.e. tried to00011290 read more data cards than existed. 00011300 00011310 221 INSTRUCTION LIMIT EXCEEDED 00011320 The user specified an I= limit on his EXEC card, and this number of00011330 instructions has been exceeded. The program was probably looping.00011340 00011350 222 RECORD LIMIT EXCEEDED 00011360 The user attempted to print or punch more records than was given by00011370 combination of R, RD, and RX option values. Execution has been00011380 terminated, and at least a partial dump given. 00011390 00011400 223 TIME LIMIT EXCEEDED 00011410 The user program has consumed more execution time than specified by00011420 the values of the T, TD, and TX option values. Execution was00011430 terminated and at least a partial dump given. 00011440 00011450 224 BRANCH OUT OF PROGRAM AREA 00011460 The user program attempted to branch outside of its area. The00011470 only branch outside not flagged this way is a branch to the return00011480 address originally supplied to the user program in register 14.00011490 , 00011540 ASSIST5-15 00011590 E. OBJECT DECKS AND LOADER MESSAGES 00011640 00011690 1. OBJECT DECK FORMAT 00011740 ASSIST provides basic facilties for reading (OBJIN) and punching00011790 (DECK) object decks which whose format is a compatible subset of normal00011840 S/360 decks. However, ASSIST does not punch External Symbol Dictionary00011890 (ESD) or Relocation Dictionary (RLD) cards, and ignores them if reading00011940 a deck. Thus, it cannot perform symbolic linkage between modules or00011990 relocate individual address constants. The facility can be useful for00012040 saving assembler utility programs, or for providing efficient running00012090 and good diagnostics for object code from student-written compilers.00012140 Two types of cards are punched and recognized: text cards (TXT),00012190 which supply actual object code, and end cards (END), which supply an00012240 optional entry point address for beginning of execution. The formats00012290 of these cards are described below. ALWAYS lists the characters which00012340 are defintely present, DECK notes those which are punched, and OBJIN00012390 those required for input. The notation IGNORED means that the given00012440 card columns are completely ignored when loading an object deck.00012490 00012540 CARD/COLUMNS ALWAYS DECK OBJIN 00012590 00012640 END CARD 00012690 1 ' ' IGNORED 00012740 2-4 END - - 00012790 5 X'00' IGNORED 00012840 6-8 entry address entry address or blanks 00012890 9-72 blank IGNORED 00012940 73-80 sequence # IGNORED 00012990 00013040 TEXT CARD 00013090 1 ' ' IGNORED 00013140 2-4 TXT - - 00013190 5 X'00' IGNORED 00013240 6-8 beginning address of text code which is on this card00013290 9-10 blanks IGNORED 00013340 11 X'00' IGNORED 00013390 12 length of object code on card, from X'00' to X'38' 00013440 (i.e. 0 to 56 decimal bytes of code). 00013490 13-16 blanks IGNORED 00013540 17-72 up to 56 bytes of code, to be loaded at given address.00013590 73-80 sequence # IGNORED 00013640 00013690 Note that the format above resembles the standard, given in: 00013740 IBM S/360 OS Assembler (F) Programmer's Guide GC26-3756, Appendix B. 00013790 00013840 When ASSIST punches an object deck, it punches the entire program00013890 storage, including character 5's which fill any DS or other areas not00013940 having specified code values. Unlike the standard system assemblers,00013990 ASSIST always punches an END card with an entry point address on it,00014040 whether the user specifies an entry point on the source END card or not.00014090 00014140 Although it is not possible to perform symbolic linkage of multiple00014190 decks, it is possible to link multiple decks if the user assembles each00014240 of several programs at particular locations known to each other, using00014290 START cards. Deck linkage can then be accomplished by locating a vector00014340 of address constants at the beginning of each assembly, which can then00014390 be used to reference any required areas or modules within that assembly.00014440 Note that this type of procedure will not work if RELOC is used.00014490 , 00014540 ASSIST5-16 00014590 00014640 2. ASSIST LOADER USAGE AND MESSAGES 00014690 00014740 The ASSIST loader is called by use of the OBJIN parameter, and00014790 loads object deck cards having the format given on the previous page,00014840 ignoring all cards having neither TXT nor END in columns 2-4. The usual00014890 use for this option is to load a deck previously produced by ASSIST or00014940 possibly by some student-written compiler being tested. However, it is00014990 possible to link decks produced by the standard system assemblers if the00015040 guidelines below are followed: 00015090 a. Use no V-type adcons. 00015140 b. Any command listed in PART II of this manual (XREAD, XDUMP, etc)00015190 is handled inside ASSIST as a special instruction, using one or00015240 more of the opcodes not already used. If any of these commands00015290 is to be used, equivalent code must be generated. 00015340 c. If multiple assemblies are used, the only way to communicate00015390 among them is to assemble each at some fixed location known to00015440 any of the others which reference it in any way. 00015490 00015540 Regardless of the method used to create the input deck, the entire00015590 object deck must follow the rules below: 00015640 a. The address on the first TXT card must be less than or equal to00015690 all other TXT card addresses received. The object code for this00015740 address is placed starting at the first byte of available memory.00015790 b. The difference between the highest address of received object00015840 code and the lowest address cannot exceed the available storage.00015890 c. The entry point address is either the address from the first END00015940 card specifying one (i.e., not blank), or if no such address is00015990 found, then the address found on the first TXT card. 00016040 d. The user program cannot modify storage beyond the last code00016090 address, so if it requires more work space, it can specify a TXT00016140 card with zero length and a high enough address to reserve space.00016190 Within the limits above, TXT addresses can occur in any order, and00016240 END cards can appear anywhere (including the first card of the deck).00016290 00016340 The user is cautioned to be careful in using the RELOC option with00016390 OBJIN. ASSIST normally computes a relocation factor used to load the00016440 code, which is equal to the lowest actual memory address minus the first00016490 TXT address. After loading the code, if RELOC is used, the relocation00016540 is set to 0, since RELOC-type programs must be run with no execution-00016590 time relocation (so they can reference low-core addresses for instance).00016640 Thus, any deck to be run under RELOC should contain no relocatable-type00016690 address constants of any type, or else should use a START card to create00016740 the same addresses as where the program will be run (which may be hard00016790 to do under general OS-MFT and MVT systems). 00016840 00016890 00016940 , 00016990 ASSIST5-17 00017040 00017090 Messages produced by the ASSIST loader are of the form AL###,00017140 and include the following messages: 00017190 00017240 a. 00017290 *** AL000 - ASSIST LOADER BEGINS LOAD AT xxxxxx ,USABLE CORE ENDS AT00017340 xxxxxx *** 00017390 This message is printed before loading is begun, and gives the00017440 beginning real address at which code can be loaded, and the address of00017490 the first byte beyond the usable area. The entire area mentioned is00017540 filled with character 5's before loading is begun. 00017590 00017640 *** AL100 - LOAD COMPLETED, USER ADDRESSES: LOW xxxxxx ,HIGH xxxxxx ,00017690 ENTRY xxxxxx , RUN-TIME RELOCATION xxxxxx *** 00017740 This message is printed at the end of a successful load. It gives00017790 the low and high addresses in user-relative values (as found in incoming00017840 TXT cards), the entry point address where execution is to begin (again,00017890 in user-relative terms), and the run-time relocation factor. This last00017940 value is used during interpretive execution, and is added to every00017990 program-defined address to obtain an actual address in memory, i.e., as00018040 far as the user program is concerned, it is actually located between the00018090 LOW and HIGH addresses given. If RELOC is used, the relocation factor00018140 will be set to zero, regardless of the relocation factor actually used00018190 to load the program. 00018240 00018290 00018340 The following messages indicate a error in the input deck. Loading00018390 is terminated, and user program execution does not occur. **NOTE** if00018440 either message AL997 or AL998 appears, it will be followed by an XSNAP00018490 labeled 'IMAGE OF INCORRECT OBJECT CARD' , and the offending card00018540 displayed beginning at the first address given by the XSNAP. 00018590  00018640 *** AL996 - NO TXT CARD RECEIVED *** 00018690 The loader encountered an end-of-file indication or ASSIST control00018740 card before finding any TXT cards. 00018790 00018840 *** AL997 - TXT CARD ADDRESS BELOW 1ST TXT CARD *** 00018890 In order to perform relocation from TXT addresses to appropriate00018940 memory addresses, no TXT card can have a lower address than the first00018990 one found. This requirement was not met by the card displayed.00019040 00019090 *** AL998 - TXT CARD ADDRESS EXCEEDED STORAGE *** 00019140 The area described in message AL000 was not sufficiently large to00019190 hold all of the object code, i.e. the address of at least one byte of00019240 code on the offending card was required to be beyond the end of the00019290 available space. 00019340 00019390 *** AL999 - LOAD ABORTED *** 00019440 This message follows any of the other messages to note the00019490 immediate termination of the loading process. 00019540 , 00001000 ASREPLGD-01 00001010 3.0/A 00001020 June 1973 00001030 ASSIST 00001040 ASSEMBLER REPLACEMENT USER'S GUIDE 00001050 00001060 Program&Documentation: John R. Mashey 00001070 Project Supervision : Graham Campbell 00001080 PSU Computer Science Department 00001090 PREFACE 00001100 This manual is the key reference source for the programmer who00001120 uses the replacement facility of ASSIST. This facility allows the00001130 programmer to write and test his own versions of certain program00001140 modules which are part of the ASSIST Assembler. The modules which00001150 are replaceable perform a wide variety of functions, thus allowing for00001160 a number of different course assignments covering important segments00001170 of a running 360 Assembler. Among those replacable are modules for00001180 management of the symbol table, base register table, scanning and00001190 covnversion of various constant types, and evaluation of both self-00001200 defining terms and general expressions. The entire replacement00001210 process can be performed with low overhead, in-core, and batched,00001220 while allowing the user program no possible way to damage the rest of00001230 the ASSIST system. 00001240 00001250 The first part of this manual briefly describes the internal00001260 structure of the ASSIST assembler, and lists the steps in the entire00001270 replacement process. Also included are the overall register and00001280 linkage conventions required of all replacable modules. 00001290 The second section describes the additional debugging facilities00001310 available to the writer of a replacement module. 00001320 The third section shows the deck setup, Job Control Language,00001340 and PARM options needed to make a replacement run. 00001350 The fourth section lists all messages which may be printed by00001370 the ASSIST Replace Monitor during a replacement run. 00001380 00001390 The reader should be familiar with the following manual:00001400 00001410 ASSIST 00001420 INTRODUCTORY ASSEMBLER USER'S MANUAL 00001430 00001440 The above manual gives various information which may be required to00001450 write a program which can be run under ASSIST, and explains the various00001460 messages which may generated (other than Replace Monitor messages).00001470 Note also that this manual is structured similar to the above one.00001480 00001490 For replacement of certain of the modules, it may be necessary to00001500 examine the following manual for additional required information:00001510 00001520 ASSIST SYSTEM 00001530 PROGRAM LOGIC MANUAL 00001540 , 00001550 ASREPLGD-02 00001560 TABLE OF CONTENTS 00001570 PART I. THE ASSIST REPLACEMENT PROCESS.............................. 0300001580 A. OVERVIEW OF THE ASSIST ASSEMBLER................................. 0300001590 B. STEPS IN THE REPLACEMENT PROCESS................................. 0400001600 C. REGISTER AND SUBROUTINE LINKAGE CONVENTIONS...................... 0600001610 00001620 PART II. REPLACE MONITOR DEBUGGING AIDS............................. 0800001630 A. THE RFLAG........................................................ 0800001640 B. THE XREPL INSTRUCTION............................................ 0900001650 00001660 PART III. JOB CONTROL LANGUAGE AND PARM OPTIONS..................... 0900001670 A. JOB CONTROL LANGUAGE FOR REPLACE RUN............................. 0900001680 B. PARM OPTIONS..................................................... 0900001690 00001700 PART IV. REPLACE MONITOR MESSAGES................................... 1000001710 , 00001720 ASREPLGD-03 00001730 00001740 PART I. THE ASSIST REPLACEMENT PROCESS 00001750 00001760 A. OVERVIEW OF THE ASSIST ASSEMBLER 00001770 00001780 The ASSIST Assembler is a section of the entire ASSIST System00001790 which translates a deck of S/360 Assembler Language statements into00001800 object code, in memory. It is made up of approximately 30 control00001810 sections, of which 3 are main control programs. The overall control00001820 program is named MPCON0, which calls the main programs for each of the00001830 two passes in the assembler, and also calls all initialzation and00001840 termination entrypoints for the various other modules in the assembler.00001850 00001860 During the first pass, under control of MOCON1, each card in the00001870 input source deck is read, scanned for label and opcode, and processed00001880 partially according to the type of opcode. Each statement is given a00001890 location counter value during this pass, and some types of statements00001900 are completely processed, such as EQU, START, ORG, etc. Each cardimage00001910 and its associated information is then saved into a large dynamic00001920 workarea, until an END card is encountered. 00001930 00001940 During the second pass, each statement saved in the dynamic area00001950 is retrieved and processed. Several different routines control the00001960 scanning of each statement and production of object code from it. Each00001970 statement's object code, if any, is loaded into memory, and the00001980 statement printed. 00001990 00002000 Approximately half of the modules of the assembler can be replaced00002010 using the ASSIST Replace Monitor. In general, these modules are00002020 those which are fairly low-level routines, which are not required to00002030 have communication with many other modules, and which generally do00002040 not have to be able to examine variables and flags global to the entire00002050 assembler. They definitely are never required to modify storage outside00002060 the limits of their own storage. These characteristics make it00002070 possible for them to be replaced without requiring a great deal of00002080 knowledge of the internal workings of the ASSIST Assembler. 00002090 , 00002100 ASREPLGD-04 00002110 00002120 B. STEPS IN THE REPLACEMENT PROCESS 00002130 00002140 1. The programmer writes one control section which is to be assembled00002150 and used as a replacement for the existing one in ASSIST of the same00002160 name. This control section must have the following characteristics:00002170 a. The CSECT and ENTRY names (if any) must be defined and spelled00002180 exactly as the existing ones. 00002190 b. Certain replacable modules (such as EVALUT), are permitted to00002200 call existing ASSIST modules. Any module so called can be done00002210 so by listing the module name in an EXTRN statement, then00002220 referencing the module name by use of a V-type address constant.00002230 00002240 2. After the user program is assembled and loaded into memory, the00002250 Replace Monitor searches its list of replaceable control sections for00002260 one defined as a csect in the user program. The required entry point00002270 names are found, if possible, in the user program. During this process,00002280 the Replace Monitor modifies certain address constants in the main00002290 control table of the assembler, which will permit it to regain control00002300 every time one of the replaced entry points is called. The messages00002310 labeled AR000, AR001, and AR002 may appear on the listing at this point.00002320 If it cannot find a legally replaceable csect name, the message AR10000002330 is printed, and the replacement process terminated. The latter can also00002340 occur if the user program contains more serious errors than given by the00002350 value of the NERR parameter. 00002360 00002370 3. VArious functions are performed to initialize the user program for00002380 later execution. These include initializing the user RFLAG to the value00002390 given by the RFLAG= option in the PARM field (see PART III). Then,00002400 instead of executing the user program directly, the ASSIST Assembler is00002410 called to process a test deck, which follows the user program.00002420 00002430 4. During the assembly of the test deck, any of the replace program's00002440 entry points may be called. Any such call is intercepted by the Replace00002450 Monitor. Using previously saved information, it supplies the parameter00002460 values to the original ASSIST entry point called, which returns the00002470 correct set of values to be computed by that entry. 00002480 At this point, depending on certain bits in the current value of00002490 the user RFLAG, various debugging information may be printed. This may00002500 include the current cardimage being processed, the values of 5 parameter00002510 registers on entry to the Replace Monitor, and their correct values as00002520 returned by the original ASSIST module. These messages have labels00002530 AR051, AR052, AR054, respectively. 00002540 00002550 5. At this point, a check is made to assure that the entry point00002560 called actually was defined properly by the user. If not, the AR10100002570 message is given, user storage is dumped, and the interception of calls00002580 is terminated. Otherwise, the user registers and counters are prepared,00002590 and the user program executed beginning at the address in his program00002600 given by the called entry point. The user program is not executed00002610 directly, but is interpreted to prevent it from damaging any part of00002620 ASSIST. The user program may thus access storage outside its area, but00002630 may not modify such storage. 00002640 , 00002650 ASREPLGD-05 00002660 00002670 6. The user program is interpreted until it either terminates00002680 normally by returning to the return address supplied to it in R14, or00002690 terminates with some error. 00002700 00002710 7. If the user program terminated normally, the register values it00002720 returned are checked against the ones returned by the original module.00002730 In some cases, the exact register values do not matter, but any value00002740 definitely wrong is noted. If anything is actually wrong, any debug00002750 information not already printed during step 4 is printed now. Then00002760 the values of the user-returned parameter registers are printed (AR058),00002770 followed by a message flagging the incorrect registers (AR059). The00002780 AR058 message may be printed in any case if the appropriate bit in the00002790 current value of the user RFLAG is turned on. Another bit in the RFLAG00002800 is set if an error has occurred. This bit may be tested by the user00002810 program the next time it is called. 00002820 The correct values are placed in the parameter registers, and00002830 control is returned to the program which originally called the replaced00002840 entry point. 00002850 00002860 8. If the user program did not terminate normally, and the error was00002870 a branch out of the user program, it may be the case that the user00002880 program was attempting to call some other original ASSIST module. The00002890 call is checked to see if it is a legitamate one. If so, the parameter00002900 registers may be printed (AR050), and then checked to make sure they00002910 contain legal values. If they are illegal for any reason, they are00002920 flagged with message AR059, the user program is dumped, and no further00002930 calls are made to user entry points. If the call is legal, the desired00002940 routine is called, and its parameter values placed in the user's00002950 registers, and step 6 is begun once more. 00002960 00002970 9. Finally, the assembly of the test program is completed, with all00002980 calls having been made to the appropriate entry points of the user00002990 replacement program. Messages AR003 and AR004 are then printed, giving00003000 various statistics about the performace of the user program. These00003010 include the number of times each entry point was called, the total00003020 number of instructions executed by each entry, the number of times the00003030 values returned by the user program were incorrect, the average number00003040 of instructions executed per call, and the percent of the calls which00003050 were handled incorrectly. 00003060 00003070 10. If the option BATCH was specified, control returns to step 1,00003080 thus allowing different modules to be tested during one run. Otherwise,00003090 ASSIST execution terminates. 00003100 , 00003110 ASREPLGD-06 00003120 00003130 C. REGISTER AND SUBROUTINE LINKAGE CONVENTIONS 00003140 00003150 1. REGISTER USAGE 00003160 The general purpose registers are referred to by two separate sets00003170 of symbols. The first is a set of absolute register equates, the00003180 symbols R0-R15 being used for registers 0-15. In addition, a second set00003190 exists which has more mnemonic meaning. The user is urged to utilize00003200 only symbolic registers in his program, and should thus include any of00003210 the required EQU instructions in his program. In particular, registers00003220 7-11 should be coded using the symbols RA-RE. The additonal symbolic00003230 register equates are as follows: 00003240 00003250 RW EQU R3 GENERAL WORK REGISTER 1 00003260 RX EQU R4 GENERAL WORK REGISTER 2 00003270 RY EQU R6 GENERAL WORK REGISTER 3 00003280 RZ EQU R6 GENERAL WORK REGISTER 4 00003290 00003300 RA EQU R7 PARAMETER REGISTER 1 00003310 This register is commonly used as a scan pointer register 00003320 inside the assembler. 00003330 RB EQU R8 PARAMETER REGISTER 2 00003340 This register is commonly used to pass a control value to 00003350 a subroutine, and on return, almost always contains either 00003360 an error code, or a zero to show no errors. 00003370 RC EQU R9 PARAMETER REGISTER 3 00003380 This register is most often used in the assembler for passing 00003390 a 24-bit value (such as the result of an expression or a 00003400 self-defining term). 00003410 RD EQU R10 PARAMETER REGISTER 4 00003420 RE EQU R11 PARAMETER REGISTER 5 00003430 Registers RD and RE may be used for subroutines needing more 00003440 than two or three arguments, but are more commonly used as 00003450 work temporary work registers. 00003460 00003470 RAT EQU R12 ASSEMBLER TABLE POINTER-READ ONLY 00003480 This register points the main assembler table (VWXTABL csect, 00003490 AVWXTABL dsect) during an assembly. No subroutine in the 00003500 assembler may modify this register. 00003510 RSA EQU R13 SAVE AREA POINTER/BASE REG FOR SOME 00003520 This register is used to point to an OS/360 save area, for 00003530 any subroutine which may call another. Almost all subroutines00003540 use this as a base register if they are not lowest-level 00003550 routines. 00003560 RET EQU R14 RETURN ADDRESS USED IN CALLS 00003570 This is used in subroutine linkage for the return address to 00003580 a calling program. This symbol is generally used whenever 00003590 subroutine linkage is being set up, while R14 is used when the00003600 register is being used as a temporary work register. 00003610 REP EQU R15 ENTRY POINT ADDRESS/OFTEN USED BASE 00003620 This register is used to hold the entry point address for all 00003630 subroutines in the assembler. Lowest-level routines usually 00003640 use this as a base register. In other routines, this may be 00003650 used as a local work register, in which case the symbol R15 00003660 is normally coded. 00003670 , 00003680 ASREPLGD-07 00003690 00003700 00003710 2. LINKAGE CONVENTIONS - THE ASSEMBLER 00003720 00003730 The linkage conventions inside the ASSIST assembler consist of00003740 a few modifications to the standard OS/360 linkage conventions, which00003750 have been changed mainly to save time and space. The differences are00003760 as follows: 00003770 00003780 a. Registers R0-R6 (or R0-R2, RW-RZ) are protected across any00003790 calling sequence and must be restored if changed. R14 (RET) must also00003800 be restored if changed before returning. 00003810 00003820 b.Register R12(RAT) may not be changed by any routine. 00003830 00003840 c. Registers R7-R11 (RA-RE) are used for parameters and temporary00003850 work registers, and are not protected at all across calls. No routine00003860 ever requires more than five arguments, so these five registers are00003870 sufficient. 00003880 00003890 d. Except for the above, all normal OS/360 conventions are followed00003900 regarding save area linkage requirements and usage. In general, most00003910 routine only save as many registers as required. Lowest-level routines00003920 use R15 as a base, and do not perfrom save area linkage, other routines00003930 usually use R13 as a base and save area pointer. 00003940 00003950 e. For replacement runs, the user must include any needed EQU00003960 symbols for registers. Note that all documentation and output produced00003970 by the Replace Monitor refers to registers 7-11 as RA-RE, so that00003980 using these symbols in a replacement program will aid reading the00003990 various diagnostic output produced. 00004000 , 00004010 ASREPLGD-08 00004020 00004030 PART II. REPLACE MONITOR DEBUGGING AIDS 00004040 00004050 A. THE RFLAG 00004060 Communication between the user program and the Replace Monitor00004070 is achieved through the use of the User Replace Flag, called the RFLAG.00004080 This is a two-byte area of storage which may initialized for an entire00004090 run using the RFLAG= option in the PARM field. Certain bits in it00004100 determine which diagnostic messages the Replace Monitor prints when00004110 it intercepts a call to a replaced module. These bits can also be00004120 changed by the user program during execution, thus allowing the user00004130 to obtain additional information when needed. The various bits of the00004140 RFLAG are used as described in the table below. 00004150 00004160 BYTE BITS DECIMAL BINARY MEANING IF BIT ON (AR### MESSAGE)00004170 ------------------------------------------------------------------------00004180 0 0-7 currently unused, user can set or test 00004190 for his own purposes. 00004200 1 7 1 00000001 print current statement on entry (AR051)00004210 6 2 00000010 print registers RA-RE on entry (AR052)00004220 5 4 00000100 print correct regs RA-RE, on exit (AR054)00004230 from original ASSIST module 00004240 4 8 00001000 print registers RA-RE on exit from (AR058)00004250 user replacement module 00004260 3 16 00010000 print registers RA-RE if user (AR050)00004270 module calls an original ASSIST module. 00004280 1,2 64,32 01100000 reserved for future use 00004290 0 128 10000000 is set to 1 when there is an error (AR059)00004300 parameter registers returned by the user 00004310 program. Is set to 0 if acceptable. 00004320 ------------------------------------------------------------------------00004330 Bit 0 of byte 1 can be used to start extra debugging output only00004350 after an error occurs. See the XREPL example for this action.00004360 The entire first byte is reserved for the user program, such as for00004370 additional debugging flag bits for controling the program. 00004380 Note that bits 5,6,7 are tested before the call to the user00004390 program. Thus, changing them affects output beginning at the next00004400 call to a user module. 00004410 00004420 B. THE XREPL INSTRUCTION 00004430 The XREPL instruction is an SI format instruction, in which the00004440 immediate field is used to specify a type of action. It is coded as00004450 XREPL ADDR,CODE with CODE meaning as follows: 00004460 00004470 0 set the RFLAG from the 2-byte area specified by ADDR. 00004480 1 fetch the RFLAG into the 2-byte area specified by ADDR. 00004490 2 fetch the number of instructions left into the 4-byte area given by00004500 ADDR. This value is decremented each time an instruction is done.00004510 00004520 The following gives an example of the use of XREPL: 00004530 XREPL MYRFLAG,1 get the value of the RFLAG 00004540 TM MYRFLAG+1,128 was there an error last time 00004550 BZ *+12 no, don't reset it 00004560 OI MYRFLAG+1,8+4+2+1 set all these for debug output 00004570 XREPL MYRFLAG,0 reset the RFLAG to new setting 00004580 , 00004590 ASREPLGD-09 00004600 00004610 PART III. JOB CONTROL LANGUAGE AND PARM OPTIONS 00004620 00004630 A. JOB CONTROL LANGUAGE 00004640 The deck setup for a single-job replacement run is as follows: 00004650 // a JOB CARD 00004670 // EXEC ASACG,PARM='REPL,other options if any' 00004680 //SYSIN DD * 00004690 .....user-written replacement program..... 00004700 END , end card of replacement program 00004710 ..... user test deck for his replacement program..... 00004720 /* 00004730 00004732 The deck setup for a replace program run under BATCH is: 00004734 $JOB ASSIST ACCT#,REPL,other options, if any 00004736 ..... user-written replacement program 00004738 $ENTRY (required to initiate test) 00004740 ..... user test deck for replacement program 00004742 $ENTRY (optional, if user wants assembled test 00004744 program to execute also - unlikely) 00004746 00004748 B. PARM OPTIONS 00004750 The following PARM field options are of particular interest to00004760 the user of the replacement facility. (see PART III. of USER'S GUIDE). 00004770 00004780 REPL required if the run is to be a replacement run rather than00004790 just a normal assembly and execution. 00004800 00004810 RFLAG=number coded to initialize the value of the RFLAG for the entire00004820 run. The default value is 0. 00004830 00004840 BATCH may be coded if the user wants to test more than one module,00004850 or more than one version of the same module in the same run. 00004860 00004890 I=number the instruction count limit specified applies to each call of00004900 a replacement module. It is therefore recommended that this 00004910 optional operand be coded, and that its value be fairly small.00004920 , 00004930 ASREPLGD-10 00004940 00004950 PART IV. REPLACE MONITOR MESSAGES 00004960 00004970 The following lists the messages which may be produced during a00004980 replace run by the Replace Monitor. Note that all these messages are00004990 printed inline with output produced by other sections of ASSIST. In00005000 particular, Replace Monitor output is embedded in the listing of the00005010 user test program, which can possibly make it difficult to read in some00005020 cases. A helpful procedure is to run the test program by itself under00005030 ASSIST, thus obtaining a listing, then insert a PRINT OFF command at00005040 the beginning. This will remove most of he test program listing.00005050 All Replace Monitor messages are of the form ///AR### message.00005060 The type of message is indicated by the value of ###, as follows:00005070 00005080 000-049 - informative or warning messages. 00005090 050-099 - debugging output messages,produced during intercepted call.00005100 100-199 - severe error message, causing replacement interception to end.00005110 00005120 AR000 REPLACE CSECT: name /// 00005130 This message appears immediately after the replace csect has been00005140 assembled, with name being the name of the replacing csect.00005150 00005160 AR001 REPLACE ENTRY: name AT LOCATION: xxxxxx /// 00005170 If message AR000 appears, each properly defined entry point in the00005180 csect will be listed here with its location xxxxxx in memory. Note00005190 that a csect which can be entered through its csect name is also00005200 listed. 00005210 00005220 AR002 REPLACE ENTRY: name NOT FOUND AS CSECT OR ENTRY /// 00005230 This message may appear with the AR000 and AR001 messages for any00005240 entry or csect name which is required, but either not defined in00005250 the user program or not declared as CSECT or ENTRY. If this entry00005260 name is called during execution, its execution will be terminated00005270 with an AR101 message and storage dump. 00005280 00005290 AR003 STATISTICS: # INSTRUCTIONS # CALLS # WRONG INSTRS/CALL %WRONG00005300 This message appears after the test program is assembled.00005310 00005320 AR004 name : 5 decimal numbers 00005330 One of this message appears for each entry point after AR003. It00005340 describes the performance of the named entry point during the run.00005350 00005360 AR050 ON CALL TO name REGISTERS RA-RE (values of regs 7-11)00005370 This message may be printed if the RFLAG byte 1 bit 3 is set and00005380 the user program calls some other ASSIST module. It may also be00005390 printed if the user program tries to pass illegal parameter values00005400 to the routine name. 00005410 , 00005420 ASREPLGD-11 00005430 00005440 00005450 AR051 ON ENTRY TO name STMT ADDR: xxxxxx -> cardimage 00005460 This message is printed before calling the user program, and shows00005470 the current statement being processed, if any. The address of the00005480 cardimage is given by xxxxxx, which corresponds to the first00005490 character following the '>' in the message. The message is00005500 if RFLAG byte 1 bit 7 is set before the call, or if an error00005510 occurs in the user program. 00005520 00005530 AR052 ON ENTRY TO name REGISTERS RA-RE: (values of 5 registers)00005540 This message displays the 5 parameter registers before the user00005550 program name is called, and is printed if RFLAG byte 1 bit 6 is00005560 on before the user program is called, or if there is an error.00005570 00005580 AR054 ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)00005590 This message shows the correct values of the parameter registers00005600 as returned by the original ASSIST module name. It is printed00005610 if RFLAG byte 1 bit 5 is on before call to the module, or if the00005620 user program makes an error. 00005630 00005640 AR058 ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)00005650 If RFLAG byte 1 bit 4 is on after completion of the user program,00005660 or if there is an error, this message appears, and gives the values00005670 of the parameter registers as returned by the user entry name.00005680 00005690 AR059 WARNING: ERROR IN USER REGS: error list 00005700 If any of the user registers has an incorrect value, this message00005710 is printed, either following AR050 or AR058, depending on whether00005720 the incorrect value(s) were in a call to another module or in a00005730 return of values to the calling program. 00005740 The error list consists of one or more of the following: 00005750 R0-R6 when a user program returned, the values in registers00005760 0-6 were not all the same as when it was called. 00005770 R12 the user program modified the value of the assembler00005780 table pointer, which is not permitted. 00005790 R13 the user did not restore the save area pointer.00005800 $$$$$$$$ The dollar signs indicate a register shown in messages00005810 AR050 or AR058 as incorrect. 00005820 If this message appears, RFLAG byte 1 bit 0 is set to 1 for the00005830 next time the user program is called. 00005840 00005850 AR100 REPLACE CSECT NOT FOUND - REPLACE ABORT /// 00005860 This message appears immediately after the assembly of the user00005870 program. None of the allowable csect names were found as a csect00005880 in the user program. 00005890 00005900 AR101 INVALID ENTRYPOINT NAME: name CALLED. REPLACE ACTION ABORTED ///00005910 If name appeared in an AR002 message and is called, this message00005920 appears, followed by a dump of user storage and the last values of00005930 the user registers. 00005940 00005950 AR102 USER PROGRAM ABENDED DURING REPLACEMENT /// 00005960 Replace action is aborted and a dump given. 00005970