ICL 1900 Series George 3 Operating System Commands

LISTFILE (LF)

Function

Outputs a part or all of a serial file on a basic peripheral or writes it to the monitoring file.

Format

LISTFILE filename description,output peripheral type,FROM number, LINES number, restart option,NUMBER,SPECIAL, MONFILE octal number,SETUP filename,PROPERTY property names

The file description is obligatory and must be the first parameter. All the other parameters are optional and may be in any order. The words FROM, LINES, NUMBER, SPECIAL and MONFILE may be replaced by abbreviations consisting of their first two letters, for example FR number.

1. The file description must not be followed by any entrant description qualifiers. The file may be a multifile.
   For the listing of a non-peripheral file, see the description of the SPECIAL parameter below.
   
   
2. The output peripheral type is that of the peripheral on which the file is to be listed. If this parameter is absent, output is sent to the monitoring file system (LISTING category). This parameter is obligatory with multifiles.
   
   
3. FROM number is required if the user does not wish to start the listing at the beginning of the file. The number is the line number of the first line to be output, where line zero is the first line of the file. If this parameter is absent, line zero is assumed. If the number specified is beyond the end of the file the message 'LINE NUMBER ERROR' is output on the peripheral. This message is not output if the specified file is empty. The message is not a command error message. This parameter is not allowed with multifiles.
   
   
4. LINES number gives the number of lines to be output. If this parameter is absent, lines will be output up to the end of the file. Runout records in a tape punch file are included in this count. This parameter is not allowed with multifiles.
   
   
5. The restart option may be specified as ALL or PAGE. PAGE is only allowed if *LP is given as the output peripheral type. This parameter is used to determine what action should be taken if the following events occur:
   
   
   • A transfer error:

     ALL		The whole listing, including the headings is repeated on the same peripheral.
     PAGE		Unless either the value of the installation parameter IPAGE is 1 or only one page has been listed, the following system request is output:     PLEASE GIVE PAGES FOR ERROR RESTART ON UNIT n The operator has the option of replying with the PAGES command or the CANTDO command. If the operator uses the PAGES command, the number of pages specified are re-output. The point from which lines are re-output is determined by counting the lines having a PFCC of #51 or #11 since each of these lines begins a page; for example, if the operator specified 5 pages, re-output would begin from the fifth line (counting back from the point of the error restart) which had a PFCC of #51 or #11. If no such line has been output, the whole listing is repeated, but without the headings. In all other cases, only the page being listed at the time of the error restart is re-output.

     If neither ALL nor PAGE is given, only the failing transfer is repeated, with no repitition of the headings.
     ALL and PAGE may be issued as AL and PA respectively.
     
     
   • A peripheral becoming inoperable:
     
     If PAGE was specified, the action is the same as for PAGE above and the operator is then requested to make the peripheral operable again. If PAGE was not specified, the operator is simply asked to make the peripheral operable again. He may then do one of three things:
     
     
     • Re-engage the device.
       In this case restart os as described for a transfer error (above).
       
       
     • Issue a CANTDO command.
       In this case the listing will be abandoned on the current output peripheral and will be restarted, when possible, on another peripheral of the required type. The headings will be output again on the new peripheral and the listing restarted according to the restart option specified:

       ALL		The whole listing, including the headings is repeated.
       PAGE		The heading and tghe number of pages specified by the PAGES command, if used, or else the page being listed at the time of the peripheral becoming inoperable, are repeated.

       If neither ALL or PAGE is given, the listing is restarted with the headings and the last attempted transfer on the peripheral that became inoperable.
       
       
     • Issue a TERMINATE command.
       In this case the rest of the listing is abandoned.
       
       
   • A PAPERLOW reply (when the listing is on a line printer):
     
     The operator should reload the line printer as requested. The listing will be restarted on the first available line printer. This may or may not be the line printer that is reloaded, according to the restart option specified:

     ALL		The whole listing, including the headings is repeated.
     PAGE		The heading and tghe number of pages specified by the PAGES command, if used, or else the page being listed at the time of the peripheral becoming inoperable, are repeated.

     If neither ALL or PAGE is given, the listing is restarted with the headings and the last attempted transfer on the peripheral that became inoperable.
     
     
   If restart is required during the output of the headings, the listing is always completely restarted. If restart is required during the output of the terminators, only these are repeated and only then if they can be output on the device used for the listing, i.e. if the operator types CANTDO the output of the terminators is abandoned and the listing is considered completed.
   
   
