Trailing-Edge
-
PDP-10 Archives
-
ap-c796e-sb
-
maklib.rnm
There are no other files named maklib.rnm in the archive.
.SPACING 1;.FLAG CAP.LC.LEFT MARGIN 1;.RIGHT MARGIN 71;
.SKIP 2
.CENTER;^&<MAKLIB ^USER'S ^GUIDE \&^V1.0
.SKIP 2
.LS
.LE;^INTRODUCTION
.B;<MAKLIB IS A PROGRAM USED TO MANIPULATE RELOCATABLE BINARY FILES
WHICH ARE EITHER SINGLE PROGRAMS OR COLLECTIONS OF PROGRAMS (LIBRARIES).
^THE RELOCATABLE BINARY FILE IS THE MACHINE READABLE OUTPUT FROM A
SOURCE LANGUAGE TRANSLATOR, SUCH AS THE <FORTRAN COMPILER
OR THE <MACRO ASSEMBLER.
<MAKLIB IS USED TO MANIPULATE THE INDIVIDUAL MODULES WITHIN A LIBRARY,
TO EXAMINE INDIVIDUAL MODULES AND LIBRARIES AND TO MAKE CHANGES TO
MODULES WHEN THEY NEED CORRECTION. <MAKLIB CAN ALSO BE USED TO
CREATE LIBRARIES BY DELETING UNNECESSARY SYMBOLS AND BY ADDING
AN INDEX, WHICH SPEEDS UP LOADING BY <LINK-10.
.LE;^COMMAND ^STRING ^FORMAT
.B;^THE <MAKLIB PROGRAM USES THE TRADITIONAL <DECSYSTEM-10 COMMAND
STRING, SUPPORTED BY USE OF THE COMMON <SCAN AND <WILD ROUTINES.
^IN ITS MOST GENERAL FORMAT, THE COMMAND STRING IS:
.B.I 5;^^OUTFILE = INFILE1/S\\WITCH/^SWITCH.., ^^INFILE2/S\\WITCH/^SWITCH..
.B;^ALL <MAKLIB COMMANDS REQUIRE AT LEAST THE OUTPUT FILE AND THE
FIRST INPUT FILE. ^THIS FIRST INPUT FILE IS CALLED THE <MASTER FILE.
^IF A SECOND INPUT FILE IS USED BY A COMMAND, THIS FILE IS CALLED THE
<TRANSACTION FILE. ^SOME COMMAND SWITCHES DO NOT REQUIRE A <TRANSACTION
FILE, PARTICULARLY THOSE THAT QUERY THE STATUS OF THE <MASTER
FILE.
^THE STANDARD <SCAN SUPPLIED SWITCHES AND FEATURES ARE SUPPORTED,
INCLUDING INDIRECT COMMAND FILES AND THE USE OF <SWITCH.INI TO
INITIALIZE THE COMMAND STRING. ^ALL SWITCHES CAN BE ABBREVIATED TO UNIQUENESS, AND COMMENTS
ARE INCLUDED IN THE COMMAND LINE BE PRECEDING THEM WITH ";" OR "!".
.LE;^COMMAND ^SWITCHES ^THAT ^GIVE ^INFORMATION ^ABOUT THE <MASTER ^FILE.
.B;.I 5;^THE INFORMATION COMMANDS YIELD DATA ON THE STATUS
AND CONTENTS OF THE FILE SPECIFIED AS THE <MASTER FILE. ^NO
<TRANSACTION FILE IS SPECIFIED WITH THESE COMMAND SWITCHES
AND THEY TAKE NO ARGUMENTS. ^THE OUTPUT FILE IS AN <ASCII FILE WITH THE
DEFAULT EXTENSION <.LST. ^THE <MASTER FILE
HAS THE DEFAULT EXTENSION <.REL.
.LS
.LE;<LIST - ^THIS COMMAND SWITCH IS USED TO LIST THE NAMES
OF THE MODULES THAT ARE IN THE <MASTER FILE.
.B;<EXAMPLE:
.B.I 5;^^OUT.LST=MASTER.REL/LIST\\
.LE;<POINTS - ^THIS COMMAND SWITCH LISTS ALL THE <ENTRY POINTS
IN THE SPECIFIED <MASTER FILE. <ENTRY POINTS ARE USED BY <LINK-10
TO DETERMINE IF A <GLOBAL REQUEST CAN BE SATISFIED BY LOADING
A MODULE FROM A LIBRARY. ^THE <ENTRY POINTS ARE USUALLY SUBROUTINE
STARTING ADDRESSES.
.B;<EXAMPLE:
.B.I 5;^^OUT.LST=MASTER.REL/POINTS\\
.LE;<TRACE - ^THIS COMMAND LISTS ALL THE INFORMATION CONTAINED IN
THE <TRACE BLOCKS IN THE SPECIFIED <MASTER FILE. ^THESE
BLOCKS (^LINK ITEM TYPE 1060) ARE CREATED BY <MAKLIB WHEN
THE <FIX COMMAND IS USED TO INSERT EDITS INTO A MODULE IN THE FILE. ^THE <TRACE
BLOCKS CONTAIN INFORMATION ABOUT WHICH EDITS ARE INSTALLED AND EXACTLY
WHAT CHANGES
WERE MADE TO THE FILE. ^BY USE OF THE <TRACE COMMAND, THE EXACT BINARY
PATCHING STATUS OF THE <MASTER FILE CAN BE ASCERTAINED.
.B;<EXAMPLE:
.B.I 5;^^OUT.LST=MASTER.REL/TRACE\\
.ELS
.LE;^COMMANDS ^USED TO ^CREATE ^LIBRARY ^FILES.
.B;.I 5;^THESE TWO SWITCHES ARE USED PRIMARILY TO CREATE LIBRARIES
OF SUBROUTINES WHICH ARE LOADED WHEN A MAIN ROUTINE REQUESTS THEM. ^AN
EXAMPLE OF SUCH A LIBRARY IS <FORLIB.REL WHICH CONTAINS THE VARIOUS
UTILITY ROUTINES USED BY PROGRAMS COMPILED BY THE <FORTRAN COMPILER.
^IF A PROGRAM REQUIRES A ROUTINE FOR A SPECIFIC FUNCTION,
IT MAKES A <GLOBAL REQUEST INDICATING THIS. ^AT LOAD TIME, <LINK-10
SEARCHES A SET OF USER-SPECIFIED AND/OR DEFAULT LIBRARIES LOOKING FOR
ROUTINES TO SATISFY THE <GLOBAL REQUESTS.
^A LIBRARY CAN BE SIMPLY A SET OF ROUTINES CONCATENATED INTO A
SINGLE PHYSICAL FILE, HOWEVER THE USE OF THE FOLLOWING TWO COMMANDS
GREATLY SPEEDS UP THE SEARCHING OF LIBRARIES. ^THE COMMAND SWITCHES ARE USED ON THE <MASTER FILE SPECIFICATION
AND THERE IS NO <TRANSACTION FILE. ^NEITHER COMMAND
TAKES AN ARGUMENT AND BOTH CAN BE SPECIFIED IN A SINGLE COMMAND STRING.
^THE DEFAULT EXTENSION FOR BOTH THE <OUTPUT
AND THE <MASTER FILE SPECIFICATION IS <.REL.
.LS
.LE;<INDEX - ^THIS COMMAND READS THE <MASTER FILE AND PRODUCES AN
<OUTPUT FILE WHICH IS IDENTICAL TO THE <MASTER FILE EXCEPT THAT <INDEX
BLOCKS ARE INSERTED DIRECTLY IN FRONT OF THE FIRST MODULE IN THE FILE.
^THE <INDEX BLOCKS (^LINK ITEM TYPE 14) PROVIDE A FAST WAY
FOR <LINK-10 TO FIND OUT WHAT <ENTRY POINTS ARE CONTAINED
IN THE FILE, AND WHERE THEY ARE IN THE FILE. <LINK CAN THEN
MAKE SEARCHES MORE QUICKLY, WITHOUT HAVING TO READ THE ENTIRE FILE, AND
IF A MODULE THAT IS NEEDED IS IN THE FILE, <LINK KNOWS WHERE IT CAN
BE FOUND. ^THIS SPEEDS UP LOADING BY REDUCING THE AMOUNT OF <I/O
NECESSARY.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MASTER.REL/INDEX\\
.LE;<NOLOCALS - ^THIS COMMAND SWITCH CAUSES AN OUTPUT FILE TO BE
CREATED, IDENTICAL TO THE <MASTER FILE EXCEPT THAT ALL <LOCAL
SYMBOLS ARE DELETED FROM THE <SYMBOL BLOCKS (^LINK ITEM TYPE 2).
^THESE <LOCAL SYMBOLS ARE USED PRIMARILY FOR DEBUGGING PURPOSES AND
BY THE <FIX COMMAND IN <MAKLIB. ^SINCE THEY SERVE NO PURPOSE IN
A PRODUCTION-MODE LIBRARY, THEY ARE OFTEN DELETED TO REDUCE THE AMOUNT
OF MASS STORAGE SPACE THE LIBRARY OCCUPIES. ^THE DELETION OF <LOCAL
SYMBOLS ALSO SPEEDS UP LOADING BECAUSE LESS <I/O HAS TO BE DONE.
<GLOBAL SYMBOLS ARE LEFT IN THE SYMBOL TABLE, SINCE THEY ARE NEEDED FOR
INTER-LINKING OF MODULES.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MASTER.REL/NOLOCALS\\
.ELS
.NOTE; ^THE OLD <FUDGE2 PROGRAM, WHICH <MAKLIB SUPERCEDES, DELETED
<LOCAL SYMBOLS WHENEVER AN <INDEX WAS CREATED. <MAKLIB DOES NOT
DO THIS. ^TO PRODUCE AN INDEXED LIBRARY WITHOUT <LOCAL SYMBOLS
THE TWO COMMAND SWITCHES ARE GIVEN TOGETHER:
.B.I 5;^^OUT.REL=MASTER.REL/INDEX/NOLOCALS\\
.END NOTE
.LE;^COMMANDS TO ^MANIPULATE ^LIBRARY ^MODULES
.B.I 5;^TO FACILITATE THE HANDLING AND CREATION OF PROGRAM LIBRARIES,
<MAKLIB INCLUDES COMMAND SWITCHES THAT MANIPULATE INDIVIDUAL
ROUTINES IN A COLLECTION OF ROUTINES. ^MOST OF
THESE COMMANDS REQUIRE THE SPECIFICATION OF A <TRANSACTION FILE , ALONG
WITH THE <OUTPUT AND THE <MASTER FILES. ^THE DEFAULT EXTENSION FOR ALL THREE FILES IS <.REL.
^THESE COMMAND SWITCHES TAKE ARGUMENTS, WHICH ARE THE NAMES OF THE MODULES THAT ARE TO
BE AFFECTED BY THE SWITCH.
.LS
.LE;<MASTER:(<^MOD1,^MOD2..) - ^THIS SWITCH CAUSES NO MANIPULATION
OF THE FILE. ^ITS PURPOSE IS TO SET UP A CORRESPONDENCE BETWEEN MODULES
IN THE <MASTER FILE AND THOSE THAT ARE SPECIFIED IN SOME COMMAND SWITCH
WHICH IS SPECIFIED FOR THE <TRANSACTION FILE. ^AN EXAMPLE IS THE
<REPLACE SWITCH. ^THE <REPLACE SWITCH IS GIVEN AS PART OF THE <TRANSACTION
FILE SPECIFICATION AND THE ARGUMENTS TO THIS SWITCH ARE NAMES OF MODULES
WHICH ARE TO REPLACE THOSE SPECIFIED AS ARGUMENTS TO THE <MASTER
SWITCH IN THE <MASTER FILE SPECIFICATION.
^THE <MASTER SWITCH IS ALWAYS GIVEN AS PART OF THE <MASTER FILE SPECIFICATION , TAKES AT LEAST
ONE ARGUMENT AND REQUIRES THAT ANOTHER COMMAND BE GIVEN
IN THE SAME COMMAND STRING.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MASTER.REL/MASTER:M\O\D1, TRANS.REL/REPLACE:M\O\D\1\\
.LE;<APPEND:(<^MOD1,^MOD2..) - ^THIS COMMAND SWITCH IS USED TO ADD
NEW ROUTINES TO THE END OF AN EXISTING LIBRARY. ^THE <OUTPUT FILE
IS CREATED BY COPYING THE ENTIRE <MASTER FILE INTO IT, FOLLOWED BY
THE ROUTINES SPECIFIED AS ARGUMENTS TO THE <APPEND SWITCH. ^THE APPENDED
ROUTINES ARE READ FROM THE <TRANSACTION FILE, AND MUST BE IN THE
SAME PHYSICAL ORDER AS SPECIFIED TO THE SWITCH.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL = MASTER.REL, TRANS.REL/APPEND:(M\O\D1,M\O\D2)\\
.LE;<DELETE:(<^MOD1,^MOD2...) - ^THIS COMMAND SWITCH DOES NOT REQUIRE
A <TRANSACTION FILE SPECIFICATION, AND MUST BE GIVEN AS PART OF THE
<MASTER FILE SPECIFICATION. ^THE ACTION TAKEN IS THAT THE ENTIRE <MASTER
FILE IS COPIED TO THE <OUTPUT FILE EXCEPT FOR THE ROUTINES
NAMED AS ARGUMENTS TO THE <DELETE SWITCH. ^THE ARGUMENTS TO THE <DELETE
SWITCH MUST BE NAMES OF MODULES IN THE <MASTER FILE, AND THEY MUST APPEAR
IN THE SAME ORDER AS THE PHYSICAL ORDER OF THE MODULES IN THE FILE.
.B;<EXAMPLE:
.B.I 5;<OUT.REL = <MASTER.REL/DELETE:(^MOD1,^MOD2)
.LE;<EXTRACT:(<^MOD1,^MOD2...) - ^THIS COMMAND CAN BE USED TO
PRODUCE AN <OUTPUT FILE CONTAINING A SUBSET OF THE ROUTINES IN THE
<MASTER FILE. ^THE SWITCH DOES NOT REQUIRE THAT A <TRANSACTION
FILE SPECIFICATION BE GIVEN AS PART OF THE COMMAND STRING. ^THE
MODULES SPECIFIED AS ARGUMENTS TO THE <EXTRACT SWITCH ARE COPIED OUT TO THE <OUTPUT FILE. ^THEY ARE
COPIED OUT IN THE ORDER SPECIFIED, WHICH MUST CORRESPOND TO THEIR
PHYSICAL ORDER IN THE <MASTER FILE.
.B;<EXAMPLE:
.B.I 5;<OUT.REL = <MASTER.REL/EXTRACT:(^MOD1,^MOD2)
.LE;<INSERT:(<^MOD1,^MOD2...) - ^THIS COMMAND IS USED TO INSERT
NEW MODULES INTO THE LIBRARY. ^THIS COMMAND REQUIRES THE USE OF THE
<MASTER SWITCH. ^THE <OUTPUT FILE IS FORMED IN THE FOLLOWING MANNER.
^THE <MASTER FILE IS COPIED TO THE <OUTPUT FILE UP UNTIL THE , BUT
NOT INCLUDING, THE MODULE NAMED AS THE FIRST ARGUMENT TO THE <MASTER SWITCH. ^THEN THE MODULE NAMED AS THE FIRST ARGUMENT TO THE <INSERT SWITCH
IS COPIED FROM THE <TRANSACTION FILE TO THE <OUTPUT FILE. ^THE PROCESS
IS THEN REPEATED, UNTIL THE ARGUMENT LIST SPECIFIED TO THE <MASTER
SWITCH IS EXHAUSTED, AT WHICH POINT THE REMAINING PARTS OF THE <MASTER FILE ARE
COPIED TO THE <OUTPUT FILE. ^THERE MUST OF COURSE BE ONE
ARGUMENT TO THE <MASTER SWITCH FOR EVERY ARGUMENT TO THE <INSERT, AND
VICE VERSA. ^TO INSERT MORE THAN ONE MODULE IN FRONT OF THE
SAME MODULE IN THE <MASTER, THE <MASTER MODULE NAME MUST APPEAR
REPEATEDLY IN THE ARGUMENT LIST.
^THE ORDER OF THE MODULE NAMES IN THE ARGUMENT LISTS OF BOTH
THE <MASTER AND THE <INSERT SWITCHES MUST CORRESPOND TO THE PHYSICAL ORDER
OF THE MODULES IN THE <MASTER AND <TRANSACTION FILES , RESPECTIVELY.
.B;<EXAMPLE:
.B.I 5;<OUT.REL = <MAST.REL/MASTER:^MOD1, <TRANS.REL/INSERT:^MODA
.LE;<REPLACE:(<^MOD1,^MOD2...) - ^THIS COMMAND IS USED TO REPLACE
MODULES IN THE <MASTER FILE WITH THOSE SPECIFIED BY THE <REPLACE
SWITCH. ^THE <OUTPUT FILE THEN IS COMPRISED OF THE ENTIRE <MASTER FILE
WITH SOME MODULES REPLACED BY THOSE READ FROM THE <TRANASCTION FILE.
^USE OF THE <REPLACE SWITCH REQUIRES THE USE OF THE <MASTER SWITCH SO
THAT <MAKLIB KNOWS WHICH <<MASTER MODULES ARE TO BE REPLACED
WITH THOSE SPECIFIED IN THE <REPLACE COMMAND. ^THERE MUST BE A ONE
TO ONE CORRESPONDENCE IN THE NUMBER OF <MASTER ARGUMENTS AND <REPLACE
ARGUMENTS. ^THE ORDER OF BOTH ARGUMENT LISTS MUST ALSO CORRESPOND TO THE
PHYSICAL ORDER OF THE MODULES IN THE RELATED FILES.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MAST.REL/MASTER:M\O\D1,TRANS.REL/REPLACE:M\O\D\\A
.ELS
.LE;^EDITING THE <MASTER FILE
.LS
.LE;<FIX - ^THIS COMMAND INDICATES THAT THE <MASTER FILE IS TO BE CHANGED.
.B.I 5;^THE <FIX COMMAND SWITCH IS USED TO MAKE CHANGES TO THE ACTUAL
CODE AND SYMBOL TABLE OF A ROUTINE OR PROGRAM. ^THE <FIX COMMAND
IS GIVEN AS PART OF THE <TRANSACTION FILE SPECIFICATION, AND THE ONLY
OTHER SWITCH ALLOWED IS THE <WHO SWITCH. ^THE DEFAULT EXTENSION
FOR BOTH THE <OUTPUT AND THE <MASTER FILE IS <.REL WHILE
THE DEFAULT FOR THE <TRANSACTION FILE EXTENSION IS <.FIX.
^THE <FIX SWITCH DOES NOT TAKE ANY ARGUMENTS, BUT INSTEAD INDICATES
THAT THE <TRANSACTION FILE IS AN <ASCII FILE FORMATTED TO TELL
<MAKLIB WHAT CHANGES TO MAKE TO WHAT MODULES, AND HOW TO IDENTIFY
THEM.
.B.I 5;^THE <FIX FILE FORMAT IS THE SAME AS THAT FOR ORDINARY <MACRO
ASSEMBLY LANGUAGE PROGRAMS, WITH SEVERAL RESTRICTIONS AND WITH THE
ADDITION OF SEVERAL SPECIAL PURPOSE PSEUDO-OPS. ^THE SPECIAL PSEUDO-OPS
ARE USED TO PASS DATA TO <MAKLIB ON WHERE AND HOW TO INSERT THE
CODE GIVEN IN THE <FIX FILE. ^THE RESTRICTIONS ARE THAT MACROS AND
REPEATS ARE NOT IMPLEMENTED, ALONG WITH SOME OF THE <MACRO-10
PSEUDO-OPS. ^IN ADDITION, SINCE THE <MAKLIB ASSEMBLER IS ONE PASS, THERE
ARE SOME RESTRICTIONS ON THE TYPES OF FORWARD REFERENCES ALLOWED.
^A DESCRIPTION OF EACH NEW PSEUDO-OP FOLLOWS.
.SKIP 3
.LS
.LE;<.EDIT NNNNNN
.BR.I 2;^GIVES THE EDIT NAME FOR THE FIX THAT FOLLOWS.
.BR.I 2;^ALL THE OTHER <MAKLIB PSEUDO-OPS MUST APPEAR
.BR.I 2;BETWEEN AN <.EDIT AND AN <.ENDE PSEUDO-OP.
.BR.I 2;^THE EDIT NAME IS STORED IN THE <TRACE
.BR.I 2;BLOCK FOR ANY MODULE AFFECTED BY THE EDIT.
.LE;<.NAME III
.BR.I 2;^GIVES INITIALS OF PERSON WHO WROTE THE FIX (OPTIONAL).
.BR.I 2;^THESE INITIALS, IF PRESENT ARE STORED IN THE
.BR.I 2;<TRACE BLOCK FOR THE EDIT.
.LE;<.DATE DD-MON-YY
.BR.I 2;^GIVES THE DATE THAT THE FIX WAS CREATED (OPTIONAL).
.BR.I 2;^THIS DATE IS REMEMBERED IN THE <TRACE BLOCK FOR THE EDIT.
.LE;<.MODULE MMMMMM
.BR.I 2;^SELECTS THE MODULE NAME THAT EDIT SHOULD BE
APPLIED TO.
.BR.I 2; ^THE SELECTED MODULE IS READ IN (LOADED)
.BR.I 2;AND REMAINS THE SELECTED MODULE UNTIL THE END OF
.BR.I 2;THE EDIT, UNLESS A NEW .<MODULE PSEUDO-OP IS ISSUED.
.BR.I 2;^WITHIN A GIVEN EDIT, EACH MODULE MAY BE SELECTED
.BR.I 2;ONCE AT MOST.
.LE ;<.ASSOCIATED +EDIT1, -EDIT2, EDIT3, +EDIT4 .....
.BR.I 2;^CONVEYS INFORMATION ABOUT WHICH OTHER EDITS MUST BE
.BR.I 2;PRESENT OR NOT PRESENT IN THE CURRENT MODULE.
.BR.I 2;^THE "+" INDICATES THAT THE FOLLOWING EDIT IS REQUIRED.
.BR.I 2;^THE "-" INDICATES THAT THE EDIT IS PRECLUDED.
.BR.I 2;^WARNING MESSAGES ARE GIVEN IF THE MODULE DOES NOT HAVE
.BR.I 2;THE APPROPRIATE COMBINATION OF ASSOCIATED EDITS.
.BR.I 2;^IF NO + OR - IS SEEN, + IS ASSUMED. (^EDIT REQUIRED)
.BR.I 2;^ALL <.ASSOCIATED PSEUDO-OPS MUST PRECEDE THE FIRST
.BR.I 2;OCCURENCE OF ANY <.INSERT,.REMOVE OR <.REINSERT OPERATOR.
.LE;<.INSERT EXPRESSION,<KEYWORD:<N,_<^CODE TO ^MATCH>
.BR.I 2;^THIS PSEUDO-OP TELLS WHERE AND HOW TO INSERT CODE.
.BR.I 2;^IT ALSO PROVIDES A METHOD FOR VERIFYING THAT THE
.BR.I 2;POSITION OF THE FIX IS CORRECT.
.BR.I 4;^THE FIRST ARGUMENT GIVES THE LOCATION AT WHICH TO
.BR.I 4;INSTALL CODE, IN EITHER NUMERIC OR SYMBOLIC
.BR.I 4;EXPRESSION, EVALUATED IN THE CURRENT RADIX.
.BR.I 4;^THIS LOCATION IS ASSUMED TO BE RELOCATABLE AND MAY
.BR.I 4;BE IN EITHER THE LOW OR HIGH SEGMENT. ^ANY NEW CODE
.BR.I 4;INSERTED WILL BE PLACED AT THE END OF THE SAME
.BR.I 4;SEGMENT.
.BR.I 4;^THE SECOND ARGUMENT IS A KEYWORD GIVING THE METHOD OF
.BR.I 4;THE INSTALLATION. ^THE KEYWORD IS ONE OF THE
.BR.I 4;FOLLOWING (ABBREVIATED TO UNIQUENESS):
.BL.I 5;<BEFORE - ^EXECUTE PATCH CODE BEFORE EXECUTING
.BR.I 10;THE INSTRUCTION AT THE LOCATION SPECIFIED.
.BR.I 5;<AFTER - ^EXECUTE PATCH CODE AFTER EXECUTING THE
.BR.I 10;INSTRUCTION AT THE LOCATION SPECIFIED.
.BR.I 5;<REPLACE - ^FOR EACH INSTRUCTION INCLUDED IN THE
.BR.I 10;PATCH, DELETE ONE FROM EXISTING CODE, STARTING
.BR.I 10;WITH THE INSTRUCTION AT THE LOCATION OF THE
.BR.I 10; PATCH.
.BR.I 5;<REPLACE:<M - ^DELETE M INSTRUCTIONS FROM THE EXISTING
.BR.I 10;CODE STARTING WITH INSTRUCTION AT THE PATCH
.BR.I 10;ADDRESS, NO MATTER HOW MANY INSTRUCTIONS
.BR.I 10;ARE INSERTED. ^THE ARGUMENT MAY
.BR.I 10; BE AN EXPRESSION, AND IS
.BR.I 10;EVALUATED IN THE CURRENT RADIX.
.BR.I 4;^THE THIRD ARGUMENT, WHICH IS OPTIONAL, GIVES THE LINE
.BR.I 4;OF CODE AT THE LOCATION SPECIFIED BY THE
.BR.I 4;FIRST ARGUMENT.
.BR.I 4;^THE EXPRESSION WITHIN THE ANGLE BRACKETS IS EVALUATED,
.BR.I 4;AND IF IT DOES NOT MATCH THE CODE ACTUALLY AT THAT
.BR.I 4;LOCATION, A FATAL ERROR MESSAGE IS GIVEN.
.BR.I 4;^IF THE CODE BEING MATCHED INVOLVES A MULTI-WORD
.BR.I 4;LITERAL, ONLY THE FIRST WORD NEED BE GIVEN.
.BR.I 2;^AFTER THE <.INSERT PSEUDO-OP, CODE GENERATED BY
.BR.I 2;THE ASSEMBLER IS INSERTED, ACCORDING TO INSTRUCTIONS.
.LE;<.ENDI - ^THIS PSEUDO-OP DELIMITS THE CODE THAT IS
.BR.I 2;PART OF THE PRECEDING INSERTION.
.BR.I 2;^WITHIN THE <.INSERT-.ENDI PAIR, IT IS ILLEGAL TO USE
.BR.I 2;<.EDIT, <.MODULE, <.REINSERT OR <.REMOVE PSEUDO-OPS.
.LE;<.ENDE - ^THIS PSEUDO-OP DELIMITS THE RANGE OF AN
.BR.I 2;EDIT. ^WHEN THIS PSEUDO-OP IS SEEN, CHECKS ARE MADE FOR
.BR.I 2;UNDEFINED LABELS, ETC. AND NEXT EDIT OR <EOF CAN
.BR.I 2;BE HANDLED.
.LE;<.REMOVE EDIT1,EDIT2,EDIT3...
.BR.I 2;^THIS PSEUDO-OPERATOR REMOVES THE SPECIFIED EDITS
.BR.I 2;FROM THE SELECTED MODULE. ^ACTUALLY, THE
.BR.I 2; ONLY ACTION TAKEN IS TO PUT BACK THE
.BR.I 2;ORIGINAL INSTRUCTIONS DISPLACED BY THE JUMPS
.BR.I 2;TO THE PATCH AREA FOR EACH <.INSERT. (^SEE APPENDIX)
.BR.I 2;^SPECIFICALLY, NO CHANGES ARE MADE TO THE SYMBOL TABLE.
.LE;<.REINSERT EDIT1,EDIT2,EDIT3...
.BR.I 2;^FOR EACH SPECIFIED EDIT, THE EFFECT OF ANY PREVIOUS
.BR.I 2;<.REMOVE PSEUDO-OP ON THAT EDIT IS REVERSED AND THE EDIT
.BR.I 2;IS MADE ACTIVE AGAIN.
.ELS
.B.I 5;^SINCE THE <MAKLIB ASSEMBLER IS ONE PASS, FORWARD REFERENCES
TO LABELS AND EXPRESSIONS ARE RESTRICTED TO SIMPLE ADDITION AND
SUBTRACTION ON THE HALFWORD BOUNDARY. ^ESSENTIALLY, REFERENCES TO
AS YET UNDEFINED LABELS OR SYMBOLS ARE LEGAL WHERE REFERENCES TO <EXTERNAL
SYMBOLS WOULD BE LEGAL IN <MACRO-10 (WITH NO POLISH FIXUPS).
^LITERALS ARE TREATED AS FORWARD REFERENCES, SINCE THE ACTUAL LOCATION
OF THE LITERAL IS NOT KNOWN UNTIL THE <.INSERT IS ENDED.
^IT IS NOT LEGAL TO DEFINE A LABEL INSIDE A LITERAL.
^AN ADDITIONAL RESTRICTION IS THAT THE QUANTITY USED IN THE RIGHT-HAND
SIDE OF AN ASSIGNMENT (^I.^E. =,==,==: ETC.) MUST NOT BE FORWARD
OR <EXTERNAL. ^ASSIGNMENTS DO NOT HAVE TO BE INSIDE <.INSERTS IN
THE FIX FILE, HOWEVER THE <.EDIT AND <.MODULE PSEUDO-OPS MUST PRECEDE
ANY ASSIGNMENTS (WHICH DEFINE NEW SYMBOLS IN THE SYMBOL TABLE). ^SINCE
IT IS IMPOSSIBLE TO BACKTRACK REFERENCES TO A SYMBOL IN THE RELOCATABLE
BINARY FILE, <MAKLIB WILL NOT ALLOW ANY RE-DEFINITIONS OF EXISTING SYMBOLS.
^THEREFORE, ANY LABEL OR SYMBOL CREATED BY USE OF THE <FIX SWITCH
MUST BE NEW TO THE PROGRAM.
.B.I 5;^FOR EASE OF PATCHING, AND TO KEEP THE APPEARANCE OF THE
BINARY PATCHES AS CLOSE TO SOURCE LEVEL AS POSSIBLE, THE FOLLOWING
PSEUDO-OPS ARE IMPLEMENTED IN THE <MAKLIB <FIX FILE
ASSEMBLER, AN BEHAVE AS THEY DO IN <MACRO-10:
.LM 10;.UC
.BL;ASCII#####ASCIZ#####BYTE
.BR;COMMENT###DEC#######EXP
.BR;IOWD######OCT#######POINT
.BR;RADIX#####RADIX50###REMARK
.BR;SIXBIT####SQUOZE####XWD
.LC.LM 1;\\
.NOTE; ^THE PSEUDO-OPS <BYTE, <DEC, <OCT AND <EXP ARE LIMITED
TO GENERATING ONE WORD OF DATA AT MOST.
.END NOTE
.B.I 5;^ALL THE <MACRO OPERATORS AND QUALIFIERS ARE AVAILABLE AS
ARE THE DEFINTIONS FOR THE USUAL MNEMONICS SUCH AS <CALLI<S,
<UUO<S, <TTCALL<S AND <MTAPE<S.
.B.I 5;^SYMBOLS MAY BE FOLLOWED BY THE "_#_#" (DOUBLE POUND SIGN) TO
INDICATE THAT THEY ARE <EXTERNAL QUANTITIES. ^HOWEVER, IF THE
SYMBOL IS ALREADY IN THE SYMBOL TABLE, DEFINED AS <EXTERNAL, THE USE
OF "_#_#" IS NOT NECESSARY. ^IT IS NOT NECESSARY TO FOLLOW UNDEFINED SYMBOL
NAMES WITH "_#" (SINGLE POUND SIGN), AS ANY UNDEFINED SYMBOL IS ASSUMED
TO BE A FORWARD REFERENCE. ^IF A SYMBOL NAME IS FOLLOWED BY THE "_#", THE
ONLY ACTION TAKEN IS TO GIVE AN ERROR MESSAGE IF THE SYMBOL ALREADY IS DEFINED.
^LABELS MAY BE DEFINED AS <GLOBAL (AVAILABLE TO OTHER PROGRAMS) IF
THEY ARE FOLLOWED BY "::" (DOUBLE COLON), AND MORE GENERALLY,
THE FULL FACILITIES AVAILABLE IN <MACRO-10 FOR COMBINATIONS OF <DDT
SUPRESSION AND <GLOBAL DECLARATION ARE AVAILABLE
FOR BOTH LABELS AND ASSIGNMENTS.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MASTER.REL,MASTER.FIX/FIX\\
.LE;<WHO<:III - ^THIS SWITCH IS USED ONLY IN CONJUNCTION
WITH THE <FIX COMMAND SWITCH. ^IT MAY APPEAR AS PART OF EITHER THE <MASTER
OR THE <TRANSACTION FILE SPECIFICATION. ^IT TAKES AS ITS ARGUMENT UP
TO THREE ALPHA-NUMERIC CHARACTERS WHICH ARE THE INITIALS OF THE PERSON
USING <MAKLIB. ^THESE INITIALS, IF PRESENT, ARE INCLUDED IN THE <TRACE
BLOCK OF ANY EDITS, IN THE FIELD OF WHO LAST AFFECTED
ANY EDIT AND IN THE FIELD OF WHO INSTALLED THE EDIT.
^THIS SWITCH COULD MOST CONVENIENTLY BE PLACED IN THE USER'S
<SWITCH.INI FILE, SO THAT PLACEMENT OF THE USERS'S INITIALS INTO THE
<TRACE BLOCKS WOULD BE AN AUTOMATIC PROCESS. ^THIS SWITCH IS IGNORED
IF THE COMMAND SWITCH USED IS NOT <FIX.
.B;<EXAMPLE:
.B.I 5;^^OUT.REL=MASTER.REL,MASTER.FIX/FIX/WHO:ILG\\
.ELS
.ELS
.PAGE.CENTER;<APPENDIX 1
.SKIP 2
.CENTER; ^& ^EXAMPLES OF <FIX ^FILES\&
.LM 0;.SKIP 2;.LITERAL 40
.EDIT 345 ;THIS IS EDIT 345
.NAME ILG ;PATCH BY ILG
.DATE 3-DEC-75 ;PATCH WRITTEN DATE
.MODULE MACRO ;NAME FROM TITLE
.ASSOCIATED 200,-333 ;EDIT 200 REQUIRED,
;EDIT 333 PRECLUDED
REMARK THIS EDIT FIXES Q ERRORS WITH COMPLEMENT OPERATOR
.REMOVE 312 ;EDIT 312 SUPERSEDED
.INSERT EVUPAR+3,BEFORE,<PUSHJ P,MREAD> ;INSERT @EVUPAR+3
;BEFORE THE "PUSHJ"
;INSTRUCTION AT EVUPAR+3
;IS ""PUSHJ P,MREAD"
MOVEI AC0,CSTATN ;PICK UP CHAR STATUS
TRNE AC0,CH.FOO ;IS IT SPECIAL?
JRST [SETOM ERSTAT ;YES,FLAG IT
MOVEI AC0,CSTATX ;CHANGE STATUS
JRST .+1 ] ;RESUME NORMAL FLOW
.ENDI ;END OF FIRST PART
.INSERT XCTOP-1,REPLACE:3,<JRST XTC1A> ;REPLACE 3
;INSTRUCTIONS AT
;LABEL XCTOP-1
;WITH THIS CODE:
PUSHJ PP,MREAD1 ;USE 1ST CASE
SKIPE AC1,OPNUM ;ANY OP TO DO?
JRST @[ OP1
OP2
OP3]-1(AC1) ;YES,GO TO IT
JRST NOP ;NO,NO OP
.ENDI ;END SECOND PART
.ENDE ;END OF EDIT 345
.END LITERAL
.PAGE.CENTER;^&^ANOTHER ^SAMPLE ^FIX ^FILE\&
.SKIP 2
.LM 0;.LITERAL 87
COMMENT $
THIS IS AN EXAMPLE OF A .FIX FILE USED TO APPLY TWO EDITS
TO A FILE. IT USES SOME FEATURES OF MAKLIB'S BINARY PATCHING
FACILITY.
$
REMARK THE FIRST EDIT DOES TWO INSERTS AND DEFINES A NEW SYMBOL
.EDIT 300 ;EDIT 300
.MODULE CBLIO ;SELECT 'CBLIO'
.ASSOCIATED 271 ;REQUIRES EDIT 271
.NAME ILG ;PATCH BY ILG
.DATE 30-DEC-75 ;ON 30TH DECEMBER
FL.JEM==FL.RAN!FL.OPN ;DEFINE NEW FLAG
.INSERT OPNUUO+3,BEFORE,<PUSHJ P, KILLIO> ;1.INSERTION @OPNUUO+3
;2.BEFORE INSTRUCTION THERE
;3.WHICH IS "PUSHJ P,KILLIO"
TRNE F,FL.JEM ;CHECK FOR THIS CASE
JRST NOFIL ;AND HANDLE IT
.ENDI ;END OF THE INSERT
.INSERT KILLIO+^D30,AFTER,<POPJ P,> ;INSERT NEW ROUTINE AFTER KILLIO
;1.@KILLIO+30.
;2.AFTER INSTRUCTION THERE
;3.WHICH IS A "POPJ P,"
NOFIL: ;NEW ROUTINE IS NOFIL.
PUSHJ P,.TCRLF## ;START NEW LINE
MOVEI T1,[ASCIZ "?NO FILE FOUND"] ;SET FOR MSG.
PUSHJ P,.TSTRG## ;OUTPUT STRING
JUMPN C,[MOVE T1,0(C) ;IF HAVE PTR TO FILENAME
PUSHJ P,.TSIXN## ;TYPE IT OUT
JRST .+1] ;AND RETURN
PUSHJ P,.TCRLF## ;NEXT LINE
POPJ P, ;END OF ROUTINE
.ENDI ;END OF INSERT
.ENDE ;END OF EDIT
REMARK THIS NEXT EDIT DELETES CODE AND REPLACES CODE
.EDIT 301 ;EDIT 301
.MODULE CBLIO ;SELECT MODULE FOR EDIT
.NAME ILG ;PATCH BY ILG
.DATE 31-DEC-75 ;DATE OF PATCH
.ASSOCIATED -265,300 ;EDIT 265 CAN'T BE PRESENT
;AND EDIT 300 MUST BE
REMARK FIRST REPLACE SOME CODE
.INSERT RANIO+1,REPLACE,<TRNE F,FL.OPN> ;1.REPLACE STARTS W/INST @
;RANIO+1
;2.NEW INST. REPLACES OLD
;3.INSTR. TO MATCH IS
;"TRNE F,FL.OPN"
TRNE F,FL.JEM ;REPLACING INSTRUCTION
.ENDI ;END OF INSERT
REMARK NOW REPLACE 2 INSTRUCTIONS WITH 4 NEW ONES
.INSERT RAND-3,REPLACE:2,<MOVEI T1,"A"> ;1.INSERT @ RAND-3
;2.REPLACE 2 INSTRUCTIONS
;3.FIRST IS "MOVEI T1,"A" "
MOVEI T1,0(V) ;PICK UP STATUS
JUMPE T1,.POPJ## ;IF 0 , RETURN
CAIN T1,"A" ;IS IT ASCII "A"?
MOVEI T1,-" "(T1) ;YES,CONVERT TO SIXBIT
.ENDI
REMARK THIS LAST PART OF EDIT 301 SHOWS HOW TO DELETE CODE
.MODULE UFLOAT ;THIS PART OF EDIT
;301 IS IN MODULE UFLOAT
.ASSOCIATE -265 ;MAKE SURE 265 NOT PRESENT
;HERE EITHER.
.INSERT FLT.1+3,REPLACE:^D10,<MOVEM C,CURFLT> ;1.INSERT @FLT.1+3 WORDS
;2.REPLACE 10. INSTRUCTIONS
;3.THE FIRST OF WHICH IS
;"MOVEM C,CURFLT".
.ENDI ;REPLACE THE 10. INSTRS WITH
;NOTHING. I.E. DELETE THEM.
.ENDE ;END OF EDIT 301
.END LITERAL
.PAGE.CENTER;<APPENDIX 2
.SKIP 2
.CENTER;^& ^FORMAT OF ^TRACE ^DATA ^BLOCK\& (^LINK ITEM TYPE 1060)
.SKIP 3
^THE LINK ITEM TYPE, "^^TRACE BLOCK DATA"\\ IS USED TO INCLUDE IN
THE REL FILE INFORMATION THAT CAN BE USED TO BOTH VERIFY AND CHANGE
THE PATCH STATUS OF A PROGRAM. ^THE FORMAT OF THE TRACE BLOCK FOLLOWS:
.BL 1
^THE FIRST PART OF THE <TRACE BLOCK IS THE STATIC AREA. ^THIS AREA APPEARS
IN EACH MODULE THAT IS AFFECTED BY THE PARTICULAR EDIT. ^THE STATIC AREAS
GIVE INFORMATION COMMON TO ALL MODULES AFFECTED BY AN EDIT AND
THE VARIABLE AREA GIVES THE CHANGING DATA ON THE
PARTICULAR EDIT AS IT GOES FROM MODULE TO MODULE.
.BL 1
.NO FILL.NO JUSTIFY;^^
!=====================================!
TB$HED ! LINK ITEM NUMBER ! LENGTH OF BLOCK !
!-------------------------------------!
TB$EDT ! SIXBIT EDIT NAME (UP TO 6 CHRS) !
!-------------------------------------!
TB$STA ! -1 IF ACTIVE !WHO LAST AFFECTED !
!-------------------------------------!
TB$MAK ! WHO CREATED ! DATE (15 BIT) !
!-------------------------------------!
TB$INS ! WHO INSTALLED ! DATE (15 BIT) !
!-------------------------------------!
TB$FUT ! RESERVED FOR FUTURE USE !
!-------------------------------------!
TB$LEN ! _# OF ASS. EDITS ! _# OF PCO GROUPS !
!=====================================!
.FILL.JUSTIFY.BL 1;\\
^THE STATIC AREA, WHICH IS REPEATED IN EACH MODULE, IS FOLLOWED
BY A VARIABLE AREA. ^THE VARIABLE AREA CONSISTS OF TWO PARTS, THE
FIRST GIVING DATA ON THE ASSOCIATED EDIT STATUS FOR THIS MODULE AND
THE NEXT GIVING THE ACTUAL PROGRAM CHANGE ORDERS (PCO'S). ^THE
LENGTH OF EACH OF THESE AREAS APPEARS IN THE STATIC AREA OF THE TRACE
BLOCK.
.BL 1
^FOR EACH ASSOCIATED EDIT, THE FOLLOWING GROUP APPEARS:
.NO FILL.NO JUSTIFY.BL 1;^^
!=====================================!
TB$AEN ! SIXBIT EDIT NAME OF A.E. !
!-------------------------------------!
TB$AES !X! RESERVED FOR FUTURE ! 0B0 IF CAN'T BE PRESENT
!=====================================! 1B0 IF MUST BE PRESENT
.BL 1
.FILL.JUSTIFY;\\
^AFTER THE ASSOCIATED EDIT GROUPS APPEAR, IF THERE ARE ANY, THE
PCO GROUPS FOR THAT MODULE APPEAR. ^THERE ARE CURRENTLY THREE TYPES
OF PROGRAM CHANGE GROUPS: ^^ INSERT,REMOVE AND REINSERT.\\ ^THEY CAN
APPEAR IN ANY ORDER AND THE TOTAL NUMBER IS OF COURSE VARIABLE.
.BL 2
.NO FILL.NO JUSTIFY;
<INSERT PROGRAM CHANGE ORDER:
^^ !=====================================!
TB$PCO !PCO TYPE CODE (1) ! LENGTH OF GROUP !
!-------------------------------------!
TB$DAT ! 0 !INSTS INSRTD! ADDR. OF INSERT ! BITS 10-17
!-------------------------------------! ARE _# OF INSTS
TB$PAT ! NEW ADDR OF ORG ! ADDR OF PAT CODE!
!=====================================!
.BL 1
\\ <REMOVE <EDIT PROGRAM CHANGE ORDER:
^^ !=====================================!
TB$PCO !PCO TYPE CODE (2) ! LENGTH OF GROUP !
!-------------------------------------!
TB$REN ! SIXBIT EDIT NAME !
!=====================================!
.BL 1
\\ <REINSERT <EDIT PROGRAM CHANGE ORDER:
^^ !=====================================!
TB$PCO !PCO TYPE CODE (3) ! LENGTH OF GROUP !
!-------------------------------------!
TB$RIN ! SIXBIT EDIT NAME !
!=====================================!
\\
.FILL.JUSTIFY
.PAGE.CENTER;<APPENDIX 3
.SKIP 2
.CENTER;^&^FORMAT OF ^CODE ^INSERTION\&
.SKIP 3
.CENTER;^INSERTION <BEFORE A ^LOCATION
.SKIP 2
.I 8;<.INSERT <LOCATION, <BEFORE, _<<ORIGINAL <INSTRUCTION_>
.SKIP 1
.CENTER;^GENERATES:
.SKIP 2
.LITERAL 23
LOCATION: JUMPA %PATCH
!-------------------------------------!
%PATCH: ! FIRST PATCH INSTRUCTION !
!-------------------------------------!
! SECOND PATCH INSTRUCTION !
!-------------------------------------!
/ /
/ /
/ /
!-------------------------------------!
! LAST PATCH INSTRUCTION !
!-------------------------------------!
! ORIGINAL INSTRUCTION !
!-------------------------------------!
! JUMPA 1, LOCATION+1 !
!-------------------------------------!
! JUMPA 2, LOCATION+2 !
!-------------------------------------!
! ANY "LITERALS" !
!-------------------------------------!
.END LITERAL
.SKIP 1
.NOTE;^THE ACTUAL LABEL CREATED AT THE LOCATION OF THE PATCHED IN CODE
IS OF THE FORM: "%"_<<EDIT-NAME_>_<EDIT-PART_>
.B;WHERE THE <EDIT-PART IS FROM "^A" TO "^Z", INCREMENTED
FOR EACH <.INSERT IN THE EDIT.
.END NOTE
.PAGE
.CENTER;^INSERTION <AFTER A ^LOCATION
.SKIP 2
.I 8;<.INSERT <LOCATION, <AFTER, _<<ORIGINAL <INSTRUCTION_>
.SKIP 1
.CENTER;^GENERATES:
.SKIP 2
.LITERAL 23
LOCATION: JUMPA %PATCH
!-------------------------------------!
%PATCH: ! ORIGINAL INSTRUCTION !
!-------------------------------------!
! FIRST PATCH INSTRUCTION !
!-------------------------------------!
! SECOND PATCH INSTRUCTION !
!-------------------------------------!
/ /
/ /
/ /
!-------------------------------------!
! LAST PATCH INSTRUCTION !
!-------------------------------------!
! JUMPA 1, LOCATION+1 !
!-------------------------------------!
! JUMPA 2, LOCATION+2 !
!-------------------------------------!
! ANY "LITERALS" !
!-------------------------------------!
.END LITERAL
.PAGE
.CENTER;^INSERTION WITH <REPLACE<MENT AT A ^LOCATION
.SKIP 2
.I 8;<.INSERT <LOCATION, <REPLACE, _<<ORIGINAL <INSTRUCTION_>
.SKIP 1
.CENTER;^GENERATES:
.SKIP 2
.LITERAL 23
LOCATION: JUMPA %PATCH
!-------------------------------------!
! ORIGINAL INSTRUCTION !
!-------------------------------------!
%PATCH: ! FIRST PATCH INSTRUCTION !
!-------------------------------------!
! SECOND PATCH INSTRUCTION !
!-------------------------------------!
/ /
/ /
/ /
!-------------------------------------!
! nTH (LAST) PATCH INSTRUCTION !
!-------------------------------------!
! JUMPA 1, LOCATION+n !
!-------------------------------------!
! JUMPA 2, LOCATION+n+1 !
!-------------------------------------!
! ANY "LITERALS" !
!-------------------------------------!
.END LITERAL
.SKIP 1
.NOTE;^IF NO INSTRUCTIONS ARE INSERTED (N=0), THEN RETURN
IS TO <LOCATION+1 AND <LOCATION+2.
.END NOTE
.PAGE
.CENTER;^INSERTION WITH <REPLACE<MENT ^INSTRUCTIONS AT A ^LOCATION
.SKIP 2
.I 8;<.INSERT <LOCATION, <REPLACE:<M, _<<ORIGINAL <INSTRUCTION_>
.SKIP 1
.CENTER;^GENERATES:
.SKIP 2
.LITERAL 23
LOCATION: JUMPA %PATCH
!-------------------------------------!
! ORIGINAL INSTRUCTION !
!-------------------------------------!
%PATCH: ! FIRST PATCH INSTRUCTION !
!-------------------------------------!
! SECOND PATCH INSTRUCTION !
!-------------------------------------!
/ /
/ /
/ /
!-------------------------------------!
! LAST INSTRUCTION OF PATCH !
!-------------------------------------!
! JUMPA 1, LOCATION+m !
!-------------------------------------!
! JUMPA 2, LOCATION+m+1 !
!-------------------------------------!
! ANY "LITERALS" !
!-------------------------------------!
.END LITERAL
.SKIP 1
.NOTE; ^IF M IS NOT SPECIFIED OR IS ZERO, THE EFFECT IS THE SAME
AS THE <REPLACE KEYWORD WITHOUT AN ARGUMENT, ^I.^E. ONE WORD
IS SKIPPED OVER ON RETURN FOR EVERY ONE INSERTED.
.END NOTE