![[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 |
Any condition value returned by LIB$SCOPY_DXDX.
The Call Routine with General Argument List routine calls a routine with an argument list specified as an array of longwords, the first of which is a count of the remaining longwords. LIB$CALLG is a callable version of the VAX CALLG instruction.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.
LIB$CALLG argument-list ,user-procedure
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
Return value, if any, of the called routine, unchanged by LIB$CALLG.
argument-list
OpenVMS usage: arg_list type: unspecified access: read only mechanism: by reference, array reference
Argument list to be passed to user-procedure. The argument-list argument is the address of an array of longwords that is the argument list. The first longword contains the count of the remaining longwords, to a maximum of 255.user-procedure
OpenVMS usage: procedure type: procedure value access: function call (before return) mechanism: by value
Routine that LIB$CALLG calls with the specified argument list.
LIB$CALLG is used to call routines that accept variable-length argument lists when the number of arguments to be passed is not known until execution time. LIB$CALLG is also used to call such routines from strongly typed languages, which require routines to be declared as having a fixed number of arguments.
None.
The Call Routine with General Argument List routine calls a routine with an argument list specified as an array of quadwords, the first of which is a count of the remaining quadwords.
LIB$CALLG_64 argument-list ,user-procedure
OpenVMS usage: quadword_unsigned type: quadword (unsigned) access: write only mechanism: by value
Return value, if any, of the called routine, unchanged by LIB$CALLG_64.
argument-list
OpenVMS usage: arg_list type: unspecified access: read only mechanism: by reference, array reference
Argument list to be passed to user-procedure. The argument-list argument is the address of an array of quadwords that is the argument list. The first quadword contains the count of the remaining quadwords, to a maximum of 255.user-procedure
OpenVMS usage: procedure type: procedure value access: function call (before return) mechanism: by value
Routine that LIB$CALLG_64 calls with the specified argument list.
LIB$CALLG_64 is useful for calling routines that accept variable-length argument lists when the number of arguments to be passed is not known until execution time. LIB$CALLG_64 can also be used to call such routines from strongly typed languages, which require routines to be declared as having a fixed number of arguments.
None.
The Transform Byte to First Character of String routine transforms a single 8-bit ASCII character to an ASCII string consisting of a single character followed by trailing spaces, if needed, to fill out the string. The range of the input byte is 0 through 255.
LIB$CHAR one-character-string ,ascii-code
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
one-character-string
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
ASCII character string consisting of a single character followed by trailing spaces, if needed, that LIB$CHAR creates when it transforms the ASCII character code. The one-character-string argument is the address of a descriptor pointing to the character string that LIB$CHAR writes.ascii-code
OpenVMS usage: byte_unsigned type: byte (unsigned) access: read only mechanism: by reference
Single 8-bit ASCII character code that LIB$CHAR transforms to an ASCII string. The ascii-code argument is the address of an unsigned byte containing the ASCII character code.
LIB$CHAR is the inverse of LIB$ICHAR. (See the description of LIB$ICHAR.) LIB$CHAR is not a binary-to-ASCII conversion routine. LIB$CHAR merely interprets ascii-code as an ASCII character code and converts it to a string.
SS$_NORMAL Routine successfully completed. LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Digital support representative. LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory. LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field. LIB$_STRTRU Routine successfully completed, but the string was truncated. The destination string could not contain all of the characters.
The Compare Two Node Names routine compares two node names to see if they resolve to the same full name.
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$COMPARE_NODENAME nodename1 ,nodename2 ,comparison-result
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
nodename1
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
First node name to be compared. The nodename1 argument contains the address of a descriptor pointing to this node-name string.The error LIB$_INVARG is returned if nodename1 contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename1 is an invalid descriptor.
nodename2
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Second node name to be compared. The nodename2 argument contains the address of a descriptor pointing to this node-name string.The error LIB$_INVARG is returned if nodename2 contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename2 is an invalid descriptor.
comparison-result
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
Result of the comparison. The comparison-result argument is the address of an unsigned longword that contains the comparison result. If the two node names are equal, 0 is returned. If they are not equal, 1 is returned.Comparison-result contains an unusable result when LIB$COMPARE_NODENAME returns in error.
This routine compares two node names and checks to see if they resolve to the same full name. The two node names are first expanded using LIB$EXPAND_NODENAME. Any errors that result from expanding the input node names are propagated and returned as condition values. A string comparison is performed on the expanded node names to check if they resolve to the same full name. The result of the comparison is returned in comparison-result as follows:
comparison-result Value Meaning 0 Node names are equal. 1 Node names are not equal.
SS$_NORMAL Routine successfully completed. LIB$_INVARG Invalid argument:
- nodename1 or nodename2 is an invalid node name.
- nodename1 or nodename2 points to a null string.
- The length of the node name is more than 1024 characters.
- The expanded DECnet-Plus for OpenVMS node name is invalid in a DECnet for OpenVMS environment.
LIB$_INVSTRDES Invalid string descriptor. LIB$_WRONUMARG Wrong number of arguments.
Any condition value returned by RTL routine LIB$SCOPY_R_DX or by the $IPC DECnet service.
The Compress a Node Name to Its Short Form Equivalence routine compresses a node name to an unambiguous short form usable within the naming environment where the compression is performed.
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$COMPRESS_NODENAME nodename ,compressed-nodename [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
nodename
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Node name to be compressed. The nodename argument contains the address of a descriptor pointing to this node-name string.The error LIB$_INVARG is returned if nodename contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if the nodename descriptor is invalid.
compressed-nodename
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Compressed node name. The compressed-nodename argument contains the address of a descriptor pointing to the compressed node-name string. LIB$COMPRESS_NODENAME writes the compressed node name into the buffer pointed to by compressed-nodename.The error LIB$_INVSTRDES is returned if compressed-nodename is an invalid descriptor.
The length field of the compressed-nodename descriptor is not updated unless compressed-nodename is a dynamic descriptor with a length less than the resulting compressed node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.
The compressed-nodename argument contains an unusable result when LIB$COMPRESS_NODENAME returns in error.
resultant-length
OpenVMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference
Length of the compressed 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$COMPRESS_NODENAME returns in error.
This routine compresses a given node name to a short form that is usable within the local naming environment in which the compression is performed. The local naming environment is defined by the underlying network directory services. Be careful when using the compressed node name for making network connections. Using the compressed node name outside the intended local naming environment may result in an ambiguous reference. Use the full name whenever you need to eliminate ambiguity.The nodename argument is validated against the supported form of node names. The error LIB$_INVARG is returned if the input node name is invalid.
When calling LIB$COMPRESS_NODENAME in a DECnet-Plus for OpenVMS environment, the underlying network layer verifies the existence of the input node name. If the input node name does not resolve to an existing node name in the naming environment, an error condition is returned by the underlying network layer and propagated back to the caller of LIB$COMPRESS_NODENAME.
If the returned compressed node name overflows the buffer pointed to by compressed-nodename, the compressed node name is truncated, and the alternate successful status LIB$_STRTRU is returned.
The actual length of the compressed node name written to the output buffer compressed-nodename is returned in resultant-length if this argument is supplied.
In a DECnet for OpenVMS environment, compressing a DECnet-Plus for OpenVMS node name results in the error condition LIB$_INVARG.
SS$_NORMAL Routine successfully completed. LIB$_STRTRU Routine successfully completed. Characters are truncated in the output buffer pointed to by compressed-nodename. LIB$_INVARG Invalid argument:
- nodename is invalid.
- nodename points to a null string.
- The length of the node name is more than 1024 characters.
- The compressed DECnet-Plus for OpenVMS node name is invalid in a DECnet for OpenVMS environment.
LIB$_INVSTRDES Invalid string descriptor. LIB$_WRONUMARG Wrong number of arguments.
Any condition value returned by RTL routine LIB$SCOPY_R_DX or by the $IPC DECnet service.
The Convert Date String to Quadword routine converts an absolute date string into an OpenVMS internal format date-time quadword. That is, given an input date/time string of a specified format, LIB$CONVERT_DATE_STRING converts this string to an OpenVMS internal format time.
LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
date-string
OpenVMS usage: time_name type: character-coded text string access: read only mechanism: by descriptor
Date string that specifies the absolute time to be converted to an internal system time. The date-string argument is the address of a descriptor pointing to this date string. This string must have a format corresponding to the currently defined input format, or it must be one of the relative day strings YESTERDAY, TODAY, or TOMORROW, or their equivalents in the currently selected language.date-time
OpenVMS usage: date_time type: quadword (unsigned) access: write only mechanism: by reference
Receives the converted time. The date-time argument is the address of an unsigned quadword that contains this OpenVMS internal format converted time.user-context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Context variable that receives the translation context from a call to LIB$INIT_DATE_TIME_CONTEXT and then retains the translation context over multiple calls to LIB$CONVERT_DATE_STRING. The user-context argument is the address of an unsigned longword that contains this context. The user program should not write directly to this variable once it is initialized.The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$CONVERT_DATE_STRING may abort if two threads of execution attempt to manipulate the context area concurrently. Therefore, when calling this routine in situations where reentrancy might occur, such as from AST level, Digital recommends that users specify a different context cell for each calling thread.
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by reference
Specifies which date or time fields of the date-string argument might be omitted so that default values are applied. The flags argument is the address of a longword bit mask that contains these flags. A set bit indicates that the field may be omitted. The bit definitions for the mask correspond to the fields in a $NUMTIM "timbuf" structure as follows:
Field Bit Number Mask Year 0 01 Month 1 02 Day of month 2 04 Hours 3 08 Minutes 4 16 Seconds 5 32 Fractional seconds 6 64 Bits 7 through 31 must be zero and are reserved for use by Compaq. If this parameter is omitted, a default value of 120 (78H) is used, indicating that the time fields may be defaulted but the date fields may not.
defaults
OpenVMS usage: vector_word_unsigned type: word (unsigned) access: read only mechanism: by reference, array reference
Supplies the defaults to be used for omitted fields. The defaults argument is the address of an array of unsigned words containing these default values. This array corresponds to a 7-word $NUMTIM "timbuf" structure. If the defaults argument is omitted, the following defaults are applied:
- For the date group, the default is the current date.
- For the time group, the default is 00:00:00.00.
defaulted-fields
OpenVMS usage: mask_longword type: longword (unsigned) access: write only mechanism: by reference
Indicates which date or time fields have been defaulted. The defaulted-fields argument is the address of a longword bit mask that specifies these fields. The bit definitions are identical to those of the flags bit mask. A set bit indicates that the field was defaulted. Bits 7 through 31, which are reserved for use by Compaq, are zeroed.
LIB$CONVERT_DATE_STRING converts an absolute date string into an OpenVMS internal format date-time quadword. The input date string can either correspond to the format specified, or it can be the language equivalent of one of the relative date strings YESTERDAY, TODAY, or TOMORROW. The language to be used and the format in which to interpret the information are programmable using either of the following methods:
- The language and format are programmable at compile time through the use of the routine LIB$INIT_DATE_TIME_CONTEXT.
- The language and format can be determined at run time through the translation of the logical names SYS$LANGUAGE and LIB$DT_INPUT_FORMAT.
In general, if an application is reading text from internal storage, the language and input format should be specified at compile time. If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and input format of your choice.
If an application is accepting text from a user, the logical name method of specifying language and format should be used. In this method, the user assigns equivalence names to the logical names SYS$LANGUAGE and LIB$DT_INPUT_FORMAT, thereby selecting the language and input format of the date and time at run time.
The calling program can choose to apply defaults for omitted fields in the date string. To do this, the flags argument is used to indicate which fields are to be defaulted, and the defaults argument is used to supply the default values. If the defaults argument is not supplied, the following default values are applied:
- For the date group, the default is the current date.
- For the time group, the default is 00:00:00.00.
Previous Next Contents Index
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)
Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal5932PRO_003.HTML