Icarus-Archive User’s Guide
Version 1.1.0
June 6, 2011

Contents

1 Overview
 1.1 Features
 1.2 Limitations
2 Quick-Start
 2.1 Creating an Archive
 2.2 Retrieving Files From an Archive
  2.2.1 Retrieving Archive Files From Tape or Removable Disk
  2.2.2 Retrieving Archive Files From a Hard Disk or Diskset
A Screenshots


Acknowledgements

ProMAX and SeisSpace are registered trademarks of Landmark Graphics Corporation. Linux is a registered trademark of Linus Torvalds. Unix is a registered trademark of The Open Group. Icarus-Archive is a product of Icarus Resources. Icarus-Archive and its documentation © 2003-2011 by Edward W. Leaver. All rights reserved.

1 Overview

Icarus-Archive facilitates the archival of datasets for Landmark Graphics Corporation’s ProMAX(tm) seismic data processing system, and the transfer of data between ProMAX installations. Icarus-Archive recognizes any mounted Linux filesystem, and arbitrary Linux files and directories may be included along with ProMAX datasets in an Icarus-Archive archive.

1.1 Features

1.2 Limitations

2 Quick-Start

When Icarus-Archive is first started you will be presented with a tabbed window containing an Info Window[6] and – if there were no license or configuration errors – a Main Window[5] 

[Picture]

Figure 1: Main Window (5)

as well. The first thing one should always do is check the configuration information displayed in the Info Window[6]. Make certain no errors are reported, and that the PromaxDataHome diskset(s) listed in the configuration – the primary and secondary ProMAX disk partitions – are the ones you actually want to create archives from, or if restoring data, the PromaxDataHome diskset(s) you really want to write data to.

If Icarus-Archive finds no obvious errors in the configuration files, it will display ”Ready” on Main Window[5]’s statusbar. You will be given opportunity to review each subsequent operation before commiting to its execution.

[Picture] [Picture]

Figure 2: Info Window and File Browser (6,7)

2.1 Creating an Archive

In addition to Info Window[6] you will work with four other windows:

  1. Main Window[5]: Here you will provide an Archive Label, an Archive Comment, select whether to Save to Tape or Save to Disk, and choose a Tape Device or Disk Volume as appropriate. For multivolume archives you must also supply a Tape Length or disk Volume Filesize. You may also choose not to save any seismic trace files.
  2. File Browser Window[7]: Here you select ProMAX data to be archived.

    [Picture] [Picture]

    Figure 3: Create Status and Verification Windows
  3. Create Status Window[8]: Displays state of creation process and prompts for confirmation before beginning.
  4. Verification Window[9]: After your archive is complete, the Verification Window will appear and prompt you to optionally reload the tape and verify its contents. Disk archives will be verified without prompting.

