User's Guide

SETAPOUT

Set parameter values for module TAPEOUT

Function:

Copies multiple LAS images to magnetic tape. Each image may be processed with its own unique set of parameters. The image may be windowed, subsampled, or converted to a new data type prior to being written to tape.

The user has the option to copy the data descriptor record (DDR) from the LAS image to tape. The DDR is updated to represent the generated output image.

SETAPOUT dynamically queries the user to input the image parameters of each LAS image that is to be copied to tape. Since SETAPOUT uses a dynamic tutor, it cannot be executed in BATCH mode. However, once all of the image parameters for each image have been input, the user may specify whether the copy should be executed in INTERACTIVE or BATCH mode. The user also has the option of saving the parameter values and then executing module TAPEOUT at a later time.

Parameters:

NIMAGE
Number of images. The number of LAS images that are to be copied to tape. The maximum number of images that can be processed at one time is 50.

COMMENT
Description of tape. A text string sent to the operator's terminal. COMMENT consists of two pieces of information:

     1. Tape library storage location ID number 
     2. Short description of the tape

The operator uses this text to find the tape to be mounted; therefore, COMMENT should be as descriptive as possible. Including both the ID number and a short description gives the operator a double check to ensure the correct tape gets mounted. Since SETAPOUT may process multiple tape volumes, COMMENT is a multi-value parameter allowing each tape volume to have a unique mount message. The comment can contain up to 80 characters of any kind.

OUTSYS(SAME)
Output computer system. The computer system for which the output data is being generated. The default is to use the same system on which the tape is being generated on. The image data is copied directly to tape.

The IEEE standard byte swaps the data for all data types if needed, and REAL data is output in a standard format. Refer to the User Notes for the IEEE standard references.

Hewlett Packard (HP) systems require an even number of bytes in each record. For BYTE images if the number of samples in the input image window is odd, a zero-valued pixel is added to the end of each input line so the output record length is even. A limit of 14,999 samples in the image window is applied.

  = SAME:  Same as input.
  = IEEE:  IEEE standard.
  = HP:    Hewlett Packard.

TAPEDENS(&$TPDENS)
Tape density. The density of the tape in bytes per inch. The default is defined by the TAE global $TPDENS and the list of valid densities are defined by the TAE global $TPVAL.

SKIPNUM(0)
Number of files to skip. The number of image files on tape to skip before copying the LAS image. An image file on tape is the DDR file (if it exists) and the image data. (Refer to User Notes.)

MVOLFLG(NO)
Multiple volume flag. The multi-volume flag allows the user to specify whether or not multi-volume sets are split at an end-of-file mark. (Refer to User Notes.)

  = YES:  Split multi-volume sets in middle of image
          file. 
  = NO:   Split multi-volume sets at the end of an 
          image file.

RUNTYPE(INTER)
Execution mode. RUNTYPE defines how the tape copy module is to be executed.

  = INTER:  Interactive mode.  Module to be run in TAE
            interactive mode. 
  = BATCH:  Batch mode.  Module to be run in TAE batch 
            mode. 
  = SAVE:   Save parameter values.  Parameters are 
            saved in specified file.  (The user may 
            execute the tape copy module TAPEOUT at a 
            later time.)

ERRFLG(YES)
Error flag. Allows the user to specify how error conditions should be handled.

  = YES:  List errors.  If an error is encountered
          while copying an image to tape, the tape is 
          backspaced to the beginning of the current 
          file and an end of volume (EOV) mark is 
          written.  TAPEOUT is aborted without copy-
          ing subsequent images.
  = NO:   Do not list errors.  If an error is encoun-
          tered while copying an image to tape, the 
          tape is backspaced to the beginning of the 
          current file and all subsequent images are 
          copied to tape.  After all subsequent 
          images have been copied, TAPEOUT terminates
          with a general error code.  

Dynamic Parameters:

IN
Input image. The input image may be BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. The input image can be of any size, and it can be a single- or multi-band image. The user may specify a subwindow and/or subband to process a smaller image area.

BFORM(BSQ)
Band format. The format of the image data on tape. If there is more than one band in the image, the data may be stored in band sequential (BSQ) or band interleaved by line (BIL) format.

  = BSQ:  Band sequential. 
  = BIL:  Band interleaved by line.

