MARCH(1)

NAME
march - Maple library archive manager

SYNOPSIS
march -a archiveDir { fileName indexName }
march -u archiveDir { fileName indexName }
march -p archiveDir
march -l archiveDir
march -c archiveDir tableSize
march -x archiveDir { indexName fileName }
march -d archiveDir { indexName }

DESCRIPTION
March (the Maple ARCHive manager) is used to manage Maple ".m" files archived in a Maple library. It performs the following functions, on a library archive:

    -adds or updates Maple ".m" files
    -packs (garbage collect)
    -lists the contents
    -creates a library archive
    -extracts (but not remove) files
    -deletes a file

Exactly one of the above command line options must be specified.

March uses or creates the library archive files "maple.lib" and "maple.ind" located in archiveDir.

The rest of this document contains the following sections:

    OPTIONS
    ARGUMENTS
    DIAGNOSTICS

plus, the standard:

    FILES
    SEE ALSO

OPTIONS
The following command line options are understood by march. Exactly one of these options must be specified per command:

-a  Adds the specified ".m" files to the archive. Each file specified by a fileName is added to the archive, and indexed using the corresponding indexName.

    If there is already a file indexed by indexName, march issues a warning, and processing continues.

-u  Updates the specified ".m" files in the archive. For each indexName, the entry is updated with the corresponding fileName.

    If there is no entry indexed by indexName, march issues a warning, and processing continues.

    If the updated version of a file is smaller or the same size as the old version (in the library archive), it is stored in the space occupied by the old version. Otherwise, it is added to the end of the archive and the space it previously occupied is wasted until the archive is packed.

-p  Packs the library archive. All wasted space is purged from the archive (see update option above). This can free up a great deal of space if a large number of archive members have been replaced, or the same archive member has been updated frequently.

-l  Lists the contents of an archive. Each member is listed in the order it appears in the index (so the order is effectively random).

    The output consists of three columns: name, offset, and size. The name column gives the index name by which Maple can retrieve the member (or -x option can extract it) from the archive. The offset column indicates the position in the archive file ("maple.lib") that the member begins. The size column indicates how many bytes the member requires.

-c  Creates a new archive in archiveDir. The tableSize argument should be approximately the number of files you wish to store in the archive. This does not limit the number of files that can be stored, but merely creates the new archive's index file, such that it can efficiently store that many files.

    If an old library exists in archiveDir, march will not create a new archive. To remove the old library, the files "maple.lib" and "maple.ind" in archiveDir, must be removed.

-x  Extracts the specified members of the archive. Each member specified by an indexName is copied into a file specified by the corresponding fileName. The member is not removed by this option.

    If a member does not exist, a warning is printed and processing continues. If fileName already exists, march over-writes it.

-d  Deletes the members specified by indexName from the library archive. The members are deleted as soon as the command is entered, with no warnings to prevent any accidental deletion. All deleted members become wasted space in the library archive, until the library is packed.

ARGUMENTS
The archiveDir argument specifies the location of the archive that is to be managed. The directory "archiveDir" must exist. The files "archiveDir/maple.lib" and "archiveDir/maple.ind" must also exist (or will be created if -c is specified).

The fileName and indexName pairs specify the file whose contents are to be added, or updated in the archive, and the name that the file should have in the archive index respectively. In the extraction case, fileName refers to the file into which, the contents of indexName are copied (from the archive).

The tableSize argument is used when creating the archive to specify the initial index size (see the description of the -c option).

DIAGNOSTICS
March may produce the following diagnostic messages:

there is already an archive in 'archiveDir'
    An attempt was made to create an archive in a directory which already contains an archive.

there is no existing archive in 'archiveDir'
    An attempt was made to add to, update, pack, list, or extract from a non-existent archive.

there must be an indexName for each fileName

there must be a fileName for each indexName
    An add, update, or extract command was followed by an odd number of names (ie. there was one left over at the end of the list).

temporary archive files could not be created

could not write to new index or archive

an error occurred while closing the new archive
    When packing an archive, the packed archive could not be created successfully. The archive will be left untouched. The usual cause of one of these messages is insufficient disk space. In order to pack an archive, you need at least as much free space as the size of the archive. Another possible cause is that you do not have permissions to write into the directory containing the archive.

an error occurred while creating 'archiveName'
    While extracting from an archive, the extracted file could not be created successfully. This is usually caused by lack of disk space or permission to write the file.

the archive data file could not be created

the archive index file could not be created

an error occurred while creating the archive

an error occurred while creating the index
    A new archive could not be created (due to lack of disk space or improper permissions).

an error occurred while reading the index
    The archive index is damaged in some way.

an error occurred while updating the archive

an error occurred while updating the index

an error occurred while updating the index or archive
    While adding to or updating an archive, an error occurred. This is usually as a result of insufficient disk space. The archive may be left in an unusable state if this happens.

no more files can be added to the index
    The index is completely full. This can happen if far more files are added to the archive than was originally intended. In this case, create a temporary directory somewhere, extract all the files from the archive, delete the archive, create a new (larger) archive, and add all the files to this archive.

the index could not be opened for updating

the archive could not be opened for updating
    You do not have permissions to update the archive.

the name 'indexName' is longer than 55 characters
    When adding to or updating an archive, you specified an indexName that is longer than 55 characters (including any "/" or "." characters).

the table size must be between 1 and 99999
    The table size for creating an archive must be between 1 and 99999. The limit of 99999 was chosen to prevent the accidental creation of ridiculously large archives.

warning, 'indexName' already in archive
    While adding to an archive, the member to be added was already in the archive. Use the -u option instead (after making sure you had typed the member name correctly).

warning, 'indexName' not found in archive
    While updating an archive, the member to be updated was not found in the archive. Use the -a option instead (after making sure you had typed the member name correctly).

warning, file 'fileName' could not be opened
    A file to be added could not be opened (it does not exist, or you do not have read permissions), or a file to be extracted could not be opened (there is no disk space, or you do not have write permissions).

FILES
archiveDir/maple.lib - the library archive file
archiveDir/maple.ind - the corresponding library index file

SEE ALSO
Other Maple related commands:
Maple, mint, m2src, and updtsrc