The first part of this manual briefly describes the internal structure of the ASSIST assembler, and lists the steps in the entire replacement process. Also included are the overall register and linkage conventions required of all replacable modules.
The second section describes the additional debugging facilities available to the writer of a replacement module.
The third section shows the deck setup, Job Control Language, and PARM options needed to make a replacement run.
The fourth section lists all messages which may be printed by the ASSIST Replace Monitor during a replacement run.
The reader should be familiar with the following manual:
For replacement of certain of the modules, it may be necessary to examine the following manual for additional required information:
PART II. REPLACE MONITOR DEBUGGING AIDS
A. THE RFLAG
B. THE XREPL INSTRUCTION
PART III. JOB CONTROL LANGUAGE AND PARM OPTIONS
A. JOB CONTROL LANGUAGE FOR REPLACE RUN
B. PARM OPTIONS
PART IV. REPLACE MONITOR MESSAGES
The ASSIST Assembler is a section of the entire ASSIST System which translates a deck of S/360 Assembler Language statements into object code, in memory. It is made up of approximately 30 control sections, of which 3 are main control programs. The overall control program is named MPCON0, which calls the main programs for each of the two passes in the assembler, and also calls all initialzation and termination entrypoints for the various other modules in the assembler.
During the first pass, under control of MOCON1, each card in the input source deck is read, scanned for label and opcode, and processed partially according to the type of opcode. Each statement is given a location counter value during this pass, and some types of statements are completely processed, such as EQU, START, ORG, etc. Each cardimage and its associated information is then saved into a large dynamic workarea, until an END card is encountered.
During the second pass, each statement saved in the dynamic area is retrieved and processed. Several different routines control the scanning of each statement and production of object code from it. Each statement's object code, if any, is loaded into memory, and the statement printed.
Approximately half of the modules of the assembler can be replaced using the ASSIST Replace Monitor. In general, these modules are those which are fairly low-level routines, which are not required to have communication with many other modules, and which generally do not have to be able to examine variables and flags global to the entire assembler. They definitely are never required to modify storage outside the limits of their own storage. These characteristics make it possible for them to be replaced without requiring a great deal of knowledge of the internal workings of the ASSIST Assembler.
At this point, depending on certain bits in the current value of the user RFLAG, various debugging information may be printed. This may include the current cardimage being processed, the values of 5 parameter registers on entry to the Replace Monitor, and their correct values as returned by the original ASSIST module. These messages have labels AR051, AR052, AR054, respectively.
The correct values are placed in the parameter registers, and control is returned to the program which originally called the replaced entry point.
RW EQU R3 GENERAL WORK REGISTER 1 RX EQU R4 GENERAL WORK REGISTER 2 RY EQU R6 GENERAL WORK REGISTER 3 RZ EQU R6 GENERAL WORK REGISTER 4 RA EQU R7 PARAMETER REGISTER 1 This register is commonly used as a scan pointer register inside the assembler. RB EQU R8 PARAMETER REGISTER 2 This register is commonly used to pass a control value to a subroutine, and on return, almost always contains either an error code, or a zero to show no errors. RC EQU R9 PARAMETER REGISTER 3 This register is most often used in the assembler for passing a 24-bit value (such as the result of an expression or a self-defining term). RD EQU R10 PARAMETER REGISTER 4 RE EQU R11 PARAMETER REGISTER 5 Registers RD and RE may be used for subroutines needing more than two or three arguments, but are more commonly used as work temporary work registers. RAT EQU R12 ASSEMBLER TABLE POINTER-READ ONLY This register points the main assembler table (VWXTABL csect, AVWXTABL dsect) during an assembly. No subroutine in the assembler may modify this register. RSA EQU R13 SAVE AREA POINTER/BASE REG FOR SOME This register is used to point to an OS/360 save area, for any subroutine which may call another. Almost all subroutines use this as a base register if they are not lowest-level routines. RET EQU R14 RETURN ADDRESS USED IN CALLS This is used in subroutine linkage for the return address to a calling program. This symbol is generally used whenever subroutine linkage is being set up, while R14 is used when the register is being used as a temporary work register. REP EQU R15 ENTRY POINT ADDRESS/OFTEN USED BASE This register is used to hold the entry point address for all subroutines in the assembler. Lowest-level routines usually use this as a base register. In other routines, this may be used as a local work register, in which case the symbol R15 is normally coded.
BYTE BITS DECIMAL BINARY MEANING IF BIT ON (AR### MESSAGE) ------------------------------------------------------------------------ 0 0-7 currently unused, user can set or test for his own purposes. 1 7 1 00000001 print current statement on entry (AR051) 6 2 00000010 print registers RA-RE on entry (AR052) 5 4 00000100 print correct regs RA-RE, on exit (AR054) from original ASSIST module 4 8 00001000 print registers RA-RE on exit from (AR058) user replacement module 3 16 00010000 print registers RA-RE if user (AR050) module calls an original ASSIST module. 1,2 64,32 01100000 reserved for future use 0 128 10000000 is set to 1 when there is an error (AR059) parameter registers returned by the user program. Is set to 0 if acceptable. ------------------------------------------------------------------------Bit 0 of byte 1 can be used to start extra debugging output only after an error occurs. See the XREPL example for this action.
The entire first byte is reserved for the user program, such as for additional debugging flag bits for controling the program.
Note that bits 5,6,7 are tested before the call to the user program. Thus, changing them affects output beginning at the next call to a user module.
XREPL ADDR,CODEwith CODE meaning as follows:
0 set the RFLAG from the 2-byte area specified by ADDR. 1 fetch the RFLAG into the 2-byte area specified by ADDR. 2 fetch the number of instructions left into the 4-byte area given by ADDR. This value is decremented each time an instruction is done.The following gives an example of the use of XREPL:
XREPL MYRFLAG,1 get the value of the RFLAG TM MYRFLAG+1,128 was there an error last time BZ *+12 no, don't reset it OI MYRFLAG+1,8+4+2+1 set all these for debug output XREPL MYRFLAG,0 reset the RFLAG to new setting
// a JOB CARD // EXEC ASACG,PARM='REPL,other options if any' //SYSIN DD * .....user-written replacement program..... END 1 end card of replacement program ..... user test deck for his replacement program..... /*The deck setup for a replace program run under BATCH is:
$JOB ASSIST ACCT#,REPL,other options, if any ..... user-written replacement program $ENTRY (required to initiate test) ..... user test deck for replacement program $ENTRY (optional, if user wants assembled test program to execute also - unlikely)
REPL required if the run is to be a replacement run rather than just a normal assembly and execution. RFLAG=number coded to initialize the value of the RFLAG for the entire run. The default value is 0. BATCH may be coded if the user wants to test more than one module, or more than one version of the same module in the same run. I=number the instruction count limit specified applies to each call of a replacement module. It is therefore recommended that this optional operand be coded, and that its value be fairly small.
All Replace Monitor messages are of the form ///AR### message. The type of message is indicated by the value of ###, as follows:
000-049 - informative or warning messages.
050-099 - debugging output messages,produced during intercepted call.
100-199 - severe error message, causing replacement interception to end.
|AR000|| REPLACE CSECT: name ///|
This message appears immediately after the replace csect has been assembled, with name being the name of the replacing csect.
|AR001||REPLACE ENTRY: name AT LOCATION: xxxxxx ///|
If message AR000 appears, each properly defined entry point in the csect will be listed here with its location xxxxxx in memory. Note that a csect which can be entered through its csect name is also listed.
|AR002||REPLACE ENTRY: name NOT FOUND AS CSECT OR ENTRY ///|
This message may appear with the AR000 and AR001 messages for any entry or csect name which is required, but either not defined in the user program or not declared as CSECT or ENTRY. If this entry name is called during execution, its execution will be terminated with an AR101 message and storage dump.
|AR003||STATISTICS: # INSTRUCTIONS # CALLS # WRONG INSTRS/CALL %WRONG|
This message appears after the test program is assembled.
|AR004|| name : 5 decimal numbers|
One of this message appears for each entry point after AR003. It describes the performance of the named entry point during the run.
|AR050||ON CALL TO name REGISTERS RA-RE (values of regs 7-11)|
This message may be printed if the RFLAG byte 1 bit 3 is set and the user program calls some other ASSIST module. It may also be printed if the user program tries to pass illegal parameter values to the routine name.
|AR051||ON ENTRY TO name STMT ADDR: xxxxxx -> cardimage|
This message is printed before calling the user program, and shows the current statement being processed, if any. The address of the cardimage is given by xxxxxx, which corresponds to the first character following the '>' in the message. The message is if RFLAG byte 1 bit 7 is set before the call, or if an error occurs in the user program.
|AR052||ON ENTRY TO name REGISTERS RA-RE: (values of 5 registers)|
This message displays the 5 parameter registers before the user program name is called, and is printed if RFLAG byte 1 bit 6 is on before the user program is called, or if there is an error.
|AR054||ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)|
This message shows the correct values of the parameter registers as returned by the original ASSIST module name. It is printed if RFLAG byte 1 bit 5 is on before call to the module, or if the user program makes an error.
|AR058||ON EXIT FROM name REGISTERS RA-RE: (values of 5 registers)|
If RFLAG byte 1 bit 4 is on after completion of the user program, or if there is an error, this message appears, and gives the values of the parameter registers as returned by the user entry name.
|AR059||WARNING: ERROR IN USER REGS: error list|
If any of the user registers has an incorrect value, this message is printed, either following AR050 or AR058, depending on whether the incorrect value(s) were in a call to another module or in a return of values to the calling program.
The error list consists of one or more of the following:
R0-R6 when a user program returned, the values in registers 0-6 were not all the same as when it was called. R12 the user program modified the value of the assembler table pointer, which is not permitted. R13 the user did not restore the save area pointer. $$$$$$$$ The dollar signs indicate a register shown in messages AR050 or AR058 as incorrect.If this message appears, RFLAG byte 1 bit 0 is set to 1 for the next time the user program is called.
|AR100||REPLACE CSECT NOT FOUND - REPLACE ABORT ///|
This message appears immediately after the assembly of the user program. None of the allowable csect names were found as a csect in the user program.
|AR101||INVALID ENTRYPOINT NAME: name CALLED. REPLACE ACTION ABORTED ///|
If name appeared in an AR002 message and is called, this message appears, followed by a dump of user storage and the last values of the user registers.
|AR102||USER PROGRAM ABENDED DURING REPLACEMENT ///|
Replace action is aborted and a dump given.