NAME

VMS::Logical - OpenVMS Logical name interface

SYNOPSIS

  use VMS::Logical qw(:all);

  $hashref = translate({lognam='sys$sysdevice',
                        case_blind=>1});

  $string = getlogical('sys$login');
  @strings = getlogical('sys$sysroot');

  $table = create_table({table=>'test_table',
			 partab=>'LNM$PROCESS_DIRECTORY'});

  $table = define({lognam=>'TEST_LOGICAL',
                    tabnam=>'LNM$JOB',
                    acmode=>'SUPERVISOR',
                    equiv->[{string=>'equivalence'},
                            {string=>'another'}]});

  $status = deassign({lognam=>'TEST_LOGICAL',
                      tabnam=>'LNM$JOB',
                      acmode=>'SUPERVISOR'});

DESCRIPTION

VMS::Logical provides access to logical names on OpenVMS systems.

translate

Translates a logical name.

$hash = VMS::Logical::translate('logical_name');
$hash = VMS::Logical::translate({option=>value});

The first form can be used for a simple logical name translation using default search options. The second form should be used if additional options are necessary.

If the translation is successful, a hash reference will be returned containing information about the logical name. undef is returned on errors. The VMS error code will be available in $^E.

The options hash may contain the following values.

lognam

The logical name to translate.

case_blind

When set to 1, case will be ignored when searching for the logical name.

interlocked

When set to 1, waits for cluster operations to complete before proceeding.

table

Specifies the name of the table to be searched for the logical name.

acmode

Access mode to use for searching. The value should be one of USER, SUPERVISOR, EXECUTIVE or KERNEL. Any abbrevation of these is accepted. If specified, only logical names at the specified mode or a more privileged mode will be returned.

getlogical

Returns the equivalence string[s] of a logical name.

$string = VMS::Logical::getlogical('logical_name');
@strings = VMS::Logical::getlogical('logical_name');
$string = VMS::Logical::getlogical({option=>value});
@strings = VMS::Logical::getlogical({option=>value});

The getlogical method calls the translate method and returns the equivalence strings. This provides a convenient shorthand if only the strings and not the attributes of the logical name are needed. If called in array context, the equivalence strings are returned as a list. Otherwise, a single string is returned with the equivalences separated by commas.

If a string is passed as the argument, it is accepted as the logical name to translate. The tables described by LNM$FILE_DEV will be searched without regard to case for a translation.

If a hash reference is passed as the argument, it will be passed directly to translate. This gives full control over the translation process.

define

Defines a logical name.

$table = VMS::Logical::define({option=>value});

The name of the table where the logical name was created is returned if the call is successful. On error, undef is returned and the VMS status code is available in $^E.

The options hash may contain the following values.

table

The name of the table to contain the logical name.

lognam

The name of the logical to be defined.

acmode

The access mode of the logical name.

attr

Attributes for the logical name. This is a hashref containing the following options.

CONFINE

Logical will not be copied to subprocesses when spawning.

NO_ALIAS

Don't allow duplicate logical names at outer levels.

equiv

An array of equivalence definitions. Each equivalence is a hashref containing the following items.

attr

Attributes for the equivalence. The following attributes are supported.

CONCEALED

Create a concealed logical.

TERMINAL

The equivalence contains no logical names.

string

The equivalence string.

deassign

Deletes a logical name.

$status = VMS::Logical::deassign({option=>value});

Returns a true value if successful. On error, undef is returned and the VMS error code is available in $^E. The options hash may contain the following values.

table

Name of the table containing the logical.

lognam

The name of the logical to delete.

acmode

The access mode of the logical name.

create_table

Creates a logical name table.

$table = create_table({option=value});

The name of the created table is returned if successful. On error, undef is returned and the VMS error code is available in $^E.

Valid options are as follows.

table

The name of the table to create.

partab

The name of the parent table.

quota

The number of bytes of system space that can be used by the table and logicals defined in it. This only applies to shared tables.

acmode

The access mode of the table.

attr

Attributes of the table.

NO_ALIAS

Don't allow tables to be created with the same name at outer access modes.

CREATE_IF

Only create the table if it doesn't exist with the specified attributes. If this is not specified and the table already exists, the new table will supercede the existing one.

CONFINE

Don't copy the table to subprocesses.

SEE ALSO

'HP OpenVMS Programming Concepts Manual' contains a chapter about logical names and logical name tables.

'HP OpenVMS System Services Reference Manual' provides detailed information about the OpenVMS logical name system services.

AUTHOR

Thomas Pfau, < tfpfau@gmail.com >

COPYRIGHT AND LICENSE

Copyright (C) 2008,2009,2012 by Thomas Pfau

This [library|program|code|module] is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license in the file LICENSE.

This program is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties.b

cpanm VMS::Logical

perl -MCPAN -e shell
install VMS::Logical