| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLVMS 1" |
| 58 |
.TH PERLVMS 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlvms \- VMS\-specific documentation for Perl |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
Gathered below are notes describing details of Perl 5's |
| 68 |
behavior on VMS. They are a supplement to the regular Perl 5 |
| 69 |
documentation, so we have focussed on the ways in which Perl |
| 70 |
5 functions differently under VMS than it does under Unix, |
| 71 |
and on the interactions between Perl and the rest of the |
| 72 |
operating system. We haven't tried to duplicate complete |
| 73 |
descriptions of Perl features from the main Perl |
| 74 |
documentation, which can be found in the \fI[.pod]\fR |
| 75 |
subdirectory of the Perl distribution. |
| 76 |
.PP |
| 77 |
We hope these notes will save you from confusion and lost |
| 78 |
sleep when writing Perl scripts on VMS. If you find we've |
| 79 |
missed something you think should appear here, please don't |
| 80 |
hesitate to drop a line to [email protected]. |
| 81 |
.SH Installation |
| 82 |
.IX Header "Installation" |
| 83 |
Directions for building and installing Perl 5 can be found in |
| 84 |
the file \fIREADME.vms\fR in the main source directory of the |
| 85 |
Perl distribution. |
| 86 |
.SH "Organization of Perl Images" |
| 87 |
.IX Header "Organization of Perl Images" |
| 88 |
.SS "Core Images" |
| 89 |
.IX Subsection "Core Images" |
| 90 |
During the build process, three Perl images are produced. |
| 91 |
\&\fIMiniperl.Exe\fR is an executable image which contains all of |
| 92 |
the basic functionality of Perl, but cannot take advantage of |
| 93 |
Perl XS extensions and has a hard-wired list of library locations |
| 94 |
for loading pure-Perl modules. It is used extensively to build and |
| 95 |
test Perl and various extensions, but is not installed. |
| 96 |
.PP |
| 97 |
Most of the complete Perl resides in the shareable image \fIPerlShr.Exe\fR, |
| 98 |
which provides a core to which the Perl executable image and all Perl |
| 99 |
extensions are linked. It is generally located via the logical name |
| 100 |
\&\fIPERLSHR\fR. While it's possible to put the image in \fISYS$SHARE\fR to |
| 101 |
make it loadable, that's not recommended. And while you may wish to |
| 102 |
INSTALL the image for performance reasons, you should not install it |
| 103 |
with privileges; if you do, the result will not be what you expect as |
| 104 |
image privileges are disabled during Perl start-up. |
| 105 |
.PP |
| 106 |
Finally, \fIPerl.Exe\fR is an executable image containing the main |
| 107 |
entry point for Perl, as well as some initialization code. It |
| 108 |
should be placed in a public directory, and made world executable. |
| 109 |
In order to run Perl with command line arguments, you should |
| 110 |
define a foreign command to invoke this image. |
| 111 |
.SS "Perl Extensions" |
| 112 |
.IX Subsection "Perl Extensions" |
| 113 |
Perl extensions are packages which provide both XS and Perl code |
| 114 |
to add new functionality to perl. (XS is a meta-language which |
| 115 |
simplifies writing C code which interacts with Perl, see |
| 116 |
perlxs for more details.) The Perl code for an |
| 117 |
extension is treated like any other library module \- it's |
| 118 |
made available in your script through the appropriate |
| 119 |
\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statement, and usually defines a Perl |
| 120 |
package containing the extension. |
| 121 |
.PP |
| 122 |
The portion of the extension provided by the XS code may be |
| 123 |
connected to the rest of Perl in either of two ways. In the |
| 124 |
\&\fBstatic\fR configuration, the object code for the extension is |
| 125 |
linked directly into \fIPerlShr.Exe\fR, and is initialized whenever |
| 126 |
Perl is invoked. In the \fBdynamic\fR configuration, the extension's |
| 127 |
machine code is placed into a separate shareable image, which is |
| 128 |
mapped by Perl's DynaLoader when the extension is \f(CW\*(C`use\*(C'\fRd or |
| 129 |
\&\f(CW\*(C`require\*(C'\fRd in your script. This allows you to maintain the |
| 130 |
extension as a separate entity, at the cost of keeping track of the |
| 131 |
additional shareable image. Most extensions can be set up as either |
| 132 |
static or dynamic. |
| 133 |
.PP |
| 134 |
The source code for an extension usually resides in its own |
| 135 |
directory. At least three files are generally provided: |
| 136 |
\&\fIExtshortname\fR\fI.xs\fR (where \fIExtshortname\fR is the portion of |
| 137 |
the extension's name following the last \f(CW\*(C`::\*(C'\fR), containing |
| 138 |
the XS code, \fIExtshortname\fR\fI.pm\fR, the Perl library module |
| 139 |
for the extension, and \fIMakefile.PL\fR, a Perl script which uses |
| 140 |
the \f(CW\*(C`MakeMaker\*(C'\fR library modules supplied with Perl to generate |
| 141 |
a \fIDescrip.MMS\fR file for the extension. |
| 142 |
.SS "Installing static extensions" |
| 143 |
.IX Subsection "Installing static extensions" |
| 144 |
Since static extensions are incorporated directly into |
| 145 |
\&\fIPerlShr.Exe\fR, you'll have to rebuild Perl to incorporate a |
| 146 |
new extension. You should edit the main \fIDescrip.MMS\fR or \fIMakefile\fR |
| 147 |
you use to build Perl, adding the extension's name to the \f(CW\*(C`ext\*(C'\fR |
| 148 |
macro, and the extension's object file to the \f(CW\*(C`extobj\*(C'\fR macro. |
| 149 |
You'll also need to build the extension's object file, either |
| 150 |
by adding dependencies to the main \fIDescrip.MMS\fR, or using a |
| 151 |
separate \fIDescrip.MMS\fR for the extension. Then, rebuild |
| 152 |
\&\fIPerlShr.Exe\fR to incorporate the new code. |
| 153 |
.PP |
| 154 |
Finally, you'll need to copy the extension's Perl library |
| 155 |
module to the \fI[.\fR\fIExtname\fR\fI]\fR subdirectory under one |
| 156 |
of the directories in \f(CW@INC\fR, where \fIExtname\fR is the name |
| 157 |
of the extension, with all \f(CW\*(C`::\*(C'\fR replaced by \f(CW\*(C`.\*(C'\fR (e.g. |
| 158 |
the library module for extension Foo::Bar would be copied |
| 159 |
to a \fI[.Foo.Bar]\fR subdirectory). |
| 160 |
.SS "Installing dynamic extensions" |
| 161 |
.IX Subsection "Installing dynamic extensions" |
| 162 |
In general, the distributed kit for a Perl extension includes |
| 163 |
a file named Makefile.PL, which is a Perl program which is used |
| 164 |
to create a \fIDescrip.MMS\fR file which can be used to build and |
| 165 |
install the files required by the extension. The kit should be |
| 166 |
unpacked into a directory tree \fBnot\fR under the main Perl source |
| 167 |
directory, and the procedure for building the extension is simply |
| 168 |
.PP |
| 169 |
.Vb 4 |
| 170 |
\& $ perl Makefile.PL ! Create Descrip.MMS |
| 171 |
\& $ mmk ! Build necessary files |
| 172 |
\& $ mmk test ! Run test code, if supplied |
| 173 |
\& $ mmk install ! Install into public Perl tree |
| 174 |
.Ve |
| 175 |
.PP |
| 176 |
VMS support for this process in the current release of Perl |
| 177 |
is sufficient to handle most extensions. (See the MakeMaker |
| 178 |
documentation for more details on installation options for |
| 179 |
extensions.) |
| 180 |
.IP \(bu 4 |
| 181 |
the \fI[.Lib.Auto.\fR\fIArch\fR\f(CI$PVers\fR\fI\fR\fIExtname\fR\fI]\fR subdirectory |
| 182 |
of one of the directories in \f(CW@INC\fR (where \fIPVers\fR |
| 183 |
is the version of Perl you're using, as supplied in \f(CW$]\fR, |
| 184 |
with '.' converted to '_'), or |
| 185 |
.IP \(bu 4 |
| 186 |
one of the directories in \f(CW@INC\fR, or |
| 187 |
.IP \(bu 4 |
| 188 |
a directory which the extensions Perl library module |
| 189 |
passes to the DynaLoader when asking it to map |
| 190 |
the shareable image, or |
| 191 |
.IP \(bu 4 |
| 192 |
\&\fISys$Share\fR or \fISys$Library\fR. |
| 193 |
.PP |
| 194 |
If the shareable image isn't in any of these places, you'll need |
| 195 |
to define a logical name \fIExtshortname\fR, where \fIExtshortname\fR |
| 196 |
is the portion of the extension's name after the last \f(CW\*(C`::\*(C'\fR, which |
| 197 |
translates to the full file specification of the shareable image. |
| 198 |
.SH "File specifications" |
| 199 |
.IX Header "File specifications" |
| 200 |
.SS Syntax |
| 201 |
.IX Subsection "Syntax" |
| 202 |
We have tried to make Perl aware of both VMS-style and Unix-style file |
| 203 |
specifications wherever possible. You may use either style, or both, |
| 204 |
on the command line and in scripts, but you may not combine the two |
| 205 |
styles within a single file specification. VMS Perl interprets Unix |
| 206 |
pathnames in much the same way as the CRTL (\fIe.g.\fR the first component |
| 207 |
of an absolute path is read as the device name for the VMS file |
| 208 |
specification). There are a set of functions provided in the |
| 209 |
\&\f(CW\*(C`VMS::Filespec\*(C'\fR package for explicit interconversion between VMS and |
| 210 |
Unix syntax; its documentation provides more details. |
| 211 |
.PP |
| 212 |
We've tried to minimize the dependence of Perl library |
| 213 |
modules on Unix syntax, but you may find that some of these, |
| 214 |
as well as some scripts written for Unix systems, will |
| 215 |
require that you use Unix syntax, since they will assume that |
| 216 |
\&'/' is the directory separator, \fIetc.\fR If you find instances |
| 217 |
of this in the Perl distribution itself, please let us know, |
| 218 |
so we can try to work around them. |
| 219 |
.PP |
| 220 |
Also when working on Perl programs on VMS, if you need a syntax |
| 221 |
in a specific operating system format, then you need either to |
| 222 |
check the appropriate DECC$ feature logical, or call a conversion |
| 223 |
routine to force it to that format. |
| 224 |
.PP |
| 225 |
The feature logical name DECC$FILENAME_UNIX_REPORT modifies traditional |
| 226 |
Perl behavior in the conversion of file specifications from Unix to VMS |
| 227 |
format in order to follow the extended character handling rules now |
| 228 |
expected by the CRTL. Specifically, when this feature is in effect, the |
| 229 |
\&\f(CW\*(C`./.../\*(C'\fR in a Unix path is now translated to \f(CW\*(C`[.^.^.^.]\*(C'\fR instead of |
| 230 |
the traditional VMS \f(CW\*(C`[...]\*(C'\fR. To be compatible with what MakeMaker |
| 231 |
expects, if a VMS path cannot be translated to a Unix path, it is |
| 232 |
passed through unchanged, so \f(CWunixify("[...]")\fR will return \f(CW\*(C`[...]\*(C'\fR. |
| 233 |
.PP |
| 234 |
There are several ambiguous cases where a conversion routine cannot |
| 235 |
determine whether an input filename is in Unix format or in VMS format, |
| 236 |
since now both VMS and Unix file specifications may have characters in |
| 237 |
them that could be mistaken for syntax delimiters of the other type. So |
| 238 |
some pathnames simply cannot be used in a mode that allows either type |
| 239 |
of pathname to be present. Perl will tend to assume that an ambiguous |
| 240 |
filename is in Unix format. |
| 241 |
.PP |
| 242 |
Allowing "." as a version delimiter is simply incompatible with |
| 243 |
determining whether a pathname is in VMS format or in Unix format with |
| 244 |
extended file syntax. There is no way to know whether "perl\-5.8.6" is a |
| 245 |
Unix "perl\-5.8.6" or a VMS "perl\-5.8;6" when passing it to \fBunixify()\fR or |
| 246 |
\&\fBvmsify()\fR. |
| 247 |
.PP |
| 248 |
The DECC$FILENAME_UNIX_REPORT logical name controls how Perl interprets |
| 249 |
filenames to the extent that Perl uses the CRTL internally for many |
| 250 |
purposes, and attempts to follow CRTL conventions for reporting |
| 251 |
filenames. The DECC$FILENAME_UNIX_ONLY feature differs in that it |
| 252 |
expects all filenames passed to the C run-time to be already in Unix |
| 253 |
format. This feature is not yet supported in Perl since Perl uses |
| 254 |
traditional OpenVMS file specifications internally and in the test |
| 255 |
harness, and it is not yet clear whether this mode will be useful or |
| 256 |
useable. The feature logical name DECC$POSIX_COMPLIANT_PATHNAMES is new |
| 257 |
with the RMS Symbolic Link SDK and included with OpenVMS v8.3, but is |
| 258 |
not yet supported in Perl. |
| 259 |
.SS "Filename Case" |
| 260 |
.IX Subsection "Filename Case" |
| 261 |
Perl enables DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE by |
| 262 |
default. Note that the latter only takes effect when extended parse |
| 263 |
is set in the process in which Perl is running. When these features |
| 264 |
are explicitly disabled in the environment or the CRTL does not support |
| 265 |
them, Perl follows the traditional CRTL behavior of downcasing command-line |
| 266 |
arguments and returning file specifications in lower case only. |
| 267 |
.PP |
| 268 |
\&\fIN. B.\fR It is very easy to get tripped up using a mixture of other |
| 269 |
programs, external utilities, and Perl scripts that are in varying |
| 270 |
states of being able to handle case preservation. For example, a file |
| 271 |
created by an older version of an archive utility or a build utility |
| 272 |
such as MMK or MMS may generate a filename in all upper case even on an |
| 273 |
ODS\-5 volume. If this filename is later retrieved by a Perl script or |
| 274 |
module in a case preserving environment, that upper case name may not |
| 275 |
match the mixed-case or lower-case expectations of the Perl code. Your |
| 276 |
best bet is to follow an all-or-nothing approach to case preservation: |
| 277 |
either don't use it at all, or make sure your entire toolchain and |
| 278 |
application environment support and use it. |
| 279 |
.PP |
| 280 |
OpenVMS Alpha v7.3\-1 and later and all version of OpenVMS I64 support |
| 281 |
case sensitivity as a process setting (see \f(CW\*(C`SET\ PROCESS\ /CASE_LOOKUP=SENSITIVE\*(C'\fR). Perl does not currently support case |
| 282 |
sensitivity on VMS, but it may in the future, so Perl programs should |
| 283 |
use the \f(CW\*(C`File::Spec\->case_tolerant\*(C'\fR method to determine the state, and |
| 284 |
not the \f(CW$^O\fR variable. |
| 285 |
.SS "Symbolic Links" |
| 286 |
.IX Subsection "Symbolic Links" |
| 287 |
When built on an ODS\-5 volume with symbolic links enabled, Perl by |
| 288 |
default supports symbolic links when the requisite support is available |
| 289 |
in the filesystem and CRTL (generally 64\-bit OpenVMS v8.3 and later). |
| 290 |
There are a number of limitations and caveats to be aware of when |
| 291 |
working with symbolic links on VMS. Most notably, the target of a valid |
| 292 |
symbolic link must be expressed as a Unix-style path and it must exist |
| 293 |
on a volume visible from your POSIX root (see the \f(CW\*(C`SHOW\ ROOT\*(C'\fR command |
| 294 |
in DCL help). For further details on symbolic link capabilities and |
| 295 |
requirements, see chapter 12 of the CRTL manual that ships with OpenVMS |
| 296 |
v8.3 or later. |
| 297 |
.SS "Wildcard expansion" |
| 298 |
.IX Subsection "Wildcard expansion" |
| 299 |
File specifications containing wildcards are allowed both on |
| 300 |
the command line and within Perl globs (e.g. \f(CW\*(C`<*.c>\*(C'\fR). If |
| 301 |
the wildcard filespec uses VMS syntax, the resultant |
| 302 |
filespecs will follow VMS syntax; if a Unix-style filespec is |
| 303 |
passed in, Unix-style filespecs will be returned. |
| 304 |
Similar to the behavior of wildcard globbing for a Unix shell, |
| 305 |
one can escape command line wildcards with double quotation |
| 306 |
marks \f(CW\*(C`"\*(C'\fR around a perl program command line argument. However, |
| 307 |
owing to the stripping of \f(CW\*(C`"\*(C'\fR characters carried out by the C |
| 308 |
handling of argv you will need to escape a construct such as |
| 309 |
this one (in a directory containing the files \fIPERL.C\fR, \fIPERL.EXE\fR, |
| 310 |
\&\fIPERL.H\fR, and \fIPERL.OBJ\fR): |
| 311 |
.PP |
| 312 |
.Vb 2 |
| 313 |
\& $ perl \-e "print join(\*(Aq \*(Aq,@ARGV)" perl.* |
| 314 |
\& perl.c perl.exe perl.h perl.obj |
| 315 |
.Ve |
| 316 |
.PP |
| 317 |
in the following triple quoted manner: |
| 318 |
.PP |
| 319 |
.Vb 2 |
| 320 |
\& $ perl \-e "print join(\*(Aq \*(Aq,@ARGV)" """perl.*""" |
| 321 |
\& perl.* |
| 322 |
.Ve |
| 323 |
.PP |
| 324 |
In both the case of unquoted command line arguments or in calls |
| 325 |
to \f(CWglob()\fR VMS wildcard expansion is performed. (csh-style |
| 326 |
wildcard expansion is available if you use \f(CW\*(C`File::Glob::glob\*(C'\fR.) |
| 327 |
If the wildcard filespec contains a device or directory |
| 328 |
specification, then the resultant filespecs will also contain |
| 329 |
a device and directory; otherwise, device and directory |
| 330 |
information are removed. VMS-style resultant filespecs will |
| 331 |
contain a full device and directory, while Unix-style |
| 332 |
resultant filespecs will contain only as much of a directory |
| 333 |
path as was present in the input filespec. For example, if |
| 334 |
your default directory is Perl_Root:[000000], the expansion |
| 335 |
of \f(CW\*(C`[.t]*.*\*(C'\fR will yield filespecs like |
| 336 |
"perl_root:[t]base.dir", while the expansion of \f(CW\*(C`t/*/*\*(C'\fR will |
| 337 |
yield filespecs like "t/base.dir". (This is done to match |
| 338 |
the behavior of glob expansion performed by Unix shells.) |
| 339 |
.PP |
| 340 |
Similarly, the resultant filespec will contain the file version |
| 341 |
only if one was present in the input filespec. |
| 342 |
.SS Pipes |
| 343 |
.IX Subsection "Pipes" |
| 344 |
Input and output pipes to Perl filehandles are supported; the |
| 345 |
"file name" is passed to lib$\fBspawn()\fR for asynchronous |
| 346 |
execution. You should be careful to close any pipes you have |
| 347 |
opened in a Perl script, lest you leave any "orphaned" |
| 348 |
subprocesses around when Perl exits. |
| 349 |
.PP |
| 350 |
You may also use backticks to invoke a DCL subprocess, whose |
| 351 |
output is used as the return value of the expression. The |
| 352 |
string between the backticks is handled as if it were the |
| 353 |
argument to the \f(CW\*(C`system\*(C'\fR operator (see below). In this case, |
| 354 |
Perl will wait for the subprocess to complete before continuing. |
| 355 |
.PP |
| 356 |
The mailbox (MBX) that perl can create to communicate with a pipe |
| 357 |
defaults to a buffer size of 8192 on 64\-bit systems, 512 on VAX. The |
| 358 |
default buffer size is adjustable via the logical name PERL_MBX_SIZE |
| 359 |
provided that the value falls between 128 and the SYSGEN parameter |
| 360 |
MAXBUF inclusive. For example, to set the mailbox size to 32767 use |
| 361 |
\&\f(CW\*(C`$ENV{\*(AqPERL_MBX_SIZE\*(Aq} = 32767;\*(C'\fR and then open and use pipe constructs. |
| 362 |
An alternative would be to issue the command: |
| 363 |
.PP |
| 364 |
.Vb 1 |
| 365 |
\& $ Define PERL_MBX_SIZE 32767 |
| 366 |
.Ve |
| 367 |
.PP |
| 368 |
before running your wide record pipe program. A larger value may |
| 369 |
improve performance at the expense of the BYTLM UAF quota. |
| 370 |
.SH "PERL5LIB and PERLLIB" |
| 371 |
.IX Header "PERL5LIB and PERLLIB" |
| 372 |
The PERL5LIB and PERLLIB environment elements work as documented in perl, |
| 373 |
except that the element separator is, by default, '|' instead of ':'. |
| 374 |
However, when running under a Unix shell as determined by the logical |
| 375 |
name \f(CW\*(C`GNV$UNIX_SHELL\*(C'\fR, the separator will be ':' as on Unix systems. The |
| 376 |
directory specifications may use either VMS or Unix syntax. |
| 377 |
.SH "The Perl Forked Debugger" |
| 378 |
.IX Header "The Perl Forked Debugger" |
| 379 |
The Perl forked debugger places the debugger commands and output in a |
| 380 |
separate X\-11 terminal window so that commands and output from multiple |
| 381 |
processes are not mixed together. |
| 382 |
.PP |
| 383 |
Perl on VMS supports an emulation of the forked debugger when Perl is |
| 384 |
run on a VMS system that has X11 support installed. |
| 385 |
.PP |
| 386 |
To use the forked debugger, you need to have the default display set to an |
| 387 |
X\-11 Server and some environment variables set that Unix expects. |
| 388 |
.PP |
| 389 |
The forked debugger requires the environment variable \f(CW\*(C`TERM\*(C'\fR to be \f(CW\*(C`xterm\*(C'\fR, |
| 390 |
and the environment variable \f(CW\*(C`DISPLAY\*(C'\fR to exist. \f(CW\*(C`xterm\*(C'\fR must be in |
| 391 |
lower case. |
| 392 |
.PP |
| 393 |
.Vb 1 |
| 394 |
\& $define TERM "xterm" |
| 395 |
\& |
| 396 |
\& $define DISPLAY "hostname:0.0" |
| 397 |
.Ve |
| 398 |
.PP |
| 399 |
Currently the value of \f(CW\*(C`DISPLAY\*(C'\fR is ignored. It is recommended that it be set |
| 400 |
to be the hostname of the display, the server and screen in Unix notation. In |
| 401 |
the future the value of DISPLAY may be honored by Perl instead of using the |
| 402 |
default display. |
| 403 |
.PP |
| 404 |
It may be helpful to always use the forked debugger so that script I/O is |
| 405 |
separated from debugger I/O. You can force the debugger to be forked by |
| 406 |
assigning a value to the logical name <PERLDB_PIDS> that is not a process |
| 407 |
identification number. |
| 408 |
.PP |
| 409 |
.Vb 1 |
| 410 |
\& $define PERLDB_PIDS XXXX |
| 411 |
.Ve |
| 412 |
.SH PERL_VMS_EXCEPTION_DEBUG |
| 413 |
.IX Header "PERL_VMS_EXCEPTION_DEBUG" |
| 414 |
The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS |
| 415 |
debugger to be invoked if a fatal exception that is not otherwise |
| 416 |
handled is raised. The purpose of this is to allow debugging of |
| 417 |
internal Perl problems that would cause such a condition. |
| 418 |
.PP |
| 419 |
This allows the programmer to look at the execution stack and variables to |
| 420 |
find out the cause of the exception. As the debugger is being invoked as |
| 421 |
the Perl interpreter is about to do a fatal exit, continuing the execution |
| 422 |
in debug mode is usually not practical. |
| 423 |
.PP |
| 424 |
Starting Perl in the VMS debugger may change the program execution |
| 425 |
profile in a way that such problems are not reproduced. |
| 426 |
.PP |
| 427 |
The \f(CW\*(C`kill\*(C'\fR function can be used to test this functionality from within |
| 428 |
a program. |
| 429 |
.PP |
| 430 |
In typical VMS style, only the first letter of the value of this logical |
| 431 |
name is actually checked in a case insensitive mode, and it is considered |
| 432 |
enabled if it is the value "T","1" or "E". |
| 433 |
.PP |
| 434 |
This logical name must be defined before Perl is started. |
| 435 |
.SH "Command line" |
| 436 |
.IX Header "Command line" |
| 437 |
.SS "I/O redirection and backgrounding" |
| 438 |
.IX Subsection "I/O redirection and backgrounding" |
| 439 |
Perl for VMS supports redirection of input and output on the |
| 440 |
command line, using a subset of Bourne shell syntax: |
| 441 |
.IP \(bu 4 |
| 442 |
\&\f(CW\*(C`<file\*(C'\fR reads stdin from \f(CW\*(C`file\*(C'\fR, |
| 443 |
.IP \(bu 4 |
| 444 |
\&\f(CW\*(C`>file\*(C'\fR writes stdout to \f(CW\*(C`file\*(C'\fR, |
| 445 |
.IP \(bu 4 |
| 446 |
\&\f(CW\*(C`>>file\*(C'\fR appends stdout to \f(CW\*(C`file\*(C'\fR, |
| 447 |
.IP \(bu 4 |
| 448 |
\&\f(CW\*(C`2>file\*(C'\fR writes stderr to \f(CW\*(C`file\*(C'\fR, |
| 449 |
.IP \(bu 4 |
| 450 |
\&\f(CW\*(C`2>>file\*(C'\fR appends stderr to \f(CW\*(C`file\*(C'\fR, and |
| 451 |
.IP \(bu 4 |
| 452 |
\&\f(CW\*(C`2>&1\*(C'\fR redirects stderr to stdout. |
| 453 |
.PP |
| 454 |
In addition, output may be piped to a subprocess, using the |
| 455 |
character '|'. Anything after this character on the command |
| 456 |
line is passed to a subprocess for execution; the subprocess |
| 457 |
takes the output of Perl as its input. |
| 458 |
.PP |
| 459 |
Finally, if the command line ends with '&', the entire |
| 460 |
command is run in the background as an asynchronous |
| 461 |
subprocess. |
| 462 |
.SS "Command line switches" |
| 463 |
.IX Subsection "Command line switches" |
| 464 |
The following command line switches behave differently under |
| 465 |
VMS than described in perlrun. Note also that in order |
| 466 |
to pass uppercase switches to Perl, you need to enclose |
| 467 |
them in double-quotes on the command line, since the CRTL |
| 468 |
downcases all unquoted strings. |
| 469 |
.PP |
| 470 |
On newer 64 bit versions of OpenVMS, a process setting now |
| 471 |
controls if the quoting is needed to preserve the case of |
| 472 |
command line arguments. |
| 473 |
.IP \-i 4 |
| 474 |
.IX Item "-i" |
| 475 |
If the \f(CW\*(C`\-i\*(C'\fR switch is present but no extension for a backup |
| 476 |
copy is given, then inplace editing creates a new version of |
| 477 |
a file; the existing copy is not deleted. (Note that if |
| 478 |
an extension is given, an existing file is renamed to the backup |
| 479 |
file, as is the case under other operating systems, so it does |
| 480 |
not remain as a previous version under the original filename.) |
| 481 |
.IP \-S 4 |
| 482 |
.IX Item "-S" |
| 483 |
If the \f(CW"\-S"\fR or \f(CW\*(C`\-"S"\*(C'\fR switch is present \fIand\fR the script |
| 484 |
name does not contain a directory, then Perl translates the |
| 485 |
logical name DCL$PATH as a searchlist, using each translation |
| 486 |
as a directory in which to look for the script. In addition, |
| 487 |
if no file type is specified, Perl looks in each directory |
| 488 |
for a file matching the name specified, with a blank type, |
| 489 |
a type of \fI.pl\fR, and a type of \fI.com\fR, in that order. |
| 490 |
.IP \-u 4 |
| 491 |
.IX Item "-u" |
| 492 |
The \f(CW\*(C`\-u\*(C'\fR switch causes the VMS debugger to be invoked |
| 493 |
after the Perl program is compiled, but before it has |
| 494 |
run. It does not create a core dump file. |
| 495 |
.SH "Perl functions" |
| 496 |
.IX Header "Perl functions" |
| 497 |
As of the time this document was last revised, the following |
| 498 |
Perl functions were implemented in the VMS port of Perl |
| 499 |
(functions marked with * are discussed in more detail below): |
| 500 |
.PP |
| 501 |
.Vb 10 |
| 502 |
\& file tests*, abs, alarm, atan, backticks*, binmode*, bless, |
| 503 |
\& caller, chdir, chmod, chown, chomp, chop, chr, |
| 504 |
\& close, closedir, cos, crypt*, defined, delete, die, do, dump*, |
| 505 |
\& each, endgrent, endpwent, eof, eval, exec*, exists, exit, exp, |
| 506 |
\& fileno, flock getc, getgrent*, getgrgid*, getgrnam, getlogin, |
| 507 |
\& getppid, getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto, |
| 508 |
\& grep, hex, ioctl, import, index, int, join, keys, kill*, |
| 509 |
\& last, lc, lcfirst, lchown*, length, link*, local, localtime, log, |
| 510 |
\& lstat, m//, map, mkdir, my, next, no, oct, open, opendir, ord, |
| 511 |
\& pack, pipe, pop, pos, print, printf, push, q//, qq//, qw//, |
| 512 |
\& qx//*, quotemeta, rand, read, readdir, readlink*, redo, ref, |
| 513 |
\& rename, require, reset, return, reverse, rewinddir, rindex, |
| 514 |
\& rmdir, s///, scalar, seek, seekdir, select(internal), |
| 515 |
\& select (system call)*, setgrent, setpwent, shift, sin, sleep, |
| 516 |
\& socketpair, sort, splice, split, sprintf, sqrt, srand, stat, |
| 517 |
\& study, substr, symlink*, sysread, system*, syswrite, tell, |
| 518 |
\& telldir, tie, time, times*, tr///, uc, ucfirst, umask, |
| 519 |
\& undef, unlink*, unpack, untie, unshift, use, utime*, |
| 520 |
\& values, vec, wait, waitpid*, wantarray, warn, write, y/// |
| 521 |
.Ve |
| 522 |
.PP |
| 523 |
The following functions were not implemented in the VMS port, |
| 524 |
and calling them produces a fatal error (usually) or |
| 525 |
undefined behavior (rarely, we hope): |
| 526 |
.PP |
| 527 |
.Vb 4 |
| 528 |
\& chroot, dbmclose, dbmopen, fork*, getpgrp, getpriority, |
| 529 |
\& msgctl, msgget, msgsend, msgrcv, semctl, |
| 530 |
\& semget, semop, setpgrp, setpriority, shmctl, shmget, |
| 531 |
\& shmread, shmwrite, syscall |
| 532 |
.Ve |
| 533 |
.PP |
| 534 |
The following functions are available on Perls compiled with Dec C |
| 535 |
5.2 or greater and running VMS 7.0 or greater: |
| 536 |
.PP |
| 537 |
.Vb 1 |
| 538 |
\& truncate |
| 539 |
.Ve |
| 540 |
.PP |
| 541 |
The following functions are available on Perls built on VMS 7.2 or |
| 542 |
greater: |
| 543 |
.PP |
| 544 |
.Vb 1 |
| 545 |
\& fcntl (without locking) |
| 546 |
.Ve |
| 547 |
.PP |
| 548 |
The following functions may or may not be implemented, |
| 549 |
depending on what type of socket support you've built into |
| 550 |
your copy of Perl: |
| 551 |
.PP |
| 552 |
.Vb 9 |
| 553 |
\& accept, bind, connect, getpeername, |
| 554 |
\& gethostbyname, getnetbyname, getprotobyname, |
| 555 |
\& getservbyname, gethostbyaddr, getnetbyaddr, |
| 556 |
\& getprotobynumber, getservbyport, gethostent, |
| 557 |
\& getnetent, getprotoent, getservent, sethostent, |
| 558 |
\& setnetent, setprotoent, setservent, endhostent, |
| 559 |
\& endnetent, endprotoent, endservent, getsockname, |
| 560 |
\& getsockopt, listen, recv, select(system call)*, |
| 561 |
\& send, setsockopt, shutdown, socket |
| 562 |
.Ve |
| 563 |
.PP |
| 564 |
The following function is available on Perls built on 64 bit OpenVMS v8.2 |
| 565 |
with hard links enabled on an ODS\-5 formatted build disk. CRTL support |
| 566 |
is in principle available as of OpenVMS v7.3\-1, and better configuration |
| 567 |
support could detect this. |
| 568 |
.PP |
| 569 |
.Vb 1 |
| 570 |
\& link |
| 571 |
.Ve |
| 572 |
.PP |
| 573 |
The following functions are available on Perls built on 64 bit OpenVMS |
| 574 |
v8.2 and later. CRTL support is in principle available as of OpenVMS |
| 575 |
v7.3\-2, and better configuration support could detect this. |
| 576 |
.PP |
| 577 |
.Vb 2 |
| 578 |
\& getgrgid, getgrnam, getpwnam, getpwuid, |
| 579 |
\& setgrent, ttyname |
| 580 |
.Ve |
| 581 |
.PP |
| 582 |
The following functions are available on Perls built on 64 bit OpenVMS v8.2 |
| 583 |
and later. |
| 584 |
.PP |
| 585 |
.Vb 1 |
| 586 |
\& statvfs, socketpair |
| 587 |
.Ve |
| 588 |
.IP "File tests" 4 |
| 589 |
.IX Item "File tests" |
| 590 |
The tests \f(CW\*(C`\-b\*(C'\fR, \f(CW\*(C`\-B\*(C'\fR, \f(CW\*(C`\-c\*(C'\fR, \f(CW\*(C`\-C\*(C'\fR, \f(CW\*(C`\-d\*(C'\fR, \f(CW\*(C`\-e\*(C'\fR, \f(CW\*(C`\-f\*(C'\fR, |
| 591 |
\&\f(CW\*(C`\-o\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, \f(CW\*(C`\-s\*(C'\fR, \f(CW\*(C`\-S\*(C'\fR, \f(CW\*(C`\-t\*(C'\fR, \f(CW\*(C`\-T\*(C'\fR, and \f(CW\*(C`\-z\*(C'\fR work as |
| 592 |
advertised. The return values for \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR |
| 593 |
tell you whether you can actually access the file; this may |
| 594 |
not reflect the UIC-based file protections. Since real and |
| 595 |
effective UIC don't differ under VMS, \f(CW\*(C`\-O\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, |
| 596 |
and \f(CW\*(C`\-X\*(C'\fR are equivalent to \f(CW\*(C`\-o\*(C'\fR, \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR. |
| 597 |
Similarly, several other tests, including \f(CW\*(C`\-A\*(C'\fR, \f(CW\*(C`\-g\*(C'\fR, \f(CW\*(C`\-k\*(C'\fR, |
| 598 |
\&\f(CW\*(C`\-l\*(C'\fR, \f(CW\*(C`\-p\*(C'\fR, and \f(CW\*(C`\-u\*(C'\fR, aren't particularly meaningful under |
| 599 |
VMS, and the values returned by these tests reflect whatever |
| 600 |
your CRTL \f(CWstat()\fR routine does to the equivalent bits in the |
| 601 |
st_mode field. Finally, \f(CW\*(C`\-d\*(C'\fR returns true if passed a device |
| 602 |
specification without an explicit directory (e.g. \f(CW\*(C`DUA1:\*(C'\fR), as |
| 603 |
well as if passed a directory. |
| 604 |
.Sp |
| 605 |
There are DECC feature logical names AND ODS\-5 volume attributes that |
| 606 |
also control what values are returned for the date fields. |
| 607 |
.Sp |
| 608 |
Note: Some sites have reported problems when using the file-access |
| 609 |
tests (\f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-x\*(C'\fR) on files accessed via DEC's DFS. |
| 610 |
Specifically, since DFS does not currently provide access to the |
| 611 |
extended file header of files on remote volumes, attempts to |
| 612 |
examine the ACL fail, and the file tests will return false, |
| 613 |
with \f(CW$!\fR indicating that the file does not exist. You can |
| 614 |
use \f(CW\*(C`stat\*(C'\fR on these files, since that checks UIC-based protection |
| 615 |
only, and then manually check the appropriate bits, as defined by |
| 616 |
your C compiler's \fIstat.h\fR, in the mode value it returns, if you |
| 617 |
need an approximation of the file's protections. |
| 618 |
.IP backticks 4 |
| 619 |
.IX Item "backticks" |
| 620 |
Backticks create a subprocess, and pass the enclosed string |
| 621 |
to it for execution as a DCL command. Since the subprocess is |
| 622 |
created directly via \f(CW\*(C`lib$spawn()\*(C'\fR, any valid DCL command string |
| 623 |
may be specified. |
| 624 |
.IP "binmode FILEHANDLE" 4 |
| 625 |
.IX Item "binmode FILEHANDLE" |
| 626 |
The \f(CW\*(C`binmode\*(C'\fR operator will attempt to insure that no translation |
| 627 |
of carriage control occurs on input from or output to this filehandle. |
| 628 |
Since this involves reopening the file and then restoring its |
| 629 |
file position indicator, if this function returns FALSE, the |
| 630 |
underlying filehandle may no longer point to an open file, or may |
| 631 |
point to a different position in the file than before \f(CW\*(C`binmode\*(C'\fR |
| 632 |
was called. |
| 633 |
.Sp |
| 634 |
Note that \f(CW\*(C`binmode\*(C'\fR is generally not necessary when using normal |
| 635 |
filehandles; it is provided so that you can control I/O to existing |
| 636 |
record-structured files when necessary. You can also use the |
| 637 |
\&\f(CW\*(C`vmsfopen\*(C'\fR function in the VMS::Stdio extension to gain finer |
| 638 |
control of I/O to files and devices with different record structures. |
| 639 |
.IP "crypt PLAINTEXT, USER" 4 |
| 640 |
.IX Item "crypt PLAINTEXT, USER" |
| 641 |
The \f(CW\*(C`crypt\*(C'\fR operator uses the \f(CW\*(C`sys$hash_password\*(C'\fR system |
| 642 |
service to generate the hashed representation of PLAINTEXT. |
| 643 |
If USER is a valid username, the algorithm and salt values |
| 644 |
are taken from that user's UAF record. If it is not, then |
| 645 |
the preferred algorithm and a salt of 0 are used. The |
| 646 |
quadword encrypted value is returned as an 8\-character string. |
| 647 |
.Sp |
| 648 |
The value returned by \f(CW\*(C`crypt\*(C'\fR may be compared against |
| 649 |
the encrypted password from the UAF returned by the \f(CW\*(C`getpw*\*(C'\fR |
| 650 |
functions, in order to authenticate users. If you're |
| 651 |
going to do this, remember that the encrypted password in |
| 652 |
the UAF was generated using uppercase username and |
| 653 |
password strings; you'll have to upcase the arguments to |
| 654 |
\&\f(CW\*(C`crypt\*(C'\fR to insure that you'll get the proper value: |
| 655 |
.Sp |
| 656 |
.Vb 9 |
| 657 |
\& sub validate_passwd { |
| 658 |
\& my($user,$passwd) = @_; |
| 659 |
\& my($pwdhash); |
| 660 |
\& if ( !($pwdhash = (getpwnam($user))[1]) || |
| 661 |
\& $pwdhash ne crypt("\eU$passwd","\eU$name") ) { |
| 662 |
\& intruder_alert($name); |
| 663 |
\& } |
| 664 |
\& return 1; |
| 665 |
\& } |
| 666 |
.Ve |
| 667 |
.IP die 4 |
| 668 |
.IX Item "die" |
| 669 |
\&\f(CW\*(C`die\*(C'\fR will force the native VMS exit status to be an SS$_ABORT code |
| 670 |
if neither of the $! or $? status values are ones that would cause |
| 671 |
the native status to be interpreted as being what VMS classifies as |
| 672 |
SEVERE_ERROR severity for DCL error handling. |
| 673 |
.Sp |
| 674 |
When \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR is active (see "$?" below), the native VMS exit |
| 675 |
status value will have either one of the \f(CW$!\fR or \f(CW$?\fR or \f(CW$^E\fR or |
| 676 |
the Unix value 255 encoded into it in a way that the effective original |
| 677 |
value can be decoded by other programs written in C, including Perl |
| 678 |
and the GNV package. As per the normal non-VMS behavior of \f(CW\*(C`die\*(C'\fR if |
| 679 |
either \f(CW$!\fR or \f(CW$?\fR are non-zero, one of those values will be |
| 680 |
encoded into a native VMS status value. If both of the Unix status |
| 681 |
values are 0, and the \f(CW$^E\fR value is set one of ERROR or SEVERE_ERROR |
| 682 |
severity, then the \f(CW$^E\fR value will be used as the exit code as is. |
| 683 |
If none of the above apply, the Unix value of 255 will be encoded into |
| 684 |
a native VMS exit status value. |
| 685 |
.Sp |
| 686 |
Please note a significant difference in the behavior of \f(CW\*(C`die\*(C'\fR in |
| 687 |
the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR mode is that it does not force a VMS |
| 688 |
SEVERE_ERROR status on exit. The Unix exit values of 2 through |
| 689 |
255 will be encoded in VMS status values with severity levels of |
| 690 |
SUCCESS. The Unix exit value of 1 will be encoded in a VMS status |
| 691 |
value with a severity level of ERROR. This is to be compatible with |
| 692 |
how the VMS C library encodes these values. |
| 693 |
.Sp |
| 694 |
The minimum severity level set by \f(CW\*(C`die\*(C'\fR in \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR mode |
| 695 |
may be changed to be ERROR or higher in the future depending on the |
| 696 |
results of testing and further review. |
| 697 |
.Sp |
| 698 |
See "$?" for a description of the encoding of the Unix value to |
| 699 |
produce a native VMS status containing it. |
| 700 |
.IP dump 4 |
| 701 |
.IX Item "dump" |
| 702 |
Rather than causing Perl to abort and dump core, the \f(CW\*(C`dump\*(C'\fR |
| 703 |
operator invokes the VMS debugger. If you continue to |
| 704 |
execute the Perl program under the debugger, control will |
| 705 |
be transferred to the label specified as the argument to |
| 706 |
\&\f(CW\*(C`dump\*(C'\fR, or, if no label was specified, back to the |
| 707 |
beginning of the program. All other state of the program |
| 708 |
(\fIe.g.\fR values of variables, open file handles) are not |
| 709 |
affected by calling \f(CW\*(C`dump\*(C'\fR. |
| 710 |
.IP "exec LIST" 4 |
| 711 |
.IX Item "exec LIST" |
| 712 |
A call to \f(CW\*(C`exec\*(C'\fR will cause Perl to exit, and to invoke the command |
| 713 |
given as an argument to \f(CW\*(C`exec\*(C'\fR via \f(CW\*(C`lib$do_command\*(C'\fR. If the |
| 714 |
argument begins with '@' or '$' (other than as part of a filespec), |
| 715 |
then it is executed as a DCL command. Otherwise, the first token on |
| 716 |
the command line is treated as the filespec of an image to run, and |
| 717 |
an attempt is made to invoke it (using \fI.Exe\fR and the process |
| 718 |
defaults to expand the filespec) and pass the rest of \f(CW\*(C`exec\*(C'\fR's |
| 719 |
argument to it as parameters. If the token has no file type, and |
| 720 |
matches a file with null type, then an attempt is made to determine |
| 721 |
whether the file is an executable image which should be invoked |
| 722 |
using \f(CW\*(C`MCR\*(C'\fR or a text file which should be passed to DCL as a |
| 723 |
command procedure. |
| 724 |
.IP fork 4 |
| 725 |
.IX Item "fork" |
| 726 |
While in principle the \f(CW\*(C`fork\*(C'\fR operator could be implemented via |
| 727 |
(and with the same rather severe limitations as) the CRTL \f(CWvfork()\fR |
| 728 |
routine, and while some internal support to do just that is in |
| 729 |
place, the implementation has never been completed, making \f(CW\*(C`fork\*(C'\fR |
| 730 |
currently unavailable. A true kernel \f(CWfork()\fR is expected in a |
| 731 |
future version of VMS, and the pseudo-fork based on interpreter |
| 732 |
threads may be available in a future version of Perl on VMS (see |
| 733 |
perlfork). In the meantime, use \f(CW\*(C`system\*(C'\fR, backticks, or piped |
| 734 |
filehandles to create subprocesses. |
| 735 |
.IP getpwent 4 |
| 736 |
.IX Item "getpwent" |
| 737 |
.PD 0 |
| 738 |
.IP getpwnam 4 |
| 739 |
.IX Item "getpwnam" |
| 740 |
.IP getpwuid 4 |
| 741 |
.IX Item "getpwuid" |
| 742 |
.PD |
| 743 |
These operators obtain the information described in perlfunc, |
| 744 |
if you have the privileges necessary to retrieve the named user's |
| 745 |
UAF information via \f(CW\*(C`sys$getuai\*(C'\fR. If not, then only the \f(CW$name\fR, |
| 746 |
\&\f(CW$uid\fR, and \f(CW$gid\fR items are returned. The \f(CW$dir\fR item contains |
| 747 |
the login directory in VMS syntax, while the \f(CW$comment\fR item |
| 748 |
contains the login directory in Unix syntax. The \f(CW$gcos\fR item |
| 749 |
contains the owner field from the UAF record. The \f(CW$quota\fR |
| 750 |
item is not used. |
| 751 |
.IP gmtime 4 |
| 752 |
.IX Item "gmtime" |
| 753 |
The \f(CW\*(C`gmtime\*(C'\fR operator will function properly if you have a |
| 754 |
working CRTL \f(CWgmtime()\fR routine, or if the logical name |
| 755 |
SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds |
| 756 |
which must be added to UTC to yield local time. (This logical |
| 757 |
name is defined automatically if you are running a version of |
| 758 |
VMS with built-in UTC support.) If neither of these cases is |
| 759 |
true, a warning message is printed, and \f(CW\*(C`undef\*(C'\fR is returned. |
| 760 |
.IP kill 4 |
| 761 |
.IX Item "kill" |
| 762 |
In most cases, \f(CW\*(C`kill\*(C'\fR is implemented via the undocumented system |
| 763 |
service \f(CW$SIGPRC\fR, which has the same calling sequence as \f(CW$FORCEX\fR, but |
| 764 |
throws an exception in the target process rather than forcing it to call |
| 765 |
\&\f(CW$EXIT\fR. Generally speaking, \f(CW\*(C`kill\*(C'\fR follows the behavior of the |
| 766 |
CRTL's \f(CWkill()\fR function, but unlike that function can be called from |
| 767 |
within a signal handler. Also, unlike the \f(CW\*(C`kill\*(C'\fR in some versions of |
| 768 |
the CRTL, Perl's \f(CW\*(C`kill\*(C'\fR checks the validity of the signal passed in and |
| 769 |
returns an error rather than attempting to send an unrecognized signal. |
| 770 |
.Sp |
| 771 |
Also, negative signal values don't do anything special under |
| 772 |
VMS; they're just converted to the corresponding positive value. |
| 773 |
.IP qx// 4 |
| 774 |
.IX Item "qx//" |
| 775 |
See the entry on \f(CW\*(C`backticks\*(C'\fR above. |
| 776 |
.IP "select (system call)" 4 |
| 777 |
.IX Item "select (system call)" |
| 778 |
If Perl was not built with socket support, the system call |
| 779 |
version of \f(CW\*(C`select\*(C'\fR is not available at all. If socket |
| 780 |
support is present, then the system call version of |
| 781 |
\&\f(CW\*(C`select\*(C'\fR functions only for file descriptors attached |
| 782 |
to sockets. It will not provide information about regular |
| 783 |
files or pipes, since the CRTL \f(CWselect()\fR routine does not |
| 784 |
provide this functionality. |
| 785 |
.IP "stat EXPR" 4 |
| 786 |
.IX Item "stat EXPR" |
| 787 |
Since VMS keeps track of files according to a different scheme |
| 788 |
than Unix, it's not really possible to represent the file's ID |
| 789 |
in the \f(CW\*(C`st_dev\*(C'\fR and \f(CW\*(C`st_ino\*(C'\fR fields of a \f(CW\*(C`struct stat\*(C'\fR. Perl |
| 790 |
tries its best, though, and the values it uses are pretty unlikely |
| 791 |
to be the same for two different files. We can't guarantee this, |
| 792 |
though, so caveat scriptor. |
| 793 |
.IP "system LIST" 4 |
| 794 |
.IX Item "system LIST" |
| 795 |
The \f(CW\*(C`system\*(C'\fR operator creates a subprocess, and passes its |
| 796 |
arguments to the subprocess for execution as a DCL command. |
| 797 |
Since the subprocess is created directly via \f(CW\*(C`lib$spawn()\*(C'\fR, any |
| 798 |
valid DCL command string may be specified. If the string begins with |
| 799 |
\&'@', it is treated as a DCL command unconditionally. Otherwise, if |
| 800 |
the first token contains a character used as a delimiter in file |
| 801 |
specification (e.g. \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`]\*(C'\fR), an attempt is made to expand it |
| 802 |
using a default type of \fI.Exe\fR and the process defaults, and if |
| 803 |
successful, the resulting file is invoked via \f(CW\*(C`MCR\*(C'\fR. This allows you |
| 804 |
to invoke an image directly simply by passing the file specification |
| 805 |
to \f(CW\*(C`system\*(C'\fR, a common Unixish idiom. If the token has no file type, |
| 806 |
and matches a file with null type, then an attempt is made to |
| 807 |
determine whether the file is an executable image which should be |
| 808 |
invoked using \f(CW\*(C`MCR\*(C'\fR or a text file which should be passed to DCL |
| 809 |
as a command procedure. |
| 810 |
.Sp |
| 811 |
If LIST consists of the empty string, \f(CW\*(C`system\*(C'\fR spawns an |
| 812 |
interactive DCL subprocess, in the same fashion as typing |
| 813 |
\&\fBSPAWN\fR at the DCL prompt. |
| 814 |
.Sp |
| 815 |
Perl waits for the subprocess to complete before continuing |
| 816 |
execution in the current process. As described in perlfunc, |
| 817 |
the return value of \f(CW\*(C`system\*(C'\fR is a fake "status" which follows |
| 818 |
POSIX semantics unless the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR is in |
| 819 |
effect; see the description of \f(CW$?\fR in this document for more |
| 820 |
detail. |
| 821 |
.IP time 4 |
| 822 |
.IX Item "time" |
| 823 |
The value returned by \f(CW\*(C`time\*(C'\fR is the offset in seconds from |
| 824 |
01\-JAN\-1970 00:00:00 (just like the CRTL's \fBtimes()\fR routine), in order |
| 825 |
to make life easier for code coming in from the POSIX/Unix world. |
| 826 |
.IP times 4 |
| 827 |
.IX Item "times" |
| 828 |
The array returned by the \f(CW\*(C`times\*(C'\fR operator is divided up |
| 829 |
according to the same rules the CRTL \f(CWtimes()\fR routine. |
| 830 |
Therefore, the "system time" elements will always be 0, since |
| 831 |
there is no difference between "user time" and "system" time |
| 832 |
under VMS, and the time accumulated by a subprocess may or may |
| 833 |
not appear separately in the "child time" field, depending on |
| 834 |
whether \f(CWtimes()\fR keeps track of subprocesses separately. Note |
| 835 |
especially that the VAXCRTL (at least) keeps track only of |
| 836 |
subprocesses spawned using \f(CWfork()\fR and \f(CWexec()\fR; it will not |
| 837 |
accumulate the times of subprocesses spawned via pipes, \f(CWsystem()\fR, |
| 838 |
or backticks. |
| 839 |
.IP "unlink LIST" 4 |
| 840 |
.IX Item "unlink LIST" |
| 841 |
\&\f(CW\*(C`unlink\*(C'\fR will delete the highest version of a file only; in |
| 842 |
order to delete all versions, you need to say |
| 843 |
.Sp |
| 844 |
.Vb 1 |
| 845 |
\& 1 while unlink LIST; |
| 846 |
.Ve |
| 847 |
.Sp |
| 848 |
You may need to make this change to scripts written for a |
| 849 |
Unix system which expect that after a call to \f(CW\*(C`unlink\*(C'\fR, |
| 850 |
no files with the names passed to \f(CW\*(C`unlink\*(C'\fR will exist. |
| 851 |
(Note: This can be changed at compile time; if you |
| 852 |
\&\f(CW\*(C`use Config\*(C'\fR and \f(CW$Config{\*(Aqd_unlink_all_versions\*(Aq}\fR is |
| 853 |
\&\f(CW\*(C`define\*(C'\fR, then \f(CW\*(C`unlink\*(C'\fR will delete all versions of a |
| 854 |
file on the first call.) |
| 855 |
.Sp |
| 856 |
\&\f(CW\*(C`unlink\*(C'\fR will delete a file if at all possible, even if it |
| 857 |
requires changing file protection (though it won't try to |
| 858 |
change the protection of the parent directory). You can tell |
| 859 |
whether you've got explicit delete access to a file by using the |
| 860 |
\&\f(CW\*(C`VMS::Filespec::candelete\*(C'\fR operator. For instance, in order |
| 861 |
to delete only files to which you have delete access, you could |
| 862 |
say something like |
| 863 |
.Sp |
| 864 |
.Vb 8 |
| 865 |
\& sub safe_unlink { |
| 866 |
\& my($file,$num); |
| 867 |
\& foreach $file (@_) { |
| 868 |
\& next unless VMS::Filespec::candelete($file); |
| 869 |
\& $num += unlink $file; |
| 870 |
\& } |
| 871 |
\& $num; |
| 872 |
\& } |
| 873 |
.Ve |
| 874 |
.Sp |
| 875 |
(or you could just use \f(CW\*(C`VMS::Stdio::remove\*(C'\fR, if you've installed |
| 876 |
the VMS::Stdio extension distributed with Perl). If \f(CW\*(C`unlink\*(C'\fR has to |
| 877 |
change the file protection to delete the file, and you interrupt it |
| 878 |
in midstream, the file may be left intact, but with a changed ACL |
| 879 |
allowing you delete access. |
| 880 |
.Sp |
| 881 |
This behavior of \f(CW\*(C`unlink\*(C'\fR is to be compatible with POSIX behavior |
| 882 |
and not traditional VMS behavior. |
| 883 |
.IP "utime LIST" 4 |
| 884 |
.IX Item "utime LIST" |
| 885 |
This operator changes only the modification time of the file (VMS |
| 886 |
revision date) on ODS\-2 volumes and ODS\-5 volumes without access |
| 887 |
dates enabled. On ODS\-5 volumes with access dates enabled, the |
| 888 |
true access time is modified. |
| 889 |
.IP "waitpid PID,FLAGS" 4 |
| 890 |
.IX Item "waitpid PID,FLAGS" |
| 891 |
If PID is a subprocess started by a piped \f(CWopen()\fR (see open), |
| 892 |
\&\f(CW\*(C`waitpid\*(C'\fR will wait for that subprocess, and return its final status |
| 893 |
value in \f(CW$?\fR. If PID is a subprocess created in some other way (e.g. |
| 894 |
SPAWNed before Perl was invoked), \f(CW\*(C`waitpid\*(C'\fR will simply check once per |
| 895 |
second whether the process has completed, and return when it has. (If |
| 896 |
PID specifies a process that isn't a subprocess of the current process, |
| 897 |
and you invoked Perl with the \f(CW\*(C`\-w\*(C'\fR switch, a warning will be issued.) |
| 898 |
.Sp |
| 899 |
Returns PID on success, \-1 on error. The FLAGS argument is ignored |
| 900 |
in all cases. |
| 901 |
.SH "Perl variables" |
| 902 |
.IX Header "Perl variables" |
| 903 |
The following VMS-specific information applies to the indicated |
| 904 |
"special" Perl variables, in addition to the general information |
| 905 |
in perlvar. Where there is a conflict, this information |
| 906 |
takes precedence. |
| 907 |
.ie n .IP %ENV 4 |
| 908 |
.el .IP \f(CW%ENV\fR 4 |
| 909 |
.IX Item "%ENV" |
| 910 |
The operation of the \f(CW%ENV\fR array depends on the translation |
| 911 |
of the logical name \fIPERL_ENV_TABLES\fR. If defined, it should |
| 912 |
be a search list, each element of which specifies a location |
| 913 |
for \f(CW%ENV\fR elements. If you tell Perl to read or set the |
| 914 |
element \f(CW\*(C`$ENV{\*(C'\fR\fIname\fR\f(CW\*(C`}\*(C'\fR, then Perl uses the translations of |
| 915 |
\&\fIPERL_ENV_TABLES\fR as follows: |
| 916 |
.RS 4 |
| 917 |
.IP CRTL_ENV 4 |
| 918 |
.IX Item "CRTL_ENV" |
| 919 |
This string tells Perl to consult the CRTL's internal \f(CW\*(C`environ\*(C'\fR array |
| 920 |
of key-value pairs, using \fIname\fR as the key. In most cases, this |
| 921 |
contains only a few keys, but if Perl was invoked via the C |
| 922 |
\&\f(CW\*(C`exec[lv]e()\*(C'\fR function, as is the case for some embedded Perl |
| 923 |
applications or when running under a shell such as GNV bash, the |
| 924 |
\&\f(CW\*(C`environ\*(C'\fR array may have been populated by the calling program. |
| 925 |
.IP CLISYM_[LOCAL] 4 |
| 926 |
.IX Item "CLISYM_[LOCAL]" |
| 927 |
A string beginning with \f(CW\*(C`CLISYM_\*(C'\fRtells Perl to consult the CLI's |
| 928 |
symbol tables, using \fIname\fR as the name of the symbol. When reading |
| 929 |
an element of \f(CW%ENV\fR, the local symbol table is scanned first, followed |
| 930 |
by the global symbol table.. The characters following \f(CW\*(C`CLISYM_\*(C'\fR are |
| 931 |
significant when an element of \f(CW%ENV\fR is set or deleted: if the |
| 932 |
complete string is \f(CW\*(C`CLISYM_LOCAL\*(C'\fR, the change is made in the local |
| 933 |
symbol table; otherwise the global symbol table is changed. |
| 934 |
.IP "Any other string" 4 |
| 935 |
.IX Item "Any other string" |
| 936 |
If an element of \fIPERL_ENV_TABLES\fR translates to any other string, |
| 937 |
that string is used as the name of a logical name table, which is |
| 938 |
consulted using \fIname\fR as the logical name. The normal search |
| 939 |
order of access modes is used. |
| 940 |
.RE |
| 941 |
.RS 4 |
| 942 |
.Sp |
| 943 |
\&\fIPERL_ENV_TABLES\fR is translated once when Perl starts up; any changes |
| 944 |
you make while Perl is running do not affect the behavior of \f(CW%ENV\fR. |
| 945 |
If \fIPERL_ENV_TABLES\fR is not defined, then Perl defaults to consulting |
| 946 |
first the logical name tables specified by \fILNM$FILE_DEV\fR, and then |
| 947 |
the CRTL \f(CW\*(C`environ\*(C'\fR array. This default order is reversed when the |
| 948 |
logical name \fIGNV$UNIX_SHELL\fR is defined, such as when running under |
| 949 |
GNV bash. |
| 950 |
.Sp |
| 951 |
For operations on \f(CW%ENV\fR entries based on logical names or DCL symbols, the |
| 952 |
key string is treated as if it were entirely uppercase, regardless of the |
| 953 |
case actually specified in the Perl expression. Entries in \f(CW%ENV\fR based on the |
| 954 |
CRTL's environ array preserve the case of the key string when stored, and |
| 955 |
lookups are case sensitive. |
| 956 |
.Sp |
| 957 |
When an element of \f(CW%ENV\fR is read, the locations to which |
| 958 |
\&\fIPERL_ENV_TABLES\fR points are checked in order, and the value |
| 959 |
obtained from the first successful lookup is returned. If the |
| 960 |
name of the \f(CW%ENV\fR element contains a semi-colon, it and |
| 961 |
any characters after it are removed. These are ignored when |
| 962 |
the CRTL \f(CW\*(C`environ\*(C'\fR array or a CLI symbol table is consulted. |
| 963 |
However, the name is looked up in a logical name table, the |
| 964 |
suffix after the semi-colon is treated as the translation index |
| 965 |
to be used for the lookup. This lets you look up successive values |
| 966 |
for search list logical names. For instance, if you say |
| 967 |
.Sp |
| 968 |
.Vb 3 |
| 969 |
\& $ Define STORY once,upon,a,time,there,was |
| 970 |
\& $ perl \-e "for ($i = 0; $i <= 6; $i++) " \- |
| 971 |
\& _$ \-e "{ print $ENV{\*(Aqstory;\*(Aq.$i},\*(Aq \*(Aq}" |
| 972 |
.Ve |
| 973 |
.Sp |
| 974 |
Perl will print \f(CW\*(C`ONCE UPON A TIME THERE WAS\*(C'\fR, assuming, of course, |
| 975 |
that \fIPERL_ENV_TABLES\fR is set up so that the logical name \f(CW\*(C`story\*(C'\fR |
| 976 |
is found, rather than a CLI symbol or CRTL \f(CW\*(C`environ\*(C'\fR element with |
| 977 |
the same name. |
| 978 |
.Sp |
| 979 |
When an element of \f(CW%ENV\fR is set to a defined string, the |
| 980 |
corresponding definition is made in the location to which the |
| 981 |
first translation of \fIPERL_ENV_TABLES\fR points. If this causes a |
| 982 |
logical name to be created, it is defined in supervisor mode. |
| 983 |
(The same is done if an existing logical name was defined in |
| 984 |
executive or kernel mode; an existing user or supervisor mode |
| 985 |
logical name is reset to the new value.) If the value is an empty |
| 986 |
string, the logical name's translation is defined as a single \f(CW\*(C`NUL\*(C'\fR |
| 987 |
(ASCII \f(CW\*(C`\e0\*(C'\fR) character, since a logical name cannot translate to a |
| 988 |
zero-length string. (This restriction does not apply to CLI symbols |
| 989 |
or CRTL \f(CW\*(C`environ\*(C'\fR values; they are set to the empty string.) |
| 990 |
.Sp |
| 991 |
When an element of \f(CW%ENV\fR is set to \f(CW\*(C`undef\*(C'\fR, the element is looked |
| 992 |
up as if it were being read, and if it is found, it is deleted. (An |
| 993 |
item "deleted" from the CRTL \f(CW\*(C`environ\*(C'\fR array is set to the empty |
| 994 |
string.) Using \f(CW\*(C`delete\*(C'\fR to remove an element from \f(CW%ENV\fR has a |
| 995 |
similar effect, but after the element is deleted, another attempt is |
| 996 |
made to look up the element, so an inner-mode logical name or a name |
| 997 |
in another location will replace the logical name just deleted. In |
| 998 |
either case, only the first value found searching PERL_ENV_TABLES is |
| 999 |
altered. It is not possible at present to define a search list |
| 1000 |
logical name via \f(CW%ENV\fR. |
| 1001 |
.Sp |
| 1002 |
The element \f(CW$ENV{DEFAULT}\fR is special: when read, it returns |
| 1003 |
Perl's current default device and directory, and when set, it |
| 1004 |
resets them, regardless of the definition of \fIPERL_ENV_TABLES\fR. |
| 1005 |
It cannot be cleared or deleted; attempts to do so are silently |
| 1006 |
ignored. |
| 1007 |
.Sp |
| 1008 |
Note that if you want to pass on any elements of the |
| 1009 |
C\-local environ array to a subprocess which isn't |
| 1010 |
started by fork/exec, or isn't running a C program, you |
| 1011 |
can "promote" them to logical names in the current |
| 1012 |
process, which will then be inherited by all subprocesses, |
| 1013 |
by saying |
| 1014 |
.Sp |
| 1015 |
.Vb 4 |
| 1016 |
\& foreach my $key (qw[C\-local keys you want promoted]) { |
| 1017 |
\& my $temp = $ENV{$key}; # read from C\-local array |
| 1018 |
\& $ENV{$key} = $temp; # and define as logical name |
| 1019 |
\& } |
| 1020 |
.Ve |
| 1021 |
.Sp |
| 1022 |
(You can't just say \f(CW\*(C`$ENV{$key} = $ENV{$key}\*(C'\fR, since the |
| 1023 |
Perl optimizer is smart enough to elide the expression.) |
| 1024 |
.Sp |
| 1025 |
Don't try to clear \f(CW%ENV\fR by saying \f(CW\*(C`%ENV = ();\*(C'\fR, it will throw |
| 1026 |
a fatal error. This is equivalent to doing the following from DCL: |
| 1027 |
.Sp |
| 1028 |
.Vb 1 |
| 1029 |
\& DELETE/LOGICAL * |
| 1030 |
.Ve |
| 1031 |
.Sp |
| 1032 |
You can imagine how bad things would be if, for example, the SYS$MANAGER |
| 1033 |
or SYS$SYSTEM logical names were deleted. |
| 1034 |
.Sp |
| 1035 |
At present, the first time you iterate over \f(CW%ENV\fR using |
| 1036 |
\&\f(CW\*(C`keys\*(C'\fR, or \f(CW\*(C`values\*(C'\fR, you will incur a time penalty as all |
| 1037 |
logical names are read, in order to fully populate \f(CW%ENV\fR. |
| 1038 |
Subsequent iterations will not reread logical names, so they |
| 1039 |
won't be as slow, but they also won't reflect any changes |
| 1040 |
to logical name tables caused by other programs. |
| 1041 |
.Sp |
| 1042 |
You do need to be careful with the logical names representing |
| 1043 |
process-permanent files, such as \f(CW\*(C`SYS$INPUT\*(C'\fR and \f(CW\*(C`SYS$OUTPUT\*(C'\fR. |
| 1044 |
The translations for these logical names are prepended with a |
| 1045 |
two-byte binary value (0x1B 0x00) that needs to be stripped off |
| 1046 |
if you want to use it. (In previous versions of Perl it wasn't |
| 1047 |
possible to get the values of these logical names, as the null |
| 1048 |
byte acted as an end-of-string marker) |
| 1049 |
.RE |
| 1050 |
.IP $! 4 |
| 1051 |
The string value of \f(CW$!\fR is that returned by the CRTL's |
| 1052 |
\&\fBstrerror()\fR function, so it will include the VMS message for |
| 1053 |
VMS-specific errors. The numeric value of \f(CW$!\fR is the |
| 1054 |
value of \f(CW\*(C`errno\*(C'\fR, except if errno is EVMSERR, in which |
| 1055 |
case \f(CW$!\fR contains the value of vaxc$errno. Setting \f(CW$!\fR |
| 1056 |
always sets errno to the value specified. If this value is |
| 1057 |
EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so |
| 1058 |
that the string value of \f(CW$!\fR won't reflect the VMS error |
| 1059 |
message from before \f(CW$!\fR was set. |
| 1060 |
.IP $^E 4 |
| 1061 |
.IX Item "$^E" |
| 1062 |
This variable provides direct access to VMS status values |
| 1063 |
in vaxc$errno, which are often more specific than the |
| 1064 |
generic Unix-style error messages in \f(CW$!\fR. Its numeric value |
| 1065 |
is the value of vaxc$errno, and its string value is the |
| 1066 |
corresponding VMS message string, as retrieved by sys$\fBgetmsg()\fR. |
| 1067 |
Setting \f(CW$^E\fR sets vaxc$errno to the value specified. |
| 1068 |
.Sp |
| 1069 |
While Perl attempts to keep the vaxc$errno value to be current, if |
| 1070 |
errno is not EVMSERR, it may not be from the current operation. |
| 1071 |
.IP $? 4 |
| 1072 |
The "status value" returned in \f(CW$?\fR is synthesized from the |
| 1073 |
actual exit status of the subprocess in a way that approximates |
| 1074 |
POSIX \fBwait\fR\|(5) semantics, in order to allow Perl programs to |
| 1075 |
portably test for successful completion of subprocesses. The |
| 1076 |
low order 8 bits of \f(CW$?\fR are always 0 under VMS, since the |
| 1077 |
termination status of a process may or may not have been |
| 1078 |
generated by an exception. |
| 1079 |
.Sp |
| 1080 |
The next 8 bits contain the termination status of the program. |
| 1081 |
.Sp |
| 1082 |
If the child process follows the convention of C programs |
| 1083 |
compiled with the _POSIX_EXIT macro set, the status value will |
| 1084 |
contain the actual value of 0 to 255 returned by that program |
| 1085 |
on a normal exit. |
| 1086 |
.Sp |
| 1087 |
With the _POSIX_EXIT macro set, the Unix exit value of zero is |
| 1088 |
represented as a VMS native status of 1, and the Unix values |
| 1089 |
from 2 to 255 are encoded by the equation: |
| 1090 |
.Sp |
| 1091 |
.Vb 1 |
| 1092 |
\& VMS_status = 0x35a000 + (unix_value * 8) + 1. |
| 1093 |
.Ve |
| 1094 |
.Sp |
| 1095 |
And in the special case of Unix value 1 the encoding is: |
| 1096 |
.Sp |
| 1097 |
.Vb 1 |
| 1098 |
\& VMS_status = 0x35a000 + 8 + 2 + 0x10000000. |
| 1099 |
.Ve |
| 1100 |
.Sp |
| 1101 |
For other termination statuses, the severity portion of the |
| 1102 |
subprocess's exit status is used: if the severity was success or |
| 1103 |
informational, these bits are all 0; if the severity was |
| 1104 |
warning, they contain a value of 1; if the severity was |
| 1105 |
error or fatal error, they contain the actual severity bits, |
| 1106 |
which turns out to be a value of 2 for error and 4 for severe_error. |
| 1107 |
Fatal is another term for the severe_error status. |
| 1108 |
.Sp |
| 1109 |
As a result, \f(CW$?\fR will always be zero if the subprocess's exit |
| 1110 |
status indicated successful completion, and non-zero if a |
| 1111 |
warning or error occurred or a program compliant with encoding |
| 1112 |
_POSIX_EXIT values was run and set a status. |
| 1113 |
.Sp |
| 1114 |
How can you tell the difference between a non-zero status that is |
| 1115 |
the result of a VMS native error status or an encoded Unix status? |
| 1116 |
You can not unless you look at the ${^CHILD_ERROR_NATIVE} value. |
| 1117 |
The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value |
| 1118 |
and check the severity bits. If the severity bits are equal to 1, |
| 1119 |
then if the numeric value for \f(CW$?\fR is between 2 and 255 or 0, then |
| 1120 |
\&\f(CW$?\fR accurately reflects a value passed back from a Unix application. |
| 1121 |
If \f(CW$?\fR is 1, and the severity bits indicate a VMS error (2), then |
| 1122 |
\&\f(CW$?\fR is from a Unix application exit value. |
| 1123 |
.Sp |
| 1124 |
In practice, Perl scripts that call programs that return _POSIX_EXIT |
| 1125 |
type status values will be expecting those values, and programs that |
| 1126 |
call traditional VMS programs will either be expecting the previous |
| 1127 |
behavior or just checking for a non-zero status. |
| 1128 |
.Sp |
| 1129 |
And success is always the value 0 in all behaviors. |
| 1130 |
.Sp |
| 1131 |
When the actual VMS termination status of the child is an error, |
| 1132 |
internally the \f(CW$!\fR value will be set to the closest Unix errno |
| 1133 |
value to that error so that Perl scripts that test for error |
| 1134 |
messages will see the expected Unix style error message instead |
| 1135 |
of a VMS message. |
| 1136 |
.Sp |
| 1137 |
Conversely, when setting \f(CW$?\fR in an END block, an attempt is made |
| 1138 |
to convert the POSIX value into a native status intelligible to |
| 1139 |
the operating system upon exiting Perl. What this boils down to |
| 1140 |
is that setting \f(CW$?\fR to zero results in the generic success value |
| 1141 |
SS$_NORMAL, and setting \f(CW$?\fR to a non-zero value results in the |
| 1142 |
generic failure status SS$_ABORT. See also "exit" in perlport. |
| 1143 |
.Sp |
| 1144 |
With the \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR logical name defined as "ENABLE", |
| 1145 |
setting \f(CW$?\fR will cause the new value to be encoded into \f(CW$^E\fR |
| 1146 |
so that either the original parent or child exit status values |
| 1147 |
0 to 255 can be automatically recovered by C programs expecting |
| 1148 |
_POSIX_EXIT behavior. If both a parent and a child exit value are |
| 1149 |
non-zero, then it will be assumed that this is actually a VMS native |
| 1150 |
status value to be passed through. The special value of 0xFFFF is |
| 1151 |
almost a NOOP as it will cause the current native VMS status in the |
| 1152 |
C library to become the current native Perl VMS status, and is handled |
| 1153 |
this way as it is known to not be a valid native VMS status value. |
| 1154 |
It is recommend that only values in the range of normal Unix parent or |
| 1155 |
child status numbers, 0 to 255 are used. |
| 1156 |
.Sp |
| 1157 |
The pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR makes \f(CW$?\fR reflect the actual |
| 1158 |
VMS exit status instead of the default emulation of POSIX status |
| 1159 |
described above. This pragma also disables the conversion of |
| 1160 |
non-zero values to SS$_ABORT when setting \f(CW$?\fR in an END |
| 1161 |
block (but zero will still be converted to SS$_NORMAL). |
| 1162 |
.Sp |
| 1163 |
Do not use the pragma \f(CW\*(C`use vmsish \*(Aqstatus\*(Aq\*(C'\fR with \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR |
| 1164 |
enabled, as they are at times requesting conflicting actions and the |
| 1165 |
consequence of ignoring this advice will be undefined to allow future |
| 1166 |
improvements in the POSIX exit handling. |
| 1167 |
.Sp |
| 1168 |
In general, with \f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR enabled, more detailed information |
| 1169 |
will be available in the exit status for DCL scripts or other native VMS tools, |
| 1170 |
and will give the expected information for Posix programs. It has not been |
| 1171 |
made the default in order to preserve backward compatibility. |
| 1172 |
.Sp |
| 1173 |
N.B. Setting \f(CW\*(C`DECC$FILENAME_UNIX_REPORT\*(C'\fR implicitly enables |
| 1174 |
\&\f(CW\*(C`PERL_VMS_POSIX_EXIT\*(C'\fR. |
| 1175 |
.IP $| 4 |
| 1176 |
Setting \f(CW$|\fR for an I/O stream causes data to be flushed |
| 1177 |
all the way to disk on each write (\fIi.e.\fR not just to |
| 1178 |
the underlying RMS buffers for a file). In other words, |
| 1179 |
it's equivalent to calling \fBfflush()\fR and \fBfsync()\fR from C. |
| 1180 |
.SH "Standard modules with VMS-specific differences" |
| 1181 |
.IX Header "Standard modules with VMS-specific differences" |
| 1182 |
.SS SDBM_File |
| 1183 |
.IX Subsection "SDBM_File" |
| 1184 |
SDBM_File works properly on VMS. It has, however, one minor |
| 1185 |
difference. The database directory file created has a \fI.sdbm_dir\fR |
| 1186 |
extension rather than a \fI.dir\fR extension. \fI.dir\fR files are VMS filesystem |
| 1187 |
directory files, and using them for other purposes could cause unacceptable |
| 1188 |
problems. |
| 1189 |
.SH "Revision date" |
| 1190 |
.IX Header "Revision date" |
| 1191 |
Please see the git repository for revision history. |
| 1192 |
.SH AUTHOR |
| 1193 |
.IX Header "AUTHOR" |
| 1194 |
Charles Bailey [email protected] |
| 1195 |
Craig Berry [email protected] |
| 1196 |
Dan Sugalski [email protected] |
| 1197 |
John Malmberg [email protected] |