<P>Perl extensions are packages which provide both XS and Perl code
to add new functionality to perl. (XS is a meta-language which
simplifies writing C code which interacts with Perl, see
<A HREF="../../lib/Pod/perlxs.html">the perlxs manpage</A> for more details.) The Perl code for an
extension is treated like any other library module - it's
made available in your script through the appropriate
<A HREF="../../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A> or <A HREF="../../lib/Pod/perlfunc.html#item_require"><CODE>require</CODE></A> statement, and usually defines a Perl
package containing the extension.</P>
<P>The portion of the extension provided by the XS code may be
connected to the rest of Perl in either of two ways. In the
<STRONG>static</STRONG> configuration, the object code for the extension is
linked directly into <EM>PerlShr.Exe</EM>, and is initialized whenever
Perl is invoked. In the <STRONG>dynamic</STRONG> configuration, the extension's
machine code is placed into a separate shareable image, which is
mapped by Perl's DynaLoader when the extension is <A HREF="../../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A>d or
<A HREF="../../lib/Pod/perlfunc.html#item_require"><CODE>require</CODE></A>d in your script. This allows you to maintain the
extension as a separate entity, at the cost of keeping track of the
additional shareable image. Most extensions can be set up as either
static or dynamic.</P>
<P>The source code for an extension usually resides in its own
directory. At least three files are generally provided:
<EM>Extshortname</EM><EM>.xs</EM> (where <EM>Extshortname</EM> is the portion of
the extension's name following the last <CODE>::</CODE>), containing
the XS code, <EM>Extshortname</EM><EM>.pm</EM>, the Perl library module
for the extension, and <EM>Makefile.PL</EM>, a Perl script which uses
the <CODE>MakeMaker</CODE> library modules supplied with Perl to generate
a <EM>Descrip.MMS</EM> file for the extension.</P>
The tests <CODE>-b</CODE>, <CODE>-B</CODE>, <CODE>-c</CODE>, <CODE>-C</CODE>, <CODE>-d</CODE>, <CODE>-e</CODE>, <CODE>-f</CODE>,
<CODE>-o</CODE>, <CODE>-M</CODE>, <CODE>-s</CODE>, <A HREF="#item_%2DS"><CODE>-S</CODE></A>, <CODE>-t</CODE>, <CODE>-T</CODE>, and <CODE>-z</CODE> work as
advertised. The return values for <CODE>-r</CODE>, <CODE>-w</CODE>, and <CODE>-x</CODE>
tell you whether you can actually access the file; this may
not reflect the UIC-based file protections. Since real and
effective UIC don't differ under VMS, <CODE>-O</CODE>, <CODE>-R</CODE>, <CODE>-W</CODE>,
and <CODE>-X</CODE> are equivalent to <CODE>-o</CODE>, <CODE>-r</CODE>, <CODE>-w</CODE>, and <CODE>-x</CODE>.
Similarly, several other tests, including <CODE>-A</CODE>, <CODE>-g</CODE>, <CODE>-k</CODE>,
<CODE>-l</CODE>, <CODE>-p</CODE>, and <A HREF="#item_%2Du"><CODE>-u</CODE></A>, aren't particularly meaningful under
VMS, and the values returned by these tests reflect whatever
your CRTL <A HREF="#item_stat"><CODE>stat()</CODE></A> routine does to the equivalent bits in the
st_mode field. Finally, <CODE>-d</CODE> returns true if passed a device
specification without an explicit directory (e.g. <CODE>DUA1:</CODE>), as
well as if passed a directory.
<P>Note: Some sites have reported problems when using the file-access
tests (<CODE>-r</CODE>, <CODE>-w</CODE>, and <CODE>-x</CODE>) on files accessed via DEC's DFS.
Specifically, since DFS does not currently provide access to the
extended file header of files on remote volumes, attempts to
examine the ACL fail, and the file tests will return false,
with <A HREF="#item_%24%21"><CODE>$!</CODE></A> indicating that the file does not exist. You can
use <A HREF="#item_stat"><CODE>stat</CODE></A> on these files, since that checks UIC-based protection
only, and then manually check the appropriate bits, as defined by
your C compiler's <EM>stat.h</EM>, in the mode value it returns, if you
need an approximation of the file's protections.</P>
A string beginning with <CODE>CLISYM_</CODE>tells Perl to consult the CLI's
symbol tables, using <EM>name</EM> as the name of the symbol. When reading
an element of <A HREF="#item_%ENV"><CODE>%ENV</CODE></A>, the local symbol table is scanned first, followed
by the global symbol table.. The characters following <CODE>CLISYM_</CODE> are
significant when an element of <A HREF="#item_%ENV"><CODE>%ENV</CODE></A> is set or deleted: if the
complete string is <CODE>CLISYM_LOCAL</CODE>, the change is made in the local
symbol table, otherwise the global symbol table is changed.
<P></P>
<DT><STRONG><A NAME="item_Any_other_string">Any other string</A></STRONG><BR>
<DD>
If an element of <EM>PERL_ENV_TABLES</EM> translates to any other string,
that string is used as the name of a logical name table, which is
consulted using <EM>name</EM> as the logical name. The normal search
order of access modes is used.
<P></P></DL>
<P><EM>PERL_ENV_TABLES</EM> is translated once when Perl starts up; any changes
you make while Perl is running do not affect the behavior of <A HREF="#item_%ENV"><CODE>%ENV</CODE></A>.
If <EM>PERL_ENV_TABLES</EM> is not defined, then Perl defaults to consulting
first the logical name tables specified by <EM>LNM$FILE_DEV</EM>, and then
the CRTL <CODE>environ</CODE> array.</P>
<P>In all operations on %ENV, the key string is treated as if it
were entirely uppercase, regardless of the case actually
specified in the Perl expression.</P>
<P>When an element of <A HREF="#item_%ENV"><CODE>%ENV</CODE></A> is read, the locations to which
<EM>PERL_ENV_TABLES</EM> points are checked in order, and the value
obtained from the first successful lookup is returned. If the
name of the <A HREF="#item_%ENV"><CODE>%ENV</CODE></A> element contains a semi-colon, it and
any characters after it are removed. These are ignored when
the CRTL <CODE>environ</CODE> array or a CLI symbol table is consulted.
However, the name is looked up in a logical name table, the
suffix after the semi-colon is treated as the translation index
to be used for the lookup. This lets you look up successive values
for search list logical names. For instance, if you say</P>
<PRE>
$ Define STORY once,upon,a,time,there,was
$ perl -e "for ($i = 0; $i <= 6; $i++) " -
_$ -e "{ print $ENV{'story;'.$i},' '}"</PRE>
<P>Perl will print <CODE>ONCE UPON A TIME THERE WAS</CODE>, assuming, of course,
that <EM>PERL_ENV_TABLES</EM> is set up so that the logical name <CODE>story</CODE>
is found, rather than a CLI symbol or CRTL <CODE>environ</CODE> element with
the same name.</P>
<P>When an element of <A HREF="#item_%ENV"><CODE>%ENV</CODE></A> is set to a defined string, the
corresponding definition is made in the location to which the
first translation of <EM>PERL_ENV_TABLES</EM> points. If this causes a
logical name to be created, it is defined in supervisor mode.
(The same is done if an existing logical name was defined in
executive or kernel mode; an existing user or supervisor mode
logical name is reset to the new value.) If the value is an empty
string, the logical name's translation is defined as a single NUL
(ASCII 00) character, since a logical name cannot translate to a
zero-length string. (This restriction does not apply to CLI symbols
or CRTL <CODE>environ</CODE> values; they are set to the empty string.)
An element of the CRTL <CODE>environ</CODE> array can be set only if your
copy of Perl knows about the CRTL's <CODE>setenv()</CODE> function. (This is
present only in some versions of the DECCRTL; check <CODE>$Config{d_setenv}</CODE>
to see whether your copy of Perl was built with a CRTL that has this
function.)
</P>
<PRE>
When an element of C<%ENV> is set to C<undef>,
the element is looked up as if it were being read, and if it is
found, it is deleted. (An item "deleted" from the CRTL C<environ>
array is set to the empty string; this can only be done if your
copy of Perl knows about the CRTL C<setenv()> function.) Using
C<delete> to remove an element from C<%ENV> has a similar effect,
but after the element is deleted, another attempt is made to
look up the element, so an inner-mode logical name or a name in
another location will replace the logical name just deleted.
In either case, only the first value found searching PERL_ENV_TABLES
is altered. It is not possible at present to define a search list
logical name via %ENV.</PRE>
<P>The element <CODE>$ENV{DEFAULT}</CODE> is special: when read, it returns
Perl's current default device and directory, and when set, it
resets them, regardless of the definition of <EM>PERL_ENV_TABLES</EM>.
It cannot be cleared or deleted; attempts to do so are silently
ignored.</P>
<P>Note that if you want to pass on any elements of the
C-local environ array to a subprocess which isn't
started by fork/exec, or isn't running a C program, you
can ``promote'' them to logical names in the current
process, which will then be inherited by all subprocesses,
by saying</P>
<PRE>
foreach my $key (qw[C-local keys you want promoted]) {
my $temp = $ENV{$key}; # read from C-local array
$ENV{$key} = $temp; # and define as logical name
}</PRE>
<P>(You can't just say <CODE>$ENV{$key} = $ENV{$key}</CODE>, since the
Perl optimizer is smart enough to elide the expression.)</P>
<P>At present, the first time you iterate over %ENV using
<A HREF="../../lib/Pod/perlfunc.html#item_keys"><CODE>keys</CODE></A>, or <A HREF="../../lib/Pod/perlfunc.html#item_values"><CODE>values</CODE></A>, you will incur a time penalty as all
logical names are read, in order to fully populate %ENV.
Subsequent iterations will not reread logical names, so they
won't be as slow, but they also won't reflect any changes
to logical name tables caused by other programs.</P>
<P>You do need to be careful with the logicals representing process-permanent
files, such as <CODE>SYS$INPUT</CODE> and <CODE>SYS$OUTPUT</CODE>. The translations for these
logicals are prepended with a two-byte binary value (0x1B 0x00) that needs to be
stripped off if you want to use it. (In previous versions of perl it wasn't
possible to get the values of these logicals, as the null byte acted as an
