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,"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.