NAME

VMS::Queue - Perl extension to manage queues, entries, and forms, and retrieve queue, entry, and form information.

SYNOPSIS

use VMS::Queue;

Queue routines

@ListOfQueues = queue_list([\%Queue_Properties]);
$Status = stop_queue($Queue_Name);
$Status = pause_queue($Queue_Name);
$Status = reset_queue($QueueName);
$Status = start_queue($Queue_Name);
$Status = delete_queue($Queue_Name);
$Status = create_queue(\%Queue_Properties);
$Status = modify_queue(\%Queue_Properties);
$EntryNum = submit(\%Entry_Properties, \%Entry_File_Properties[,...]] );
\%QueueProperties = queue_info($Queue_Name);
\%ValidQueueProperties = queue_properties();
\%DecodedBitmap = queue_bitmap_decode($AttribName, $Bitmap);

Entry routines

@ListOfEntries = entry_list([\%Entry_Properties[, \%Queue_Properties]]);
$Status = delete_entry($Entry_Number);
$Status = hold_entry($Entry_Number);
$Status = release_entry($Entry_Number);
$Status = modify_entry(\%Entry_Properties);
\%EntryProperties = entry_info($Entry_Number);
\%ValidEntryProperties = entry_properties();
\%DecodedBitmap = entry_bitmap_decode($AttribName, $Bitmap);

File routines @ListOfFileHashrefs = file_list($Entry_Number); \%ValidFileProperties = file_properties(); \%DecodedBitmap = file_bitmap_decode($AttribName, $Bitmap)

Form Routines

@ListOfForms = form_list([\%Form_Properties]);
$Status = create_form(%Form_Properties);
$Status = delete_form($Form_Name);
\%Form_Properties = form_info($Form_Number);
\%ValidFormProperties = form_properties();
\%DecodedBitmap = form_bitmap_decode($AttribName, $Bitmap);

Characteristic Routines

@ListOfCharacteristics = characteristic_list([\%Characteristic_Properties]);
$Status = create_characteristic(%Characteristic_Properties);
$Status = delete_characteristic($Characteristic_Name);
\%Characteristic_Properties = characteristic_info($Characteristic_Number);
\%ValidCharacteristicProperties = characteristic_properties();
\%DecodedBitmap = characteristic_bitmap_decode($AttribName, $Bitmap);

Queue Manager Routines @ListOfQueueManagers = manager_list([\%Manager_Properties]); $Status = stop_manager($Manager_Name); $Status = start_manager($Manager_Name); $Status = delete_manager(%Manager_Properties); \%Manager_Properties = manager_info($Manager_Name); \%ValidManagerProperties = manager_properties(); \%DecodedBitmap = manager_bitmap_decode($AttribName, $Bitmap);

DESCRIPTION

The VMS::Queue module lets a perl script (running as a user with appropriate privileges) manage queues, queue entries, forms, characteristics, and queue managers.

Queue functions

The queue functions create, delete, manipulate, or list queues. Most functions take either a queue name or a queue property hash. (With the exception of submit, which takes an entry property hash) The valid hash keys for each of the hashes is detailed in the "Property hashes" section.

queue_list()

The queue_list function takes an optional Queue_Properties hash, and returns a list of all the queues that match the properties in the hash. If no property hash is passed, then a list of all queues is returned.

stop_queue()

The stop_queue function stops the passed queue, essentially doing a STOP/QUEUE from DCL. If the optional second parameter is TRUE, then a STOP/QUEUE/NEXT is done instead.

start_queue()

The start_queue function starts the passed queue.

delete_queue()

The delete_queue function deletes the named queue.

create_queue()

The create_queue function creates a new queue with the passed properties.

modify_queue()

The modify_queue function modifies the queue referenced in the passed properties hash. Any property passed in the hash will be applied to the queue referenced in the hash if at all possible. (Some things can't be modified for existing queues. In that case, you'll have to delete and recreate the queue)

submit()

submit takes a reference to an Entry_Properties hash, and a reference to one or more Entry_File_Properties hashes. The files are submitted as a single entry to the queue manager. It returns the entry number if sucessful, or undef if not.

