OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

Table lib-6 lists the formats used for the string interpretations.

Table lib-6 Item Code Formats for LIB$GETQUI
Item or Format Description

QUI$_AFTER_TIME Returns a quadword resultant-value as well as a resultant-string.

QUI$_CHARACTERISTICS Returns an octaword resultant-value as well as a comma-separated list that lists all the characteristic numbers, output as a resultant-string.

QUI$_SUBMISSION_TIME Returns a quadword resultant-value as well as a resultant-string.

QUI$_UIC Returns a formatted resultant-string as well as a longword.

**Table lib-6 Item Code Formats for LIB$GETQUI**
Item or Format	Description
QUI$_AFTER_TIME	Returns a quadword resultant-value as well as a resultant-string.
QUI$_CHARACTERISTICS	Returns an octaword resultant-value as well as a comma-separated list that lists all the characteristic numbers, output as a resultant-string.
QUI$_SUBMISSION_TIME	Returns a quadword resultant-value as well as a resultant-string.
QUI$_UIC	Returns a formatted resultant-string as well as a longword.

Note

This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_STRTRU String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.

SS$_BADPARAM Unrecognized item code. The item-code argument was not recognized as valid by $GETQUI.

LIB$_INSEF Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.

LIB$_INVARG Invalid arguments. The $GETQUI Item Code describes the item as a "string", and no resultant-string argument was specified.

LIB$_INVSTRDES Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETQUI.

Any condition value returned by LIB$SCOPY_xxx, or the $GETQUI system service.

LIB$GETSYI

The Get Systemwide Information routine provides a simplified interface to the $GETSYI system service. The $GETSYI system service obtains status and identification information about the system. LIB$GETSYI returns only one item of information in a single call.

Format

LIB$GETSYI item-code [,resultant-value] [,resultant-string] [,resultant-length] [,cluster-system-id] [,node-name]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

item-code

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Item code specifying the desired item of information. The item-code argument is the address of a signed longword containing this item code. All valid $GETSYI item codes are accepted.
resultant-value

OpenVMS usage: varying_arg

type: unspecified

access: write only

mechanism: by reference

Numeric value returned by LIB$GETSYI. The resultant-value argument is the address of a longword or quadword containing this value. If an item is listed as returning only a string value, this argument is ignored.
resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Information returned by LIB$GETSYI. The resultant-string argument is the address of a descriptor pointing to the character string that will receive this information.
See the Description section for more information about value formats. If resultant-string is not specified and if the returned value has only a string representation, the error status LIB$_INVARG is returned.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Number of significant characters written to resultant-string, not including blank padding or truncated characters. The resultant-length argument is the address of an unsigned word into which LIB$GETSYI returns this number.
cluster-system-id

OpenVMS usage: identifier

type: longword (unsigned)

access: modify

mechanism: by reference

Cluster system identification (CSID) of the node for which information is to be returned. The cluster-system-id argument is the address of this CSID. If cluster-system-id is specified and is nonzero, node-name is not used. If cluster-system-id is specified as zero, LIB$GETSYI uses node-name and writes into the cluster-system-id argument the CSID corresponding to the node identified by node-name.
The cluster-system-id of an OpenVMS node is assigned by the cluster-connection software and may be obtained by the DCL command SHOW CLUSTER. The value of the cluster-system-id for an OpenVMS node is not permanent; a new value is assigned to an OpenVMS node whenever it joins or rejoins the OpenVMS Cluster.
If cluster-system-id is specified as --1, LIB$GETSYI assumes a wildcard operation and returns the requested information for each OpenVMS node in the cluster, one node per call.
If cluster-system-id is not specified, node-name is used.
node-name

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Name of the node for which information is to be returned. The node-name argument is the address of a descriptor pointing to the node name string. If cluster-system-id is not specified or is specified as zero, node-name is used. If neither node-name nor cluster-system-id is specified, the caller's node is used. See the cluster-system-id argument for more information.
The node name string must contain from 1 to 15 characters and must correspond exactly to the OpenVMS node name; no trailing blanks nor abbreviations are permitted.

Description

LIB$GETSYI provides the following features in addition to those provided by the $GETSYI system service:

