VMS Help RTL Routines, LIB$, LIB$GET_LOGICAL  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The Get Logical Name routine calls the system service routine
    $TRNLNM to return information about a logical name.

    Format

      LIB$GET_LOGICAL  logical-name [,resultant-string]

                       [,resultant-length] [,table-name]

                       [,max-index] [,index] [,acmode] [,flags]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword
    access:       write only
    mechanism:    by value

2 - Arguments

 logical-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Logical name for which LIB$GET_LOGICAL searches. The logical-name
    argument is the address of a descriptor pointing to the logical
    name string.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Logical name equivalent returned. The resultant-string argument
    is the address of a descriptor pointing to a character string
    into which LIB$GET_LOGICAL writes the equivalence name of the
    logical.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the equivalence name string returned by LIB$GET_
    LOGICAL. The resultant-length argument is the address of an
    unsigned word integer into which LIB$GET_LOGICAL writes the
    length.

 table-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Name of the table in which to search for the logical name. The
    table-name argument contains the address of a descriptor pointing
    to a character string which contains the table name. If no table
    is specified, LNM$FILE_DEV is used.

 max-index

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Largest equivalence name index. Each equivalence name for the
    logical name has an index associated with it. The max-index
    argument is the address of a signed longword integer into which
    LIB$GET_LOGICAL write the value. If no equivalence names (and,
    therefore, no index values) exist, LIB$GET_LOGICAL returns a
    value of -1.

 index

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Equivalence name index value. LIB$GET_LOGICAL will return the
    equivalence name string that has the specified index value. The
    index argument is the address of an unsigned longword integer
    specifying the index value.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Access mode to be used in the translation. The acmode argument
    is the address of a byte specifying the access mode. The $PSLDEF
    macro defines symbolic names for the four access modes.

    When you specify the acmode argument, all names at access modes
    which are less privileged than the specified access mode are
    ignored.

    If you do not specify acmode, the translation is performed
    without regard to access mode; however, the translation process
    proceeds from the outermost to the innermost access modes. Thus,
    if two logical names with the same name, but at different access
    modes, exist in the same table, the name with the outermost
    access mode is translated.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Flags controlling the search for the logical name. The flags
    argument is the address of a longword integer that contains the
    control flags. The $LNMDEF macro defines these flags. Currently
    only bit 0 of this argument is used.

    Bit  Value           Description

    0    LNM$M_CASE_     If set, LIB$GET_LOGICAL does not distinguish
         BLIND           between uppercase and lowercase letters in
                         the logical name to be translated.

    This is an optional argument. If omitted the default is 0.

3 - Description

    LIB$GET_LOGICAL provides a simplified interface to the $TRNLNM
    system service. It provides most of the features found in $TRNLNM
    with some additional benefits. For string arguments, all string
    classes supported by the Run-Time Library are understood. The
    list of item descriptors, which may be difficult to construct in
    high-level languages, is handled internally by LIB$GET_LOGICAL.

    See the description of the $TRNLNM system service in the OpenVMS
    System Services Reference Manual for more information.

4 - Condition Values Returned

    SS$_NORMAL         Routine successfully completed.
    SS$_ACCVIO         Access violation. Cannot access the location
                       specified.
    SS$_BADPARAM       Bad parameter value.
    SS$_IVLOGNAM       Invalid logical name. The logical name or its
                       value contained more than 255 characters.
    SS$_IVLOGTAB       Invalid logical name table.
    SS$_NOLOGNAM       The logical name was not found in the
                       specified table.
    SS$_NOPRIV         No privileges for attempted operation.
    SS$_TOOMANYNAM     Logical name translation exceeded allowed
                       depth.
    LIB$_INVARG        Required argument is missing.
    LIB$_INSVIRMEM     Insufficient virtual memory.
    LIB$_INVSTRDES     Invalid string descriptor.
    LIB$_STRTRU        Success, but source string truncated.
    LIB$_WRONUMARG     Wrong number of arguments.