package VMS::Queue; use strict; use vars qw($VERSION @ISA @EXPORT @EXPORT_OK); require Exporter; require DynaLoader; @ISA = qw(Exporter DynaLoader); # Items to export into callers namespace by default. Note: do not export # names by default without a very good reason. Use EXPORT_OK instead. # Do not simply export all your public functions/methods/constants. @EXPORT = qw(); @EXPORT_OK = qw(&queue_list &stop_queue &pause_queue &reset_queue &start_queue &delete_queue &create_queue &modify_queue &submit &queue_info &queue_properties &queue_bitmap_decode &entry_list &delete_entry &hold_entry &release_entry &modify_entry &entry_properties &entry_bitmap_decode &entry_info &file_list &file_properties &file_bitmap_decode &form_list &delete_form &create_form &modify_form &form_info &form_properties &form_bitmap_decode &characteristics_list &create_characteristics &delete_characteristics &modify_characteristics &characteristic_info &characteristic_properties &characteristic_bitmap_decode &manager_list &stop_manager &start_manager &create_manager &modify_manager &delete_manager &manager_info &manager_properties &manager_bitmap_decode); $VERSION = '0.57'; bootstrap VMS::Queue $VERSION; #sub new { # my($pkg,$pid) = @_; # my $self = { __PID => $pid || $$ }; # bless $self, $pkg; #} #sub one_info { get_one_proc_info_item($_[0]->{__PID}, $_[1]); } #sub all_info { get_all_proc_info_items($_[0]->{__PID}) } #sub TIEHASH { my $obj = new VMS::ProcInfo @_; $obj; } #sub FETCH { $_[0]->one_info($_[1]); } #sub EXISTS { grep(/$_[1]/, proc_info_names()) } # Can't STORE, DELETE, or CLEAR--this is readonly. We'll Do The Right Thing # later, when I know what it is... #sub FIRSTKEY { # $_[0]->{__PROC_INFO_ITERLIST} = [ proc_info_names() ]; # $_[0]->one_info(shift @{$_[0]->{__PROC_INFO_ITERLIST}}); #} #sub NEXTKEY { $_[0]->one_info(shift @{$_[0]->{__PROC_INFO_ITERLIST}}); } # Autoload methods go after =cut, and are processed by the autosplit program. 1; __END__ # Below is the stub of documentation for your module. You better edit it! =head1 NAME VMS::Queue - Perl extension to manage queues, entries, and forms, and retrieve queue, entry, and form information. =head1 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); =head1 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. =head2 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 L<"Property hashes"> section. =item queue_list() The C function takes an optional C 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. =item stop_queue() The C 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. =item start_queue() The C function starts the passed queue. =item delete_queue() The C function deletes the named queue. =item create_queue() The C function creates a new queue with the passed properties. =item modify_queue() The C 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) =item submit() C takes a reference to an C hash, and a reference to one or more C hashes. The files are submitted as a single entry to the queue manager. It returns the entry number if sucessful, or undef if not. =item queue_info() The C function returns a reference to a C hash, with the properties for the queue filled in. =item queue_properties() This funnction returns a reference to a hash whose keys are the valid keys for a C hash. The values for the keys are currently undefined, though they might mean something in a future release. =item 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 C, C, or C. C properties may be specified to a call that takes a queue_propery hash, while C properties may be returned by a call that returns a queue_property hash. =head2 Entry functions The entry functions provide a way to manipulate queue entries. =item entry_list() This function provides a list of all the entries that match the optional C hash. If no hash is passed, all entries in all queues are returned. =item delete_entry() Deletes the entry identified by the passed entry number. =item hold_entry() Marks the passed entry as on hold. =item release_entry() Releases the passed entry. =item 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. =item entry_info() Returns an entry_property hash with the properties for the passed entry. =item 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: C, C, C, and C. 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) =item 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. =head2 File functiond The file functions deal with files within queue entries. =item 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.) =item file_properties() This function returns a list of all the valid properties that can be returned for a file. =item 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. =head2 Form functions The form functions manipulate the form information kept by the queue manager. =item 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. =item create_form() This function creates a form with the properties specified in the form_properties hash. =item delete_form() This function deletes the form specified. =item form_info() Returns an form_properties hashref with all the properties for the specified form. =head2 Characteristic functions =item characteristic_list =item create_characteristic =item delete_characteristic =item characteristic_info =item characteristic_properties =item characteristic_bitmap_decode =head2 Manager functions =item manager_list =item stop_manager =item start_manager =item delete_manager =item manager_info =item manager_properties =item manager_bitmap_decode =head2 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) =head1 BUGS May leak memory. May not, though. =head1 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 C. The test suite's of limited utility.(Okay, it doesn't test anything really) =head1 AUTHOR Dan Sugalski =head1 SEE ALSO perl(1), VMS System Services Reference Guide, SNDJBC and GETQUI entries. =cut