User's Guide

HALFORB

Retrieve information relating to a half orbit

Function:

Read an orbital stitch list and return information associated with a half orbit of data. HALFORB should only be called from within a procedure PDF.

Parameters:

PROCOPT
Processing option. Parameter indicating for which purpose a half orbit of data is being acquired:

  = READ:       Information about a half orbit of data is
                required to ensure that all of the
                input scenes are on disk.  A half orbit
                of data will only be returned if at least
                one of the input scenes is on the UCFM and
                the remainder of the input scenes within
                the half orbit not on the UCFM are on disk.
  = STITCH:     Information about a half orbit of data is
                required so that it can be stitched.  A half
                orbit of data will only be returned if all
                of the input scenes have been line detected
                but not yet stitched.
  = DETECT:     Information about a half orbit of data is
                required so that it can be line detected.  A
                half orbit of data will only be returned if
                at least one of the input scenes resides on
                the disk and has not yet been line detected.

INFILE
Input file. The file containing the list of orbital stitching information. Refer to User Note 1 for the input file format.

LOGFILE
Log file. Name of the log file that the processing messages will be appended to.

STRSCENE(--)
Starting scene ID. The scene ID within INFILE at which processing should begin. If STRSCENE is not found within INFILE, no scenes will be processed. If defaulted, processing will begin at the first scene ID in INFILE.

ENDSCENE(--)
Ending scene ID. The scene ID within INFILE at which processing should end. If ENDSCENE is defaulted or the specified ID is not found within INFILE, processing will continue to the end of INFILE.

LINENUM
Line number. The line number to begin processing within INFILE. LINENUM should be initialized to 1 prior to the first call to HALFORB and left unaltered thereafter. HALFORB will return an incremented value in the specified TAE integer variable so that subsequent calls to HALFORB will progress through INFILE.

PROCFLG
Processing flag. Processing status is defined as:

  = 0:   Starting scene ID not yet found, processing has
         not began
  = 1:   Starting scene has been found, processing has begun
  = 2:   The ending scene has been encountered, this is the
         last orbit to process.

Prior to the first call to HALFORB, PROCFLG should be initialized to 1 if STRSCENE has not been specified. PROCFLG should be initialized to 0 if STRSCENE has been specified. HALFORB will return an updated processing flag value in the specified TAE integer variable which should be left unaltered between subsequent calls to HALFORB.

TAPEID
Tape identifiers. The tape identifiers corresponding to the scene identifiers in SCENEID will be returned in the specified TAE string variable.

NSCENES
Number of scenes. The number of scenes in SCENEID will be returned in the specified TAE integer variable.

SCENEID
Scene identifiers. The input scenes belonging to a half orbit will be returned in the specified TAE string variable.

LOCATE
Location of scenes. The locations corresponding to the scene identifiers in SCENEID will be returned in the specified TAE string variable. Valid return values are:

  = DISK:  Scene is located on disk in the sub-directory below
           the directory specified by the environmental
           variable ADAPSORB.
  = SILO:  The scene is located on the silo.
  = TAPE:  The scene is located on the tape specified in TAPEID.

SRCLNK
Source link. The data base source link that uniquely identifies a scene. The source links corresponding to the scene identifiers in SCENEID will be returned in the specified TAE string variable.

ORBITNM
Orbit name. The name of the output stitched half orbit will be returned in the specified TAE string variable. See User Note 3.

DONEFLG
Done flag. This variable should be initialized to TRUE indicating that all of the half orbits within INFILE have been processed. A return value of FALSE indicates that not all half orbits within the file have been processed. This parameter is returned in the specified TAE integer variable only if it has a value of FALSE. A value of TRUE indicates that the entire orbital stitch list INFILE has been read without finding any half orbital data to return to TAE.

EOFFLG
End-of-file flag. A flag indicating the end-of-file status of INFILE will be returned in the specified TAE integer variable:

  = 0:  End-of-file was not encountered
  = 1:  End-of-file was encountered

Example:

  1. LAS> halforb procopt="stitch" infile=ss050110.txt logfile=mylog strscene=ah11061293021213 endscene=ah11061293231203 linenum=linenum procflg=procflg tapeid=tapeid nscenes=nscenes sceneid=sceneid locate=locate srclnk=srclnk orbitnm=orbscene doneflg=doneflg eofflg=eofflg

    The input stitch list "ss050110.txt" is read and the information relating to the first half orbit between ah11061293021213 and ah11061293231203 is returned. Since a processing option of "STITCH" has been specified, only a half orbit that is ready for orbital stitching will be returned. If all of the input scenes within a half orbit have a line detect flag value of "L" within "ss050110.txt", this half orbit is ready for orbital stitching. The log messages are written to the file "mylog.log". The number of scenes will be returned in the integer variable "nscenes". The line number at which to begin reading within INFILE is defined by the integer variable "linenum". This value will be incremented by HALFORB. The processing status is passed in through "procflg" and will be altered and returned by HALFORB. The corresponding scene ID's, tape ID's, scene locations, and source links are returned in "sceneid", "tapeid", "locate", and "srclnk" respectively. The name of the half orbit to be stitched is returned in "orbscene". Processing will take place in the sub-directory "process" under the ADAPSORB directory. If a half orbit of data was found that was not ready to process, a done flag value of FALSE is returned (not all half orbits within the file have been processed). The end-of-file status is returned in "eofflg", an integer variable.

