hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

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:

  1. If the clsnam parameter is omitted, clsnam defaults to "FILE."
  2. 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.
  3. 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.
  4. 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).
  5. 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:


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.

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.


Previous Next Contents Index