{{htmlmetatags>metatag-description:(GIN Reference Manual - Chapter 7 Steering GIN)}} ====== 7 STEERING GIN ====== ===== 7.0 Loading the Compiler ===== The compiler of GIN is itself written in GIN, and so the magnetic tape dumps which are available are in the format produced by GIN. As a general rule GIN is published as a magnetic tape subfile called GIN5 or a similar appropriate name, in the format produced by #BIP. FINDable dumps can be supplied on special request. GIN is not overlaid. \\ To load the compiler under operators' Executive it is necessary to use - A seek program such as #XK0F for subfile-format dumps, or \\ \\ - FIND from the operator's console for FINDable dumps. Under GEORGE it is possible to load from subfile-format dumps on online magnetic tape - by using #XK0F or \\ \\ - by using the system macro FIND: FIND #name , MT, magnetic tape description where #name is #GIN5 for a virgin compiler, or the name in the request slip at #DUMP time for a dumped compilation. \\ It is also possible to FIND in exactly the same way from a FINDable dump. \\ The same methods are available for off-line tapes in Marks of GEORGE where CONT from off-line tape is permitted, and in these Marks the LOAD command can be used for FINDable dumps to off-line tapes. \\ GIN is usually generated with a type 2 entry block, causing it to be entered immediately after loading. When this is done GIN is entered at word 25. \\ ===== 7.1 #XK0F Seek Program ===== The #XK0F Seek Program is available on cards or paper tape as a bootstrap loader for binary programs on magnetic tape, provided such programs are enclosed in subfiles. At least for GEORGE 3 development, GIN is held in a subfile on the GEORGE source tapes and #XK0F used to load the compiler. #XK0F accepts any program status and has in addition a facility to rename the program loaded. It does not require a printer; it reads all steering lines first and then opens the magnetic tape. #XK0F has an 'F' load block and a type 2 (GO) entry block and therefore begins execution immediately after being loaded. \\ ==== STEERING LINES ==== | OFR %A,%B,%C | mandatory | | NAM %A,%B | optional | | RES %A,%B | mandatory | Provided a space precedes %A all steering lines allow filler characters to follow the control characters, e.g. OFREADING would be acceptable, though Delta characters are unacceptable when the input medium is paper tape. The 3-character control mnemonic must begin in column 1 of the line. The required order for the directives is as shown above. \\ === Open for Reading === OFR %A,%B,%C\\ | %A | the name of the magnetic tape. | | %B | the generation number of the tape (optional). | | %C | the reel sequence number (optional). | When %B is zero it is equivalent to omitting it, as the generation number will not be checked; %C can only be omitted if the reel sequence number is known to be zero. \\ Assuming remaining steering lines contain no errors, the specified magnetic tape is opened in mode 64/#100 (no check on the absence of the write-permit ring). The tape is opened via normal Executive search procedures. \\ === Change Program Name === NAM %A,%B\\ | %A | the name to which the program is to be changed, in the format #AAAA where AAAA is the 4-character name required. | | %B | program status letters. | %B is essentially all characters between the character following %A and the last character before termination of the line, inclusive. The only significant characters are: | P | No status bits required. | | Q | System/directory file (System Control Area) accessible. | | R | SSTP facilities used. | | S | Reserved, status lost on dumping. | | T | Reserved for GEORGE 3. | The above-given significance applies to range compatible trusted programs. For the significance of the 1904/5 scheme see the ICL Programmer's Reference Manual. \\ If no character P exists bits set will depend on the existence of Q, R, S, T in the line. If a P is encountered then all bits are cleared, including any previously set, and the rest of the line is not scanned. \\ This Directive allows programs such as RCTPs to be compiled and loaded by #GO and run immediately (because it is not possible for a program to set a previously unset trusted bit in its request slip via a 166 (RRQ) order). \\ In the case where the program has trusted bits already set in its request slip #XK0F will leave these bits set, unless P is given, whereupon an error results. \\ The NAM directive is optional and can be used to allow timesharing. In the case of timesharing, at least the first program loaded with #XK0F must use the NAM directive. \\ === Restore Subfile === RES %A,%B\\ | %A | the name of the subfile containing the binary program to be loaded. | | %B | the generation number of the subfile required. If the parameter is omitted no check will be made on the subfile generation number. | ==== GENERAL EXECUTION ==== All blank steering lines are ignored. In this context any Delta shift character on paper tape is regarded as a line terminator, thus precluding the use of tab. \\ The named magnetic tape is opened and searched for the required subfle. If found, the request block is scanned for and when found, read and examined. First the program's core request is implemented, then the peripheral request word is implemented except that the load peripheral is always retained as, too is the slow input peripheral. The request block with status bits and possibly name change is. filed with Executive via RRQ (166) extracode. In the absence of a NAM directive, the program name will remain #XK0F and it will have the trusted status specified in its request slip. If a supplementary request block (Type 6) follows the standard request slip, appropriate branch and address modes are set. A CONT (154) extracode is then used to load the program. \\ If a Type 2 entry block follows the binary blocks on tape the loaded program will begin execution immediately. If Type 3 or Type 4 it will halt. \\ On entry, the accumulators will be preset as follows: \\ | X0 | B0-B8 | Load peripheral type (actually 5). | | | B9-B23 | Load peripheral unit number (actually 0). | | X1 | | peripheral type (0 or 3) | | X2,X3,X4 | | File (tape) name of the load peripheral. | | X5,X6,X7 | | Subfile name as given in the RES directive. | It should not be assumed that words not specifically set by the program are zero. In particular, word 30 is likely to be non-zero. \\ === Error Messages === ^ Error message ^^ Action ^ | HALTED: | TR, TP, LP, CR, CP | Make a peripheral available of the type indicated by the 2-characters mnemonic given and GO. | | | NOT ENOUGH CORE AVAILABLE | make more core available and GO. | | DISPLAY: | WRONG DIRECTIVE ON STEERING LINE | Correct the steering line and re-engage the card or tape reader. | | | ILLEGAL FILENAME ON STEERING LINE | The file or subfile name does not begin with a letter. \\ Correct the steering line and re-engage the card or tape reader. | | DISPLAY and DELETE: | (%A of RES) SUBFILE FORMAT IS INCORRECT | %A of the RES steering line does not contain binary blocks or else the format of the binary program is incorrect, or there is something wrong with the request slip (length or checksum). | | | S/F (%A of RES) IS NOT ON (%A of OFR) | Either the subfile cannot be found on the tape, or, if %B was specified in the RES card, the generation number is wrong. | | | EBM/22AM NOT AVAILABLE | Extended mode program cannot be run on this processor. | | | TAPE FAIL ON MT0 | Try the same tape on another deck, a duplicate tape on another deck, clean the tape deck, or give up assuming the tape is bad | | | ILLEGAL STATUS REQUEST | Incompatible status requested.\\ Caused by specifying P in NAM directive when the program requires trusted status. | === Illegal Messages === ^ Error message ^ Action ^ | HALTED: ZZ | The program has gone illegal under a double slot trusted Executive at the address in word 10. Should never occur. | | ILLEGAL: | Usually on a 166 order at address *242, and usually caused by #XK0F trying to change its name to that of a program already in the machine.\\ Can also be caused by an incorrect request block of the program being loaded. | **Note**\\ When a multi-overlay program is being loaded, #XK0F does not mind if the request slip and overlay 0 of the program is enclosed in a subfile. \\ The GIN directive #BIP at the moment does not enclose overlay 0 in a subfile, but may do so at some future date. \\ #XK0F can be used to load programs from subfile format library tapes (i.e. most current libraries). The name of the subfile is the same as the program required without the '#' e.g. OFR ICLKG3SYSTEM NAM #XK60 RES XK60 Overlay programs cannot be loaded from MLTs in this way because the subfile format is not the same as that produced by GIN. ===== 7.2 FINDable loading ===== When #DUMP or #BIP are used to produce a FINDable dump, the dump is not enclosed in composite subfiles. In the case of multi-overlaid program and the use of #BIP, all overlays except overlay 0 will be in simple subfiles.\\ GIN will only put one FINDable program on a tape, the tape being rewound and renamed PROGRAM XXXX, where XXXX is the 4-character name given in the name field of the request slip interlude.\\ A FIND command issued from an operator's console, or as a command under a comprehensive operating system, will either scan a given device type if this can be a parameter to the command, or will load a seek program which will search all forms of backing store for the program.\\ In any case, from the user point of view, FINDing a program is as simple as placing an #XK0F seek program in front of his job. ===== 7.3 Starting a Compilation ===== All versions of GIN are written so as to be entered automatically at entry point 5, unless the user forces another entry. Normally GIN attempts to use a tape-reader if one has been allocated to and failing that a card reader. (If #XK0F was used GIN will have the peripheral it was loaded on). If GIN has neither of these it halts : LD, when the user can enter it at either 20 or 21 (see below) - typing GO is equivalent to GO 21. \\ When entered in this way GIN assumes that it has a magnetic tape from which it has just been loaded as unit 0, and that #XK0F has set up the accumulators as described in 7.1. (#RESTORE sets up the accumulators identically). If this is not true there will be no ill-effects, except that the page header line will contain rubbish.\\ Entering at word 20 causes GIN to allocate a tape reader, and at 21 a card reader. \\ In any case the peripheral so allocated will be used to read the first directive to GIN. \\ ==== #CORE AND #MANDATORY ==== The one and only thing that every non-trivial GIN compilation must have is either #CORE or #MANDATORY. These two directives are identical except for one small point, and wherever #CORE is referred to "or #MANDATORY" should be understood. \\ The reason why #CORE is essential is that it causes the compiler to obtain the specified amount of core, and this has far-reaching effects on the internal organisation of GIN. Furthermore, it has been found convenient to make GIN perform many initialising functions at this stage.\\ It will be seen when the list of directives is read that some of them are unavailable before #CORE, and others after it. What happens is that those directives which may only be used before #CORE (i.e. #PROGRAM, #WORKFILE, #NAME, #BLOCKSIZE, #LOCALS, #CHAINS and #ITEM cause various data words to be altered within the compiler (a11 of them having default settings), and at #CORE time all of these settings are made use of to determine the action of the compiler. Similarly, the directives which may only be used after #CORE (almost all the rest) require for their operation that the #CORE initialisation has already taken place. \\ In addition to this, it is illegal to define or use identifiers or macros before #CORE. In some versions of GIN this is liable to cause GIN to delete; GIN 510 onwards will merely flag such errors. However, it is permissible before #CORE to use expressions which do not refer to identifiers in such directives as #DEFINE or #SKIP, and even to compile and enter interludes following these rules. \\ The events which take place at #CORE time are as follows: \\ - The amount of core required (specified as a number of 1K units) is requested from Executive. If the directive was #MANDATORY and the amount of core obtained is less than that requested, GIN halts:CM.\\ If the directive was #CORE and the amount obtained is less than a certain minimum (18?+1]+18]+32?) GIN halts:CL. In any other case GIN continues using the amount that was obtained. Thus it is possible to use all the available core on a machine by specifying a parameter larger than the machine with #CORE, or to leave some for other programs by using #MANDATORY with a smaller parameter. \\ \\ - The various switches preventing the use of certain facilities before #CORE and others after it are reset.\\ \\ - The program file described by the #PROGRAM directive and the #NAME directive is opened.\\ \\ - The core-store is subdivided to allow for: * The compiler itself * Chains for locals, universals, segments and macros * Local working storage * Information about peripherals * Magnetic tape input buffers * An index to the workfile * An index to show which part of the workfile is in each core area. Unless the workfile is in core. * An area to hold workfile blocks (this is normally much the largest area) * If the program file is in core, the program file.\\ \\ - The various: chain-base areas are initialised. Each of the directives which are allowed only before #CORE is optional. In every case, the default settings are appropriate for compiling a version of GEORGE 3 somewhat larger than that current when the GIN version was issued. For example, if no #PROGRAM directive is present the assumed program file device type is 10; if no #NAME directive is present the name of the program file is taken to be GEORGE THREE.\\ ==== #PROGRAM ==== The first parameter is the expected size of the program in units of 1K words. Unless the program file is in core, or backing store is in short supply, it is a good idea to leave a generous margin. The second parameter is the device type to be used : generally 1(core), 6(UDAS or EDS) or 10(drum).\\ ==== #WORKFILE ==== The first parameter is the expected size of the workfile in units of 1K words. This can only be found out experimentally (print out 18?+0]+26] at the end of the run) but a good rough guess is 10+0.6p, where p is the first parameter of #PRO. If GIN deletes WU your guess was too low (or there wasn't enough scratch space on backing store). The second parameter is the device type: 0(core), 6(UDAS or EDS), 9(drum).\\ If the second parameter was 6, you can specify a serial number as the third parameter, or have rubbish to indicate the GIN should halt to ask the operators for a serial number. (Rubbish here means any character string not starting with "#", ",", "[" or a digit).\\ ==== #NAME ==== The parameter is the filename of the program file. If the program file device is 6, a file of the stated name must be online or GIN will halt: PC; if it is 10, GIN will use an already-existing file if it can, and if not create one. \\ ==== #LOCALS ==== The parameter is the number of words of local storage used. The default is enough for a program which uses a very large number of locals and recursive macros to substantial depths. GEORGE is such a program. If you don't use many macros you may be able to reduce it to 1000 or so. If this isn't enough GiN deletes: CI. \\ ==== #BLOCKSIZE ==== The parameter is the size of blocks on input magnetic tape. If you know that your blocks are always less (or occasionally more) than 512 words you can change it and possibly save some core for other uses. If you aren't going to input from tape, specify zero. #BLOCKSIZE can be used after #CORE to reduce the size, but this gives no advantage. \\ ==== #CHAINS ==== Rather technical; this directive can be used to save some core and/or provide faster access to macros and identifiers. It is possible to specify the number of chains for macros, for locals and for universals with each initial letter. More chains mean shorter searches for any required name. \\ ==== #ITEM ==== Even more technical; it is possible to use this directive to allow extra information to be gathered by GIN, such as frequency-of-use counts. This information can be output by appropriate interludes. ==== Input from tape ==== When GIN is loaded from tape, immediately thereafter the tape used will be open to GIN as MT0 and positioned after the end of GIN. If the source is on the same tape, it should be #POSITIONed on the appropriate subfile #REWIND being used first if the source precedes GIN). This is necessary even if the subfile comes immediately after GIN. \\ Example \\ The following is fairly typical of the start of a compilation of GEORGE 4 (although GEORGE users should not rely on it as correct and up-to-date). LO#XK0F↑ Binary dump of #XK0F 0FR GEORGE TAPE0 RES GIN5 #LIS 3 #PRO ,6 [DEFAULT SIZE, DISC #WOR 220 [220K ON DRUM #NAM GEORGE FOUR [FILE MUST BE ONLINE #LOC 3000 #COR 180 #POS MT0 GEORGE3.0.1 #DEF GEORGE=4 #DEF G3MARK=6 #DEF G4MARK=6 . . #USE MT0 ==== The workfile ==== Current versions of GIN, for no particular reason, refrain from opening the workfile until this is unavoidable. Thus, the opening may take place after the compilation has proceeded for some time. \\ ==== Errors in #CORE ==== Up to and including GIN 510, GIN will delete CB or CC if certain errors are detected. \\ In GIN511 onwards, these errors will cause GIN to display : CB or CC and then - under GEORGE 3 or 4, halt with a message, or \\ \\ - otherwise, display a message and disengage the input device. If this occurs, the #CORE directive and the source line following should be corrected and re-input. If required, other directives which may precede #CORE may also be re-input before the new #CORE directive. \\ The following figure gives details of the layout of store in a GIN compilation on a 64K machine where the steering directives used were: #PR0 350,10 #WOR 200,6 #LOC 4000 #COR 180 {{gin:GRM7.3_1.png}} ===== 7.4 Restoring a Compilation ===== The action taken when a compilation which was saved by #DUMP is restored is very similar to that when GIN is loaded for the first time. As before, GIN will be entered at word 25 and will pick up certain information from its accumulators. It recognizes by the contents of certain words that it is continuing a compilation already started. When it is loaded, therefore, it re-initialises certain words, and resets various switches to indicate that it is before #CORE in a restored compilation. ==== #CORE and #MANDATORY ==== The remarks in [[gin:chapter7#7.3 Starting a Compilation|Section 7.3]] still apply, except that two directives (#CHAINS and #ITEM) cannot be used at restore time as they would invalidate already-existing information. The course of action also differs somewhat; the subdivision of core leaves the chain-base areas untouched, and (except for local identifiers) they are not re-initialised. When core has been subdivided GIN proceeds to : - Copy the program file from the load tape into the core or backing-store program-file, and display: RP. \\ \\ - Copy the workfile from the load tape into core, opening the backing store workfile when core is filled up. After this GIN displays: RW. Presetting information before #CORE \\ As when GIN is first loaded, the directives which may precede #CORE are all optional. However, in this case the default settings are the same as in the original compilation. For example, unless otherwise stated by a #NAME directive in the restore, the program file will have the same name as it did before, whether it was then specified by #NAME or left as preset. If a compilation is dumped and restored a number of times, the default settings are always those in force at the time of the last dump. \\ As a particular case, it can never be necessary to decrease the size of the program file or workfile in a restore, and it is only necessary to increase them if it is known that further compilation will cause the limits to be overstepped. Thus it will be unusual to specify the first parameter of #PROGRAM or #WORKFILE in a restore. \\ ==== EXAMPLE ==== To restore the GEORGE 4 compilation in 7.3 : LO#XK0F↑ Binary dump of #XK0F 0FR G4TAPE RES G4DUMP #LIS 3 #COR 180 #MEN PAGTABLE . . ===== 7.5 Controlling Peripherals ===== A number of directives are available to control input and output peripherals.\\ All input peripherals: #OFR, #USE, #FINISH \\ Cards and paper tape only : #READ \\ Magnetic tape for output only : #OFW, #RENAME, #SCRATCH, #DUMP \\ Magnetic tape for input : #RESTORE \\ Magnetic tape for input or output : #POSITION, #REWIND \\ All peripherals : #RELEASE \\ ==== Opening and allocating peripherals ==== At the start of a compilation GIN must possess CR0 or TR0, and may possess MT0. Other peripherals must be allocated by #OFR, #OFW or #SCRATCH.\\ #OFR \\ Specifies a device type and unit number and a name. For magnetic tape, opens (mode #100) a tape of that name. For slow peripherals allots a device and reads the first non-blank record, which must be DOCUMENT name. \\ #OFW\\ Opens the specified magnetic tape in mode #300. \\ #SCRATCH \\ Opens a magnetic tape in mode #600. \\ === Input === #READ \\ Causes input to take place from the specified CR or TR indefinitely. (Must not be in macro or from #USED peripheral). \\ #USE \\ Causes input to take place from the specified device until #FINISH is either read or simulated. (Must not be from #USEd peripheral). \\ #FINISH \\ When read from or simulated on a #USEd peripheral, causes source lines to be read from the peripheral from which #USE was issued. #FINISH will be simulated when GIN reaches the end of a subfile which was #POSITIONed on before #USE.\\ #RESTORE \\ Loads a program from a magnetic tape positioned by #POSITION.\\ === Output === #RENAME \\ Renames the specified output tape (already opened).\\ #BIP, #DUMP \\ See [[gin:chapter4#4.3 Dumping the Compilation|section 4.3]] === General control === #POSITION \\ Causes the tape specified to be positioned either at the specified subfile or at the end of the tape. A subsequent #USE will start from the first record in the subfile; a \RESTORE will load the first program in the subfile; a #BIP or #DUMP will obliterate the sentinel for the subfile (or the trailer label) and insert a subfile containing the dump followed by a trailer label. \\ #REWIND \\ Rewinds the tape; it should be followed by a #POSITION directive.\\ #RELEASE\\ Closes a tape or tapes and/or releases slow peripherals. \\ ===== 7.6 Loading other programs ===== The #RESTORE directive may be used to load from MT0 any program satisfying the restrictions given below. The tape must be positioned immediately before the request slip of the program. The restrictions on programs which can be loaded are: - When using #RESTORE in GIN versions up to GIN 512, the core size must be at least 9000 words, since this is approximately where the CONT in GIN is held \\ \\ - It is not possible to load a program #BIPped by GIN which has more than one overlay. \\ \\ The request slip is ignored except that the required amount of core is obtained. The supplementary request slip, if any, will be implemented in respect of branch and address modes. If these are unavailable GIN halts: MU. \\ The program file and workfile are closed. Other peripherals, (except MT0) remain as before. \\ The contents of the accumulators are the same as for #XK0F (see 7.1). \\ It is possible to use #RESTORE - To load a virgin GIN and start a new compilation.\\ \\ - To load a dumped compilation and continue it.\\ \\ - To load a non-overlaid #BIPped program.\\ \\ It is hoped that some of the above restrictions will eventually be removed. ===== 7.7 Operating GIN ===== Although full lists of GIN's halts and error messages are available elsewhere in the manual, the following details should be all that is needed in normal circumstances. ==== Loading GIN ==== GIN is usually held on a magnetic tape, which should be loaded initially. If using #XK0F to load GIN, put the #XK0F pack and data cards in a card reader and type LO #XK0F in or press the F button. GIN will be loaded and entered if #XK0F can find it: see [[gin:chapter7#7.1#XK0F Seek Program|section 7.1]] for #XK0F error halts. Carry on from the step #CORE time below. === Entry points === GIN can be entered at the following points : | 2O | Start compilation reading from a tape reader. | | 21 | Start compilation reading from a card reader | | 24 | Enter GIN postmortem, dumping core on a line printer. This is your last resort. It takes 3-6 minutes depending on core-size. At the end GIN deletes: AB. If it goes illegal there's nothing for it but a ten-thousand word OU. GIN occasionally enters postmortem directly. | | 25 | Standard entry point after MT load - should have a tape or card reader. | | 26 | Forces #DELETE - remember that GIN may spend several minutes listing the universals. | | 27 | Forces GIN to read the next source line. Can be useful in the event of tape failures during DUMP - just insert a corrected DUMP macro (or directive #BIP or #DUMP) in the reader and GO 27. In a GEORGE compilation GIN may attempt a #DUMP on the same tape before reading the card you inserted, if the failure was in dumping the loader-allocator. | === #CORE time === This can be recognised by GIN issuing a GIVE/4 causing its core size to be output on the console. After this the following are possible failures : | Halted CL or CM | Not enough core | | Halted PC | The program file (on disc) is not online | | ILLEGAL X |Can happen (on a 157 instruction addressing a control area whose first word is *01100100) when the program file is on drum but the machine hasn't got one. Some UDAS executives don't know about drums. | The halts can be remedied and you can then type GO; after the illegal it is necessary to restart with #PRO ,6 immediately before #CORE. \\ The display: ALTER 6 TO SERIAL NUMBER OF SCRATCH DISC can happen at any time after #CORE; the action required should be clear. If X6 is set zero, any online disc with a zero scratch-inhibit bit may be used. \\ A similar illegal to that mentioned above can arise when the workfile is opened: in this case the first word of the control area will be *01100600. If this happens, restart with #WOR ,6. In a restore, GIN should display: RP and RW in that order, after reading from MT0. === During running. === Normally while the job is running no action is required except possibly to load and unload tapes and reload printers. The following can happen occasionally : | Display: | LP | Paper low on the printer | | Halted: | F? | Where ? is almost anything - failure on an input or output tape. If possible, re-run with a different tape (input) or dump on another tape (output):see GO 27 above. | | Halted:\\ (?any letter) | D? | Drum or disc failure. X2 points to the five-word control area. Inform the engineer. DB can mean that the wrong disc file was chosen out of several with the same name. | | Deleted: | WA or WU | #WOR was too small | | Halted: | PO | #PRO was too small | | Display: | CI | #LOC was too small or the user is misusing macro recursion | but if any others turn up look at Section 9.1. === At the end. === GIN wi11 signal the end of a compilation by a DISPLAY about the number of errors in the run. Normally it then deletes: OK but if the #GO or #RESTORE directives are used another program - possibly GIN - is loaded.\\ ==== LOADING GEORGE ==== After a compilation or restore of GEORGE it can be loaded by loading a GEORGE Executive and typing DA or DR name DA if the program file is on disc, DR if on drum, and name as in the #NAME directive. ===== 7.8 Running GIN under GEORGE ===== GIN can be, and often is, run under GEORGE 3 or GEORGE 4 and the purpose of this Section is to give some hints on how this can be done. ==== GIN DIRECTIVES ==== #CORE \\ It should be realised that while under Operators' Executive the bigger #CORE is the faster GIN runs, under GEORGE 3 a large core size can slow down the whole system drastically or cut GIN out almost completely. Thus a considerable amount of trial and error may be needed to determine the best average value for a given machine, which will itself depend largely on what else the system is trying to do. \\ #PROGRAM and #WORKFILE \\ If these are on drum, this must be a filestore file and so cannot exceed 245K. If on disc, an exofile can be ONLINEd, or a filestore file ASSIGNed. In any case, the device types given to GIN and GEORGE must correspond. Some marks of GEORGE require a serial number to be specified for an exofile used as a workfile. Core program file and workfile are generally not efficient under GEORGE 3. ==== GEORGE COMMANDS ==== Probably the easiest ways of loading GIN under GEORGE are the following: - Use the FIND system macro to load GIN from an online magnetic tape. \\ \\ - Use #XK0F in exactly the same way as under Operators' Executive; if the parameters for #XK0F and the GIN source are in the same file as #XK0F there is no need to ASSIGN a slow input device. \\ \\ - Load GIN from a pre-existing filestore file containing it. \\ \\ In cases 1 and 3 GIN should be entered by ENTER 0 or ENTER 1 after the source file has been ASSIGNed. In case 2 #XK0F should be entered by RESUME. ==== TIME command ==== This will be necessary for all but the shortest runs. ==== PERIPHERAL ASSIGNMENT ==== === Slow input peripherals === Unless GIN was loaded by a version of #XK0F which is in the same file as the slow input source, you will need to ASSIGN or ONLINE at least one file as CRO or TRO. \\ A tape reader file should have been input in NORMAL mode. Any slow peripheral stream other than the first must be headed DOCUMENT name, and if it is to be read online there must be a DOCUMENT command for GEORGE as well. \\ === Line printer listing === LP0 must be ASSIGNed or ONLINEd. If more than about one hundred pages of Output are expected the file ASSIGNed should be a multifile, and should have a LIMIT qualifier allowing 60 transfers per page or more, e.g. ASSIGN *LP0, GIN LISTING (MULTIPLE, LIMIT 8388607) LISTFILE GIN LISTING, *LP ERASE GIN LISTING If #SUMMARY is used, LP1 must be provided in the same way. === Magnetic tapes === 0ff-line magnetic tape files need to be ASSIGNed; online magnetic tapes may be 0NLINEd, or the user can leave GIN to issue unanticipated PERIs. In the last case the serial number of the required tape cannot be specified, and the operators may be asked for a tape by name which they may be unable to identify. \\ An input tape should be connected by one of the commands : a. ASSIGN *MTn, file description b. ONLINE *MTn, magnetic tape description An output tape should be connected by one of the commands : c. ASSIGN *MTn, file descriptions(WRITE) d. ASSIGN *MTn, file description(EMPTY, TG( .... )) e. ONLINE *MTn(WRITE), magnetic tape description f. ONLINE *MTn(WRITE) For output tapes, "d" is used for creating new files and overwriting unwanted files, "c" if an existing file is to be extended. "f" is only used with the #SCRATCH directive, "e" with #OFW. \\ These commands can be issued at any time from the job description. It is possible, if at most eight tapes are used, to have different unit numbers for each tape and to open them all initially. This practice can of course lead to wasteful use of tape decks if the tapes are online, but is very useful for offline tapes. If this is not thought appropriate, the best way of getting the tapes connected is probably to insert a #PAUSE directive at the appropriate point in the source with a suitable message: for example : #PAUSE MT3 with corresponding commands 1 RESUME IF HALTED(MT), GO 2%;MESSAGE(3); . . . 23 AS *MT3, NEWDUMP(EMPTY,TG(ALL)) GO 1 If a secure tape is opened by an unanticipated PERI and the user has insufficient traps to it, the job may fail ONLINE *MTn FAIL. ==== PROGRAM FILE ==== The program file is unit 0 of its device type. It should be on a disc exofile if it exceeds 245K in size, otherwise it may be on a disc or drum filestore file. | Online disc | ONLINE *DA0(OVERLAY), (usn, filename) or unanticipated open mode PERI | | Offline disc | CREATE filename (*DA, BUCK1, KWORsize) ASSIGN *DA0, filename(OVERLAY) | | Offline drum | CREATE filename (*DR, KWORsize) ASSIGN *DR0, filename (WRITE) | ==== WORKFILE ==== The same rules apply as for the program file; the workfile is unit 1 of its device type. If it is on a disc exofile, several serial numbers can be specified in an ONLINE command; or if the Command is not to be used one serial number should be specified in the #WORKFILE directive. | Online disc | ONLINE *DA1(SCRATCH), (blocks, 1, #usn, ..., #usn) or unanticipated open mode PERI | | Offline disc | CREATE filename (*DA, BUCK1, KWORsize) ASSIGN *DA1, filename (SCRATCH) | | Offline drum | CREATE filename (*DR, KWORsize) ASSIGN *DR1, filename (SCRATCH) | In the above CREATE commands, size is the first parameter of #PROGRAM or #WORKFILE; in the ONLINE commands, usn is a unit serial number and blocks is eight times the first parameter of #WORKFILE. ==== EXAMPLE ==== The following example is of card packs to be input to compile a version of GIN : IN :USER, GINSOURCE, S#DEL #LIS 3 #PRO 10 #WOR 9,6 #COR 18 #OFR MT0 NEWGIN6 #POS MT0 GIN511 #DEF K0ALLGIN=4 #USE MT0 #OVE ENT5 #REL MT0 [SHOULD PRECEDE ASSIGN OR ONLINE COMMAND #PAU OUT #OFW MT0 DUMMY [NAME IS IRRELEVANT DUMP BIP,0,GIN5,GIN5 [ CONTAINS #BIP DIRECTIVE #DEL JB COMPGIN, :USER LO :LIB.PROGRAM GIN5 AS *LP0, GINLIST (MULT, LIMI8388607) LF GINLIST, *LP ER GINLIST OL *MT0, (36044,NEWGIN6) CE !(*DR, KWOR10) AS *DR0, !(WRITE) CE !(*DA, BUCK1,KWOR9) AS *DA1, !(SCRTACH) TI 5MINS EN 1 IF NOT HAL(OUT), GO 9ER AS *MT0, GINDUMP(EMPTY, TG(ALL)) RM IF NOT DEL(OK), GO 9ER 1 DP 1, END OF RUN ER GINSOURCE EJ ALL 9ER DP 1, ERROR EN 4 IF COR, PT 0(10000) GO 1 **** ==== MISCELLANEOUS NOTES ==== GIN keeps its own record of the magnetic tapes and slow input peripherals which are assigned to it. If GIN reads a directive to open or allocate a peripheral having the same type and unit number as one already open, the peripheral previously opened will be released. At present the new peripheral will not be opened until it is referred to, but the user must not rely on this. \\ For these reasons it is essential to ensure that GIN's records agree at all relevant times with the actual state of affairs. This effectively means that the directive #RELEASE should be used before opening or allotting a peripheral with a previously-used unit number and before any GEORGE command is issued to ASSIGN or ONLINE the new peripheral. (It is not necessary to use #RELEASE if the peripheral is a tape to be opened by an unanticipated open mode PERI). Failure to #RELEASE the old peripheral will lead GIN to free the new peripheral just connected by GEORGE command and attempt to open another one. If the peripheral concerned is a magnetic tape GIN will issue an unanticipated open mode PERI which GEORGE will attempt to implement; if it is a card or tape reader GIN will halt CR or TR. ===== 7.9 Writing Efficient GIN ===== It is no part of the function of this manual to explain how to write code which runs efficiently. However, it is possible to suggest ways of writing code which compiles efficiently. \\ Firstly, it must be recognised that many of the more advanced facilities of GIN will impose a certain penalty in compilation time if they are used to the full. However, if using them can produce a more efficient object program or one which is easier to maintain the gains to be obtained in this way will generally outweigh the loss in speed of compilation. The suggestions which follow should therefore only be applied in so far as they do not force the object program to be less comprehensible or efficient. The arrangement of a program can have a very considerable effect on the time taken to compile it, and indeed on the storage resources which are used. In particular, forward references can very often be avoided, and doing this will also produce a more informative listing. For this purpose, all data words used by a segment should precede the code if possible, and the code should start with frequently-used low-level subroutines and end with the routines that call them. \\ It is also economical to use short identifier names (but only if they are also clear and informative) and to arrange macros so as to take up the minimum of space. \\ A certain amount of improvement in efficiency will be found if the identifier and macro definitions most frequently used occur as close as possible to one another in the source stream. This will reduce the amount of rarely-accessed information that GIN needs to keep in core because it is near information that is often required. It is particularly helpful to keep all #INCLUDEs together. \\ Former versions of this manual advised users to define the most frequently mentioned macros and identifiers last. GIN has now undergone a change such that this will not bring about any substantial improvement in efficiency, although it will do no harm. ===== 7.10 The structure of a GIN program ===== This section gives an example of a GIN source stream which includes all the essential features of a GIN program. In some places excessive detail has been excluded. \\ The source on cards or paper tape is: #LIS 3 [PRODUCE FULL LISTING: S2.4 #PRO 8,6 [SET UP ENVIRONMENT FOR COMPILER: S7.3 #W0R 6,0 #COR 20 [CORE SIZE WANTED: S7.3 #DEF ASWITCH=1 [SET SKIPPING IDENTIFIERS BEFORE #DEF CSWITCH=1 [COMPILING FROM MT: S3.3, 3.7 #DEF K0PROG=3 [SET GENERAL LISTING LEVEL #INC OUTPUT3 [INCLUDE DIFFERENT VERSION OF SEGT: S3.7 #OFR MT0 SOURCE TAPE [POSITION TAPE: S7.5 #P0S MT0 PROGSUBFILE #USE MT0 [READ MT SOURCE #LIS 3 #DEF GB1=G76 [DEFINE UNSET UNIVERSAL #OFW MT1 OUTPUT TAPE DUMP MT1,DUMPSF [DUMP PROGRAM: S4.3 BIP MT1,BINDUMP,XKWK,CORESIZE,DBM,22AM #GO ENT5 [ENTER PROGRAM: S4.3 blank record On magnetic tape SOURCE TAPE, the subfile PROGSUBFILE contains the following data, possibly in several lower-level subfiles as required. #OPT K0PROG=0 [SET DEFAULT LISTING LEVEL #LIS K0PROG #OPT ASWITCH=0 [DEFAULT SETTINGS #OPT BSWITCH=0 #OPT CSWITCH=0 #SKI ASWITCH ( #MAC BIP [INTERLUDE FOR #BIP #INT #ORD REQ #73160001,4H%C,0,+%D+63/64:0,0,0,0,4H70←0,0,0,0,0,0,0 SUB 6,0,12H%B [NEW LINE IN CASE %B IS LESS THAN 12 CHARS 0,0,0,47?,48?,0,0,0,0,0,0,0,0,0,0 #STR DBM15AM,%E%F [SKIP IF %E = "DBM", %F = "15AM" ( SUPP #73100006,0 [SUPPLEMENTARY REQUEST SLIP #STR DBM,%E [SKIP IF %E = "DBM" #FID 21 21 1 [SET B21 OF WORD 1 #STR 15AM,%F [SKIP IF %F = "15AM" #FID 23 23 1 [SET B21 0,0,0,0,0,0 ) X EXIT 0 0 [LEAVE INTERLUDE #JUM X [ENTER INTERLUDE #STR DBM15AM,%E%F #BIP %A REQ,SUB,SUPP #STR DBM15AM, %E%F #STR [SKIP IF %E NOT "DBM" OR %F NOT "15AM" #BIP %A REQ,SUB #NOR ) # HERE FOLLOW OTHER MACRO DEFINITIONS #INC LOWPREST #INC INPUT2 #INC OUTPUT2 [SUPERSEDED BY #INC ON CARDS/PT #INC SUBS #SKI BSWITCH #INC MAINSEG4 [IF BSWITCH=1 #INC MAINSEG [FIRST VERSION MET IF BSWITCH=0 #INC OVER #INC OVERA #INC CHAP929 #OPT APROGLOWEST=36 [FIRST "LOWER VARIABLE" WORD #DEF ADATA=APROGLOWEST [SETTING UP A SERIES OF LOWER #DEF BUFFER=ADATA+1 [VERIABLES #DEF COUNT=BUFFER+32 #DEF ISPARE=COUNT+1 #DEF ABASE=ISPARE+5 [BASE OF FIRST OVERLAY #BAS RESIDENT +ABASE [FIRST OVERLAY MUST BE MULTI-SEG: S3.1 #SEG LOWPREST [FIRST SEGMENT #OPT K0LOWPREST=K0PROG [LISTING LEVEL #LIS K0LOWPREST CONTLP 2:0,0,121,+BUFFER.3 [PRESET DATA ERPAR 15:ERPAR+1, 15HPARAMETER ERROR . . . #END #SEG INPUT . . . CARDREAD [UTILITY SUBROUTINES LDX 7 CONTCR+1 . . . EXIT 0 0 . . . #END # MORE SEGMENTS FOLLOW: . . . #SEG MAINSEG [NORMAL VERSION #ENT 0 #ENT0 ALLOT 0 0 . . . #ENT 1 ALLOT 0 3 . . . #END #SEG MAINSEG4 [DEVELOPMENT VERSION #ENT 0 ENT0 ALLOT 0 512 . . . #END #OVE ENT0,H [HALT LD THEN GO 20 #BAS OVERONE BASMOVE [BASE OF NON-RESIDENT OVERLAY #SEG OVER . . . #END #SEG OVERA . . . #END #OVE [NO ENTRY BLOOCK REQUIRED #SEG CHAP929 [A CHAPTER (SINGLE-SEG OVERLAY) . . . #END end of source tape subfile