The Maple Archive manager, march, is used to manage files and variables archived in a Maple library.

The LibraryTools[Browse] command provides a graphical interface for executing most of the operations available through march.

The general calling sequence for a march command is:

march( action, archive_path, options );

Only one action can be performed on the library file or directory specified by archive_path at a time. Actions can be divided into two categories summarized in the tables below.

A Maple library archive can contain variables and/or files. Files can only be stored or extracted from a library. Variables are live and are automatically loaded into the current session when referenced, provided the archive is referred to by libname.

Most Maple variables can be saved in a single .m file using the save command.  The only exception is a module, which needs to split each of its exports and locals into individual ".m" files.  The save command only writes out the module structure, and not the values of each export and local.  An entire module can be properly saved using the savelib command.

The march command stores variables using the variable name as the index.  When dealing with variables it assumes ".m" can be appended to the end of the name.  For this reason there can be confusion when a file with the extension ".m" is stored in an archive.  A file with the name var.m cannot be stored in the same archive as a variable named "var".  Also referencing the name "var", when var.m is saved in an archive, attempts to load the contents of the file var.m, which fails if var.m is not a proper Maple data structure.

Note: Options can be strings, for example, "list". Details of individual command actions are provided below.

The 'add' and 'addfile' options add the specified files to the archive. Each file specified by filename is added to the archive, and is indexed using the corresponding indexname.  Multiple pairs of filename and indexname can be specified. If the file inserted is a Maple .m file that defines a variable named the same as indexname, then the value of indexname will be automatically loaded in your next session (provided the given archive is referenced by libname).

The 'add' option can be used only with a WRITABLE archive.

If a file is already indexed by indexname, march issues a warning, and processing continues.  To overwrite an existing index, use the 'update' or 'updatefile' option.

Files inserted by the 'add' option implicitly get ".m" appended to their index name, and are assumed to be files created by the Maple save command.  Ordinary files should be inserted using the 'addfile' option.

The 'create' option creates a new archive in the pre-existing directory specified by archive_path. The archive_path should be the full path of the .mla or .lib file to be created. For example, use the calling sequence, march('create',"c:/lib/my.mla") to create an archive called my.mla. If archive_path is a directory, maple.mla is created.

The table_size argument is optional and designates the approximate number of functions to store in the archive.  This does not limit the number of files that can be stored (the actual limit is approximately twice the table_size), but merely creates the new archive's index table, such that it can efficiently store that number of files. When the specified library name ends in .lib, library and index files in the standard format used by Maple 9 and earlier releases are created.  If the library file extension is .mla, a single archive file is created.

Note: When determining the number of functions to store in the archive, count each member of a module as one function.

If an old library exists in archive_path, march does not create a new archive. To remove the old library, the .mla file (or the .lib and .ind files) specified by archive_path must be removed.

When an archive is first created, its mode is set to WRITABLE and its priority is set to zero (see the following setattribute section.)

The 'create' option also accepts optional arguments, 'mode', 'priority', and 'time' as described in the setattribute section.

The 'convert' option converts between .mla and .lib library formats.  If the given library is in .lib format, a .mla library of the same name is created and vice versa. This is primarily used to combine a .lib and .ind pair into a single .mla file.

The 'delete' option deletes the members specified by indexname from the library archive.  The members are deleted immediately. No warning is displayed to prevent accidental deletion.  All deleted members become wasted space in the library archive, until the library is packed (see the following pack section). The 'delete' option can be used only with a WRITABLE archive.

Files inserted by the 'add' option should be removed with the 'delete' option. Similarly, files inserted by the 'addfile' option should be deleted with the 'deletefile' option.

The 'extract' and 'extractfile' options 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.  Multiple pairs of filename and indexname can be specified.

If a member does not exist, a warning is printed and processing continues.  If filename already exists, march overwrites it.

Files inserted by the 'add' option should be extracted with the 'extract' option. Similarly, files inserted by the 'addfile' option should be extracted with the 'extractfile' option.

The 'gc' option garbage collects the archive to remove index entries referring to inaccessible module members. When a module is saved in an archive, its members are also saved. If another instance of the module is saved with the same name, the new instance overwrites the old, and the members of the old instance become inaccessible. The 'gc' option finds these, and removes them from the index. They are then removed from the archive during the next 'pack' operation. The 'gc' option can be used only with a WRITABLE archive.

After garbage collection, march returns some information about what was accomplished: the number of objects in the archive before garbage collection, the number of objects remaining, and the number of bytes that would be freed if the archive were packed.

In general, manually garbage collecting an archive is not necessary, (and has no effect). Maple does this whenever a module instance is saved into the library. The 'gc' option is used internally by Maple to accomplish this. There may be cases where some other entry in the library refers to an otherwise-inaccessible module member. If this entry is removed, the member is truly inaccessible, but Maple cannot detect such a situation. In such cases, manually invoking march with the 'gc' option collects such objects.

