User's Guide

SETAPIN

Set parameter values for module TAPEIN

Function:

Reads multiple image files from tape and copies the images into LAS image files on disk. Each image file may be processed with its own unique set of parameters. The image on tape may be windowed and/or subsampled when copied to the disk file. If the end of tape (EOT) or the end of volume (EOV) is encountered while processing a file from tape, the user and the operator are signaled to mount the next tape volume to complete the processing of the image files.

The user has the option to copy the data descriptor record (DDR) file into the LAS image file. If the DDR file exists on tape, it is assumed that the DDR file and the image data are in two separate tape files. The DDR is updated to represent the generated output image.

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

NOTE: There are three restrictions:

       1. The maximum number of images that can be 
          copied on one run is 50.  
       2. The sum of the bands for all images to be
          copied cannot exceed 256 bands.
       3. If one of the dynamic parameters TOTLINES,
          TOTSAMPS, TOTBANDS, or BANDS is required
	  for one input image then the parameter(s)
	  used is required for all input images.

Parameters:

COMMENT
Description of tape. A 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 SETAPIN 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.

FILENUM
File number(s). A list of file numbers of the input image to be read from tape. The file numbers must be positive numbers and in ascending order.

INSYS(--)
Input computer system. The computer system on which the input data was generated. If the DDR file exists for the image, the input computer system can be obtained from the DDR. In this case, the parameter value of INSYS is ignored.

  = SAME:  Same as output
  = IEEE:  IEEE standard
  = VAX:   VAX system
  = SUN:   SUN workstation
  = IBMR2: IBM RS6000 POWERstation
  = PN:    Power Node
  = HP:    Hewlett Packard

NOTE: Hewlett Packard (HP) systems require an even number of bytes in each record. When the image being read contains BYTE data with an odd number of samples in HP format, the last sample of each input line is stripped off. The user may specify parameter TOTSAMPS as either the original odd number of samples or the even number of samples that are actually on the tape. If the even number is specified, the output image contains the zero-value sample at the end of each image line.

RUNTYPE(INTER)
Execution mode. 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 TAPEIN at a
            later time.)

OUTFILE(--)
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 TAPEIN with these parameter values by executing the TAE RESTORE command.

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

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 file, TAPEIN is 
          aborted without copying subsequent image 
          files.
  = NO:   Do not list errors.  If an error is encoun-
          tered while copying an image file the tape
          is forward spaced to the end of file, and 
          subsequent image files are copied.  
          After all subsequent images have been cop-
          ied, TAPEIN terminates with a general error 
          code.  

Dynamic Parameters:

OUT
Output image. The output image data type, size, and number of bands are determined by parameters ODTYPE, WINDOW, LINEINC, SAMPINC, and BANDS. OUT is a multi-value parameter defining up to fifty LAS images. The number of unique images specified in parameter OUT must be (1) equal to the number of files specified in parameter FILENUM, or (2) equal to 1 (one). Either each input file is written to a corresponding output file, or all of the input files are written to one output file.

NOTE: Unexpected results may occur if the input data is converted to a lower-order output data type, i.e., REAL*4 converted to BYTE.

NHEADREC(--)
Number of header records. The number of input header records associated with the image. Specifies the number of header records at the beginning of the image file that are to be skipped. NHEADREC is a multi-value parameter.

TOTLINES(--)
Total number of lines. Number of lines in the input image. TOTLINES is a multi-value parameter allowing each image file on tape to have a unique number of lines.

If the DDR file exists for the image, the number of lines can be obtained from the DDR. In this case, the parameter value of TOTLINES is ignored.

TOTSAMPS(--)
Total number of samples. Number of samples in the input image. TOTSAMPS is a multi-value parameter allowing each image file on tape to have a unique number of samples.

If the DDR file exists for the image, the number of samples can be obtained from the DDR. In this case, the parameter value of TOTSAMPS is ignored.

TOTBANDS(--)
Total number of bands. Number of bands in the input image. TOTBANDS is a multi-value parameter allowing each image file on tape to have a unique number of bands.

If the DDR file exists for the image, the number of bands can be obtained from the DDR. In this case, the parameter value of TOTBANDS is ignored.

IDTYPE(--)
Input data type. The data type of the input image. IDTYPE is a multi-value parameter allowing each image file on tape to have a unique data type.

If the DDR file exists for the image, the data type of the image is obtained from the DDR. In this case, the parameter value of IDTYPE is ignored.

  = SAME:  Same as input DDR
  = BYTE:  BYTE (8-bit unsigned integer)
  = I*2:   INTEGER*2  (16-bit signed integer)
  = I*4:   INTEGER*4  (32-bit signed integer)
  = R*4:   REAL*4     (32-bit signed real) 

BFORM(--)
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.

If the DDR file exists for the image, the band format of the image is obtained from the DDR. In this case, the parameter value of BFORM is ignored.

If more than one input images are being copied to one LAS image, the value of BFORM must be BSQ for all input images.

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