6. NUMBER causes units of output (lines or cards) to be numbered. It is not allowed in conjunction with peripheral type *TP, though a paper tape file may be numbered when output on a line printer.
   
   
   • The monitoring file system or a line printer
     The parameter causes the lines to be numbered sequentially in units of one, starting with the number specified for the first line (see 3 above) or with zero, if no start number was specified. This number is output as the first seven characters of the line, followed by one space. If it causes the total number of characters in a record to exceed the maximum allowed for the peripheral in question, excess characters are lost at the end of the line. If the line number exceeds 7,999,999 output of it ceases and the first eight character positions of the following lines will be indeterminate.
     
     
   • A card punch
     The lines are sequenced in units of ten, starting with n x 10 where n is the number specified for the first line, (see 3 above) or with 10 if the file is being listed from the beginning. The number appears in columns 76 to 80 inclusive on the card and overwrites anything previously written in these columns. If the sequence number exceeds 99,990 the sequence numbering is discontinued and these columns will contain whatever information was read from the file, or spaces if the record did not extend to these columns.
     
     
   Note: The file being listed is not altered in any way by the inclusion of the NUMBER parameter.
   
   Basic peripheral files are stored in the filstore with a two-word record header for each record. The second word contains information such as the Paper Feed Control Character (PFCC) for line printer type files. System file and any other files which are not basic peripheral files, including files produced by file writers, are stored in the filestore with a one-word record header for each record. LISTFILE normally ignores the first two words of each record.
   
   
7. SPECIAL causes the second word of the two word record header to be printed at the start of each line. It is allowed only when output is to the monitoring file system or a line printer. It may be used together with the NUMBER parameter, in which case the line number is given first.
   
   SPECIAL will be assumed if the file to be output is not a basic peripheral file, so again files of this kind may be output only to the monitoring file system or a line printer.
   
   Note: If a line printer type file is output to a line printer with SPECIAL specified, the PFCC in the second word of each record header is ignored and LISTFILE provides a PFCC with 'throw to top of form' if 'end of page' reply is encountered.
   
   
8. MONFILE octal number is looked for only if the LISTFILE command was issued internally or from within the LOGANAL macro-command. The octal number is a mask used as a sieve for the category word, which is the first word after the header in each record. The record is ignored unless the category word has at least one bit in common with the octal number. The category word itself is never printed.
   
   If a record is being listed when MONFILE is present and it fails to fit into a line, a continuation marker (-) will be inserted in each line, except the last in the record. Each line following the first will be indented.
   
   At present, LISTFILE assumes that MONFILE listings will always be SPECIAL but never NUMBER.
   
   
9. SETUP filename is required to indicate the test pattern file that the user wishes to be repeatedly printed until the operator has correctly aligned the paper on the line printer. This parameter may only be given if the output peripheral type is a line printer. After the headings are listed the test pattern is printed and then there is a throw to head of form. The printer then disengages itself and the message
   
       PLEASE LINE UP UNIT n
   
   appears on the operator's console. When the operator engages the printer, the test pattern file is again printed and the printer disengages itself. The PLEASE LINE UP message is output at an interval set by the installation parameter MESSAGETIME, thus it will not be output each time the printer disengages itself. On engaging the printer the process will be repeated. When the operator has aligned the paper he should type
   
       TE n
   
   Immediately the printer is re-engaged the main file will be listed.
   
   The printer will be considered to be 'lined up' until the operator disengages the peripheral, and in the 'lined up' state no further SETUP parameters will be effective. If the LISTFILE does not specify PAGE or ALL restart then, should a restart occur the test pattern will not be repeated and the printer will be considered not lined up for subsequent listings. If PAGE or ALL has been specified the printer will have to be re-aligned for the restart of this listing and GEORGE will then consider the printer to be lined up for any special stationary listing which follow the restartedone. If a different test pattern file is required, the printer must be disengaged to allow a new SETUP parameter to be effective.
   
   
