Undocumented OpenVMS: LIB$SYS_TRNLOG

This libary function is kind of a special case. It was documented in former times properly, but then removed from the docset by mistake. Apparently Digital was not able to fix this error up to now, so here you'll find the old documentation, which was provided by Ferry Bolhár.

LIB$SYS_TRNLOG

Searches the logical name tables for a specified logical name and returns an equivalence name string into a user-specified buffer; the search is not iterative. The process, group, and system logical name tables are searched in this order.

This routine is a jacket to the SYS$TRNLOG system service.

Format

LIB$SYS_TRNLOG lognam, [rsllen], rslbuf, [table], [acmode], [dsbmsk]

Returns

VMS Usage	cond_value
type	longword (unsigned)
access	write only
mechanism	by value

Longword condition value. Condition values that can be returned by this routine are listed under 'Condition Values Returned'.

Arguments

lognam

VMS Usage	logical_name
type	character-coded text string
access	read only
mechanism	by descriptor

Name of the logical name to be translated. The 'lognam' argument is the address of a descriptor pointing to the logical name string.

rsllen

VMS Usage	word_unsigned
type	word (unsigned)
access	write only
mechanism	by reference

Length in bytes of the equivalence name to which the logical name translates. The 'rsllen' argument is the address of a word to receive this length.

rslbuf

VMS Usage	char_string
type	character-coded text string
access	write only
mechanism	by descriptor

Buffer into which LIB$SYS_TRNLOG writes the equivalence name. The 'rslbuf' argument is the address of a descriptor pointing to this buffer.

table

VMS Usage	byte_unsigned
type	byte (unsigned)
access	write only
mechanism	by reference

Logical name table in which the equivalence name was found. The 'table' argument is the address of a byte into which LIB$SYS_TRNLOG writes a value. The value 0 means the system logical name table, 1 the group table, and 2 the process table.

acmode

VMS Usage	access_mode
type	byte (unsigned)
access	write only
mechanism	by reference

Access mode associated with the logical name and equivalence name. The 'acmode' argument is the address of a byte into which LIB$SYS_TRNLOG writes this access mode. The $PSLDEF macro defines the symbols for the four access modes. The contents of this byte is meaningful only if the equivalence name was found in the process logical name table (table 2).

dsbmsk

VMS Usage	mask_longword
type	longword (unsigned)
access	read only
mechanism	by reference

Logical name tables that are not to be searched by LIB$SYS_TRNLOG. The 'dsbmsk' argument is a longword bit vector wherein a bit, when set, disables the search of the corresponding logical name table. Bit 0 corresponds to the system logical name table; bit 1 to the group logical name table; and bit 2 to the process logical name table.

If dsbmsk is not specified or is specified as 0 (the default), all three logical name tables are searched. A value greater than 6 is not allowed and will return SS$_BADPARAM.

Note that this argument is specified by value with SYS$TRNLOG, but is specified by reference with this routine.

Description

The LIB$SYS_TRNLOG routine invokes the SYS$TRNLOG system service to translate a logical name and return its equivalence string and string length into user-specified buffers. The logical name table value and the access mode associated with the logical name may be returned as well. By default, all tables are searched; you may restrict the search to a particular table with 'dsbmsk'.

If the first character of a specified logical name is an underscore character (_), no translation is performed. However, the underscore character is removed from the string and the modified string is returned in the output buffer.

Condition values returned

SS$_NORMAL	Routine completed successfully
LIB$_WRONUMARG	Wrong number of arguments
LIB$_STRTRU	Success, but source string truncated
LIB$_INSVIRMEM	Insufficient virtual memory
LIB$_INVSTRDES	Invalid string descriptor

Condition values returned from SYS$TRNLOG

SS$_NOTRAN	Successful, but input logical name string was placed in output buffer because no equivalence name was found.
SS$_ACCVIO	The logical name string or string descriptor cannot be read, or the output length, output buffer, or table or access mode field cannot be written by the caller.
SS$_IVLOGNAM	The specified logical name string has a length of zero or has too many characters.
SS$_BADPARAM	A mask value greather than 6 was specified in the dsbmsk argument.

In VMS versions prior V4, the following restrictions in logical name behaviour exist:

There were no other logical name tables than system, group and process table. There was no job logical name table nor user-created private or shareable name tables. There were no descendant tables.
There were no logical names pointing to logical name tables. Logical name tables were always identified by values:
- 0 = system table
- 1 = group table
- 2 = process table
There were no logical name table directories.
There were no access modes associated with logical names, except for per-process logicals.
There were no multiple equivalence strings (search lists). (LIB$SYS_TRNLOG always returns equivalenve string 0.)
There were no logical name and equivalence string attributes.

Starting with VMS V4, the $CRELOG, $DELLOG and $TRNLOG system services were rewritten as jackets to $CRELNM, $DELLNM and $TRNLNM, respectively (to avoid changes in existing code). The services become obsolete with this VMS version. There is, however, no V4-replacement for LIB$SYS_TRNLOG; this routine is still supported, although its description was removed from the VMS documentation.

(P) 1986 by Ing. Ferry Bolhár (ADVBOL)

Comments to: Martin P.J. Zinser
Last modified: 20020628