|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs] [,secondary-nodename] [,nodespec-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
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 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.
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 environment, compressing a DECnet-Plus 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.
| Previous | Next | Contents | Index |