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

- NAME
- SYNOPSIS
- DESCRIPTION
- REVISION

# 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);

# 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, `use`ing 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, `undef`d, 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:

bin

  Disables LF to CRLF translation

cvt

  Negates previous setting of `ctx=noctx`

nocvt

  Disables conversion of FORTRAN carriage control

rec

  Force record-mode access

stm

  Force stream mode

xplct

  Causes records to be flushed only when the file is closed, or when an explicit flush is done

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)

ctg

  Contiguous.

cbt

  Contiguous-best-try.

dfw

  Deferred write; only applicable to files opened for shared access.

dlt

  Delete file on close.

tef

  Truncate at end-of-file.

cif

  Create if nonexistent.

sup

  Supersede.

scf

  Submit as command file on close.

spl

  Spool to system printer on close.

tmd

  Temporary delete.

tmp

  Temporary (no file directory).

nef

  Not end-of-file.

rck

  Read check compare operation.

wck

  Write check compare operation.

mxv

  Maximize version number.

rwo

  Rewind file on open.

pos

  Current position.

rwc

  Rewind file on close.

sqo

  File can only be processed in a sequential manner.

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:

cr

  Carriage-return control.

blk

  Disallow records to span block boundaries.

ftn

  FORTRAN print control.

none

  Explicitly forces no carriage control.

prn

  Print file format.

rfm=STRING

  File record format. Takes one of the following:

fix

  Fixed-length record format.

stm

  RMS stream record format.

stmlf

  Stream format with line-feed terminator.

stmcr

  Stream format with carriage-return terminator.

var

  Variable-length record format.

vfc

  Variable-length record with fixed control.

udf

  Undefined format

rop=STRING

  Record processing operations. Takes one or more of the following in a comma-separated list:

asy

  Asynchronous I/O.

cco

  Cancel Ctrl/O (used with Terminal I/O).

cvt

  Capitalizes characters on a read from the terminal.

eof

  Positions the record stream to the end-of-file for the connect operation only.

nlk

  Do not lock record.

pmt

  Enables use of the prompt specified by pmt=usr-prmpt on input from the terminal.

pta

  Eliminates any information in the type-ahead buffer on a read from the terminal.

rea

  Locks record for a read operation for this process, while allowing other accessors to read the record.

rlk

  Locks record for write.

rne

  Suppresses echoing of input data on the screen as it is entered on the keyboard.

rnf

  Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control commands on terminal input, but are to be passed to the application program.

rrl

  Reads regardless of lock.

syncsts

  Returns success status of RMS$_SYNCH if the requested service completes its task immediately.

tmo

  Timeout I/O.

tpt

  Allows put/write services using sequential record access mode to occur at any point in the file, truncating the file at that point.

ulk

  Prohibits RMS from automatically unlocking records.

wat

  Wait until record is available, if currently locked by another stream.

rah

  Read ahead.

wbh

  Write behind.

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:

del

  Allows users to delete.

get

  Allows users to read.

mse

  Allows mainstream access.

nil

  Prohibits file sharing.

put

  Allows users to write.

upd

  Allows users to update.

upi

  Allows one or more writers.

tmo=INTEGER

  I/O timeout value

vmssysopen

  This function bears the same relationship to the CORE function `sysopen` as `vmsopen` does to `open`. Its first three arguments are the name, access flags, and permissions for the file. Like `vmsopen`, it takes up to 8 additional string arguments which specify file characteristics. Its return value is identical to that of `vmsopen`.

  The symbolic constants for the mode argument are exported by VMS::Stdio by default, and are also exported by the Fcntl package.

waitfh

  This function causes Perl to wait for the completion of an I/O operation on the file handle specified as its argument. It is used with handles opened for asynchronous I/O, and performs its task by calling the CRTL routine fwait().

writeof

  This function writes an EOF to a file handle, if the device driver supports this operation. Its primary use is to send an EOF to a subprocess through a pipe opened for writing without closing the pipe. It returns a true value if successful, and `undef` if it encounters an error.

# REVISION

This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and 5.6.0.

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