OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$GET_FULLNAME_OFFSET

The Get the Offset to the Starting Position of the Most Significant Part of a Full Name routine returns the offset to the starting position of the most significant part of a full name.+ The most significant part of a full name is determined by the underlying network services.

Format

LIB$GET_FULLNAME_OFFSET fullname, offset

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

fullname

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Full name. The fullname argument contains the address of the descriptor pointing to this full name string.
The error LIB$_INVARG is returned if fullname contains an invalid full name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if fullname is an invalid descriptor.
offset

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

The offset in bytes of the starting position of the most significant part of fullname. The offset argument is the address of an unsigned word that contains this offset.
The offset argument contains an unusable result when LIB$GET_FULLNAME_OFFSET returns in error.

Description

This routine returns the byte offset of the starting position of the most significant part of the input full name. The returned offset can be used to position the display of a full name in a fixed-size output region, for example, scroll regions in DECwindows applications. The most significant part of a full name is determined by the underlying network services.
You must validate fullname by expanding it with LIB$EXPAND_NO DENAME before calling LIB$GET_FULLNAME_OFFSET. LIB$GET_FULLNAME_OFFSET returns the error LIB$_INVARG if fullname is invalid.
In a DECnet for OpenVMS environment, processing a DECnet-Plus for OpenVMS full name using LIB$GET_FULLNAME_OFFSET results in the error condition LIB$_INVARG.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_INVARG Invalid argument:

fullname is invalid.
fullname points to a null string.
The length of the full name is more than 1024 characters.
Processing a DECnet-Plus for OpenVMS node name in a DECnet for OpenVMS environment is invalid.

LIB$_INVSTRDES Invalid string descriptor.

LIB$_WRONUMARG Wrong number of arguments.

Any condition value returned by the $IPC DECnet service.

Examples

The following table gives some examples of the results of LIB$GET_FULLNAME_OFFSET:

Full Name Offset

NODE 0

DEC:.FOO.NODE 9

Full Name	Offset
NODE	0
DEC:.FOO.NODE	9

Note

+ No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

LIB$GET_HOSTNAME

The Get Host Node Name routine returns the host node name of the local system.

Note
No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$GET_HOSTNAME hostname [,resultant-length] [,flags]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

hostname

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

The host node name. The hostname argument contains the address of a descriptor pointing to the host node name. LIB$GET_HOSTNAME writes the host node-name string into the buffer pointed to by the hostname descriptor.
The error LIB$_INVSTRDES is returned if hostname is an invalid descriptor.
The length field of the hostname descriptor is not updated unless hostname is a dynamic descriptor with a length less than the host node name to be returned. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.
The hostname argument contains an unusable result when LIB$GET_HOSTNAME returns in error.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Length of the host node name. The resultant-length argument is the address of an unsigned word that contains this length in bytes.
The resultant-length argument contains an unusable result when LIB$GET_HOSTNAME returns in error.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

The value LIB$GET_HOSTNAME uses to control the form of the host node name that it returns in the output descriptor hostname. If flags is equal to 0, or if flags is omitted, the host node name returned is in the network usable form. If flags is equal to 1, the host node name returned is in the parsable form.
Unused bits in flags must be 0. Nonzero unused bits result in the error condition LIB$_INVARG.

Description

This routine returns the host node name. The routine searches for the first host node name using the following order:

Get host node name from $GETSYI system service.
Translate the executive mode logical SYS$NODE_FULLNAME once.
Translate the executive mode logical SYS$NODE once.

The error LIB$_NOHOSNAM is returned if no host node name is found.
LIB$GET_HOSTNAME can return the host node name in the following two forms:

