NAME

VMS::Stat - Perl extension for access to File Access Blocks (read-only) and HP C extensions to the mkdir() function in the C RTL.

SYNOPSIS

use VMS::Stat qw(&vmsmkdir &get_fab);
vmsmkdir( 'SYS$DISK:[.MARS]',0777,,1 ); # Equivalent to DCL: $ create/directory/version_limit=1 [.MARS]
my %fab = get_fab( 'SYS$LOGIN:LOGIN.COM' );

DESCRIPTION

vmsmkdir

The vmsmkdir function enables you to specify optional RMS arguments to the VMS CRTL when creating a directory. Its operation is similar to the built-in Perl mkdir function (see perlfunc for a complete description). Up to 4 optional arguments may follow the directory name. These arguments should be numbers which specify optional directory characteristics as allowed by the CRTL. (See the CRTL reference manual description of mkdir() and chmod() for details.) If successful, vmsmkdir returns a true value; error occurs, it returns undef.

Directory characteristic options:

mode

A file protection.

uic

The user identification code that identifies the owner of the created directory.

max_versions

The maximum number of file versions to be retained in the created directory.

r_v_number

The volume or device on which to place the created directory if the device is part of a volume set.

get_fab

For an accessible file returns a keyed list of integers and bit settings from the File Access Block (FAB). Many of the keys are similar to the item (second) argument that would be passed in a call to the F$FILE_ATTRIBBUTES() lexical function in DCL. Not all items supported by the lexical function are currently supported by get_fab().

In particular the following are available:

ai

Returns a perl true value if after image journaling is enabled; perl false (but defined()) if disabled.

alq

Allocation quantity in blocks.

bi

Returns a perl true value if before image journaling is enabled; perl false (but defined()) if disabled.

bls

Block size (for tape?).

ctg

Returns a perl true value if the file is contiguous; perl false (but defined()) otherwise.

deq

Default extension or allocation quantity.

erase

Returns a perl true value if a file's contents are erased before a file is deleted (erase regardless of lock); otherwise perl false (but defined) is returned.

fsz

Fixed header (control area) size.

gbc

Global buffer count.

mrn

Maximum record number.

mrs

Maximum record size.

org

Organization: 0 for sequential, 16 for relative, and 32 for indexed.

rat

Record attributes: 1 for Fortran, 2 for CR, 4 for PRN.

rfm

Record format: 0 for undefined, 1 for fixed, 2 for variable, 3 for variable fixed control, 4 for stream, 5 for stream LF, 6 for stream CR.

ru

Returns a perl true value if recovery unit journaling is enabled; otherwise perl false (but defined) is returned.

wck

Returns a perl true value if write checking is enabled; otherwise perl false (but defined) is returned.

get_fab() is implemented via a default access mode call to sys$open() and a call to sys$close(). If either system call fails for any reason (e.g. does not exist, access locked, security blocked, etc.); the undef value will be returned.

HISTORY

0.03

Included the initial (simple) get_fab() xsub.

0.02

Updated the README file.

0.01

Original version; created by h2xs 1.22 with options -C -c -n VMS::Stat stat.h

EXAMPLE

Here is a determination of a file allocation quantity:

use VMS::Stat qw(&get_fab);
my %fab = get_fab('SYS$LOGIN:LOGIN.COM');
if ( defined( $fab{'alq'} ) {
    print "Login.com has $fab{'alq'} blocks allocated.\n";
}
else {
    print "Was unable to call get_fab for login.com:"
}

SEE ALSO

The VMS::Stdio extension provides VMS::Stdio::vmsopen() as an interface to the C RTL's fopen() function. VMS::Stdio ships with perl for VMS.

The rms extension on CPAN also provides indexfile access.

AUTHOR

Peter Prymmer, <pprymmer at best dot com>

COPYRIGHT AND LICENSE

Copyright 2004 by Peter Prymmer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.