BLKSIZ(--)
Block size. Number of image lines per physical tape records.

BANDS(--)
Band number(s). The image bands to be processed. By default, all bands in the image are processed. Input window specification. Specifies the starting line, starting sample, number of lines, and number of samples to be processed. The default is to process the whole image.

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

  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer) 
  = I*2:   INTEGER*2  (16-bit signed integer) 
  = I*4:   INTEGER*4  (32-bit signed integer) 
  = R*4:   REAL*4     (32-bit signed real) 

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.

LINEINC(--)
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, become 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 tape to be included in the image file on disk.

SAMPINC(--)
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, become 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 tape to be included in the image file on disk.

DDRFLG(--)
DDR flag. Option to copy the DDR file from tape into the DDR of the LAS image.

  = YES:  Copy the DDR.  The DDR on tape is copied
          into the DDR of the LAS image.
  = NO:   Do not copy the DDR.  The DDR is not
          copied or does not exist on tape (DDR
          file is ignored).
If more than one input images are being copied to one LAS image, the value of DDRFLG must be NO for all input images.

Examples:

  1. LAS> setapin comment="b12345 washington 1 of 1" filenum =(1,3) insys=same runtype=batch errflg=no

    LAS-setapin> OUT="IMAGE1" TOTLINES=512 TOTSAMPS=512 TOTBANDS=1 IDTYPE=BYTE BFORM=BSQ + BANDS=-- WINDOW=-- ODTYPE=I*2 LINEINC=1 SAMPINC=1 DDRFLG=NO

    LAS-setapin> OUT="IMAGE2" NHEADREC=0 TOTLINES=1024 TOTSAMPS=1024 TOTBANDS=3 IDTYPE=I*4 BFORM=BSQ BANDS=(1,3) WINDOW=-- ODTYPE=SAME LINEINC=2 SAMPINC=2 DDRFLG=YES

    The initial parameter set specifies that the tape B12345 is to be mounted on a drive; the first file on tape is to to be copied into LAS image IMAGE1. The input image is a one-band 512 by 512 BYTE image file. If a DDR file exist, it is skipped. The complete image is converted to INTEGER*2 and copied to the appropriate LAS image file.

    The second dynamic tutor queries the user to define the parameters to process the third file on tape. The third file is copied into the LAS image IMAGE2. The input image is a three-band (band sequential) 1024 by 1024 INTEGER*4 image. If a DDR file exists on tape, it is updated and copied into the DDR of the LAS image. The first and third bands of the image are copied to image IMAGE2. Subsampling is applied to the whole image taking every other line and sample starting at line 1 and sample 1. The resulting output image is a 512 by 512 INTEGER*4 image.

  2. LAS> setapin comment=("b3732 washington 1 of 2", "b2678 washington 2 of 3") insys=vax filenum=(3,9) runtype=inter errflg=yes

    LAS-setapin> OUT=IMAGE1 BFORM=BSQ BANDS=-- WINDOW=(100,1,512,512) ODTYPE=SAME LINEINC=2 SAMPINC=2 DDRFLG=YES

    LAS-setapin> OUT=IMAGE2 BFORM=BIL LINEINC=1 SAMPINC=1 DDRFLG=YES

    The initial parameter set specifies that the tape B3732 is the first tape volume to be mounted on a drive and when an end of volume (EOV) or end of tape (EOT) is encountered, the tape B2678 is to be mounted. The third and ninth image files of the tape are to be copied into LAS images. The tape was generated on a VAX machine and may need to be converted to the current system format. The tape copy is to be run in INTERACTIVE mode, and if an error occurs while copying an image file, the process is to be aborted. The first dynamic tutor queries the user to define the parameters to process the third image file on tape. The third image file is copied into the LAS image IMAGE1. The DDR file is read from tape and used to determine the parameters TOTLINES, TOTSAMPS, TOTBANDS and IDTYPE. A 512 by 512 subwindow is processed starting at line 100 sample 1. The image is also subsampled taking every other line and sample resulting in a 256 by 256 INTEGER*2 LAS image.

    The second dynamic tutor queries the user to define the parameters to process the ninth image file on tape. The ninth image file is copied into the LAS image IMAGE2. The DDR file is read from tape and used to determine the parameters TOTLINES, TOTSAMPS, TOTBANDS and IDTYPE. The DDR file is then updated and copied to the DDR of the LAS image. The complete image from tape is copied to the LAS image IMAGE2.

  3. LAS> setapin comment="b12345 washington 1 of 1" insys=same filenum=(1,3) runtype=save outfile=washdc errflg=no

    LAS-setapin> OUT="IMAGE1" NHEADREC=0 TOTLINES=512 TOTSAMPS=512 TOTBANDS=1 IDTYPE=BYTE BFORM=BSQ BANDS=(1) WINDOW=-- ODTYPE=I*2 LINEINC=1 SAMPINC=1 DDRFLG=NO

    LAS-setapin> OUT="IMAGE1" NHEADREC=0 TOTLINES=1024 TOTSAMPS=1024 TOTBANDS=3 IDTYPE=I*4 BFORM=BSQ BANDS=(1,3) WINDOW=-- ODTYPE=I*2 LINEINC=2 SAMPINC=2 DDRFLG=NO

    The initial parameter set specifies that the tape B12345 is to be mounted on a drive. The first and third file of the tape are to be copied into LAS images. The parameters are to be saved in a file, and the LAS module TAPEIN may be executed at a later date. If an error occurs while copying an image file, processing is to continue with subsequent image files.

    The first dynamic tutor queries the user to define the parameters to process the first file on tape. The first file is copied into the LAS image, IMAGE1. The input image is a one-band 512 by 512 BYTE image file. If there is a DDR file, it is not copied into the LAS image. The complete image is converted to INTEGER*2 and copied to the appropriate LAS image file.

    The second dynamic tutor queries the user to define the parameters to process the third file on tape. The third file is also copied into the LAS image IMAGE1. The input image is a three-band (band sequential) 1024 by 1024 INTEGER*4 image file. If there is a DDR file, it is not copied into the LAS image. The first and third bands of the image are copied to image IMAGE1. Subsampling is applied to the whole image taking every other line and sample starting at line 1 and sample 1. The resulting output image is a 512 by 512 INTEGER*2 image.