To create an archive:

  1. From Main Window[5] select ”Create New Archive” and either ”Save to Tape” or ”Save to Disk” from the top row of radio buttons. If you select ”Save to Tape” the Tape Device combo box will initially be empty. Click on the down-arrow at its right, and select a tape drive or removable disk drive from the drop-down list. The Status entry should then indicate whether or not the drive is online and if it is, whether or not a tape (or removable disk) is loaded.

    If a tape is loaded, please be certain it is your own: Icarus-Archive has no facility to lock a drive to a specific user.

  2. In Main Window[5] fill in your Archive Label and Archive Comment. Archive Labels may consist only of alphanumeric characters, underscore, and hyphen. For disk archives, the Archive Label will be appended with a volume number and timestamp to give the disk filename, so whitespace and other weird characters cannot be allowed. The label must be no longer than 60 characters.

    In contrast, Archive Comment may be any text of arbitrary length. Your comment will be included in the Archive Header, and will be displayed in archive lists presented by the Retrieve Window[10]. A label should be short but descriptive. The comment should include any important keywords near its beginning so they are readily visible during display.

    The remaining five entries in Main Window[5] may usually be ignored:

    1. Main Window[5]: Archive Size will be computed by the program and presented for your approval before the archive is finally created. No need to enter anything here.
    2. Main Window[5]: Tape Length may be left at ”Default” unless your archive will need more than one tape (multivolume archive). In this case set the Tape Length to the length of your tape (MBytes or GBytes) or, if you are writing to removable disk, the size of the removable media.
    3. Main Window[5]: Tape Compression. Most raw seismic data is essentially random and cannot be compressed. Leave this at its default ”none.”
    4. Checksum Type: You have a choice between ”Adler-32”, ”CRC-32”, ”MD5sum”, and ”None”. The default ”Adler-32” is a reasonable choice.
    5. Main Window[5]: Exclude Trace Files. Check this entry if you do not wish for ProMAX Trace dataset TRC and HDR files, or JavaSeis TraceFileN and TraceHeadersN files, to be included in your archive. This switch only excludes the lengthy TRCn and HDRn files and JavaSeis TraceFileN and TraceHeadersN files: Trace data CIND and CMAP files and primary disk JavaSeis metadata files will always be retained. You must choose whether to select Exclude Trace Files before activating the Select Files file browser window (see next), so that window’s tree search will know whether or not to include the Trace TRC and HDR files in its selection.
  3. Next, from Main Window[5] press Select Files. You will be presented with a window containing two adjustable panes. The top pane displays a ProMAX directory-browser treeview which (if Icarus-Archive was launched from ProMAX) will be initialized to the ProMAX Area, Line, and Flow under which you are currently working. The treeview in the bottom ”Selection” pane will initially be empty:

    1. Select one or more ProMAX Area, Line, or Trace datasets from the top browser treeview, then press the ”Select Items” button underneath. After a few minutes of file-searching and disk-usage computation, your Selected Items will appear (along with their size) in the bottom pane’s ”Selection” treeview. Browse the Selection treeview to make sure it has the items you want archived. You may add more from the browser treeview. You may also select excess items from the Selection treeview and remove them with the ”Remove Items” button. (Note: you should never remove a ”MustSave” row from the Selection treeview unless you also remove the entire parent row that contains it. ”MustSave” subrows contain files critical to restoring and using the data you have selected.)
    2. When you are satisfied with the archive contents displayed in the Selection treeview, you may click the ”Create Archive” button to start the archive process. Or you may return to the Main Window[5], check the Archive Label and Comment, optionally add any additional files from Main Window[5]’s Filename: entry, and click on the ”Create Archive” button there.
  4. Returning to the Main Window[5], you should see your archive contents displayed in the Main Window[5]’s ”Selected Files” treeview, with the Archive Size entry filled in with the actual size your archive will occupy on tape or disk. Additional files or directories from outside the ProMAX diskset may be added as desired, using the Filename: entry near the top. After you have everything, click the ”Create Archive” button to start the process of archive creation. A Create Status Window[8] will appear, telling you the number of volumes in your proposed archive, their size, and (if there is more than one volume) the largest file contained in each. Here you also have an opportunity to Exclude Trace Files, SEGY Files Last, and elsewise Order the files in your archive. The defaults are reasonable. You may alternate these Create Status Window[8] selections with Main Window[5]’s Tape Length and Archive Comment entries until you get a satisfactory archive file order and volume arrangement. Press ”Ok” to confirm, and your archive creation will begin:
    1. File checksums will be computed first. This may take a while, so be patient.
    2. Next the archive volumes will be written to tape or to disk. If writing to tape or similarly configured removable USB drives, you will be prompted to change the media if more than one volume is required.
  5. After your archive has been successfully written, a Verification Window[9] will appear and prompt you to verify the integrity of the archive just written. The tape will be ejected first; you must reload the tape before it may be verified. (Note: the Icarus-Archive program becomes unresponsive during tape rewind and eject.) If Verification Window[9] does not automatically appear upon creation of an archive, it may be activated by selecting ”Archive Verification Tool” from the Main Window[5]’s ”Tools” submenu.

Upon completion the Verification Window[9] will show the number of files that passed verification, the number that failed, and the total number of files in your archive. A good archive has zero verification failures. However, occasionally the verification might fail on a good archive, perhaps due to a tar failure: you may always re-run the verification to be sure.

2.2 Retrieving Files From an Archive

There are several possibilities. You may retrieve an entire archive or just selected parts - a particular ProMAX Line or Flow for example. You may have a choice of one or more Data Home disk areas upon which to put the retrieved files. Your archive may either be stored on tape or on disk. And there may or may not be a copy of your archive’s table-of-contents online. Icarus-Archive can handle each of these, and has three windows associated with archive retrieval:

  1. A Retrieve Window[10] that allows you to choose both a source (tape or disk) for the archive being retrieved and a destination Data Home diskset upon which to write the retrieved data. The destination diskset may be your current PromaxDataHome, or it may be any other ProMAX (possibly SeisSpace-configured) Data Home diskset, an Icarus-Archive configured diskset, or an arbitrary Linux disk directory.
  2. A Retrieve Editor Window[11] that allows you to select either the entire archive, or specific parts of the archive, for retrieval and
  3. A Retrieve Status Window[12] that informs of the progress of the retrieve operation.