10. PROPERTYproperty names is required to specify the properties required by the peripheral. This parameter is permitted with all basic output peripheral types. The property parameter must be given if a listing to special stationary is required. The action is that GEORGE will look for a line printer with the specified property. If no available printer has the required temporary property, the operator will be asked to ATTRIBUTE the required property to a printer. He must then WRONG the printer, load the appropriate paper, ATTRIBUTE the property and RIGHT the printer again. It should be noted that if several types of special stationary are required they should each have a seperate property assiciated with them. If the output peripheral required is WRONGed thed LISTFILE awaits for the peripheral to be RIGHTed. No message is output to the monitoring file or the operator's console.
    
    

Forbidden contexts

NO USER, OPERATOR

Execution

The format of a listing is as follows:

HEADING FORMAT

LISTFILE outputs three lines of heading at the start of a listing. These are preceeded by two pages of blank paper, 30 inches of paper tape run-out or two blank cards, as appropriate. In the case of the line printer a line of asterisks with upward pointing arrows at either end is also output, so that the print hammers may be checked. If output is sent to the monitoring file system, no heading is given.

The lines of the heading are as follows:

1. #LISTING OF username.filename PRODUCED ON date AT time
   This gives the date and time when the file was last written to. These are given in the standard formats for dates and times.
   
   
2. #OUTPUT BY LISTFILE IN username.jobname ON date AT time
   The usename and jobname are those of the job in which the LISTFILE command was issued. The date and time indicate when the listing was started.
   
   
3. DOCUMENT file description
   This is the file description that was given as the first parameter of the LISTFILE command. If the total number of characters in this line exceed the maximum allowed for the output peripheral in question characters are lost from the end of the line.
   
   If the file is a multifile, each element will be listed seperately with its own heading and terminations. The elements will be listed in the order they are produced, however, there may be other listings between listings of consecutive elements.
   
   In the case of a paper tape punch, legible headings are produced in the form:
   
       filename FROM JOB username.jobname
   
   A legible heading is one which can be read by the operator: appropriate holes are punched to represent each letter. These legible headings are preceeded and followed by 30 inches of runout.
   
   If the document is to be reintroduced to the system, the first two headings need not be removed as they are preceeded by #, which indicates to the command processor that they are only comment lines. Since these lines will be read in the NO USER context, they will be ignored. Before reintroducing the document, the user should check that the file description is in acceptable document name format.
   
   

LISTING FORMAT

1. TP to *TP, CP or CR to *CP, LP to *LP
   The file is output record by record according to the character count and mode specified in each record header. If a card record of less than 80 characters is encountered the rest of the line is spacefilled; hence a zero length card record will produce a blank card (unless the cards are being sequenced). If a card record is longer than 80 characters, the first 80 characters are output and the rest lost. If the 'end of page' reply is received when listing a file in LP format to a line printer, LISTFILE will overwrite the PFCC of the next record with a PFCC of #51.
   
   
2. TR to *TP
   The records are punched in the appropriate shift indicated by the shift tracing character in the record header. Runout records created by LISTFILE do not count in the number of records to be output (see LINES) above but runout records in the file itself do.
   
   LISTFILE will reinstate newline characters where necessary, and will provide three runout characters between records, unless the file is marked ALLCHAR, in which case no runout is inserted.
   
   
3. CR or CP to *TP
   The record is output up to 128 charactersusing mode #10. Each record is separated from the next by a newline and three runouts provided by LISTFILE. A zero length record results in only the newline and runout being output.
   
   
4. LP to *CP
   The PFCC is ignored and up to 80 characters are output from each record, the rest being lost. If there are less than 80 characters, the line is spacefilled.
   
   
5. CR or CP to *LP
   A PFCC is created for each line with 'throw to top of form' if 'end of page' reply is encountered. The line is spacefilled for unbuffered printers. A zero length record results in a blank line being output. If the number of characters in the line exceeds the maximum for the line printer being used, characters are lost from the end of the line.
   
   
6. CR, CP or LP to monitoring file system
   A simple record is output, unless SPECIAL has been specified. The file must not be a multi-file.
   
   
