 |
OpenVMS RTL Library (LIB$) Manual
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.
|
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
symbol libraries in module $SYIDEF (where appropriate) supplied by
Compaq.
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: A--GETUAI 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.
|
