OpenVMS RTL Library (LIB$) Manual

Document revision date: 19 July 1999

OpenVMS RTL Library (LIB$) Manual

Contents

Index

Any condition value returned by LIB$SCOPY_DXDX.

LIB$CALLG

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.

Format

LIB$CALLG argument-list ,user-procedure

RETURNS

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.

Arguments

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.

Description

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.

Condition Values Returned

None.

LIB$CALLG_64 (Alpha Only)

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.

Format

LIB$CALLG_64 argument-list ,user-procedure

RETURNS

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.

Arguments

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.

Description

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.

Condition Values Returned

None.

LIB$CHAR

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.

Format

LIB$CHAR one-character-string ,ascii-code

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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.

Description

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.

Condition Values Returned

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.

LIB$COMPARE_NODENAME

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.

Format

LIB$COMPARE_NODENAME nodename1 ,nodename2 ,comparison-result

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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.

Description

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.

comparison-result Value	Meaning
0	Node names are equal.
1	Node names are not equal.

Condition Values Returned

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.

LIB$COMPRESS_NODENAME

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.

Format

LIB$COMPRESS_NODENAME nodename ,compressed-nodename [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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.

Description

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.

Condition Values Returned

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.

LIB$CONVERT_DATE_STRING

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.

Format

LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

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.

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

Description

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

privacy and legal statement

5932PRO_003.HTML

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

OpenVMS usage:	arg_list
type:	unspecified
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

OpenVMS usage:	quadword_unsigned
type:	quadword (unsigned)
access:	write only
mechanism:	by value

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

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

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

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.

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.

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

OpenVMS usage:	time_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

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

OpenVMS usage:	vector_word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference, array reference