[Picture] [Picture]

Figure 4: Archive Retrieve Editor (11) and Status Windows (12)

At the top of Main Window[5] press the ”Retrieve Existing Archive” radio button. This will bring up the Retrieve Window[10].

At the top of Retrieve Window[10] are ”Retrieve From Tape” and ”Retrieve From Disk” radio buttons. Select the one appropriate for your archive. If you know your archive has a copy of its table-of-contents online, you may select the appropriate Disk Database area from the ”Archive Location” combo list. Otherwise you may read the archive’s table-of-contents directly from the tape (by checking the Read Label From Tape checkbox), or from the archive’s datafile on disk (done automatically for disk archives).

2.2.1 Retrieving Archive Files From Tape or Removable Disk

This section applies to SCSI tape drives and DVD-RAM drives. External drives (USB, Firewire, eSATA) drives may also either be configured as Removable Disks, or as hard drives1 Beneath the Retrieve Window[10]’s ”Retrieve From Tape” and ”Retrieve From Disk” radio buttons you will see Tape Device and Status entries, and a ”Read Label From Tape” checkbox. The tape device itself must be selected from the Tape Device drop-down list in the Main Window[5]; the device and its status will be re-displayed here. Tape devices include removable disk drives such as Magneto-Optical (MO) and DVD-RAM. For archive retrieval, ordinary CDROM and DVD may be used as well.

  1. Choose a tape device or removable disk drive from the list on Main Window[5], and load the archive tape to be retrieved in the drive.
  2. The Retrieve Window[10] contains a listview of the labels of the archives written at your site, in the Database Diskset selected by ”Archive Location”. An archive’s label identifies its table-of-contents, which Icarus-Archive needs before it can retrieve any of that archive’s data. If your archive’s label appears in the online listview, you may select it from here.

    Otherwise (or if you are unsure) check the ”Read Label From Tape” checkbutton, and (after your tape has finished loading) press the ”Read Label” button that has appeared at the bottom of the Retrieve Window[10]. A Retrieve Status Window[12] will appear and the table-of-contents will be read from the header file on the tape and placed on the Retrieve Window[10]’s table-of-contents list. This will take a few minutes.

  3. Now select your desired archive label from the Retrieve Window[10]’s table-of-contents treelist. If you read the label from tape, there will only be the one label in the listview. (It is under your username, and you still must select it.) Then press the ”Select Archive” button. This will bring up the Retrieve Editor Window[11] which allows you to select the archive (or specific portions) for retrieval.
  4. At the top of the Retrieve Editor Window[11] are displayed your archive’s label, creation date, size, and the archive’s complete comment. The next row contains a drop-down list of Data Home disk areas to which you may restore your archive. This ”Restore to” entry is editable: if you wish to restore your archive to some other location such as a temporary directory, you may type that directory’s absolute path into the entry, then press the ”Add” button to add it temporarily to the list.

    Beneath the ”Restore to” entry is a treeview of the archive’s table-of-contents, i.e. a list of all the files in the archive. It works much like a typical file browser, but there will be a few differences: in particular, the treeview will show the archive files as they appeared on the host ProMAX system from which the archive was written, starting at root (”/”) and (usually) continuing with the original host’s PromaxDataHome. When you actually retrieve your archive the original host’s PromaxDataHome segment of each filepath will be replaced by the Data Home you have selected on your current system, or by the directory path to the alternate ”Restore to” disk area if you have selected another disk area for your restore.

    Any archive files that were not in the original host’s PromaxDataHome will be restored with their full original filepaths, but now relative to the primary directory path of your currently selected local Data Home, or of whatever other ”Restore to” disk area you have selected. Icarus-Archive will not write files outside your selected disk area.

    1. Select the files and directories you wish to retrieve. Selecting any row automatically selects all the subrows beneath it, as well as the contents of all ”MustSave” rows above it. Check whether or not you wish TRC and OPF data files to go on your primary partition (Skip Primary checkbox), or whether you wish to skip retrieval of Trace datafiles and headers (TRCn, HDRn, and JavaSeis TraceFileN, TraceHeadersN) altogether (Exclude Trace Files checkbox).
    2. Choose a retrieve order: Round-Robin, Most-Space, or Original-Source. Original-Source attempts to restore the archived files onto the same disk partitions on your current system that correspond to the ProMAX disk partitions of the original host. It can do this only if the number of partitions on your current system is greater than or equal to the number of partitions on the original host. You may not select both Skip Primary and Original-Source: if the original host placed TRC and OPF data files on the primary disk and you select Original-Source, you shall end up with TRC and OPF data on your primary disk partition as well. Press the ”Select Items” button to copy each selected item in the upper ”browser” treeview to the lower ”Selection” treeview.
    3. Press the ”Check Disk” button after you have selected all the files and directories you wish to retrieve. This checks to see whether the disk area you have selected to place your retrieved files already contains files with the same names. Perhaps you didn’t really want to overwrite these existing files, and selected this disk area by mistake. Or perhaps you did wish to overwrite them: now would be a good time to make sure.

      If you do choose to overwrite existing files, Icarus-Archive will try (space permitting) to make backups of those existing files by renaming them with an .archive-bak extension. But before doing so, the ”Check Disk” operation first checks for the existance of such backup files that Icarus-Archive may have made during a previous retrieval of this archive to this disk area and that were not subsequently removed. It will let you know if it finds any, and ask whether you want them removed now. ”Check Disk” does quite a bit of file renaming and possibly removal: for this reason you should not answer ”Ok” to any of ”Check Disk’s” questions until you are certain of your choice of files to retrieve.

    4. Press the ”Retrieve Selection From Archive” button after you have decided to continue with the archive retrieve. This will bring up a Retrieve Status Window[12] and send the tape drive the commands to write your selected files out onto disk. Afterward there will be a verification phase where the integrity of the retrieved files is checked by recomputing their checksums after they have been written, and comparing that checksum with the value stored in the table-of-contents when the archive was created. If the checksums do not match, you will be given the choice of
      1. Retry the retrieve process starting at the first failed file. Sometimes a bad tape can be successfully read given enough patience.
      2. Abandon the retrieve and restore any previously existing files from their backups.
      3. Abandon the retrieve and leave everything as it is. (Usually not a good idea.)

      The Retrieve Status Window[12] will eject the tape when it is through. Note that tape ejection is a synchronous process, and the application will become unresponsive while it completes. If you are retrieving from a multivolume archive, the Retrieve Status Window[12] will also prompt you to change the tape. Finally, you will need to press the Retrieve Editor Window[11]’s ”Finish” button when you are done.

