NAME

IMS::ReleaseMgr::FileList - Create a simple IMS-compatible upload package.

SYNOPSIS

    use IMS::ReleaseMgr::FileList;

    ...

    upload_files($user,
                 $mirror_group,
                 $project,
                 $directory_base,
                 {
                  file1 => '/path/to/file1',
                  file2 => $open_fh_on_file2,
                  'dir/file3' => '/diff/path/to/file3'
                 });

    if ($text = error)
    {
        die "Error creating upload package: $text, stopped";
    }

DESCRIPTION

The IMS::ReleaseMgr::FileList package is a small, generalized interface to the release manager class, IMS::ReleaseMgr. This interface allows a program to create small distributions from a handful of files and take advantage of the existing release management facility to facilitate the actual distribution. For machines that are one part of a larger mirrored pool, this also ensures that the files will be propagated to all other members of the mirror pool.

This package is not an object class, like its predecessor. There are only two routines, which are exported by default.

ROUTINES

There are two routines exported by this package. If either or both are expected to conflict with other routines in the application, explicit import can be used instead:

    use IMS::ReleaseMgr::FileList qw(upload_files); # Don't import error()

and the other routine (IMS::ReleaseMgr::FileList::error) called by fully-qualified package name.

These routines are:

upload_files($user, $mirror, $project, $dir, $files)

This is the main interface routine. The arguments are:

$user

A user name to associate with this package transfer. In a more CGI-centric view, this would be the authenticated user for a page that was access-controlled. This information is bundled into the uploaded package.

$mirror

The name of the system pool that this is running on, i.e. "www.interactive.hp.com". This information is used to insure that the package is delivered into the correct area, and propagated out to the correct subset of secondary servers.

$project

The name of the project, as known by on the server (mpgawg, etc.)

$dir

A directory path prefixed to all the file names when the archive is being created. This has no bearing on the location of the local files that are read from, it is only here as a shortcut for groups of files all under the same directory path relative to $project.

$files

A hash-table reference, whose keys are the file names as they will appear in the archive, and whose values are either names of physical files on the host filesystem, or open filehandles that can be read from directly. If a value in this table is a file name, it must either be an absolute path or relative to the current working directory of the running process. No checks are made that the paths are correct; failure to open a file means failure of this routine call. Any values that are file handles (of a reference type GLOB or IO::File) are first subjected to a seek system-call to make certain the pointer is at the start of the file. After reading, another seek-to-start is done, so after the call to this routine all filehandles will be at the head of their respective files.

Any errors that are encountered are reported via the error routine documented below.

error

Returns the text of the most recent error, or none if the last call to upload_files was successful. Note that the return value is not specifically set to undef, so the test should be looking for a return value that is both defined and non-null.

BUGS

None currently known.

CAVEATS

Any error results in the working directory under /tmp to be removed. There is currently no option to disable this behavior.

SEE ALSO

IMS::ReleaseMgr

AUTHOR

Randy J. Ray <randyr@nafohq.hp.com>