The 'list' option 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 is a list, with one entry for each archive member. Each archive entry is a list of four items:

Member name, as a string

Date and time, as a list of integers specifying the year (all four digits), month (1..12), day (1..31), hour (0..23), minute (0..59), and second (0..59)

Offset, as an integer

Member size, as an integer

The name column gives the index name by which Maple can retrieve the member (or the 'extract' option can extract it) from the archive.  The date and time column indicates when the member was added to the archive.  The offset column indicates the position in the (.mla or .lib) archive file at which the member begins. The size column indicates how many bytes the member requires.

The 'listdir' option lists all archives and their corresponding attributes in a given directory.

The output is a list, with one entry for each archive. Each archive entry is a list of four items:

Full path of the archive .mla or .lib file, as a string

Date and time of the archive creation, as a list of integers specifying the year (all four digits), month (1..12), day (1..31), hour (0..23), minute (0..59), and second (0..59)

Mode (READONLY or WRITABLE), as a name

Lookup priority, as an integer

The 'moduleref' option returns the unique numeric identifier of a module member in the archive.

The 'open' option appends the given archive to libname so that variables in it are available for use in the active session. It also invokes the command specified by LibraryTools[ActivationModule] passing it its file name.

The 'pack' option packs the library archive.  All space wasted by old copies of named objects is purged from the archive (see the previous update and delete options). This can free a great deal of space if a large number of archive members have been replaced, or an archive member has been updated many times. The 'pack' option can be used only with a WRITABLE archive.

In general, manually packing an archive is not necessary. Maple repacks it whenever the amount of unused space exceeds one third of the total size of the .mla or .lib file.

The 'prefix' option lists all members of the archive that start with the specified prefix string. The output is a list of strings corresponding to the selected member names.

The 'reindex' option reindexes the library archive.  The existing index table is scanned, and a new index of optimal size is built. This index has the least number of hash buckets possible such that none of the buckets are full. This ensures O(1) search time when Maple reads from the library. The 'reindex' option can be used only with a WRITABLE archive.

In general, manually reindexing an archive is not necessary. Maple reindexes it whenever more than 10 hash buckets are read in a single search.

After reindexing, march returns some information about the newly created index: the number of entries, the old and new number of available index spaces, and the range of bucket sizes used.

The 'setattribute' option changes the attributes of the archive such as READONLY/WRITABLE mode, lookup priority, and timestamp. At least one of the mode_type, priority_value, or timestamp arguments must be provided in 'setattribute' option.  The mode_type argument must be READONLY or WRITABLE. The priority argument must be an integer. The timestamp argument must be an integer which is the number of seconds since the epoch. When timestamp is zero, the timestamp of the archive is updated to the current time.

In changing priority, archive_path must be the full path of the .mla file. In changing mode_type, archive_path can also be a directory so that the mode_type of all the .mla files in the directory can be changed all at once.

A WRITABLE archive can be written to. A READONLY archive can only be read, but cannot be modified. An attempt to modify a READONLY archive raises an error.

The priority argument specifies the lookup (search) order of the archive if there are multiple archives in the same directory. When Maple searches a directory that contains multiple archives, the archives with higher priority are searched first. Archives with the same priority are searched in alphabetical order.

The 'update' and 'updatefile' options are the same as 'add' and 'addfile' except the given indexname must already exist in the archive. For each indexname, the entry is updated with the corresponding filename.  Multiple pairs of filename and indexname can be specified.

'update' option can be used only with a WRITABLE archive.

If no entry is indexed by indexname, march issues a warning, and processing continues.  The updated version of a file is added to the end of the archive and the space it previously occupied is wasted until the archive is packed (see the following pack section). To insert an index for the first time, use the 'add' or 'addfile' option.

Files inserted by the 'add' option should be updated with the 'update' option. Similarly, files inserted by the 'addfile' option should be updated with the 'updatefile' option.

$\mathrm{libname}$

$''/usr/local/maple/lib'',''/u/joeuser/lib''$

$L≔\mathrm{march}\left('\mathrm{list}'\,\mathrm{cat}\left(\mathrm{libname}\left[2\right]\,''/joe.mla''\right)\right)\:$

$\mathrm{nops}\left(L\right)$

$20796$

$L\left[4..6\right]$

$\left[\left[''radnormal/evalf.m''\,\left[1999\,10\,9\,16\,29\,45\right]\,10167706\,181\right]\,\left[''limit/Ei.m''\,\left[1999\,10\,9\,16\,27\,17\right]\,4667673\,1241\right]\,\left[''int/hypergeom/power.m''\,\left[1999\,10\,9\,16\,26\,52\right]\,8099180\,827\right]\right]$

$\mathrm{march}\left('\mathrm{reindex}'\,\mathrm{libname}\left[2\right]\right)$

$20796,25664,29504,32..62$