Doc patch to VMS::Stdio module

	Message-Id: <3.0.6.32.19981013151057.00a947a0@ous.edu>

p4raw-id: //depot/perl@1999

1 files changed, 389 insertions, 19 deletions

diff --git a/vms/ext/Stdio/Stdio.pm b/vms/ext/Stdio/Stdio.pm
index ea5d9074ef..04b339725f 100644
--- a/vms/ext/Stdio/Stdio.pm
+++ b/vms/ext/Stdio/Stdio.pm
@@ -3,6 +3,7 @@
 #   Author:  Charles Bailey  bailey@genetics.upenn.edu
 #   Version: 2.1
 #   Revised: 24-Mar-1998
+#   Docs revised: 13-Oct-1998 Dan Sugalski <sugalskd@ous.edu>
 
 package VMS::Stdio;
 
@@ -81,24 +82,25 @@ VMS::Stdio - standard I/O functions via VMS extensions
 
 =head1 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);
+  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);
+
 =head1 DESCRIPTION
 
 This package gives Perl scripts access via VMS extensions to several
@@ -221,6 +223,373 @@ as a normal Perl file handle only.  When the scalar containing
 a VMS::Stdio file handle is overwritten, C<undef>d, or goes
 out of scope, the associated file is closed automatically.
 
+=over 4
+
+=head2 File characteristic options
+
+=over 2
+
+=item alq=INTEGER
+
+Sets the allocation quantity for this file
+
+=item bls=INTEGER
+
+File blocksize
+
+=item ctx=STRING
+
+Sets the context for the file. Takes one of these arguments:
+
+=over 4
+
+=item bin
+
+Disables LF to CRLF translation
+
+=item cvt
+
+Negates previous setting of C<ctx=noctx>
+
+=item nocvt
+
+Disables conversion of FORTRAN carriage control
+
+=item rec
+
+Force record-mode access
+
+=item stm
+
+Force stream mode
+
+=item xplct
+
+Causes records to be flushed I<only> when the file is closed, or when an
+explicit flush is done
+
+=back
+
+=item deq=INTEGER
+
+Sets the default extension quantity
+
+=item dna=FILESPEC
+
+Sets the default filename string. Used to fill in any missing pieces of the
+filename passed.
+
+=item fop=STRING
+
+File processing option. Takes one or more of the following (in a
+comma-separated list if there's more than one)
+
+=over 4
+
+=item ctg
+
+Contiguous.
+
+=item cbt
+
+Contiguous-best-try.
+
+=item dfw
+
+Deferred write; only applicable to files opened for shared access.
+
+=item dlt
+
+Delete file on close.
+
+=item tef
+
+Truncate at end-of-file.
+
+=item cif
+
+Create if nonexistent.
+
+=item sup
+
+Supersede.
+
+=item scf
+
+Submit as command file on close.
+
+=item spl
+
+Spool to system printer on close.
+
+=item tmd
+
+Temporary delete.
+
+=item tmp
+
+Temporary (no file directory).
+
+=item nef
+
+Not end-of-file.
+
+=item rck
+
+Read check compare operation.
+
+=item wck
+
+Write check compare operation.
+
+=item mxv
+
+Maximize version number.
+
+=item rwo
+
+Rewind file on open.
+
+=item pos
+
+Current position.
+
+=item rwc
+
+Rewind file on close.
+
+=item sqo
+
+File can only be processed in a sequential manner.
+
+=back
+
+=item fsz=INTEGER
+
+Fixed header size
+
+=item gbc=INTEGER
+
+Global buffers requested for the file
+
+=item mbc=INTEGER
+
+Multiblock count
+
+=item mbf=INTEGER
+
+Bultibuffer count
+
+=item mrs=INTEGER
+
+Maximum record size
+
+=item rat=STRING
+
+File record attributes. Takes one of the following:
+
+=over 4
+
+=item cr
+
+Carriage-return control.
+
+=item blk
+
+Disallow records to span block boundaries.
+
+=item ftn
+
+FORTRAN print control.
+
+=item none
+
+Explicitly forces no carriage control.
+
+=item prn
+
+Print file format.
+
+=back
+
+=item rfm=STRING
+
+File record format. Takes one of the following:
+
+=over 4
+
+=item fix
+
+Fixed-length record format.
+
+=item stm
+
+RMS stream record format.
+
+=item stmlf
+
+Stream format with line-feed terminator.
+
+=item stmcr
+
+Stream format with carriage-return terminator.
+
+=item var
+
+Variable-length record format.
+
+=item vfc
+
+Variable-length record with fixed control.
+
+=item udf
+
+Undefined format
+
+=back
+
+=item rop=STRING
+
+Record processing operations. Takes one or more of the following in a
+comma-separated list:
+
+=over 4
+
+=item asy
+
+Asynchronous I/O.
+
+=item cco
+
+Cancel Ctrl/O (used with Terminal I/O).
+
+=item cvt
+
+Capitalizes characters on a read from the terminal.
+
+=item eof
+
+Positions the record stream to the end-of-file for the connect operation
+only.
+
+=item nlk
+
+Do not lock record.
+
+=item pmt
+
+Enables use of the prompt specified by pmt=usr-prmpt on input from the
+terminal.
+
+=item pta
+
+Eliminates any information in the type-ahead buffer on a read from the
+terminal.
+
+=item rea
+
+Locks record for a read operation for this process, while allowing other
+accessors to read the record.
+
+=item rlk
+
+Locks record for write.
+
+=item rne
+
+Suppresses echoing of input data on the screen as it is entered on the
+keyboard.
+
+=item 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.
+
+=item rrl
+
+Reads regardless of lock.
+
+=item syncsts
+
+Returns success status of RMS$_SYNCH if the requested service completes its
+task immediately.
+
+=item tmo
+
+Timeout I/O.
+
+=item tpt
+
+Allows put/write services using sequential record access mode to occur at
+any point in the file, truncating the file at that point.
+
+=item ulk
+
+Prohibits RMS from automatically unlocking records.
+
+=item wat
+
+Wait until record is available, if currently locked by another stream.
+
+=item rah
+
+Read ahead.
+
+=item wbh
+
+Write behind.
+
+=back
+
+=item rtv=INTEGER
+
+The number of retrieval pointers that RMS has to maintain (0 to 127255)
+
+=item shr=STRING
+
+File sharing options. Choose one of the following:
+
+=over 4
+
+=item del
+
+Allows users to delete.
+
+=item get
+
+Allows users to read.
+
+=item mse
+
+Allows mainstream access.
+
+=item nil
+
+Prohibits file sharing.
+
+=item put
+
+Allows users to write.
+
+=item upd
+
+Allows users to update.
+
+=item upi
+
+Allows one or more writers.
+
+=back
+
+=item tmo=INTEGER
+
+I/O timeout value
+
+=back
+
+=back
+
 =item vmssysopen
 
 This function bears the same relationship to the CORE function
@@ -250,6 +619,7 @@ it encounters an error.
 
 =head1 REVISION
 
-This document was last revised on 10-Dec-1996, for Perl 5.004.
+This document was last revised on 13-Oct-1998, for Perl 5.004, 5.005, and
+5.006.
 
 =cut