queue_info()

The queue_info function returns a reference to a Queue_Property hash, with the properties for the queue filled in.

queue_properties()

This funnction returns a reference to a hash whose keys are the valid keys for a queue_property hash. The values for the keys are currently undefined, though they might mean something in a future release.

queue_bitmap_decode()

Takes an attribute and an integer, and returns a reference to a hash. The properties are in the keys, while the values are INPUT, OUTPUT, or INPUT,OUTPUT. INPUT properties may be specified to a call that takes a queue_propery hash, while OUTPUT properties may be returned by a call that returns a queue_property hash.

Entry functions

The entry functions provide a way to manipulate queue entries.

entry_list()

This function provides a list of all the entries that match the optional entry_properties hash. If no hash is passed, all entries in all queues are returned.

delete_entry()

Deletes the entry identified by the passed entry number.

hold_entry()

Marks the passed entry as on hold.

release_entry()

Releases the passed entry.

modify_entry()

Modifies the entry, as identified in the entry_properties hash, with the new properties in the hash. Not all properties for a queue entry are modifiable, so this might throw an error.

entry_info()

Returns an entry_property hash with the properties for the passed entry.

entry_properties()

Returns the valid properties that can be in an entry_property hash. The properties are in the keys, while the values is a hashref with these four elements: INPUT_INFO, OUTPUT_INFO, INPUT_ACTION, and OUTPUT_ACTION. Each of these four hash entries will be set to true or false depending on whether the particular property can be specified as input or output for an action or info routine. (Action routines do something--create or delete a queue for example--while info routines return information on a queue or entry)

entry_bitmap_decode()

Takes an attribute and an integer, and returns a reference to a hash. The hash decodes the bitmap--each key refers to a bit in the bitmap, with the value set to true or false, depending on the value of the bit in the integer.

File functiond

The file functions deal with files within queue entries.

file_list()

This function returns a list of hashrefs. Each hashref corresponds to one file for the entry. (We do things this way since there's no easy way to refer to a particular file within an entry, so the xxx_list/xxx_info pair that the other groups use has no easy way to implement.)

file_properties()

This function returns a list of all the valid properties that can be returned for a file.

file_bitmap_decode

Takes an attribute and an integer, and returns a reference to a hash. The hash decodes the bitmap--each key refers to a bit in the bitmap, with the value set to true or false, depending on the value of the bit in the integer.

Form functions

The form functions manipulate the form information kept by the queue manager.

form_list()

This function returns a list of all forms that match the optional form properties hash. If no hash is passed, then all forms are returned.

create_form()

This function creates a form with the properties specified in the form_properties hash.

delete_form()

This function deletes the form specified.

form_info()

Returns an form_properties hashref with all the properties for the specified form.

Characteristic functions

characteristic_list

create_characteristic

delete_characteristic

characteristic_info

characteristic_properties

characteristic_bitmap_decode

Manager functions

manager_list

stop_manager

start_manager

delete_manager

manager_info

manager_properties

manager_bitmap_decode

Property hashes

There are several different property hashes that are passed around, either directly or by reference. The keys are always the symbol names as found in the documentation for the system calls $GETQUI and $SNDJBC, minus any prefix (i.e. $QUI$_ACCOUNT_NAME is ACCOUNT_NAME, and QUI$V_SEARCH_BATCH is SEARCH_BATCH)

BUGS

May leak memory. May not, though.

LIMITATIONS

The documentation isn't finished. (Hey, it's 0.12)

There's a very limited amount of error checking at the moment. If you try to modify something with a parameter that's for creation only (or vice versa), the syscall will fail and the function will croak().

The test suite's of limited utility.(Okay, it doesn't test anything really)

AUTHOR

Dan Sugalski <dan@sidhe.org>

Now maintained by Craig Berry <craigberry@mac.com>

SEE ALSO

perl(1), VMS System Services Reference Guide, SNDJBC and GETQUI entries.

cpanm VMS::Queue

perl -MCPAN -e shell
install VMS::Queue