Ammendments to this manual have been added, dated March 1966
This document describes the compilation and loading processes used with the S3 Fortran compiler on Atlas 2. It supersedes the document "Fortran Loader on Atlas Two" published in April 1965.
The facilities described are those available in January 1966, except in chapter 2, where the preset job description described looks ahead somewhat. At present the following job description prevails:
OUTPUT PO FOLLOWS OUTPUT 0 PRINTER 50 PAGES 14 PRINTER 1 PAGE 15 CARDS 10 PAGES COMPUTING 5 MINUTES EXECUTION 5 MINUTES STORE 79K
The system is based on, and closely resembles, the Hartran system developed for the Atlas 1 at Harwell. It differs mainly in the use of a compact region of store, and in the ability to handle a PRELUDE interlude.
In general a job will consist of three distinct phases, compilation, loading and execution. Whilst execution always immediately follows loading of the program into store, the compilation phase may be omitted, altogether, or have been interspersed with compilations for other jobs. It is, of course , possible to compile routines without subsequent execution. The Atlas 2 supervisor program handles the scheduling of all jobs, and must be informed of the type of job to be run by means of a special card, actually the first of the program deck.
In the compilation phase the program is processed so that all routines written in FORTRAN are replaced by an equivalent relocatable binary version, providing a form of the program suitable for the loader. The compiled form of a routine is also punched onto cards. It is known as BAS (Binary and Arbitrarily Symbolic).
References entirely within a routine are resolved by the compiler, except for private arrays, whose positions relative to the routine are determined by the loader. References to public symbols such as subroutine names remain in a condensed symbolic form to be resolved during loading. All optimisation of object code occurs during compilation. It is not modified in any way by the loader.
During the loading phase BAS routines, resulting from the compilation phase or from binary cards produced by previous compilation, are loaded. That is, each is placed in the core store in the position at which it is to be executed with all the necessary adjustment of internal addresses (relocation). References to other routines are completed at the earliest opportunity. If necessary, the loader will remember a reference until the required subroutine appears.
Whilst the majority of jobs are capable of being contained within the core store, some are not. Special provision has been made for these jobs, but because of their comparative rarity, discussion is confined to Chapter 7.
A library of standard subroutines, including the input/output package, is included within the system. Whenever an entry directive (or new chapter directive in the case of a chain job) is met, and there appear to be missing subroutines, the library is scanned to select the required routines. If some cannot be found, a message is printed.
Provision is also made for the use of a private library tape. Details may be found in Chapter 7.
The S3 compiler produces object code for COMMON variables in an absolute form using a COMMON list. This list contains one location for each COMMON variable name used. In the case of a scalar this location contains the value of the variable, but for an array it contains the base address of that array. The actual allocation of COMMON array storage is under the direct control of the programmer, who must, if he is using COMMON arrays, provide a subroutine PRELUDE to set their bases. The inclusion of a PRELUDE is not mandatory, and it can be omitted if not required.
Locations below 100 (decimal) are used for special purposes and should not be altered. The COMMON list starts at 101. The first routine will be loaded immediately after the COMMON list, which is presumed to be satisfactorily defined by that routine. No subsequent routine must have a longer COMMON list. Chain jobs will normally begin their chapter region at location 10240, but this can be modified if required. Whilst the remaining part of the store is entirely at the disposal of the programmer for COMMON arrays, it is preferable from the point of view of overall efficiency of the supervisor S3 complex for common arrays to be given store immediately above the end of the program, which is printed by the loader. Loader work space commences at approximately 81K. Space above this is only available for COMMON arrays.
later commenced at 26K (25.5K if a library is being written)
A simple job, not requiring any compilation, not using any form of backing store, and using only READ, PRINT and PUNCH statements for input and output, could consist of a card deck made up as follows (Using $ to represent a column with 7 and 8 punched):-
123 80 Column numbers $GO (Job Title) N Heading Card with Job Title OUTPUT 0 PRINTER 30 PAGES ) OUTPUT 15 CARDS 100 CARDS ) Job Description Sections COMPUTING 5 MINUTES ) $ U End of Job Description the subroutine PRELUDE ) Only if a PRELUD.3 is required * ENTERPRELUDE prelude data ) the program * ENTER the data to be read by the READ statements $ End of job
where the symbol $ means that the card concerned has column 1 punched in rows 7 and 8.
A job description always starts with a card bearing a 7, 8 punch in column 1 , and N in column 80. Starting in column 2 is a keyword indicating the type of run. There are three possibilities:-
GO if no compilation is required, FORTRAN if just compilation is required, FORGO if both compilation and execution are required,
Heading cards, and all other warning sequence cards with 7/8 punches, will normally be available already punched.
The Job Title may appear either on the heading cards after the type word, or on a separate card. If a separate card is used, it must immediately follow the heading card. It nay be punched starting in any column, but should have been terminated by a close bracket ) in or before column 71. It should start with an open bracket ( and is followed by the code part of the job title, which may be divided into two parts by a stroke /. The code part commences with an installation letter, and ends after 16 characters (possibly including a stroke) or a second stroke, whichever comes first.
The code should identify the job uniquely, as it will be used for communication concerning the job by the operators and for logging purposes.
The body part of the title commences with either the character following the second stroke or the 17th character, and will end either 48 characters later or with a close bracket ).
The body of the job description consists of a number of cards giving information about various aspects of a job, such as documents required and produced, tapes required, length of execution and so on. Normally each card bears a section name, although this may be omitted if it is the same as the preceding card. Note that continuation cards are not allowed, so that any one definition must be punched within the first 72 columns.
Cards for the individual sections do not need to be adjacent to each other, but may have cards from other sections interspersed among them, provided, of course, that each bears a heading.
This section is not compulsory, and will probably be omitted from most jobs. It is necessary whenever input is required on a stream other than zero (e.g. by READ INPUT TAPE 2). The section is announced by the word INPUT, and consists of input stream definitions. Up to 16 separate input streams are permitted (numbered from 0 to 15), and these may be read at any card reader or paper tape reader. The program refers to the logical number of a stream, and the job description allows this to be correlated with a title appearing at the head of an input document.
The title of a document must be unique or confusion may arise. Since the code part of the job title is itself unique the corresponding part of the document title may be constructed from it in the following way. Within a single job description, if a document title appears to start with a stroke, then that part of the job title before the stroke is automatically inserted. The part of the code of the document title following the stroke may then be used to distinguish documents within the same job.
The actual documents to be read must have the full part of the code punched out, to avoid confusion. It is also wise to use a warning sequence punch, that is the input document is headed by a card with a 7,8 punch in column 1, then the title of the document within brackets, and finally an N in column 80. The warning sequence punch ensures that this document is handled correctly, even if the preceding one was incorrectly terminated.
Input stream 0 is always defined as the untitled document (if any) following the job description. This will normally include data to be read. There is no need to mention stream zero in the job description unless there is something unusual about it, for example it may be exceptionally long.
Should it be necessary to refer to stream zero as following the job description, the word FOLLOWS is used in place of a title.
The word LONG-= may be inserted between the stream number and title to inform the supervisor that the particular document referred to is exceptionally longj, more than a tray or two. Special arrangements may then be made with the use of backing store which would aid efficiency.
INPUT 2 (title) INPUT 3 (title) INPUT 0 LONG FOLLOWS
This section is announced by the word OUTPUT, and like the input section consists of a logical stream number, notes and a title. The title is optional. The notes specify the destination of the output stream and usually the amount of output expected. Up to 16 output streams are permitted, numbered 0-15.
Associated with the FORTRAN statements PRINT and PUNCH are the logical output streams 0 and 15 respectively. It is only necessary to define these streams if the output limit required is other than the standard value. All jobs within the system will automatically have the following output sections:-
OUTPUT 0 PRINTER 50 PAGES OUTPUT 14 PRINTER 1 PAGE OUTPUT 15 CARDS 10 PAGES
Note that these limits do not apply to the compilation phase of a job.
The following list gives the key-word appropriate for output on different media:-
PRINTER line printer CARDS (or CARD) card punch PUNCH 5 ) PUNCH 7 ) paper tape punch, various widths PUNCH 8 ) TELEPRINTER (or TELE) teleprinter NONE will suppress an output
This follows the destination and takes the form of an integer followed by a suitable unit such as CHARS (for characters), PAGES, CARDS. If no limit is specified, it is assumed to be 50 pages or blocks of buffered information, which corresponds to rather more than 50 line printer pages.
It is essential to specify a title for these; the inferred title will not do. On all output streams going to peripherals the job title appears first followed on the next line (card) by the word STREAM and the number. The specified title follows on a fourth line and. then the document itself. If the first two cards are removed, then the remaining cards are all ready for reading with a subsequent job.
Each tape has a very special first block (block 0) which contains certain information of use to the supervisor. This information cannot be altered directly by the programmer - only by the supervisor under directions contained in the job description. Each tape has a number of the form P1234, identifying the installation and tape within that installation. The number can only be altered by the operator. Also in block 0 is the tape name which the programmer may write when he originates a tape or read and check when he uses a private tape he has used before. In both cases these operations are done by the use of special extracodes.
Tape titles are divided into two parts by a stroke / as with other titles, but the meaning is different. The first part is the tape number and the second part is the tape name. As before, titles are enclosed within brackets. The basic job description format is similar to that of the input and output sections and consists of the logical number (in the range 0 to 15) followed by notes and then the tape title. The section is announced by the word TAPE or TAPES.
No notes are needed. An example is
TAPE 5 (P1234/STANDARD TABLE OF DATA)
TAPE 6 READ (P1235/STANDARD TABLE OF DATA)
Any attempt by the programmer to write to this tape would, cause immediate monitoring of the job.
He refers to the tape in the following way
TAPE 7 NEW (P1236/PRESSURE DISTRIBUTION)
The phrase PRESSURE DISTRIBUTION is ignored by the supervisor. The main effect of TAPE NEW is to upgrade any grey (suspect) blocks on a tape to black so that they are not subsequently used. TAPE NEW should not be used once there is useful information on the tape.
Frequently tapes are used as working spaces and do not need to be retained when the job is completed. In this case neither a number nor a name need be specified and instead the word BLOCKS is given followed by the range of blocks (512 words) required. For example
TAPE 11 BLOCKS 400
The plates of the disc are referred to by logical number (in the range 0 to 15) and the number of blocks (512 words) used is specified as with working space tapes. The word DISC is used in place of the word BLOCKS. For example
TAPS 10 DISC 25
means that 25 blocks of working space are required on the disc, and will be referred to as backing store stream 10.
Although each plate contains 512 blocks, the supervisor will continue onto another plate(s) if the number specified is greater than 512.
The half inch IBM tapes do not contain a magnetically written number, but a number and title are given in the job description so that the operator can identify the tape. A tape of this type is indicated by the note IBM e.g.
TAPE 12 IBM (A2790/IBM FILE TAPE)
If the note LOW is added after IBM, low density mode will be set. Otherwise high density is assumed.
This is announced by the word STORE, and consists of estimates of the form n K, where K = 1024 and n specifies the amount of core store to be used. For example
STORE 40K
sets a store limit of 40,960 words. If no STORE section is specified, 40K is assumed. Monitoring occurs if the limit is exceeded. The maximum permitted size is 98K.
When magnetic tape is being used either through the READ TAPE etc. statements or by calling xxLIBRF, then it is necessary that the store size specified, +nK where n is the number of tapes in use at any one time, be less than 102K.
There are two entries possible, one for computing time, and one for execution time. Each appears on a separate card with the words COMPUTING or EXECUTION followed by the amount of time to be expended, for example
COMPUTING 6 MINUTES EXECUTION 1 HOUR EXECUTION 20 SECONDS
The numbers are decimal integers.
Computing time is taken as an estimate of the actual computing time to be used, whereas execution time is the total time spent including tape transfer times. Any time specified is applied individually to the compilation and execution phases of a job. I.e., a job consisting of 2 minutes compilation and 4 minutes execution might well contain the specification COMPUTING 5 MINUTES. Note that the time printed in the program log is for the execution phase only of FORGO jobs.
If neither computing nor execution limits are declared, then 1 minute is set for both. If just one is declared, it is automatically assumed for the other also.
If a job is such that its expected time of execution is quite short, but it might take much longer, this fact may be communicated to the supervisor scheduler by specifying two times on the COMPUTING or EXECUTION card. The first is taken as a maximum, and the second as an estimate of the expected time. E.G.
EXECUTION 15 MINUTES 5 MINUTES
The whole of the system is directive controlled. This means that a directive of some sort is always required to initiate an operation, generally the processing of subsequent cards. Directive cards are distinguished by the presence of an asterisk in column 1. The type of directive is defined by columns 2-8, within which the key word must be left adjusted. The remainder of the card may be used to specify further information, and a free format is allowed, except on two directives which are not normally punched by hand. Several lists or expressions may appear, each terminated by a comma or column 72. Expressions, when allowed, may be a sum of products of constants and known identifiers. They must not contain brackets, divisions or identifiers whose value is not yet defined. An identifier is frequently a routine name, but may also be a parameter defined by a DEFINE directive. A constant may be written in decimal or octal or a mixture. An integer is presumed decimal with a single octal fraction digit of zero. If a point occurs, it marks the end of the decimal part of the number, all subsequent digits being regarded as octal. The composite number is right adjusted within a halfword according to the number of fraction digits specified. When using octal store locations, a final zero must usually be added E.g.
10 appears as 00000120 10. 00000012 10.0 00000.20 .123450 00123450
Within expressions, spaces are ignored. After the last expression on a card, a comment may be introduced by $ if desired.
The directives of the system are of three main types, for entry, routine introducers, and symbol manipulation, together with several miscellaneous directives.
It is necessary that the subroutine PRELUDE should obey a few simple rules, because it is executed at a rather special time in the middle of the loading process.
The maximum length of the COMMON list will normally be defined by the prelude, since it will normally be the first routine loaded.
Columns 1-4 *BAS 9-16 The name of the routine, left adjusted. 17-23 The entry point, relative to the routine origin. 25-31 The length of the routiner1 33-39 The number of auxilliary symbols defined (always zero for an S3 routine) 41-47 The length of the COMMON list 50 Indicates origin of routine (A,blank: ASP; 3: S3; V: SRC Fortran)
All other columns from 5-48 must be blank.
All numbers are in octal and right adjusted. Leading zeros are optional.
The term auxilliary symbols includes subsidiary entry points.
All binary cards are distinguished by having rows 7 and 9 of column 1 punched. Each card normally contains up to 16 words of information. Columns 73-80 can be used for labelling and serial numbering - they are not inspected by the loader. Each information word occupies 4 columns on the card, the most significant bit appearing at the top (+ row) of the first of the four columns, the first column being completed before the second is started. Relocation bits are available for each halfword of information. They are arranged in columns 2-4 and start at row + of column 2 for the first halfword, continuing down column 2, then 3, then 4 for each halfword for which the card contains information. The loading origin for the card (relative to the routine origin) and the checksum.each occupy a pair of columns and are regarded as half word quantities. The checksum is such that the sum of all column pairs, from 1 to 72, computed with end around carry over 24 bits, is octal, 77777777. The checksum calculation is ignored if the checksum is itself zero or row 0 of column 1 is punched.
The format may be summarised as follows:-
Column 1 row + punched unless last card of a routine row 0 punched to ignore checksum rows 2-6 count of number of information words on card rows 7, 9 punched to indicate binary Columns 2,3,4 relocation bits Columns 5,6 checksum Columns 7,8 loading origin Columns 9-72 up to 16 information words Columns 73-80 label etc.
These directives may appear anywhere within the deck, except within a routine, and there may be any number of them. They allow manipulation of public identifiers, i.e. those names used for inter routine communication. Continuation cards are not allowed - further directives must be used.
*RENAME C = A, A = B, B = C
Examples
(l) Routine A calls routine B which does not exist. Routine C is available with the same specification as B. After routine C use
*RENAME B = C
(2) Routine A calls routine B which does not exist. Routine C is available with the same specification as B, but is called from other routines as C. After routine C use
*DEFINE B = C
Column 1 | Form of new word | Layout in columns |
---|---|---|
Blank | Basic instruction | 2-4 remainder of function (octal) |
0 | 6-8: Ba (octal) | |
1 | Extracode instruction | 10-12: Bm (octal) 13 on: S (expression) |
H | Halfwords | 2 on: expression, expression |
T | Text | 5-12: characters |
Greater generality is allowed in the expressions on amendment cards than on directives themselves. In particular * may be used as a symbol meaning the current location. Also, references to undefined symbols are allowed provided that they are purely additive e.g. A + 2, B, A + B but not -A.
This chapter describes the whole of a FORTRAN type job, or the first phase of a FORGO job. The former is simply the processing of a succession of FORTRAN or ASP routines, producing for each a printed listing, a report on the compilation, and relocatable binary card output. Each routine is processed entirely on its own merits. It is compiled without any reference to any other routine and the faulting of a routine does not inhibit the processing of other routines. The finding of an error in a routine does not stop compilation of that routine immediately. The compiler attempts to get as far as it can, but of course some errors will be regarded as sufficiently serious as to render further compilation processes inappropriate.
A FORGO type of job involves not only this, but transforming the input stream into one suitable for the loading process, i.e. it generates an internal stream similar to that provided by the programmer, but in which every FORTRAN or ASP routine has been replaced by its relocatable binary (BAS) equivalent. A compilation failure leads to a gap in this stream, and such a job is likely to be faulted during loading for missing routines. Note that mis-punched directives will not be detected until the loading stage.
The end of the processing in the compile phase is indicated by one of the directives *END, *ENTER or *ENDCOMP. It is normal to use *END in a FORTRAN type job, and one of the other two in a FORGO job. Failure to use any of these directives will result in an error stop on fault 11.
The output from the S3 compiler may include
If errors have occurred during translation, some of this output may not occur.
The output from the ASP assembler consists of side-by-side listings of the written instructions and the generated code.
Finally, END OF COMPILER STREAM 0 is printed.
The BAS routine resulting from a compilation consists of
Note that detection of errors during translation may prevent binary cards from being produced. Some errors will cause the S3 compiler to produce a *NONEXEC card after a complete routine. Other errors cause the ASP assembler to produce a binary lacey failed card as part of the routine. Finally, END OF COMPILER STREAM is punched.
Diagnostic messages may appear either at the end of the listing of the Fortran cards, or interspersed. In the latter case the diagnostic refers to the penultimate statement, and not that immediately preceding the diagnostic. For some types of diagnostic originating while a statement is being analysed, the diagnostic message shows the later part of the statement that could not be processed. This will usually determine the position of the error within the statement.
The loading process operates upon a stream of routines in BAS, interspersed with various directives. In the case of a GO type of job this stream is precisely as provided by the programmer. If there has been a preceding compilation phase, the stream is the relocatable binary equivalent of that which the programmer provided. In either case routines occur and are loaded in the order in which they are placed.
Loading continues until an entry directive (3.2) is met, whereupon library routines are called to complete the program which is then entered via. a special library routine known as the executor. The executor performs initialisations of various kinds which cannot, in general, be done by the loading system itself. The executors used for entry through *ENTERPRELUDE and *ENTER are different.
The loader first prints out the time and date when loading began. When all routines provided, and those required from the system library, have been loaded, the heading GLOBAL is printed followed by a list of the entry points to each routine, with the relocation origin of the routine, as an integer, and the value of the entry point, which may in some cases include an octal fraction. Similarly public arrays (arrays in the program area, as distinct from the COMMON area. They are not included in the S3 Fortran language) are listed giving for each its length, as an integer, and its base address. Then, if any parameters have been defined by *DEFINE cards, their values are printed. Lastly, the first location not used is printed, giving the total size of the program. All numbers printed are entirely in octal.
When a PRELUDE is provided, the lists of identifiers and their values will be printed for both the PRELUDE and the main phases of the job, the former being preceded by the heading PRELUDE instead of GLOBAL.
Various messages, both diagnostic and informative, nay be printed during loading. Some faults are regarded as so serious, that it is most unlikely that execution could be meaningful, and so it is prevented, unless the programmer deliberately specifies otherwise.
During program development it nay be found useful to have the system directives printed. This may be achieved by including the directive *SUMMARY (3.7), which forces most subsequent directives to be printed, in particular the program card of each routine.
At the start of loading various constants, etc. required by the library or S3, compiled routines are placed in store. These constants, etc. should not be modified by PRELUDE, or in any other way.
The information used directly by S3 Fortran routines is:-
location constant (octal) notes 99 40000000 00000000 floating point zero 98 00000000 00000000 97 03000000 00000000 integer zero 96 06400000 00000000 used in truncation 95 03000000 00000000 high half for positive short integer 94 03177777 00000000 high half for negative short integer 93 00077777 77777777 1 - epsilon 89 00210000 00000000 floating point one 88 00220000 00000000 floating point two
In addition to these constants, a routine for integer multiplication occupies locations 77 to 84.
There are also three arrays used by library routines
name length (dec.) base address (dec.) purpose LIBRTAB 16 32 used with magnetic tape routines, /IOU 16 48 used with input/output routines. ERRDUMP 8 64 holds SETEDMP information.
The S3 Fortran compiler handles COMMON variables by means of a list, one cell per COMMON variable (irrespective of whether it be a scalar or array), starting at location 101 decimal. The length of the COMMON list is implied by the first routine loaded, which must therefore contain the maximum COMMON list length. It is regarded as an error if a subsequent routine has a greater COMMON list length. Note that a PRELUDE will define the length of the list for the whole job.
The COMMON list is initialised to integer zero when it is defined. It is not altered subsequently by the loader.
Not all programming errors can be detected by the compiler since routines are compiled independently and it is only at load time that they are linked together and incompatibilities can arise and be detected. Other errors may be the result of inserting directives as well as syntactic errors in the directives themselves. The loader therefore checks certain items and prints appropriate messages when errors are found.
Each message will be preceded, if necessary, by the offending directive, or the name of the routine in which the error is found. Some error printing is no more than a comment. Other errors are regarded as sufficiently gross as to nullify the loading process, and execution will therefore be prevented unless a *GOGOGO directive is used. The phrase EXECUTION DELETED follows each diagnostic of this type. It is also possible that the loader may find itself incapable of proceeding further with the loading process. In this case a message is printed giving the reason, and also the name of the last routine to be loaded, either completely or partially.
A list of messages is given in appendix 1.
The first line of any output document consists of the title of the job and the date of the run. In FORTRAN and FORGO jobs output during compilation is headed COMPILER STREAM 0on the line printer and COMPILER STREAM 15 on cards. FORGO and GO jobs have the execution phase output headed STREAM n. All system output appears in stream 0, except detailed diagnostics from the transfer package, which appear in stream 14.
In FORGO and GO jobs stream 0 consists of loader comments, probably a storage map, and finally the word EXECUTION, which indicates that loading is over and any further output is from the program. Upon reaching the end of the job (by calling EXIT) the comment END OF JOB appears in stream 0, followed by the positions of all magnetic tapes, and then all output streams are terminated by the message END OF OUTPUT STREAM n. For streams 1-13 these messages always appear on a new page if output has been produced by the program, otherwise on the same page as the heading. In the case of streams 14, 15, the comment does not appear if there has been no output on that stream.
The first part of the printing is produced by the Atlas supervisor on Stream 0. This is followed by the comment JOB TERMINATED, then the positions of tapes, and finally any *SETEDMP dumps which have been requested.
The supervisor heads its output with the word MONITOR and then FAULT n AT m where n is the fault number and m is the current value of the main control register. If m is within the programmers region of core, this is followed by a print of the machine instructions at that location, and the previous three locations. Otherwise (faults 2 and 4) no instructions are printed.
A full list of fault numbers is given in appendix 2. Faults 0-39 are detected by the supervisor or computer, and result in an immediate stop, or within two instructions. Faults 40-49 are detected by the library routines. Faults 50-89 are detected by the supervisor or computer, but the point at which the machine stops is likely to be much further on in the program than the instruction which initiated the action which failed. Faults 90-99 are supervisor detected or provoked, and are similar to those in the range 0-39.
Amendment 16.3.66
The terminal printing of a job which ends abruptly has been modified. If a job monitors, i.e. the supervisor prints out FAULT n AT m and the B registers, this is followed by JOB TERMINATED BY SYSTEM AT LOCATION 01234560 and then any error dumps etc. as before. The location is in octal. Actually, at the time of writing the location does not appear, but will do shortly.
If a job terminates by calling EEXTT, then the comment JOB TERMINATED BY EEXIT is printed, on a new page, followed by FAULT 42 AT m after which the supervisor provides the contents of all B registers, and then any error dumps are printed.
The Atlas supervisor provides a means, known as trapping whereby the programmer can take remedial action if he desires. This flexibility is not at present available to the S3 programmer, but may be used in ASP subroutines. If a trap is set for a particular fault number, then control is transferred to a specified address rather than to tho supervisor monitor should a fault of that type occur.
Other faults for which traps are not set monitor as described in Section 6.2. For further information, supervisor documentation on the use of traps should be consulted.
The transfer package is designed to stop as soon as any error is detected, irrespective of whether the transfer involves input-output or magnetic tape. This action can be modified by calling the routine TPERRS with two arguments. The first argument is the maximum number of recoverable errors permitted (if -ve, an infinite number). The second argument is zero if short messages are required in the current output, and non-zero to suppress such printing. The normal settings correspond to
CALL TPERRS (1,0)
There are three circumstances under which magnetic tape may be required for a program. Firstly, a frequently required program may be stored in loaded form on magnetic tape, so that it is not necessary to read cards for and relocate the program each time it is run. Instead, a transfer from magnetic tape is sufficient to load the program into core store.
Secondly a job may be so large that the program cannot all be contained within core store at one time. This is known as a chain job. It must be split into a series of chapters, only one of which is in core at any time. Of course it might be required to re-run jobs of this sort, and the re-run facilities extend to chain jobs.
Thirdly, use may be made of a private library tape to hold standard pre-compiled routines. Such tapes may be easily prepared.
Throughout this chapter the word tape implies either one inch tape or disc, although the latter or working tape is not of course meaningful where the use implies preservation of information from one run to the next. It is not possible to use half inch tape for any of the purposes described in this chapter.
A chain job is written as a series of chapters. Each chapter has a distinct chapter number, which is usually written as an unsigned integer. Each chapter consists of a number of routines of which one is the main program. Chapter 0 is treated specially and does not need to have a main program. It is synonymous with GLOBAL (see below 7.3.2).
During loading, when the last routine of a non-zero chapter has been loaded, the library is scanned to find routines required to complete the chapter, which is then written to tape, accompanied by a comment stating where on tape it has been put. Usually the same tape is used for the chapters of one job, but not necessarily.
The execution of a chain jobs starts at the first executable statement of the main routine of a specified chapter, preferably the last one loaded. To change chapters two library routines are provided.
CALL CHAPTR (n) or CALL CHAIN (n)
causes chapter n to be read from the chain tape to the chapter region of store and entered at its main program.
If n is zero, or the chapter is already in core, no transfer from tape takes place.
Since use of magnetic tape is always likely to result in delays while searches are made, it is better to position the chain tape ready for the next chapter just as soon as its number is known.
CALL NEXTCH (n) causes the chain tape to be positioned at the nearer end of chapter n. Chapters can be read from tape either backwards or forwards.
Communication between chapters is provided by the GLOBAL region of the store. This section of store is not affected by chapter changes, and can be used for both storage of global variables and for routines common to several chapters.
It can even have a main program and be entered as any other chapters, but of course without any tape transfer.
Any routines which appear before a *CHAPTER directive (see 7.3.3) or in chapter 0 are automatically upgraded from their initial chapter status to global mode. So also are any routines or public variables referred to by these routines.
To force a library routine or public variables, not explicitly mentioned in chapter 0, to have global mode, use the directive *GLOBAL which expects a list of names in columns 9-72. This directive must appear before any other mention of the identifiers concerned. Note that all subroutines called from a global routine are automatically updated to global status, provided that they had not previously been loaded into the chapter region.
Note that it is not possible for the same name to be used for entities in both the global region and a chapter without renaming.
The effect of the *LIBR directive (see 3.8) is modified slightly in chain jobs. When it is met, the complete list of entry points is scanned. If at least one is required, the following routine will be loaded. If any of the requests were of global status, then the routine is loaded into the global area. Otherwise it goes into the chapter area.
All the routines of a chapter are placed together and the whole preceded by the directive
*CHAPTER n
where n may be an expression, but is usually an unsigned integer. The chapters of a job are then placed together with chapter 0 first, and the whole preceded by the directive
*CHAIN i j k
where
i is the logical number of the chain tape or disc,
j is the number of the first block to be used on that tape,
k is the highest chapter number of the job.
If k is omitted, 8 is assumed. If j is also omitted, 1 is assumed.
The *CHAIN directive will usually be the first after PRELUDE data. If there is no PRELUDE, place it after the first routine and before the second *CHAPTER directive.
A special system array is used to record the positions (in core and on tape), length and entry point of each chapter. It also contains the logical disc or tape nmber, so it is possible to use more than one tape or disc to contain the chapters of a job. Simply insert a *CHAIN directive immediately after the *CHAPTER directive of the first chapter to go on the new tape.
Entry to a multichapter job is obtained by
*ENTER expression
where tho value of the expression is the number of the chapter to be placed in core store (if it is not already there), and its main program entered.
A chain job may be repeated by using the directive
*RESTORE l, m, n
where l, m, n are integers as printed out during loading by the comment
GLOBAL TAPE l, m, n
Execution is then obtained with *ENTER p where p is the chapter no. It is, however, necessary to ensure that the tape(s) containing chapters have the same logical numbers as they did during the original loading.
*COPY 1, m, n where l is a tape number m is the position of a chapter n is the length of that chapter
enables a single chapter to be copied from a chain tape to the place specified by the last *CHAIN directive, which will normally be on the disc. The values of m and n for separate chapters were printed when the tape was written.
If it is desired to change just one chapter of a chain job, use *RESTORE to set global, followed by *CHAIN and * CHAPTER and routines for the revised chapter. Since after * CHAIN global is always written to the chain tape immediately following the last chapter 3 care should be exercised in the choice of position on the *CHAIN directive. If it is desired to overwrite the old version of the chapter (assuming that the number of blocks required by the new one is not greater) then use the sequence
* CHAPTER *CHAIN n, m *ENTER p
where n, m define the position to which it is required to write the global area. The original chain tape may be preserved, and a new one generated, by use of the *COPY directive described in 7.3.5.
The first part of store contains the preset constants, etc and then the COMMON list in the usual way. This is followed by the global routines and arrays, which are allowed up to location 23777 octal (10239 decimal). The chapter region, which is the part replaced at chapter changes, starts at location 24000 octal (10240 decimal). COMMON arrays will normally occupy the highest area of store.
If the preset chapter origin is inconvenient, it may be changed by the directive
*CHORIGN expression
where the value of the expression is the required chapter origin. If the value is not a multiple of 512, the next highest multiple is taken. This directive must only be used at the beginning of a chapter. If desired, each chapter may have a different origin.
*WRLIB l,m,n
indicates that succeeding directives and routines are to be written to a library tape in addition to the normal loading process.
1 is the logical tape number m is the first block to be used on the tape n is the number of blocks on tape available for the library
If n is omitted, 4096 is assumed. If in is also omitted, 1 is assumed.
The process of forming the library ceases as soon as the directive
*ENDLIB
appears on the input stream. This directive is written to the tape to signal the end of the library.
It will be usual to include only routines and *LIBR directives in a library, but in fact any other directive may be included. When using *LIBR with a hierarchy of routines, always make sure that the calling routine precedes those called. Otherwise the latter will not be included in the loaded program unless one inserts *CALL directives for each routine. Generally a job preparing a library is not good for execution, so end it with the directive *END.
Note that it is not possible at present to obtain part of the data for a new library from an existing one. The *LIBRARY directive is copied across to the new library, but thereafter nothing more is copied until after the library is scanned, and input is resumed from an input stream. Such a directive will be ignored when the new private library is subsequently scanned.
Amendment 16.03.66
Beginning with version N of the loader, the writing of a private library is a process completely independent of loading. This greatly eases the writing of libraries containing *LIBR cards for true optional loading, and avoids unnecessary diagnostic messages. Symbolic cards will be copied across without checking, but binary cards will be checked as far as practicable, i.e. checksums, sequencing of S3 routines, and correct termination.
For some purposes a library with true optional loading may be regarded as a frill, and no *LIBR cards inserted. The penalty is that if one wishes to replace one library routine by a new version, then provided the new one comes before the *LIBRARY directive, the required effect is obtained, but the presence of a routine with the same name in the library will give rise to a diagnostic of the form ROUTIN ALPHA PREVIOUSLY LOADED.
It is possible to write one or more sections of a library tape within one job, and then to use it or them to load routines.
*LIBRARY n1, n2 where n1 and n2 are expressions, causes a private library on tape n1, beginning at block n2, to be scanned immediately. Any routines which had previously been called but not provided will be looked for and loaded if present. Any further calls are satisfied likewise. Scanning of the tape ceases where all calls are satisfied, or when the directive *ENDLIB is met. Loading then continues normally, no complaint being rendered about any missing routines at that stage.
This directive may appear anywhere within a program deck. It may be used more than once, and may refer to different libraries. Use of it does not preclude use of the system library.
Routines may -be explicitly called by means of the directive *CALL, which expects a list of names in columns 9-72. In a chain job, in order to force a library routine into the global rather than chapter region, use the directive *GLOBAL instead (see7.3.2).
A main program has by convention a name consisting of all blanks. It is not possible to refer to such a name by a *CALL directive. Instead, compile the routine as though it were a subroutine, e.g. SUBROUTINE MAIN3. Then to use it as a main program have
*CALL MAIN3 *LIBRARY n1, n2" *RENAME =MAIN3 *ENTER
This sequence would result in the main program, plus any subsidiaries required, being loaded from the private library, and then being executed.
In this appendix a complete list of loader messages at the time of writing is given. For convenience it is divided into four sections.
1. Gross errors after which loading cannot continue.
2. Serious errors which result in execution being prevented.
3. Minor errors which are not in themselves serious.
4. General comments which arise under certain conditions.
Most messages include the name of an identifier. For the sake of example, the words ALPHA, BETA etc, are used where such names would occur in actual examples. Where a message includes numbers, typical values are shown. Comments to ease understanding messages are given in lower case. A line containing the word directive preceding a message indicates that the offending card will be printed out. When the message can only follow certain directives, this is indicated.
EXECUTION HAS BEEN DELETED. JOB TERMINATED GLOBAL AND CHAPTER REGIONS OVERLAP. JOB TERMINATED This check takes place at the end of a chapter. GLOBAL LENGTH READ FROM TAPE DISAGREES WITH THAT SPECIFIED, JOB TERMINATED After an invalid *RESTORE directive. directive (*CHAIN) HAS NOT BEEN PRECEDED BY SETTING OF COMMON LIST LENGTH, JOB TERMINATED directive (*RESTORE) LENGTH SPECIFIED IS TOO SHORT. JOB TERMINATED Number of blocks is less than eight directive LIBRARY RECORD SEPARATOR ERROR AFTER ABOVE DIRECTIVE. JOB TERMINATED NO EXECUTOR, JOB TERMINATED Indicates a system fault, or perhaps *RESTORE reading an overwritten loader symbol table from tape. PROGRAM AND LOADER OVERLAP, JOB TERMINATED. ROUTINE ALPHA WAS THE LAST ONE LOADED. TOO MANY FORWARD REFERENCES, JOB TERMINATED. ROUTINE ALPHA WAS THE LAST ONE LOADED. TOO MANY IDENTIFIERS. JOB TERMINATED. ROUTINE ALPHA WAS THE LAST ONE LOADED.
The loader can only deal with 2048 identifier names, including those generated by the system (later reduced to 512).
ARRAY ALPHA REFERRED TO BY ROUTINE BETA PREVIOUSLY DEFINED WITH SHORTER LENGTH. LENGTH NOW SPECIFIED IS 020000 EXECUTION DELETED. CHAPTER 23 HAS IT'S NUMBER TOO HIGH. EXECUTION DELETED. CHECKSUM DISAGREEMENT IN ROUTINE ALPHA ON CARD ORIGIN 00001 32,0 EXECUTION DELETED. directive INADMISSIBLE CHARATER AT COLUMN 19 EXECUTION DELETED. INITIAL COMMON LIST LENGTH EXCEEDED IN ROUTINE ALPHA. EXECUTION DELETED. NO *CHAIN DIRECTIVE IN MULTICHAPTER JOB. EXECUTION DELETED. PARAMETER ALPHA REFERRED TO IN ROUTINE BETA HAS NOT BEEN DEFINED. EXECUTION DELETED. This diagnostic should not arise from an S3 routine. ROUTINE ALPHA JUST LOADED, CONTAINS ERRORS. EXECUTION DELETED. This diagnostic originates from a *NONEXEC directive. directive THE ABOVE LINE IS NOT RECOGNISED AS A DIRECTIVE. EXECUTION DELETED. THE FOLLOWING PARAMETRIC PRODUCT IN ROUTINE ALPHA OVERFLOWS. EXECUTION DELETED, VALUE NAME/ADDRESS 0017253.0 BETA a named parameter - not applicable to S3 0003400.0 0000163.0 a parameter specified by address, 0000055.0 a constant If a value exceeds 10485?6? "TOO BIG" printed. THE FOLLOWING ROUTINES ARE MISSING. EXECUTION DELETED. ALPHA (GLOBAL) 0001234.4 0001467.4 these are the locations desiring the 00l6745.4 missing routines. Locations appearing BETA (PUBLIC) on the same line are in the same 0030342.4 routine. directive (*CALL, *GLOBAL, ^RENAME, * DEFINE) TOO MANY NAMES IN ONE LIST. EXECUTION DELETED. If a list contains more than 20 names, the directive is ignored. ALPHA IS REFERRED TO IN ROUTINE B3TA AS GLOBAL. EXECUTION DELETED. ALPHA is already defined as a public variable. directive (*GLOBAL) ALPHA PREVIOUSLY DEFINED AS PUBLIC. EXECUTION DELETED. directive containing an expression ALPHA UNDEFINED BUT PREVIOUSLY REFERRED TO. EXECUTION DELETED. directive containing an expression ALPHA. UNKNOWN. EXECUTION DELETED.
directive (*SETEDMP) AN UNKNOWN FORMAT IS REQUESTED. OCTAL PRESUMED. BINARY CARD WITHOUT A 7,9 PUNCH IN ROUTINE ALPHA. ROUTINE NOT LOADED. CHAPTER ORIGIN CANNOT BE CHANGED IN THE MIDDLE OF A CHAPTER, The directive is ignored, PRIVATE LIBRARY INCOMPLETE, The loader has run out of space on the tape before *ENDLIB appeared. This diagnostic does not appear until the *ENDLIB directive is met. ROUTINE ALPHA APPEARS TO BE WITHOUT CARD ORIGIN 0000740.0 This diagnostic can only appear with an S3 routine. although the fault, if proven, is serious, the execution is not deleted due to uncertainties in the checking process. ROUTINE ALPHA ASSIGNED GLOBAL ALTHOUGH BLOCK REQUESTED, This diagnostic should not appear with S3 routines. directive (*LIBRARY) THE ABOVE DIRECTIVE APPEARS WITHIN A LIBRARY. IT IS IGNORED. directive (*SETEDMP) TOO MANY ERROR DUMP REGIONS. DIRECTIVE IGNORED. ALPHA REFERRED TO IN ROUTINE BETA IS NOT A PARAMETER. This diagnostic should not appear with S3 routines. directive (*CALL, *GLOBAL) ALPHA PREVIOUSLY CALLED, REQUEST IGNORED.
CHAPTER NUMBER 3 PREVIOUSLY ENCOUNTERED. CHAPTER ORIGIN CHANGED TO 01^6000. EXECUTION NOT REQUIRED. EXECUTION WILL BE FORCED. Indicates presence of a *GOGOGO directive. LOADER MODIFIED. Indicates a *ALTER correction modifying the loader. Accompanied by a message to the supervisor. LST MODIFIED. Indicates a *ALTER correction modifying the loader symbol table. NO MAIN ROUTINE. The executor will stop such a job being entered. NO NEW /CHAIN ARRAY Produced when *CHAIN does not define the chapter changing array. NON-BINARY CARD IN ROUTINE ALPHA. ROUTINE NOT LOADED. PRIVATE LIBRARY SUCCESSFULLY WRITTEN. LAST BLOCK USED WAS 49. ROUTINE ALPHA CONTAINS ERRORS. ROUTINE NOT LOADED. ROUTINE ALPHA HAS A DIFFERENT SOURCE TO PREVIOUS ROUTINES. Will arise if S3 and SRC Fortran routines are mixed. ROUTINE ALPHA PREVIOUSLY LOADED. SYSTEM LIBRARY MODIFIED. Indicates a *ALTER correction modifying part 1 of the system library. The supervisor is informed. ALPHA HAS BEEN DEFINED BEFORE ROUTINE BETA. ALPHA is included in the auxilliary symbols defined by BETA. ALPHA NOW DEFINED AS AN ARRAY. ALPHA was referred to by a previous routine as though it was a routine, but the current routine defines it as an array. directive (*CALL, *GLOBAL, *RENAME) ALPHA. PREVIOUSLY DEFINED.
When the supervisor monitors a line is printed of the form FAULT n AT m. The position p of the offending instruction may be actually at m, or in the preceding few instructions or a jump may have just occurred. In other cases the fault does not occur until well after the offending instruction. Faults of this sort are known as delayed faults. In the table below a delayed fault is indicated by D, and those where a jump may occur by J. In the case of errors detected by the library, m is the return address, that is the first instruction following the call of the library. This is indicated by R in the table below.
n . p 0 Illegal function m-1, m-2 or J 2 Sacred violation by instruction (out of control) m 3 Sacred violation, by operand (subscript error ?) m-1 , m-2 or J 4 Lock out by instruction (out of control) m 6 Lock out by operand (subscript or job description error) m 7 Extracode not yet available m 8 Negative argument for square root m-1 9 Negative or zero argument for logarithm m-1 10 Inverse trig. function argument out of range m-1 11 End of current input m-1 12 Requested input stream not defined in job description m-1 13 Requested output stream not defined in job description m-1 14 Privileged extracode used by non-privileged program m-1 19 Misuse of monitoring or trapping extracode m-1 20 Backing store not defined in job description m-1 21 Backing store extracode not preceded by selection m-1 22 Misuse of backing store extracode (see Note) m-1 40 Library transfer package irrecoverable error R 41 Library transfer package too many recoverable errors R 42 m-1 51 Division overflow D 52 Exponent overflow D 60 Backing store transfer outside core store limit m-1 61 Backing store transfer outside backing store limit m-1 or End of half inch tape D 62 Backing store search failure D 63 Backing store write failure D 64 Backing store read failure D 66 File mark in middle of a read D 67 Search not attempted due to breakdown of device D 68 Write not attempted due to breakdown of device D 69 Read not attempted due to breakdown of device D 70 Search not attempted due to failure of previous request D 71 Write not attempted due to failure of previous request D 72 Read not attempted due to failure of previous request D 90 Supervisor error m-1 96 Computing time exceeded D 97 Execution time exceeded D 98 Output limit exceeded m-1 99 Forced fault by operator intervention m-1
Notes
Fault 22 can arise in many ways. Of those given below, only the first two are likely to arise in Fortran jobs.
Some Fortran statements give rise to calls for library subroutines. All these subroutines are supplied automatically by the loader from the system library. Their existence need not worry the Fortran programmer, but they may be of interest to him. Note that all statements involving transfer of information involve both O2LIBRR and O3LIBRR in addition to one of the others.
statement, etc. Subroutine name Arguments PRINT f O1LIBRR O,f PUNCH f O1LIBRR 15,f WRITE OUTPUT TAPE i,f O1LIBRR i,f end of transfer list O2LIBRR none transfer list item(s) O3LIBRR transfer list item(s) READ f O4LIBRR 0,f READ INPUT TAPE i,f O4LIBRR i,f READ TAPE i O5LIBRR i WRITE TAPE i O6LIBRR i READ DISC i,J (etc) O7LIBRR i,J WRITE DISC i,J (etc) O8LIBRR i,J ENDFILE i EBLIBRR i BACKSPACE i BSLIBRR i REWIND i RWLIBRR i STOP XXLIBRR none CALL EXIT XXLIBRR none CALL EEXIT EXLIBRR none exponentiation /RXPLIB non-standard form
N.B. If a tape and an I/O stream has the same number, then routines 01LIBRR and 04LIBRR use tape in preference to the input/output stream.
A description of the ASP language can be found in A.E.R.E. Harwell report R4285. A revised description may soon be published by the Atlas Computer Laboratory at Chilton. Programmers who intend to use ASP subroutines in conjunction with S3 Fortran routines must obey certain rules in addition to those described in ASP manuals, and these are given in this appendix.
B-register 1 contains the actual return address. It is also used as a pointer to the argument list, which is in the form of address of the arguments, stored in reverse order in the low halves of words immediately preceding the return address. Thus to put the address of the nth argument into B2 in ASP use
CALB2 -n,1
Return will normally be by the instruction
TRA ,1
2-9 temporary use - never saved or restored. 10-19 trapping routines and other system programs. 20-64 subroutine use - saved and restored on exit. 65-89 used by library and subroutines which do not contain calls for other subroutines. 90 b-accumulator: contains the result of short integer functions.