![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS RTL Library (LIB$) Manual
| Previous | Contents | Index |
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.
LIB$GET_FULLNAME_OFFSET fullname, offset
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
The following table gives some examples of the results of LIB$GET_FULLNAME_OFFSET:
Full Name Offset NODE 0 DEC:.FOO.NODE 9
+ No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine. |
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.
LIB$GET_HOSTNAME hostname [,resultant-length] [,flags]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
The Get Line from SYS$INPUT routine gets one record of ASCII text from the current controlling input device, specified by SYS$INPUT.
LIB$GET_INPUT resultant-string [,prompt-string] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
The Get Invocation Context routine gets the invocation context of any active procedure.
LIB$GET_INVO_CONTEXT invo_handle, invo_context
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.
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.
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.
None.
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.
LIB$GET_INVO_HANDLE invo_context
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.
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.
LIB$GET_INVO_HANDLE gets an invocation handle of any active procedure.See the OpenVMS Calling Standard manual for additional information.
None.
The Get Logical Name routine calls the system service routine $TRNLNM to return information about a logical name.
LIB$GET_LOGICAL logical-name [,resultant-string] [,resultant-length] [,table-name] [,max-index] [,index] [,acmode] [,flags]
OpenVMS usage: cond_value type: longword access: write only mechanism: by value
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.
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.
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.
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
5932PRO_023.HTML
|