7. TR or TP to *LP to monitoring file system
   SPECIAL may be specified when listing tape type files to a line printer or monitoring file. No conversion is done when listing to a line printer and characters are lost from the end of the line if the record is too long. A PFCC is provided by LISTFILE with 'throw to top of form' if 'end of page' reply is encountered.
   
   Note: Runout records in a punch file will not necessarily contain spaces and will most probably contain irrelevant information.
   
   
8. Non-peripheral file to *LP or monitoring file system
   Lines are output from the second word of the record. SPECIAL listing is assumed, even if it has not been specified. Otherwise, output is as for CR or CP to *LP or monitoring file system
   
   

LISTING TERMINATORS

At the end of the listing the LISTFILE command again outputs a line of asterisks with upward pointing arrows at either end (in the case of the line printer, one paper throw, 30 inches of paper tape run-out or two blank cards, as appropriate. If the listing was to the card punch, the punch is disengaged and the operator informed that the listing is complete. For a paper tape punch, five feet of paper runout is considered sufficient to indicate to the operator the break between two docuents, and the paper tape punch is disengaged in the same manner as a card punch.

Examples

Notes

1. If more lines than are present in the file are requested, or if the sum of the start line and the number of lines is greater than the length of the file, no error is flagged and the listing stops at the end of the file.
   
   
2. If files have been produced using a file writer, it is posible that the information in the second word of the record header is not legal. Where applicable the mode is checked and an output mode of zero is always assumed if that stored is not recogised. In the case of the PFCC in a line printer type file this is not checked but sent straight to the line printer.
   
   
3. The following messages may be output on the operator's console:
   
   
   • RELOAD number
     
     where the number is the operator's number of a peripheral. This message is output after a PAPERLOW reply has been received on a line printer.
     
     
   • UNLOAD number
     
     where the number is as above. This message is output after a listing on either a card punch or paper tape punch has been completed. The document should be removed and the peripheral re-engaged.
     
     
4. If a file is empty, the start line number given will be ignored and only the headings and terminators will be output. The message FILE EMPTY will be output on the peripheral.
   
   
5. A file cannot be listed while it is open for writing or appending. The effect of this is as follows
   
   
   • When listing is directed to a slow peripheral, no difficulties arise because the listing is queued (if necessary) waiting for the file to be closed and for a suitable peripheral to become available; the job is allowed to continue once the LISTFILE command has been accepted, whether or not the listing needs to be queued. Thus, if a file is open to the job concerned, the listing is queued until the file is closed either by a command in the job or by the termination of the job.
     
     
   • Listings directed to the monitoring file system cannot be queued but must be implemented immediately while the monitoring file is still available; in this case the job is not allowed to continue until the listing is complete. Consequently, the file to be listed must not be open for writing or appending in the job on which the LISTFILE is issued. If it is, an error is reported and the listing will not be implemented. As the job cannot continue until the listing is complete, an interminable wait wait would result if the listing was queued, as the file would never be closed.
     
     
6. This command should not be used for outputting system files.
   
   
7. If an error occurs in one of the elements of a multifile, the previous elements will still be listed.
   
   
8. In the case of a basic output peripheral listings are output in chronological order within urgency.

Error Messages

NEGATIVE NUMBER ILLEGAL IN z
NUMBERED LISTING NOT ALLOWED ON z
PAGE RESTART NOT ALLOWED IF *LP NOT SPECIFIED
PARAMETER z HAS TOO MANY CHARACTERS
PERIPHERAL PROPERTIES z NOT AVAILABLE
PERIPHERAL TYPE z NOT AVAILABLE
SPECIAL LISTING NOT ALLOWED ON z
TOO MANY NUMBERS IN z
z 'ALL' RESTART ALREADY SPECIFIED
z IS NOT AN OUTPUT DEVICE
FROM AND/OR LINES NOT ALLOWED WITH MULTI-REEL FILES
MORE PROPERTIES SPECIFIED THAN ALLOWED
TRACING AND REPORTING ARE SUCH THAT YOU WILL GET NO OUTPUT FROM THIS COMMAND