Instead of a list of item descriptors, which may be difficult to construct in high-level languages, the single item desired is specified as an integer code which is passed by reference. Results are written to separate arguments.
For items which return numeric values, LIB$GETSYI can optionally provide a formatted string interpretation of the value.
For string arguments, all string classes supported by the Run-Time Library are understood.
Calls to LIB$GETSYI are synchronous. LIB$GETSYI calls LIB$GET_EF to allocate a local event flag number for synchronization.

All item codes that can be used with the $GETSYI system service may be used as the item-code argument to LIB$GETSYI. See the description of the $GETSYI system service for a list of the defined item codes. Note that the symbolic names for these items are defined in Digital supplied symbol libraries in module $SYIDEF (where appropriate).
Value Formats

By using the resultant-value and resultant-string arguments to LIB$GETSYI, you can request that the information be returned in two ways. For each item described as a "string" in the table of Item Codes for the $GETSYI service, the value is returned in resultant-string. For all other items---those which have numeric values---the numeric representation is returned in resultant-value (if specified), and an unsigned decimal integer representation is stored in resultant-string.
Each formatted item is written left-justified; resultant-length, if specified, gives the number of characters used.
See the OpenVMS System Services Reference Manual for a description of the $GETSYI system service.

Note
This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_BADPARAM Unrecognized item code. The item-code argument was not recognized as valid by $GETSYI.

LIB$_INSEF Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.

LIB$_INVARG Invalid arguments. The $GETSYI Item Code describes the item as a "string", and no resultant-string argument was specified.

LIB$_INVSTRDES Invalid string descriptor. The descriptor of the resultant-string argument is not a valid descriptor.

LIB$_STRTRU String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETSYI.

Any condition values returned by LIB$SCOPY_xxx, or the $GETSYI system service.

LIB$GET_ACCNAM

The Get Access Name Table for Protected Object Class (by Name) routine is a simplified interface to the $GET_SECURITY system service, and returns a pointer to the access name table for a protected object class that is specified by name.

Format

LIB$GET_ACCNAM [clsnam] , [objnam] ,accnam

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

clsnam

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

The address of a character-string descriptor pointing to the name of a protected object class. This argument is optional and defaults to FILE.
objnam

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

The address of a character-string descriptor pointing to the name of a protected object. This argument is optional. If it is omitted, the access name table returned is that used for objects of the class specified by the clsnam argument.
accnam

OpenVMS usage: access_names

type: longword (unsigned)

access: write only

mechanism: by reference

The address of a longword into which this routine writes the address of the access name table.

Description

LIB$GET_ACCNAM returns the address of the access name table for the specified protected object. The format of the table is a vector of 32 quadword string descriptors. Each table entry points to the name of an access type. The index into the vector is the bit position in an access-desired mask. Undefined access types have zero-length names. The table can be used as input to the LIB$PARSE_SOGW_PROT, LIB$FORMAT_SOGW_PROT, LIB$PARSE_ACCESS_CODE, $PARSE_ACL, and $FORMAT_ACL routines.
The semantics of this routine are as follows:

If the clsnam parameter is omitted, clsnam defaults to "FILE."
If clsnam is not the name of an object class, then the routine returns an error status (SS$_NOCLASS), and the value of accnam is undefined.
If the objnam parameter is omitted, then accnam points to the table corresponding to clsnam, and the routine returns a success status (SS$_NORMAL). The table returned is the table of access names for a new object of class clsnam.
Otherwise, if clsnam and objnam do in fact name a protected object, then accnam points to the table corresponding to the protected object class, and the routine returns a success status (SS$_NORMAL).
Otherwise, if clsnam and objnam do not name a protected object, then the routine returns an error status (the exact status value depends on the security class), and the value of accnam is undefined.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_NOCLASS No matching object class was found.

LIB$_INVARG The accnam argument was omitted.

LIB$_WRONUMARG Wrong number of arguments.

In addition, any completion status may be returned from $GET_SECURITY.

LIB$GET_ACCNAM_BY_CONTEXT

The Get Access Name Table for Protected Object Class (by Context) routine is a simplified interface to the $GET_SECURITY system service, and returns a pointer to the access name table for a protected object class that is specified by a context longword returned from $GET_SECURITY or $SET_SECURITY.

