Welcome to VMS::IndexedFile
Version 0.02
Copyright (c) 1996 Kent A. Covert and Toni L. Harbaugh-Blackford.
All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.
This used to be called VMDBM, and was repackaged in the VMS::
namespace in April 1999.
DESCRIPTION
-----------
This is a module for VMS Perl which implements DBM-like functionality
using OpenVMS RMS Indexed files.
BUILDING VMS::IndexedFile
------------------
If you normally use MMK as your MAKE facility, then substitute MMK for MMS
in the following instructions.
1.) Issue the command
$ perl makefile.pl
This will create a DESCRIP.MMS file
2.) Issue the command
$ MMS
depending on which make facility you have. This will build VMS::IndexedFile
as a dynamic extension.
3.) Test the module
Perl 5.001:
-----------
Type the command
$ perl "-Iblib" test.pl
Perl 5.002:
-----------
Either type the command
Alpha:
$ perl "-Iblib" "-Iblib/VMS_AXP" test.pl
VAX:
$ perl "-Iblib" "-Iblib/VMS_VAX" test.pl
PROBLEMS:
---------
Send bug reports to COVERTKA@muohio.edu. Please include basic hardware
and system information with your message.
EXAMPLE PROGRAMS:
-----------------
There is currently 1 example program in the [.EXAMPLES] directory.
SYSUAF Reads the SYSUAF file and displays the first 20 entries
in order alphabetically and the first 20 entries in order
by UIC.
I recommend that you read through the sample runs *before* trying the programs
KNOWN PROBLEMS:
---------------
- There is a bug in Perl 5.002.01 and before that prevents the indexed file
from being closed when the untie() function is called if the hash
variable has been populated using an array.
- If a flag in the tie() function is set, but O_RDONLY, O_WRONLY, or
O_RDWR is not specified, the system defaults to O_RDONLY.
USAGE:
------
initialization
--------------
The VMS::IndexedFile interface needs to be initialized using the command:
use VMS::IndexedFile;
at the beginning of your Perl program.
tie() funcation
---------------
To access the VMS::IndexedFile interface, you must tie a hash variable to VMS::IndexedFile.
This is accomplished using the tie() function in Perl. The syntax for
this function in the context of VMS::IndexedFile is as follows:
objvar = tie(%hash_variable,VMS::IndexedFile,filespec,[key],[flags],[fdlspec]);
where
objvar - reference to the object created. This can be used to
access special methods within the VMS::IndexedFile interface. The
2 currently defined methods are store() and replace().
hash_variable - the hash variable to be tied to. This can be any valid
hash variable you want.
filespec - the name of the indexed file you want to open. This
filespec should be a valid VMS file specification.
key - the key that should be used when accessing the indexed
file. The primary key is 0, the first alternate key is
1, etc. If this parameter is omitted, it defaults to 0
(the primary key).
flags - flags used when opening the file. The valid flags are
listed below:
O_RDONLY - opens the file for reading only.
O_WRONLY - opens the file for writing only.
O_RDWR - opens the file for reading and writing.
O_CREAT - opens the file and creates it if needed.
If this flag is specified, then the
fdlspec parameter must also be specified.
O_EXCL - when used with the O_CREAT flag, this
flag will cause an error if the file
already exists.
O_TRUNC - alway create a new file. If this flag
is specified, then the fdlspec parameter
must also be specified.
When specifying any flags, O_RDONLY, O_WRONLY, or O_RDWR
must always be specified. Multiple flags can be
specified by seperating the flags with an | symbol. If
this parameter is omitted, it will default to O_RDWR.
fdlspec the fdl specification for the file to be created. This
can either be the fdl specified as a string or the name
of a file containing the fdl specification. When
specifying the fdlspec as a file, the filename must be
preceeded by a < character.
Examples:
tie(%h,VMS::IndexedFile,"test.dat",0,O_RDWR|O_CREAT,"<test.fdl");
$testobj = tie(%test,VMS::IndexedFile,"test.dat");
$hobj = tie(%h,VMS::IndexedFile,"test.dat",1,O_RDWR|O_TRUNC,
"FILE; ORGANIZATION indexed; RECORD; CARRIAGE_CONTROL carriage_return;" .
"FORMAT variable; SIZE 10;" .
"KEY 0; CHANGES no; DUPLICATES no; SEG0_POSITION 0; SEG0_LENGTH 3;" .
"TYPE string;" .
"KEY 1; CHANGES no; DUPLICATES yes; SEG0_POSITION 3; SEG0_LENGTH 2;" .
"SEG1_POSITION 0; SEG1_LENGTH 3; TYPE string;");
fetching records
----------------
You can retrieve records in the indexed file just as you would an ordinary
hashed array the only major differences being that VMS::IndexedFile will return the
entire record rather than just the non-key portion. For example,
print $h{'ABC'};
This will print the entire record whose key begins with ABC.
Segmented keys should be specified by concatenating the key segments together.
For example, the following statement would print the record with the SEG0 of
'12' and the SEG1 of 'ABC' from the file whose FDL is listed in the third
tie() example above.
print $h{'12ABC'};
Specifying an empty key will force VMS::IndexedFile to begin reading sequentially from
the file. For example:
print $h{'ABC'};
print $h{''};
print $h{''};
Will read the record whose key is 'ABC' and the next 2 records.
storing records
---------------
Storing records are done in a similar manner to storing data in a hash table.
For example,
$h{'ABC'} = 'ABC12345';
Notice that the right-hand side of the equation is specified as the entire
record rather than just the non-key portion. In fact, the key specification
is completely ignored except for error-checking (Perl will store the record
and then fetch it to see if it was successful).
The error message returned by a store is actually not the error message from
the store, but rather the error message from the fetch that is performed after
the store. For this reason, a store() method has been added to VMS::IndexedFile. This
method can be used if you need to know the true error message returned by the
act of storing the record. To use it, you must store the objvar returned by
the tie() function. Using this you can access the store() method. The syntax
is as follows:
retval store(string);
where
retval - success of the store. 0 is a failure, 1 is a success.
string - string to store in the file. This should be the entire record to
be store.
Examples,
$h = tie(%h,VMS::IndexedFile,"test.dat");
$h->store("ABC12345") || die "Couldn't store record - $!";
By default, the act of storing a record will always attempt replace the current
record (if there are no duplicates allowed on the key being added) or add an
additional record (if duplicates are allowed). This can be changed with the
replace() method. The syntax is as follows:
oldvalue = replace(newvalue);
where
oldvalue - the previous replace() mode.
newvalue - the replace mode(). 0 indicates that records should not be
replaced. 1 indicates the default action.
If duplicates are allowed on the key, the current replace() mode is ignored.
deleting records
----------------
Records can be deleted with the Perl delete() function. For example,
delete($h{'ABC'});
would delete the record whose key is 'ABC'. VMS::IndexedFile will delete the first
record it encounters when a key is provided as shown above. If the key is
empty, though, VMS::IndexedFile will delete the last record read. This can be useful
when dealing with duplicate keys. For example,
print $h{'ABC'};
print $h{''};
print $h{''};
delete($h{''});
would display the record whose key is 'ABC' and the 2 records that follow. It
would then delete the last record that was read and displayed.
additional options
------------------
VMS::IndexedFile will also work with foreach() and each() and keys() and values() in a
manner similar to the way Perl treats associative arrays. Remember, though,
that VMS::IndexedFile always returns whole records, though, for values.
CREDITS:
--------
I would like to thank the following:
Toni L. Harbaugh-Blackford - author of the original VDBM
implementation on which this much of this code was based. Toni also
helped me work on the command syntax for VMS::IndexedFile.
Charles Bailey - the primary porter for VMS Perl who answered several
of my questions about Perl internals and offered several very good
suggestions that were incorporated into the implementation.