ODTYPE(SAME)
Output data type. The data type of the output image. ODTYPE is a multi-value parameter allowing each image on tape to have a unique data type.

  = SAME:  Same as input
  = BYTE:  BYTE       (8-bit unsigned integer) 
                      (0 through 255)
  = I*2:   INTEGER*2  (16-bit signed integer) 
                      (-32768 through 32767) 
  = I*4:   INTEGER*4  (32-bit signed integer) 
                      (-2147483648 through 2147483647) 
  = R*4:   REAL*4     (32-bit signed real) 
                      (System dependent)

Unexpected results may occur if the input data type is converted to a lower order data type, i.e., REAL*4 converted to BYTE. If the pixel value is larger than what the new type will support, the least significant bytes are used.

BLKSIZ(1)
Block size. The number of image lines to be written as a physical tape record.

LINEINC(1)
Line increment. Specifies that every LINEINCth line, starting at line 1 is to be processed. When selecting lines to write to the image file, every LINEINCth + 1 line, beginning with the starting line of the input window, becomes part of the output image.

Increasing the line increment reduces the number of lines in the output image. The default value of 1 results in all image lines on disk to be included in the image file on tape.

SAMPINC(1)
Sample increment. Specifies that every SAMPINCth sample, starting with sample 1, is to be processed. When selecting samples to write to the image file, every SAMPINCth + 1 sample, beginning with the starting sample of the input window, becomes part of the output image.

Increasing the sample increment reduces the number of samples in the output image. The default value of 1 results in all image samples on disk to be included in the image file on tape.

DDRFLG(NO)
DDR flag. Option to copy the DDR from the input LAS image into a file on tape. The DDR is also updated to represent the generated output image.

  = YES:  Copy the DDR.  The DDR from the input
          image is copied into a DDR file on tape.
  = NO:   Do not copy the DDR.  The DDR is not
          copied into a DDR file on tape.

Dynamic Parameters:

Output file. Name of the file in which the TAE parameter values are to be saved. The parameter values are saved by executing the TAE SAVE command. The user may then execute module TAPEOUT with these parameter values by executing the TAE RESTORE command.

This parameter set is used only if parameter RUNTYPE is set to SAVE.

Examples:

  1. LAS> setapout nimage=2 comment="please mount tape mo55 wash dc" outsys=same tapedens=6250 skipnum=1 mvolflg=no runtype=inter errflg=yes

    LAS-setapout> IN=IMAGE1 BFORM=BSQ ODTYPE=SAME LINEINC=2 SAMPINC=2 DDRFLG=NO

    LAS-setapout> IN="IMAGE2(100,150,1023,1024:1,3)" BFORM=BIL ODTYPE=I*2 LINEINC=1 SAMPINC=1 DDRFLG=YES

    The initial parameter set specifies that two LAS images are to be copied to tape MO55. The first image file on tape is skipped prior to the copy. The user has specified that an image file is not to be split over multiple tape volumes. The tape copy is to be run in INTERACTIVE mode, and if an error occurs while copying an image file, processing is to be aborted.

    The first dynamic tutor queries the user to define the parameters required to copy the first LAS image to tape. It specifies that image IMAGE1 is to be copied to tape in BSQ format with the same data type. The image on tape is subsampled, taking every other line and sample of the input image. The DDR from the input image is ignored.

    A second dynamic tutor queries the user to define the parameters required to copy the second LAS image to tape. It specifies that a subwindow of image IMAGE2 is to be copied to tape in BIL format with data type of INTEGER*2. The subwindow specifies a starting line of 100, starting sample of 150, number of lines of 1023, number of samples of 1024, and bands 1 and 3 are to be copied to tape. The DDR information from the input image is updated to reflect the window, band, and data type of the output and copied into a file on tape.

  2. LAS> setapout nimage=2 comment="please mount tape a scratch tape" outsys=ieee tapedens=6250 skipnum=0 mvolflg=yes runtype=batch errflg=no

    LAS-setapout> IN=IMAGE1 BFORM=BSQ ODTYPE=SAME LINEINC=2 SAMPINC=2 DDRFLG=NO

    LAS-setapout> IN="IMAGE2(100,150,1023,1024:1,3)" BFORM=BIL ODTYPE=R*4 LINEINC=1 SAMPINC=1 DDRFLG=YES

    The initial parameter set specifies that two LAS images are to be copied to a scratch tape. The user has specified that an image file may be split over multiple tape volumes. The tape copy is to be run in BATCH mode, and if an error occurs while copying the image file, processing is to continue with subsequent image files. The input data is also converted to the IEEE standard format before it is written to tape.

    The first dynamic tutor queries the user to define the parameters required to copy the second LAS image to tape. It specifies that image IMAGE1 is to be copied to tape in BSQ format with the same data type. The image on tape is subsampled, taking every other line and sample of the input image. The input data is also converted to the IEEE standard format. The DDR from the input image is ignored.

    A second dynamic tutor queries the user to define the parameters required to copy the second LAS image to tape. It specifies that a subwindow of image IMAGE2 is to be copied to tape in BIL format with data type of REAL*4. The subwindow specifies a starting line of 100, starting sample of 150, number of lines of 1023, number of samples of 1024, and bands 1 and 3 are to be copied to tape. The input data is formatted to the IEEE standard for REAL data before it is written to tape. The DDR information from the input image is updated to reflect the window, band, data type, and subsampling of the output and is then copied into a file on tape.

  3. LAS> setapout nimage=1 comment="please mount tape a scratch tape" outsys=same tapedens=6250 skipnum=0 mvolflg=yes runtype=save errflg=yes

    LAS-setapout> IN=IMAGE1 BFORM=BSQ ODTYPE=SAME LINEINC=1 SAMPINC=1 DDRFLG=NO

    LAS-setapout> OUTFILE=WASHDC

    The initial parameter set specifies that one LAS image is to be copied to a scratch tape. The user has specified that an image file may be split over multiple tape volumes. If an error occurs while copying the image file, processing is aborted. The parameters are to be saved in a file, and the LAS module TAPEOUT may be executed at a later time.

    The first dynamic tutor queries the user to define the parameters required to copy the LAS image to tape. It specifies that image IMAGE2 is to be copied to tape in BSQ format with the same data type. The DDR from the input image is ignored.

    A second dynamic tutor queries the user for the file name into which the parameter values are saved. The user may then execute the proc TAPEOUT by using the TAE restore command with the file WASHDC.

