User's Guide

FILEUTIL

Write a file to the terminal, line printer, and/or output file.

Function:

Performs the necessary functions on the file "program_time.pr" generated by LAS programs according to the specified values of the PRINT parameter.

1.  TERM
    The output file is sent to the user's terminal.
    The user will have the ability to issue the
    following commands:

       h: list valid terminal commands
       l: output one line of data to terminal
       p: terminal data is to be paged
       s: terminal data is to be scrolled
       b: terminal data is output starting
          at the beginning
       c: continue processing without writing
          output to the terminal
       /: search for the specified string
       q: quit processing

    NOTE: The program execution will be suspended when
          waiting for a command to be issued.

2.  LP
    The output file has the standard header added to 
    the "program_time.pr" file and then prints the 
    file to the printer specified by $PRINTER.  The 
    "program_time.pr" file is then deleted.
	
    The standard header is created using the 
    parameters TEXT and REPNUM and the TAE globals 
    $FADDR and $FNAME.

    Banners will be printed if BANRFLG is left as
    the default value "YES".  If banner pages are not
    desired, set BANRFLG to "NO".
 
3.  filename
    The output file is renamed from the input file 
    "program_time.pr" to filename and saved on disk.  
    The filename has a default extension of ".prt".

Parameters:

INFILE
Input file. The name of the file generated by the LAS program. This should be the program name with a _time.pr extension (all in lower case).

SRCCODE
Source code. Description of the source code generating the file specified in INFILE. SRCCODE(1) describes the type of language the source program was written in; SRCCODE(2) describes how output to the terminal is handled.
  (1) = C:  C.  Source code is written in the C 
	    programming language.
      = F:  FORTRAN.  Source code is written in 
	    FORTRAN programming language.
  (2) = P:  PTERM.  The application program will 
	    generate the terminal output using the 
	    PTERM subroutine.
      = F:  File.  A file is built and TERMOUT is 
	    called to display the terminal output.

     NOTE:  If there will be no terminal output, set 
	    SRCCODE(2) to "F."  This avoids an error
	    that will occur if a FORTRAN program
	    handles the output on a UNIX system.
PRINT
Output destination. The destination of the output.
  = TERM:      Terminal.  Output is sent to the user's
               terminal.
  = LP:        Line printer.  Output is sent to the 
               line printer defined by $PRINTER.
  = Filename:  User supplied file name.  Output
               is sent to the user supplied file
	       with the extension ".prt"
See the User Notes section for specific combinations.
NPGLINS(59)
Number of lines on printer page. The total number of lines allowed on one printer page. The default (59) is an average value for printers. A maximum of 66 lines may be specified.

LPWIDTH(132)
Line printer page width. The number of columns to be printed. This can be 80 for terminals or 80 column printers and 132 for 132 column printers.

REPNUM(" ")
Report number. The report number or character string to appear at the upper-right corner of the standard header. This is usually the program name.

TEXT(" "," ")
Text string. The two title lines to be written into the standard header on the output. Limited to 132 characters.

BANRFLG(YES)
Banner flag. For output sent to a line printer, PRINT=LP, this flag determines wheter banner pages will be printed. If the value is the default "YES" a banner page is printed. If banner pages are not desired set to "NO". See User Note 5.

Examples:

LAS> fileutil infile="list_103515.pr" srccode=(c,f) print=(term,savlst)
The file LIST_103515.PR, generated in the LAS application LIST, is written to the user's terminal and then renamed to the user-specified file SAVLST.PRT. After the first page of information is written to the user's terminal, the process is suspended for a terminal command request. This allows the user to look at the output and specify paging, scrolling, etc. of the output data. See the User Notes section for the terminal command options.
LAS> fileutil infile="plenter_132411.pr" srccode=(c,f) print=(lp) lpwidth=80 repnum="plenter" text=("ancillary information","test tapes")
The file PLENTER_132411.PR, generated by the LAS application PLENTER, has a standard header inserted before each page. The standard header information will contain a title of "Ancillary Information" and a secondary title of "Test Tapes." The file will then be printed to the printer specified in the global parameter $PRINTER. The following is a sample output heading (width = 80):
```
Tue. July 7 1988         EROS Data Center          Report No. PLENTER
Time 12:24       Sioux Falls, South Dakota  57198  Page 0001
                       Ancillary Information
                           Test Tapes
```

Description/Algorithm:

