r1 - 26 May 2008 - TWikiGuest

NAME

VMS::Stdio - standard I/O functions via VMS extensions

SYNOPSIS

  use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam

                     &vmsopen &vmssysopen &waitfh &writeof );

  setdef("new:[default.dir]");

  $uniquename = tmpnam;

  $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;

  $name = getname($fh);

  print $fh "Hello, world!\n";

  flush($fh);

  sync($fh);

  rewind($fh);

  $line = <$fh>;

  undef $fh;  # closes file

  $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");

  sysread($fh,$data,128);

  waitfh($fh);

  close($fh);

  remove("another.file");

  writeof($pipefh);

  binmode($fh);

voltar para o topo

DESCRIPTION

This package gives Perl scripts access via VMS extensions to several C stdio operations not available through Perl's CORE I/O functions. The specific routines are described below. These functions are prototyped as unary operators, with the exception of vmsopen and vmssysopen, which can take any number of arguments, and tmpnam, which takes none. All of the routines are available for export, though none are exported by default. All of the constants used by vmssysopen to specify access modes are exported by default. The routines are associated with the Exporter tag FUNCTIONS, and the constants are associated with the Exporter tag CONSTANTS, so you can more easily choose what you'd like to import:

    # import constants, but not functions

    use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );

    # import functions, but not constants

    use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS );

    # import both

    use VMS::Stdio qw( :CONSTANTS :FUNCTIONS );

    # import neither

    use VMS::Stdio ();

Of course, you can also choose to import specific functions by name, as usual. This package ISA IO::File, so that you can call IO::File methods on the handles returned by vmsopen and vmssysopen. The IO::File package is not initialized, however, until you actually call a method that VMS::Stdio doesn't provide. This is done to save startup time for users who don't wish to use the IO::File methods. Note: In order to conform to naming conventions for Perl extensions and functions, the name of this package has been changed to VMS::Stdio as of Perl 5.002, and the names of some routines have been changed. Calls to the old VMS::stdio routines will generate a warning, and will be routed to the equivalent VMS::Stdio function. This compatibility interface will be removed in a future release of this extension, so please update your code to use the new routines.

binmode

This function causes the file handle to be reopened with the CRTL's

carriage control processing disabled; its effect is the same as that

of the b access mode in vmsopen. After the file is reopened,

the file pointer is positioned as close to its position before the

call as possible (i.e. as close as fsetpos() can get it -- for

some record-structured files, it's not possible to return to the

exact byte offset in the file). Because the file must be reopened,

this function cannot be used on temporary-delete files. binmode

returns true if successful, and undef if not.

Note that the effect of binmode differs from that of the binmode()

function on operating systems such as Windows and MSDOS, and is not

needed to process most types of file.

flush

This function causes the contents of stdio buffers for the specified

file handle to be flushed. If undef is used as the argument to

flush, all currently open file handles are flushed. Like the CRTL

fflush() routine, it does not flush any underlying RMS buffers for the

file, so the data may not be flushed all the way to the disk. flush

returns a true value if successful, and undef if not.

getname

The getname function returns the file specification associated

with a Perl I/O handle. If an error occurs, it returns undef.

remove

This function deletes the file named in its argument, returning

a true value if successful and undef if not. It differs from

the CORE Perl function unlink in that it does not try to

reset file protection if the original protection does not give

you delete access to the file (cf. the perlvms manpage). In other words,

remove is equivalent to

  unlink($file) if VMS::Filespec::candelete($file);

rewind

rewind resets the current position of the specified file handle

to the beginning of the file. It's really just a convenience

method equivalent in effect to seek($fh,0,0). It returns a

true value if successful, and undef if it fails.

setdef

This function sets the default device and directory for the process.

It is identical to the built-in chdir() operator, except that the change

persists after Perl exits. It returns a true value on success, and

undef if it encounters an error.

sync

This function flushes buffered data for the specified file handle

from stdio and RMS buffers all the way to disk. If successful, it

returns a true value; otherwise, it returns undef.

tmpnam

The tmpnam function returns a unique string which can be used

as a filename when creating temporary files. If, for some

reason, it is unable to generate a name, it returns undef.

vmsopen

The vmsopen function enables you to specify optional RMS arguments

to the VMS CRTL when opening a file. Its operation is similar to the built-in

Perl open function (see the perlfunc manpage for a complete description),

but it will only open normal files; it cannot open pipes or duplicate

existing I/O handles. Up to 8 optional arguments may follow the

file name. These arguments should be strings which specify

optional file characteristics as allowed by the CRTL. (See the

CRTL reference manual description of creat() and fopen() for details.)

If successful, vmsopen returns a VMS::Stdio file handle; if an

error occurs, it returns undef.

You can use the file handle returned by vmsopen just as you

would any other Perl file handle. The class VMS::Stdio ISA

IO::File, so you can call IO::File methods using the handle

returned by vmsopen. However, useing VMS::Stdio does not

automatically use IO::File; you must do so explicitly in

your program if you want to call IO::File methods. This is

done to avoid the overhead of initializing the IO::File package

in programs which intend to use the handle returned by vmsopen

as a normal Perl file handle only. When the scalar containing

a VMS::Stdio file handle is overwritten, undefd, or goes

out of scope, the associated file is closed automatically.

File characteristic options:

alq=INTEGER: Sets the allocation quantity for this file
bls=INTEGER: File blocksize
ctx=STRING: Sets the context for the file. Takes one of these arguments:
deq=INTEGER: Sets the default extension quantity
dna=FILESPEC: Sets the default filename string. Used to fill in any missing pieces of the; filename passed.
fop=STRING: File processing option. Takes one or more of the following (in a; comma-separated list if there's more than one)
fsz=INTEGER: Fixed header size
gbc=INTEGER: Global buffers requested for the file
mbc=INTEGER: Multiblock count
mbf=INTEGER: Bultibuffer count
mrs=INTEGER: Maximum record size
rat=STRING: File record attributes. Takes one of the following:
rfm=STRING: File record format. Takes one of the following:
rop=STRING: Record processing operations. Takes one or more of the following in a; comma-separated list:
rtv=INTEGER: The number of retrieval pointers that RMS has to maintain (0 to 127255)
shr=STRING: File sharing options. Choose one of the following:
tmo=INTEGER: I/O timeout value

vmssysopen