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