2.2.2 Retrieving Archive Files From a Hard Disk or Diskset

This section applies to archives stored on an Archive Database Diskset, a hard disk directory, or any other media that has been mounted to look like a readable directory on the filesystem. From Main Window[5] press the ”Retrieve Existing Archive” radio button to bring up a Retrieve Window[10].

  1. Press the Retrieve Window[10]’s ”Retrieve From Disk” radio button. You will need to know on which filesystem directory or Archive Database Diskset your archive is stored. Pre-configured Archive Database areas may be selected from the ”Archive Location” combo list. This entry is editable: if your archive is in some filesystem directory not on the list, you may enter it here.
  2. If an Archive Database area is selected, the archives contained therein will be listed under the name of the user who created them. If some other directory was entered, the list will display all the tarfiles in that directory (regardless of whether or not they are Icarus-Archive tarfiles). Select the archive you wish to retrieve, and press ”Select Archive”. A Retrieve Editor Window[11] will appear identical to the one displayed when retrieving tape archives.
  3. Proceed as for tape archives:
    1. Select a ”Restore to” location on which to write the retrieved files.
    2. From the top treeview select all or part of the archive for retrieval. Press ”Select Items” to add each selection to the lower ”Selection” treeview.
    3. Press ”Check Disk” to get the status of the ”Restore to” disk area.
    4. Choose whether to ”Skip Primary”, and select a retrieve Order. (Round-Robin, Most-Space, or Original-Source.)
    5. Press Retrieve Selection From Archive to start the retrieval. A successful retrieve will be followed by verification.
    6. Press ”Finish” when you are done.

A Screenshots

[Picture]
Figure 5: Main Window


[Picture]

Figure 6: Info Window


[Picture]

Figure 7: Promax File Selection


[Picture]

Figure 8: Create Status Window


[Picture]

Figure 9: Verification Window


[Picture]

Figure 10: Retrieve Window


[Picture]

Figure 11: Retrieve Editor Window


[Picture]

Figure 12: Retrieve Status Window


[Picture]

Figure 13: Cleanup Window


[Picture]

Figure 14: Compare Disksets Window

1Icarus-Archive configures hard drive partitions to store large numbers of archives: they contain Data and Toc subdirectories for separate storage of data and table-of-contents files, with subdirectories for individual users. Removable Disks are assumed to contained only one (or a few) archives: their filesystems are flat and contain only datafiles from which tables-of-contents are read directly.