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]);
$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()

Characteristic functions

Manager functions

Property hashes

There are several different property hashes that are passed around, either directly or by reference.

Queue_Properties

Entry_Properties

Form_Properties

Characteristic_properties

Manager_Properties

BUGS

May leak memory. May not, though.

LIMITATIONS

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

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 optional hash for the xxx_list isn't used. (Don't pass it--things'll screw up)

AUTHOR

Dan Sugalski <sugalskd@ous.edu>

SEE ALSO

perl(1)

cpanm VMS::Queue

perl -MCPAN -e shell
install VMS::Queue