FILEUTIL first determines the print option and sets flags indicating that the input file is to be output to the terminal, line printer, or a user-specified file. When in batch and output is specified to the terminal, the program sets the line printer flag so that the output is not lost.

   o  If the line printer flag is set, it inserts the standard 
      header and prints the file to the printer specified with 
      the global variable $PRINTER.  A delete flag is also set 
      to delete the input file.  

   o  If the terminal flag is set, the input file is written to 
      the user's terminal.  After the first page is displayed, 
      the process is suspended for the user's input to a 
      terminal command request.  The user will have the ability to 
      page, scroll, list one line, search, start at beginning, 
      continue processing without writing output to the terminal
      and quit processing.  A delete flag is also set to delete 
      the input file.  

   o  If the file flag is set, the program renames the input 
      file to the user-specified file.  The delete flag is also 
      turned off because the input file does not need to be 
      deleted.

If the delete flag is set, the input file is removed.

Nonfatal Error Messages:

[fileutil-length] Text line is too long. Line is truncated to X characters
The text line is too long to fit on the terminal or the line printer. The line is truncated to the width of the terminal or line printer. Data after the width size is lost.
[fileutil-search] No search pattern specified
No search string pattern was specified at the terminal command prompt.

Fatal Error Messages:

[fileutil-crt] Terminal is not a supported CRT
The output device is not a terminal nor a supported CRT for output to the terminal screen.
[fileutil-open] Error opening input file in print file utility
The input file could not be opened. The file has already been opened by another user, or the user has insufficient privileges to open the file or has specified an invalid name.
[fileutil-open] Error opening output file in print file utility
The output file could not be opened or created. The file already exists, or the user has insufficient privileges to open the file or has specified an invalid name.
[fileutil-seek] Error seeking to beginning of temporary file
There was an error trying to reset the file pointer to the beginning of the temporary file. The temporary file is not open or contains no information.
[fileutil-write] Error writing record to the output file
An error occurred while trying to write a record from the input file to the user-specified output file.
[fileutil-quit] Process terminated by the user
The user specified a "quit" command at the terminal command prompt--and the process is terminated with the "quit" command. A "continue" command will continue processing without writing output to the terminal screen.

User Notes:

If the terminal output is required to be real time, the application program should call the support routine PTERM to actually write the data to the terminal.
If the terminal output can be written after the program has finished and is the same format as the line printer file, the function TERMOUT is called by FILEUTIL to output the file to the terminal.

Output destination of the specific PRINT and SRCCODE(2) parameter options.

If running in batch, terminal is specified, and using a file for terminal output, the file will have the standard header added and then is sent to the line printer specified by $PRINTER. If running in batch and using the PTERM call in the application code, the data sent to PTERM will be sent to the log file.

    $RUNTYPE = interactive  SRCCODE(2)='P' or 'F'
          PRINT Value    Output Destination
          ___________    __________________

          TERM           terminal
          TERM,FILE      terminal, file
          TERM,LP        terminal, line printer
          FILE           file
          FILE,LP        file, line printer
          LP             line printer
          TERM,FILE,LP   terminal, file, line printer


    $RUNTYPE = batch  SRCCODE(2)='F'
          PRINT Value    Output Destination
          ___________    __________________

          TERM           line printer
          TERM,FILE      line printer, file
          TERM,LP        line printer
          FILE           file
          FILE,LP        line printer, file
          LP             line printer
          TERM,FILE,LP   line printer, file

    $RUNTYPE = batch  SRCCODE(2)='P'
           PRINT Value    Output Destination
          ___________    __________________

          TERM           log file
          TERM,FILE      log file, file
          TERM,LP        log file, line printer
          FILE           file
          FILE,LP        line printer, file
          LP             line printer
          TERM,FILE,LP   log file, line printer, file

When the output is to the terminal screen, the user will have the ability to issue the following terminal commands:

	   h: list valid terminal commands
	   l: output one line of data to terminal
	   p: terminal data is to be paged
	   s: terminal data is to be scrolled
	   b: terminal data is output starting
	      at the beginning
           c: continue processing without writing
              output to the terminal
	   /: search for the specified string
	   q: quit writing output to the terminal

	NOTE: The program execution will be suspended
	      when waiting for a command to be issued.

When a "quit" command is specified at the terminal command prompt, the process is terminated. A "continue" command will continue processing without writing output to the terminal screen.
The system command 'lp' is used to print to line printers. The option to disable printing of banner pages by 'lp' may be overridden by the system administrator. Because of this, banner pages will be printed regardless of the value of BANRFLG when overridden.