 |
HP OpenVMS RTL Library (LIB$) Manual
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.
LIB$GET_COMMON
The Get String from Common routine copies a string in the common area
to the destination string. (The common area is an area of storage that
remains defined across multiple image activations in a process.) The
string length is taken from the first longword of the common area.
Format
LIB$GET_COMMON resultant-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 |
Destination string into which LIB$GET_COMMON writes the string copied
from the common area. The resultant-string argument is
the address of a descriptor pointing to the destination string.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters written into resultant-string by
LIB$GET_COMMON, not counting padding in the case of a fixed-length
string. The resultant-length argument is the address
of an unsigned word integer containing the number of characters copied.
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$PUT_COMMON allows a program to copy a string into the process's
common storage area. This area remains defined during multiple image
activations. LIB$GET_COMMON allows a program to copy a string from the
common area into a destination string. The programs reading and writing
the data in the common area must agree upon its amount and format.
The maximum number of characters that can be copied is 252. The actual
number of characters copied is returned by the optional argument,
resultant-length (if given).
You can use LIB$PUT_COMMON and LIB$GET_COMMON to pass information
between images run successively, such as chained images run by
LIB$RUN_PROGRAM. Since the common area is unique to each process, do
not use LIB$GET_COMMON and LIB$PUT_COMMON to share information across
processes.
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 HP.
|
|
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
|
Successfully completed. The string was longer than the buffer and was
truncated.
|
LIB$GET_CURR_INVO_CONTEXT (Alpha and I64 Only)
The Get Current Invocation Context routine gets the current invocation
context of any active procedure.
A thread can obtain the invocation context of a current procedure using
the following function format:
Format
LIB$GET_CURR_INVO_CONTEXT invo_context
RETURNS
None.
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
write only |
| mechanism: |
by reference |
Address of an invocation context block into which the procedure context
of the caller will be written.
Description
LIB$GET_CURR_INVO_CONTEXT gets the current invocation context of any
active procedure.
See the HP OpenVMS Calling Standard manual for additional information.
Condition Values Returned
None.
LIB$GET_DATE_FORMAT
The Get the User's Date Input Format routine returns information about
the user's choice of a date/time input format.
Format
LIB$GET_DATE_FORMAT format-string [,user-context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
format-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Receives the translation of LIB$DT_INPUT_FORMAT.
The format-string argument is the address of a
descriptor pointing to this format string.
user-context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Context variable that retains the translation context over multiple
calls to this routine. The user-context argument is
the address of an unsigned longword that contains this context. The
initial value of the context variable must be zero. Thereafter, the
user program must not write to the cell.
The user-context argument is optional. However, if a
context cell is not passed, LIB$GET_DATE_FORMAT 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, HP recommends that
users specify a different context cell for each calling thread.
Description
Depending on which method was used to specify the input formats,
LIB$GET_DATE_FORMAT either translates the logicals LIB$DT_INPUT_FORMAT
and LIB$FORMAT_MNEMONICS, or uses the preinitialized context components
LIB$K_FORMAT_MNEMONICS and LIB$K_INPUT_FORMAT to return the user's
specified date/time input format in a legible form. This format string
can then be used as a guideline for entering date/time strings.
The string returned by LIB$GET_DATE_FORMAT parallels the currently
defined input format string, consisting of the format punctuation (with
most whitespace compressed) and "legible" mnemonics
representing the various format fields. The English (default) versions
of these mnemonics are as follows:
| Format Field |
Legible Mnemonic (Default) |
|
Year
|
YYYY
1
|
|
Numeric month
|
MM
|
|
Alphabetic month
|
MONTH
|
|
Numeric day
|
DD
|
|
Hours (12- or 24-hour)
|
HH
|
|
Minutes
|
MM
|
|
Seconds
|
SS
|
|
Fractional seconds
|
CC
1
|
|
Meridiem indicator
|
AM/PM
|
1This variable-length field mnemonic has a numeric suffix
representing the number of digits allowed or required in the field. For
instance, YYYY4 indicates a four-digit year field.
For example, consider the following input format string:
$ DEFINE LIB$DT_INPUT_FORMAT -
_$ "!MAAU !D0, !Y2 !H02:!M0:!S0.!C4 !MIU"
|
If LIB$GET_DATE_FORMAT were called for this format string, the format
string returned would be as follows:
MONTH DD, YYYY2 HH:MM:SS.CC4 AM/PM
|
See the HP OpenVMS Programming Concepts Manual for a description of system date and time
operations as well as a detailed description of the format mnemonics
used in these routines.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_DEFFORUSE
|
Default format used; unable to determine desired format.
|
|
LIB$_ENGLUSED
|
English used; unable to determine or use desired language.
|
|
LIB$_ILLFORMAT
|
Illegal format string.
|
|
LIB$_INVARG
|
Invalid argument; a required argument was not specified.
|
|
LIB$_INVSTRDES
|
Invalid input string descriptor.
|
|
LIB$_REENTRANCY
|
Reentrancy detected.
|
|
LIB$_STRTRU
|
String truncated.
|
|
LIB$_UNRFORCOD
|
Unrecognized format code.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
Any condition value returned by LIB$GET_VM, LIB$SCOPY_R_DX, and
LIB$SFREE1_DD.
|