Description/Algorithm:

From the parameter FILENUM, SETAPIN knows the number of files that are to be processed. Because the tapes are processed sequentially the FILENUM parameter must be in ascending order. For each file to be processed, a dynamic tutor is initiated to define the image parameters.

Once the parameters for each image have been input, SETAPIN does one of three things depending on the value of RUNTYPE.

If RUNTYPE = INTER  SETAPIN invokes the module TAPEIN in inter-
                    active mode using parameter values just 
                    input by the user, 
                    or
If RUNTYPE = BATCH  SETAPIN invokes the module TAPEIN in batch
                    mode using parameter values just input by 
                    the user, 
                    or
If RUNTYPE = SAVE   The user should have specified an output file
                    name for the parameter OUTFILE.  The parameters
		    specified are saved into the parameter file.
                    The user may then execute the module TAPEIN
                    at a later time by using the TAE restore 
                    command on the specified value.

Description of the tape copy routine TAPEIN:

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; control is returned to TAPEIN. The tape copy routine is invoked for each image file that is to be copied starting at the current position of the tape. When the last image file has been processed, the tape is dismounted.

Once the tape 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 User Notes). At this point, the tape is at the desired file to be copied into a LAS image. A check is made to see if a DDR file exists. If parameter DDRFLG is set to YES, the DDR file on tape is read and the parameters TOTLINES, TOTSAMPS, TOTBANDS and IDTYPE are set. The DDR information is updated and copied to the DDR of the LAS image. Otherwise, the DDR file is skipped. The tape is now at the beginning of the image data. The image data is in either BIL or BSQ format and may be any valid data type (BYTE, INTEGER*2, INTEGER*4, REAL*4). Each line of image data is read into a buffer. It is then determined whether or not the line of data is to be written to the LAS image file. The following checks are made to ensure that the line of data is to be included in the output image file:

   o  Verifies that the current image line is from a band that is 
      to be included in the output image.

   o  Verifies that the current image line is within the specified 
      window.

   o  Verifies that the current image line is to be included within 
      the subsampling that was specified.

If the current image line is to be included, only the samples of the image line after subsampling are written to the output image file that was converted to the specified data type. When the complete window has been written to the output image file, any lines remaining in the tape file are skipped and the LAS image file is closed.

If at any time during processing an end of volume (EOV) or an end of tape (EOT) is encountered, the operator and the user are signaled to mount the next tape volume so that processing may continue.

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

Nonfatal Error Messages:

  1. [setapin-warning]

    Current parameter values are insufficient to continue. The message immediately preceding this message will describe the error message in detail.

Fatal Error Messages:

  1. [setapin-dup] Duplicate File Numbers cannot be specified

    Duplicate file numbers were input.

  2. [setapin-band] INVALID BAND NUMBER

    An invalid band number was specified.

  3. [setapin-nbnds] SUM OF THE BANDS CANNOT EXCEED 256

    The sum of the specified bands exceeds 256.

    The user should refer to the TAPEIN user's guide for additional error message information.

User Notes:

  1. If the end of tape is encountered before processing is complete, the operator and the user are signaled to mount a new tape to complete the processing.

  2. 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.

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

          1.  DDR records 
          2.  Image data                                               
    

    The parameter FILENUM specifies the image files rather than physical files on tape. For example, the following diagram shows a valid tape format. If the user specified FILENUM=2, then the third physical file on tape is copied as image data into the LAS image.

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

  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.

  5. When the input system is not the same as the current system, the data must be reformatted and/or byte swapped before being written to the LAS image. The reformatting and byte swapping increases the processing time.

  6. Related LAS modules are TAPEIN, SETAPOUT, and TAPEOUT.