Description/Algorithm:

The specified input stitch list is read to determine which scenes are to be stitched into a half orbit. If a starting and ending scene ID are not specified, all of the scenes within the input file will be evaluated. All of the information relating to the half orbit is returned to the calling PDF. HALFORB should only be called from a procedure PDF due to the large number of predefined values required as parameters.

Nonfatal Error messages:

  1. [halforb-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The error message that is displayed immediately preceding this message is the specific error that was encountered. Processing will continue.

  2. [halforb-pre] Processing partial orbit following STRSCENE

    The specified starting scene ID STRSCENE excludes one or more scenes in the half orbit. Consequently, a partial orbit will be created.

  3. [halforb-end] Processing partial orbit preceding ENDSCENE

    The specified ending scene ID ENDSCENE excludes one or more scenes in the half orbit. Consequently, a partial orbit will be created.

  4. [halforb-clos] Error closing <XXXXXX> file

    An error was encountered while trying to close the specified file. If this error continues to occur, contact the system administrator.

  5. [halforb-dup] Duplicate scene specified

    A scene was specified more than once in the input file. Duplicate entries will be ignored.

Fatal Error messages:

  1. [halforb-fatal] Fatal error encountered

    A fatal error was encountered. The message displayed preceding this message is the error that was encountered. Processing terminates.

  2. [halforb-open] Error opening <XXXXXX> file

    The specified file does not exist or does not have the proper file permissions set.

  3. [halforb-conv] Error converting line buffer data

    A buffer of data read from INFILE is not in the expected format. Investigate the data in the specified input file (see User Note 1 for input file format).

  4. [halforb-read] Error reading line in input file

    An error occurred reading a line from the input orbital stitch list. Verify that the file has not been corrupted.

  5. [halforb-unkw] Scene <XXXXX> location unknown

    The specified scene does not exist in the ADAPSORB directory, does not exist on the UCFM, nor is an archive tape identifier available. Consequently, this scene will not be stitched. Check the origin of this scene identifier.

  6. [halforb-dcon] Error converting date

    An error occurred while converting a scene acquisition date to a julian date. Check the input file for invalid acquisition dates.

  7. [halforb-rparm] Error returning parameter to TAE

    An error was encountered while trying to return a parameter to TAE. Contact the system administrator.

  8. [halforb-ftp] UCFM/FTP not operational

    The File Transfer Protocol is unable to communicate with the UCFM file system. Contact the system administrator.

  9. [halforb-envron] Error retrieving <XXXXXX>

    An error occurred while trying to retrieve the specified environment variable. Make certain the variable has been assigned a value.

User Notes:

  1. The expected format of the input file is as follows:

    tapeid mth acqdate  start  stop ceos st d a source flg
    031185 AH 04/01/92   5332  10408 NGC 11 D A  31376
    019990 AH 04/01/92  34636  35718 HBT 11 D A  37446
    020403 AH 04/01/92  35703  40438 TSV 11 D A  38496
    031272 AL 04/01/92  41800  42906 NOA 11 D A  31435
    019990 AH 04/01/92  52626  54118 HBT 11 D A  37447
    020403 AH 04/01/92  53416  54728 TSV 11 D A  38497
             .                            .
             .                            .
             .                            .
    

    The header is read until the line beginning with "tapeid" has been encountered. Valid lines of data are expected following this line.

  2. The input file is generated by LISTITCH or is a data base listing of scenes on archive tape.

  3. The name of the stitched output image is the same as the scene ID of the first pass of the half orbit with the second character within the name changed to "o". For example, if the scene ID of the first pass within an orbit is ah11063092144517, the name of the stitched orbit will be ao11063092144517.

  4. HALFORB is utilized by multiple orbital stitching applications:

        HALFORB is called by ORBSTITCH with PROCOPT set to "STITCH".
        HALFORB is called by ORBREAD with PROCOPT set to "READ".
        HALFORB is called by LAPSTITCH with PROCOPT set to "READ".
        HALFORB is called by ORBLN with PROCOPT set to "DETECT".
    

  5. Refer to the orbital stitching overview for more detailed information.