vms/perlvms.pod

   1 =head1 Notes on Perl5 for VMS
   2
   3 Gathered below are notes describing details of perl 5's
   4 behavior on VMS.  They are a supplement to the regular perl 5
   5 documentation, so we have focussed on the ways in which perl
   6 5 functions differently under VMS thatn it does under Unix,
   7 and on teh interactions between perl and the rest of the
   8 operating system.  We haven't tried to duplicate complete
   9 descriptions  of perl5 features from the main perl
  10 documentation, which can be found in the F<[.pod]>
  11 subdirectory of the perl 5 distribution.
  12
  13 We hope these notes will save you from confusion and lost
  14 sleep when writing perl scripts on VMS.  If you find we've
  15 missed something you think should appear here, please don't
  16 hesitate to drop a line to vmsperl@genetics.upenn.edu.
  17
  18 =head2 Installation
  19
  20 Directions for building and installing perl 5 can be found in
  21 the file F<ReadMe.VMS> in the main source directory of the
  22 perl5 distribution..
  23
  24 =head2 File specifications
  25
  26 We have tried to make perl aware of both VMS-style and Unix-
  27 style file specifications wherever possible.  You may use
  28 either style, or both, on the command line and in scripts,
  29 but you may not combine the two styles within a single fle
  30 specfication.  Filenames are, of course, still case-
  31 insensitive.  For consistency, most perl5 routines return
  32 filespecs using lower case latters only, regardless of the
  33 case used in the arguments passed to them.  (This is true
  34 only when running under VMS; perl5 respects the case-
  35 sensitivity of OSs like Unix.)
  36
  37 We've tried to minimize the dependence of perl library
  38 modules on Unix syntax, but you may find that some of these,
  39 as well as some scripts written for Unix systems, will
  40 require that you use Unix syntax, since they will assume that
  41 '/' is the directory separator, etc.  If you find instances
  42 of this in the perl distribution itself, please let us know,
  43 so we can try to work around them.
  44
  45 =head2 Command line redirection
  46
  47 Perl for VMS supports redirection of input and output on the
  48 command line, using a subset of Bourne shell syntax:
  49     <F<file> reads stdin from F<file>,
  50     >F<file> writes stdout to F<file>,
  51     >>F<file> appends stdout to F<file>,
  52     2>F<file> wrtits stderr to F<file>, and
  53     2>>F<file> appends stderr to F<file>.
  54
  55 In addition, output may be piped to a subprocess, using the
  56 character '|'.  Anything after this character on the command
  57 line is passed to a subprocess for execution; the subprocess
  58 takes the output of perl as its input.
  59
  60 Finally, if the command line ends with '&', the entire
  61 command is run in the background as an asynchronous
  62 subprocess.
  63
  64 =head2 Pipes
  65
  66 Input and output pipes to perl filehandles are supported; the
  67 "file name" is passed to lib$spawn() for asynchronous
  68 execution.  You should be careful to close any pipes you have
  69 opened in a perl script, lest you leave any "orphaned"
  70 subprocesses around when perl exits.
  71
  72 You may also use backticks to invoke a DCL subprocess, whose
  73 output is used as the return value of the expression.  The
  74 string between the backticks is passed directly to lib$spawn
  75 as the command to execute.  In this case, perl will wait for
  76 the subprocess to complete before continuing.
  77
  78 =head2 Wildcard expansion
  79
  80 File specifications containing wildcards are allowed both on
  81 the command line and within perl globs (e.g. <C<*.c>>).  If
  82 the wildcard filespec uses VMS syntax, the resultant
  83 filespecs will follow VMS syntax; if a Unix-style filespec is
  84 passed in, Unix-style filespecs will be returned..
  85
  86 If the wildcard filespec contains a device or directory
  87 specification, then the resultant filespecs will also contain
  88 a device and directory; otherwise, device and directory
  89 information are removed.  VMS-style resultant filespecs will
  90 contain a full device and directory, while Unix-style
  91 resultant filespecs will contain only as much of a directory
  92 path as was present in the input filespec.  For example, if
  93 your default directory is Perl_Root:[000000], the expansion
  94 of C<[.t]*.*> will yield filespecs  like
  95 "perl_root:[t]base.dir", while the expansion of C<t/*/*> will
  96 yield filespecs like "t/base.dir".  (This is done to match
  97 the behavior of glob expansion performed by Unix shells.)
  98
  99 Similarly, the resultant filespec will the file version only
 100 if one was present in the input filespec.
 101
 102 =head2 %ENV
 103
 104 Reading the elements of the %ENV array returns the
 105 translation of the logical name specified by the key,
 106 according to the normal search order of access modes and
 107 logical name tables.  In addition, the keys C<home>,
 108 C<path>,C<term>, and C<user> return the CRTL "environment
 109 variables" of the same names.  The key C<default> returns the
 110 current default device and directory specification.
 111
 112 Setting an element of %ENV defines a supervisor-mode logical
 113 name in the process logical name table.  B<Undef>ing or
 114 B<delete>ing an element of %ENV deletes the equivalent user-
 115 mode or supervisor-mode logical name from the process logical
 116 name table.  If you use B<undef>, the %ENV element remains
 117 empty.  If you use B<delete>, another attempt is made at
 118 logical name translation after the deletion, so an inner-mode
 119 logical name or a name in another logical name table will
 120 replace the logical name just deleted.
 121
 122 In all operations on %ENV, the key string is treated as if it
 123 were entirely uppercase, regardless of the case actually
 124 specified in the perl expression.
 125
 126 =head2 Perl functions
 127
 128 As of the time this document was last revised, the following
 129 perl functions were implemented in the VMS port of perl
 130 (functions marked with * are discussed in more detail below):
 131
 132     file tests*, abs, alarm, atan, binmode*, bless,
 133     caller, chdir, chmod, chown, chomp, chop, chr,
 134     close, closedir, cos, defined, delete, die, do,
 135     each, eof, eval, exec*, exists, exit, exp, fileno,
 136     fork*, getc, glob, goto, grep, hex, import, index,
 137     int, join, keys, kill, last, lc, lcfirst, length,
 138     local, localtime, log, m//, map, mkdir, my, next,
 139     no, oct, open, opendir, ord, pack, pipe, pop, pos,
 140     print, printf, push, q//, qq//, qw//, qx//,
 141     quotemeta, rand, read, readdir, redo, ref, rename,
 142     require, reset, return, reverse, rewinddir, rindex,
 143     rmdir, s///, scalar, seek, seekdir, select(internal)*,
 144     shift, sin, sleep, sort, splice, split, sprintf,
 145     sqrt, srand, stat, study, substr, sysread, system*,
 146     syswrite, tell, telldir, tie, time, times*, tr///,
 147     uc, ucfirst, umask, undef, unlink, unpack, untie,
 148     unshift, use, values, vec, wait, wantarray, warn,
 149     write, y///
 150
 151 The following functions were not implemented in the VMS port,
 152 and calling them produces a fatal error (usually) or
 153 undefined behavior (rarely, we hope):
 154
 155     chroot, crypt, dbmclose, dbmopen, dump, fcntl,
 156     flock, getlogin, getpgrp, getppid, getpriority,
 157     getpwent, getgrent, kill, getgrgid, getgrnam,
 158     getpwnam, getpwuid, setpwent, setgrent,
 159     endpwent, endgrent, gmtime, ioctl, link, lstst,
 160     msgctl, msgget, msgsend, msgrcv, readlink,
 161     select(system call), semctl, semget, semop,
 162     setpgrp, setpriority, shmctl, shmget, shmread,
 163     shmwrite, socketpair, symlink, syscall, truncate,
 164     utime, waitpid
 165
 166 The following functions may or may not be implemented,
 167 depending on what type of socket support you've built into
 168 your copy of perl:
 169     accept, bind, connect, getpeername,
 170     gethostbyname, getnetbyname, getprotobyname,
 171     getservbyname, gethostbyaddr, getnetbyaddr,
 172     getprotobynumber, getservbyport, gethostent,
 173     getnetent, getprotoent, getservent, sethostent,
 174     setnetent, setprotoent, setservent, endhostent,
 175     endnetent, endprotoent, endservent, getsockname,
 176     getsockopt, listen, recv, send, setsockopt,
 177     shutdown, socket
 178
 179
 180 =item File tests
 181
 182 The tests -b, -B, -c, -C, -d, -e, -f, -o, -M, -s, -S, -t, -T,
 183 and -z work as advertised.  The return values for -r, -w, and
 184 -x tell you whether you can actually access the file; this
 185 may mot reflect the UIC-based file protections.  Since real
 186 and effective UIC don't differ under VMS, -O, -R, -W, and -X
 187 are equivalent to -o, -r, -w, and -x.  Similarly, several
 188 other tests, including -A, -g, -k, -l,-p, and -u, aren't
 189 particularly meaningful under VMS, and the values returned by
 190 these tests reflect whatever your CRTL stat() routine does to
 191 the equivalent bits in the st_mode field.
 192
 193 =item binmode
 194
 195 The B<binmode> operator has no effect under VMS.  It will
 196 return TRUE whenever called, but will not affect I/O
 197 operations on the filehandle given as its argument.
 198
 199 =item exec
 200
 201 The B<exec> operator behaves in one of two different ways.
 202 If called after a call to B<fork>, it will invoke the CRTL
 203 L<execv()> routine, passing its arguments to the subprocess
 204 created by B<fork> for execution.  In this case, it is
 205 subject to all limitation that affect L<execv>.  (In
 206 particular, this usually means that the command executed in
 207 the subprocess must be an image compiled from C source code,
 208 and that your options for passing file descriptors and signal
 209 handlers to the subprocess are limited.)
 210
 211 If the call to B<exec> does not follow a call to B<fork>, it
 212 will cause perl to exit, and to invoke the command given as
 213 an argument to B<exec> via lib$do_command.  If the argument
 214 begins with a '$' (other than as part of a filespec), then it
 215 is executed as a DCL command.  Otherwise, the first token on
 216 the command line is treated as the filespec of an image to
 217 run, and an attempt is made to invoke it (using F<.Exe> and
 218 the process defaults to expand the filespec) and pass the
 219 rest of B<exec>'s argument to it as parameters.
 220
 221 You can use B<exec> in both ways within the same script, as
 222 long as you call B<fork> and B<exec> in pairs.  Perl only
 223 keeps track of whether B<fork> has been called since the last
 224 call to B<exec> when figuring out what to do, so multiple
 225 calls to B<fork> do not generate multiple levels of "fork
 226 context".
 227
 228 =item fork
 229
 230 The B<fork> operator works in the same way as the CRTL
 231 L<fork()> routine, which is quite different under VMS than
 232 under Unix.  Sepcifically, while B<fork> returns 0 after it
 233 is called and the subprocess PID after B<exec> is called, in
 234 both cases the thread of execution is within the parent
 235 process, so there is no opportunity to perform operations in
 236 the subprocess before calling B<exec>.
 237
 238 In general, the use of B<fork> and B<exec> to create
 239 subprocess is not recommended under VMS; wherever possible,
 240 use the B<system> operator or piped filehandles instead.
 241
 242 =item system
 243
 244 The B<system> operator creates a subprocess, and passes its
 245 arguments to the subprocess for execution as a DCL command.
 246 Since the subprocess is created directly via lib$spawn, any
 247 valid DCL command string may be specified.  Perl waits for
 248 the subprocess to complete before continuing execution in the
 249 current process.
 250
 251 =item times
 252
 253 The array returned by the B<times> operator is divided up
 254 according to the same rules the CRTL L<times()> routine.
 255 Therefore, the "system time" elements will always be 0, since
 256 there is no difference between "user time" and "system" time
 257 under VMS, and the time accumulated by subprocess may or may
 258 not appear separately in the "child time" field, depending on
 259 whether L<times> keeps track of subprocesses separately.
 260
 261 =head2 Revision date
 262
 263 This document was last updated on 16-Oct-1994, for perl 5,
 264 patchlevel 0.