Description/Algorithm:

For each LAS image to be copied to tape, SETAPOUT dynamically queries the user to define the parameters of each image. Once the parameters for each image have been input, SETAPOUT does one of the following depending on the value of parameter RUNTYPE.

If RUNTYPE=INTER  
   SETAPOUT invokes the module TAPEOUT in interactive mode using 
   parameter values just input by the user, or

if RUNTYPE=BATCH  
   SETAPOUT invokes the module TAPEOUT in batch mode using param-
   eter values just input by the user, or    

if RUNTYPE=SAVE   
   the user is queried to input a file name into which the param-
   eter values are to be saved.  The user may then execute the 
   module TAPEOUT at a later time by using the TAE restore com-
   mand on the specified value.

Description of the tape copy routine TAPEOUT:

On the first invocation of the tape copy routine, the tape is mounted and the physical tape drive name is saved so that the tape may be reopened. After processing of the image file is complete, the tape is closed (but not dismounted) as long as there is another image file to be copied. When the last image has been copied to tape, the tape is dismounted.

Once the tape file is opened, the specified number of image files are skipped. An image file is defined as the DDR (if it exists) and as the image data. (Refer to the User Notes.) If parameter DDRFLG is set to YES, the DDR from the LAS image is updated and copied into a file on tape. The window and bands from the LAS image are then subsampled by the specified line and sample increments and copied to tape in BIL or BSQ format. If the end of tape is encountered before processing is complete, the value of MVOLFLG is checked. If MVOLFLG is set to YES, a new tape is requested to complete processing. If MVOLFLG is set to NO, the tape is backspaced to the beginning of the current image file, an EOV is written to tape, and a new tape is requested. The current image is then copied to the new tape. When all files have been copied, the tape is rewound and dismounted.

If the user types "control C abort" after the tape copy is invoked. The tape is rewound and dismounted.

