HP OpenVMS RTL Library (LIB$) Manual
LIB$BUILD_NODESPEC
The Build a Node-Name Specification routine builds a node-name
specification from the primary node name. The output node-name
specification can be used for other node-name parsing operations.
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$BUILD_NODESPEC primary-nodename, nodespec [,acs]
[,secondary-nodename] [,nodespec-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
primary-nodename
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Primary node name. The primary-nodename argument
contains the address of a descriptor pointing to this node-name string.
The primary node name should not contain unnecessary quotation marks
(that is, quotation marks (" ") that are not part of a simple
name within the node name).
The error LIB$_INVARG is returned if primary-nodename
points to a null string. The error LIB$_INVSTRDES is returned if
primary-nodename is an invalid descriptor.
nodespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Node-name specification. The nodespec argument
contains the address of a descriptor pointing to this output node-name
specification string. LIB$BUILD_NODESPEC writes the output node-name
specification into the buffer pointed to by the
nodespec descriptor.
The error LIB$_INVSTRDES is returned if nodespec is an
invalid descriptor.
The length field of the nodespec descriptor is not
updated unless nodespec is a dynamic descriptor with a
length less than the resultant node-name specification. Refer to the
OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.
The nodespec argument contains an unusable result when
LIB$BUILD_NODESPEC returns in error.
acs
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Access control string. The acs argument contains the
address of a descriptor pointing to this access control string. The
access control string must be a quoted string.
The error LIB$_INVSTRDES is returned if acs is an
invalid descriptor.
secondary-nodename
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Secondary node name. The secondary-nodename argument
contains the address of a descriptor pointing to this secondary
node-name string.
The error LIB$_INVSTRDES is returned if
secondary-nodename is an invalid descriptor.
nodespec-length
| OpenVMS usage: |
unsigned_word |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the output node-name specification. The
nodespec-length argument is the address of an unsigned
word that contains this length in bytes.
The nodespec-length argument contains an unusable
result when LIB$BUILD_NODESPEC returns in error.
Description
This routine builds the parsable form of a node name as the output
node-name specification from the network usable form. Refer to
LIB$GET_HOSTNAME for the definitions of both the parsable form and the
network usable form.
The network usable form is specified by the argument
primary-nodename. If primary-nodename
contains special characters, it is enclosed in quotation marks ("
") to build the node-name specification. The quotation marks
prevent the special characters from being recognized as terminator
characters and enables correct parsing of the node-name syntax.
If you enclose primary-nodename in quotation marks,
any quotation marks that are part of any simple names within
primary-nodename are doubled (that is, each quotation
mark (") is turned into two quotation marks ("")).
LIB$BUILD_NODESPEC checks if the fully quoted primary node name exceeds
1024 characters. The error condition LIB$_NODTOOLNG is returned if this
is the case.
To form the output node-name specification, the fully quoted primary
node name is concatenated with the access control string (if supplied)
and the double colons and is followed by the secondary node name (if
supplied).
This routine does not validate any of the input arguments to ensure
they can form a syntactically valid node name when they are
concatenated.
If the routine overflows the output buffer pointed to by
nodespec, the output node-name specification is
truncated, and the alternate successful status LIB$_STRTRU is returned.
The nodespec-length argument, if supplied, is always
set to the length of the node-name specification that is written into
the output buffer pointed to by nodespec.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Invalid argument. The
primary-nodename argument points to a null string.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
|
LIB$_NODTOOLNG
|
The primary node name after quoting exceeds 1024 characters.
|
|
LIB$_STRTRU
|
Routine successfully completed. Characters are truncated in the output
buffer pointed to by the
nodespec argument.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
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 and I64 systems, OpenVMS Alpha and I64 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 and I64 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 HP 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.
|
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 environment, compressing a DECnet-Plus 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.
|