Network usable form --- The form that can be passed directly to the network. This form does not contain unnecessary double quotation marks (double quotation marks ["] that are not part of the node name) and also does not contain trailing double colons, for example: DEC:.FOO."simple name with spaces" .
Parsable form --- The form that can be passed directly to the part of the system that does node-name syntax parsing, for example, $FILESCAN and DCL command parsing. This form contains trailing double colons and is fully quoted if there are special characters. Individual double quotation marks (") that are part of a simple name are doubled (""), for example: "DEC:.FOO.""simple name with spaces""":: .
You must use double quotation marks for a node name with special characters to facilitate correct parsing.

If the returned node name overflows the buffer pointed to by hostname, the host node name is truncated at the end, and the alternate success status LIB$_STRTRU is returned.
The resultant-length argument, if supplied, is set to the length of the node-name string copied to the output buffer pointed to by hostname.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_STRTRU Routine successfully completed. Characters are truncated in the output buffer pointed to by hostname.

LIB$_INVARG Invalid input argument. Unused bits in flags are not set to 0.

LIB$_INVSTRDES Invalid string descriptor.

LIB$_WRONUMARG Wrong number of arguments.

LIB$_NOHOSNAM No host node name found.

Any condition value returned by LIB$SCOPY_R_DX, or the $FILESCAN system service.

LIB$GET_INPUT

The Get Line from SYS$INPUT routine gets one record of ASCII text from the current controlling input device, specified by SYS$INPUT.

Format

LIB$GET_INPUT resultant-string [,prompt-string] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String that LIB$GET_INPUT gets from the input device. The resultant-string argument is the address of a descriptor pointing to the character string into which LIB$GET_INPUT writes the text received from the current input device.
prompt-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Prompt message that is displayed on the controlling terminal. The prompt-string argument is the address of a descriptor containing the prompt. Any string can be a valid prompt. By convention however, a prompt consists of text followed by a colon (:), a space, and no carriage-return/line-feed combination. The maximum size of the prompt message is 255 characters. If the controlling input device is not a terminal, this argument is ignored.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Number of bytes written into resultant-string by LIB$GET_INPUT, not counting padding in the case of a fixed string. The resultant-length argument is the address of an unsigned word containing this number. If the input string is truncated to the size specified in the resultant-string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of resultant-string.

Description

LIB$GET_INPUT uses the OpenVMS RMS $GET service to get one record of ASCII text from the current controlling input device, specified by SYS$INPUT. (For more information about the RMS $GET service, see the OpenVMS Record Management Services Reference Manual.)
When you log in, the OpenVMS operating system creates three files as default I/O control streams for your process.

SYS$INPUT, your default input device
SYS$OUTPUT, your default output device
SYS$COMMAND, the device that supplies the commands to your process

These files remain open until you log out. They are the interface between your interactive input and output or your batch commands and the OpenVMS software. Initially, all three names are equated with the terminal. However, with the DCL command ASSIGN, you can change these assignments to obtain information from a file or put information into a file. SYS$INPUT and SYS$COMMAND are usually identical, but the input and command streams can be different. For example, during the execution of an indirect command file from an interactive terminal, SYS$COMMAND refers to the terminal and SYS$INPUT refers to the command file.
LIB$GET_INPUT opens file SYS$INPUT on the first call. The RMS internal stream identifier (ISI) is stored in the routine's static storage for subsequent calls.
If prompt-string is provided and the SYS$INPUT device is a terminal, LIB$GET_INPUT displays the prompt message. If the device is not a terminal, the prompt-string argument is ignored.
If you want to get input from some source other than the current input stream, use LIB$GET_COMMAND.

Condition Values Returned

SS$_NORMAL Routine successfully completed. RMS completion status.

LIB$_FATERRLIB An internal consistency check on Run-Time Library data structures has failed. This may indicate a programming error in the Run-Time Library, or that your program may have overwritten those data structures.

LIB$_INPSTRTRU The input string has been truncated to the size specified in the resultant-string descriptor (fixed-length strings only). The resultant-length argument is also set to this size. This is an error (as opposed to LIB$_STRTRU, which is a success) because the truncation is not under program control.

LIB$_INSVIRMEM Insufficient virtual memory to allocate the dynamic string.

LIB$_INVARG Invalid arguments. The descriptor class field is not a recognized code or is zero.

Any RMS condition value returned by $GET.

Any condition value returned by LIB$GET_VM, LIB$GET_VM_64, LIB$SCOPY_R_DX, or LIB$SCOPY_R_DX_64.

LIB$GET_INVO_CONTEXT (Alpha Only)

The Get Invocation Context routine gets the invocation context of any active procedure.

Format

LIB$GET_INVO_CONTEXT invo_handle, invo_context

RETURNS

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by value

A value of 1 indicates success; a value of 0 indicates failure.

Arguments

invo_handle

OpenVMS usage: invo_handle

type: longword (unsigned)

access: read only

mechanism: by value

Handle for the desired invocation. Returned by LIB$GET_INVO_HANDLE.
invo_context

OpenVMS usage: invo_context_blk

type: structure

access: write only

mechanism: by reference

Address of an invocation context block into which the procedure context of the frame specified by invo_handle will be written.

Description

LIB$GET_INVO_CONTEXT gets the invocation context of any active procedure.

Note
If invo-handle does not represent any procedure context in the active call chain, the new contents of the invocation context block are unpredictable.

See the OpenVMS Calling Standard manual for additional information.

Condition Values Returned

None.

LIB$GET_INVO_HANDLE (Alpha Only)

The Get Invocation Handle routine gets an invocation handle of any active procedure.
A thread can obtain an invocation handle corresponding to any invocation context block by using the following function format.

Format

LIB$GET_INVO_HANDLE invo_context

RETURNS

OpenVMS usage: invo_handle

type: longword (unsigned)

access: write only

mechanism: by value

Invocation handle of the invocation context that was passed. If the returned value is LIB$K_INVO_HANDLE_NULL, the invocation context that was passed was invalid.

Argument

invo_context

OpenVMS usage: invo_context_blk

type: structure

access: read only

mechanism: by reference

Address of an invocation context block. Here, only the frame pointer and stack pointer fields of an invocation context block must be defined.

Description

LIB$GET_INVO_HANDLE gets an invocation handle of any active procedure.
See the OpenVMS Calling Standard manual for additional information.

Condition Values Returned

None.

LIB$GET_LOGICAL

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]

RETURNS

OpenVMS usage: cond_value

type: longword

access: write only

mechanism: by value

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_BLIND If set, LIB$GET_LOGICAL does not distinguish between uppercase and lowercase letters in the logical name to be translated.

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

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

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.

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.

Contents

Index

privacy and legal statement

5932PRO_024.HTML

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

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

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

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument: fullname is invalid. fullname points to a null string. The length of the full name is more than 1024 characters. Processing a DECnet-Plus for OpenVMS node name in a DECnet for OpenVMS environment is invalid.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.

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

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Routine successfully completed. Characters are truncated in the output buffer pointed to by hostname.
LIB$_INVARG	Invalid input argument. Unused bits in flags are not set to 0.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.
LIB$_NOHOSNAM	No host node name found.

SS$_NORMAL	Routine successfully completed. RMS completion status.
LIB$_FATERRLIB	An internal consistency check on Run-Time Library data structures has failed. This may indicate a programming error in the Run-Time Library, or that your program may have overwritten those data structures.
LIB$_INPSTRTRU	The input string has been truncated to the size specified in the resultant-string descriptor (fixed-length strings only). The resultant-length argument is also set to this size. This is an error (as opposed to LIB$_STRTRU, which is a success) because the truncation is not under program control.
LIB$_INSVIRMEM	Insufficient virtual memory to allocate the dynamic string.
LIB$_INVARG	Invalid arguments. The descriptor class field is not a recognized code or is zero.

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	invo_handle
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	invo_context_blk
type:	structure
access:	write only
mechanism:	by reference

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

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

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.