Nonfatal Error Messages:

  1. [tapeout-tpeot] EOT encountered. Image does not fit on one tape.

    The end of the tape was encountered before processing of an image is complete. If the parameter MVOLFLG is YES, the next tape is requested; otherwise, the tape is backspaced to the beginning of the file, an EOV is written, and the next tape is requested. (Refer to User Notes.)

  2. [tapeout-tpclos] Error closing tape

    An error was detected while closing the tape device.

  3. [tapeout-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The image data is probably valid and therefore saved. The message that is displayed immediately preceding this error message is the specific error that was encountered.

Fatal Error Messages:

  1. [tapeout-abort] Error encountered--TAPEOUT is aborting

    This is a general error message informing the user that the specified image was not copied to tape. This error occurs only if parameter ERRFLG is set to YES.

  2. [tapeout-malloc] Error allocating memory

    There is not sufficient memory on the system to do the specified processing. Other applications may have reserved enough of the memory area that there is currently not sufficient memory for this application. The user should try running the application again.

  3. [tapeout-cont] Error encountered during one of the image copies

    This is a general error message informing the user that an attempt was made to copy all specified images to tape but that an error was detected in one or more of the copies. This error occurs only if parameter ERRFLG is set to NO.

  4. [tapeout-fatal] Fatal error encountered, no output created

    A fatal error was encountered during processing. The output image file is deleted. The message that is displayed immediately preceding this error message is the specific error that was encountered.

  5. [tapeout-hpmax] Maximum image size for HP computer system [tapeout-hpmax] is 14999 samples

    If the output computer system is specified to be Hewlett Packard, the maximum number of samples for the output image is limited to 14999 samples.

  6. [tapeout-input] Input images are not of same data type

    This error occurs when there are multiple input images of different data types and ODTYPE is defaulted. The user can either ensure all input images have the same data type or specify the data type of the output image by assigning a value to parameter ODTYPE.

  7. [tapeout-read] Error reading input image

    An error was detected while reading a line of the input image.

  8. [tapeout-tpdmnt] Error dismounting the tape

    An error was detected while dismounting the tape device.

  9. [tapeout-tpeov] Unexpected EOV encountered

    An unexpected end of volume (EOV) was encountered while skipping the specified number of image files on tape prior to the copy.

  10. [tapeout-tpfsf] Error forward spacing files

    An error was detected while forward spacing files on the tape device.

  11. [tapeout-tpopen] Error mounting tape

    An error was detected while mounting the tape device.

  12. [tapeout-tpread] Error reading from tape

    An error was detected while reading a record from tape.

  13. [tapeout-tpreop] Error reopening tape

    An error was detected while reopening the tape device.

  14. [tapeout-tpwrit] Error writing to tape

    An error was detected while writing a record to tape.

  15. [tapeout-user] Process aborted by the user

    This error occurs if the user types "control C abort" after the tape copy is invoked. The tape is rewound and dismounted.

  16. [tapeout-window] Input images do not have same window sizes

    Error occurs if multiple input images are specified with different window sizes.

User Notes:

  1. Format of tapes containing a DDR file. Each image file consists of two files:

          1.  DDR record 
          2.  Image data 
    

    The parameter SKIPNUM specifies the image files rather than physical files on tape. For example, the following diagram shows a valid tape format. If the user specified SKIPNUM=2, then the LAS image would be copied to the fourth physical record on tape (the third image file is overwritten).

                   Image                  Physical
                   File                     File
                          --------------
                     1 -->| Image Data |<--- 1
                          |     EOF    |
                       -->|  DDR File  |<--- 2
                     2 |  |     EOF    |
                       -->| Image Data |<--- 3
                          |     EOF    |
                     3 -->| Image Data |<--- 4
                          |     EOF    |
                          |     EOF    |
                          --------------
    

  2. If the end of tape is encountered before processing of an image is complete, the value of parameter MVOLFLG is checked.

    If MVOLFLG=YES, the operator and the user are signaled to mount a new tape to complete the processing. The image file will be split onto multiple tape volumes.

    If MVOLFLG=NO, the tape is backspaced to the beginning of the current image file, an EOV is written to tape, the operator and the user are signaled to mount a new tape, and the current image is recopied to the new tape. If the image does not fit on a single tape, the software forces the image to be split onto multiple tape volumes.

  3. Unexpected results may occur if the input data type is converted to a lower-order data type. If the sample value is larger than what the new type supports, the least significant bits are used.

  4. The IEEE standard is taken from "IEEE Standard for Binary Floating-Point Arithmetic" (Std 754-1985). This publication establishes a standard format for the output of REAL and DOUBLE data types. When on a DEC machine, the data must also be byte swapped before being written to the output tape. The reformatting and byte swapping increases the processing time.

  5. Related LAS modules are TAPEOUT, SETAPIN, and TAPEIN.