Format

LIB$GET_ACCNAM_BY_CONTEXT contxt ,accnam

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

contxt

OpenVMS usage: context

type: longword (unsigned)

access: read only

mechanism: by reference

The address of a nonzero longword context value returned by $GET_SECURITY or $SET_SECURITY.
accnam

OpenVMS usage: access_names

type: longword (unsigned)

access: write only

mechanism: by reference

The address of a longword into which this routine writes the address of the access name table.

Description

LIB$GET_ACCNAM_BY_CONTEXT returns the address of the access name table for the specified protected object class. The format of the table is a vector of 32 quadword string descriptors. Each table entry points to the name of an access type. The index into the vector is the bit position in an access-desired mask. Undefined access types have zero-length names. The table can be used as input to the LIB$PARSE_SOGW_PROT, LIB$FORMAT_SOGW_PROT, LIB$PARSE_ACCESS_CODE, $PARSE_ACL, and $FORMAT_ACL routines.
The semantics of this routine are as follows:

If the contxt argument is valid, then the accnam argument points to the table corresponding to the protected object class, and the routine returns a success status (SS$_NORMAL).
If the contxt argument is not valid, then the routine returns an error status, and the value of accnam is undefined.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_WRONUMARG Wrong number of arguments.

In addition, error status may be returned from $GET_SECURITY.

LIB$GET_COMMAND

The Get Line from SYS$COMMAND routine gets one record of ASCII text from the current controlling input device, specified by the logical name SYS$COMMAND.

Format

LIB$GET_COMMAND resultant-string [,prompt-string] [,resultant-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String that LIB$GET_COMMAND gets from SYS$COMMAND. The resultant-string argument is the address of a descriptor pointing to this string.
prompt-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Prompt message that LIB$GET_COMMAND displays on the controlling terminal. The prompt-string argument is the address of a descriptor pointing to the prompt. Any string can be a valid prompt. By convention however, a prompt string 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_COMMAND, not counting padding in the case of a fixed string. The resultant-length argument is the address of an unsigned word containing this length. 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.

Description

LIB$GET_COMMAND uses the OpenVMS RMS $GET service (see the OpenVMS Record Management Services Reference Manual) to get one record of ASCII text from the current controlling input device, specified by SYS$COMMAND.
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 files 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_COMMAND opens file SYS$COMMAND on the first call. The RMS internal stream identifier (ISI) is stored in the routine's static storage for subsequent calls. Hence, this routine is not AST reentrant.
If prompt-string is provided and if the SYS$COMMAND device is a terminal, LIB$GET_COMMAND displays the prompt message. If the device is not a terminal, the prompt-string is ignored.
LIB$GET_COMMAND is used when a program needs input from some source other than the current input stream. Usually, it is used to input from the terminal rather than from an indirect command file. For example, a program may ask a question which cannot be answered by an indirect command file entry. In this case the program would call LIB$GET_COMMAND to get one record of ASCII text from SYS$COMMAND, the terminal.

Condition Values Returned

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 valid RMS status code.

Any code returned by LIB$GET_VM, LIB$GET_VM_64, LIB$SCOPY_R_DX, or LIB$SCOPY_R_DX_64.

Contents

Index

Legal

 
5932PRO_021.HTML

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	String truncated. This is an alternate success return status. The resultant-string argument could not contain all the characters of the returned item.
SS$_BADPARAM	Unrecognized item code. The item-code argument was not recognized as valid by $GETQUI.
LIB$_INSEF	Insufficient event flags. A local event flag number could not be allocated by a call to LIB$GET_EF.
LIB$_INVARG	Invalid arguments. The $GETQUI Item Code describes the item as a "string", and no resultant-string argument was specified.
LIB$_INVSTRDES	Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$GETQUI.

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

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

OpenVMS usage:	varying_arg
type:	unspecified
access:	write only
mechanism:	by reference

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

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

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

OpenVMS usage:	access_names
type:	longword (unsigned)
access:	write only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
SS$_NOCLASS	No matching object class was found.
LIB$_INVARG	The accnam argument was omitted.
LIB$_WRONUMARG	Wrong number of arguments.

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

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.