OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

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 Compaq.

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 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 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, Compaq 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 ¹

Numeric month MM

Alphabetic month MONTH

Numeric day DD

Hours (12- or 24-hour) HH

Minutes MM

Seconds SS

Fractional seconds CC ¹

Meridiem indicator AM/PM

Format Field	Legible Mnemonic (Default)
Year	YYYY ¹
Numeric month	MM
Alphabetic month	MONTH
Numeric day	DD
Hours (12- or 24-hour)	HH
Minutes	MM
Seconds	SS
Fractional seconds	CC ¹
Meridiem indicator	AM/PM

¹This 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 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.

LIB$GET_EF

The Get Event Flag routine allocates one local event flag from a processwide pool and returns the number of the allocated flag to the caller. If no flags are available, LIB$GET_EF returns an error as its function value.

Format

LIB$GET_EF event-flag-number

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

event-flag-number

OpenVMS usage: ef_number

type: longword (unsigned)

access: write only

mechanism: by reference

Number of the local event flag that LIB$GET_EF allocated, or --1 if no local event flag was available. The event-flag-number argument is the address of a signed longword integer into which LIB$GET_EF writes the number of the local event flag that it allocates.

Description

LIB$GET_EF and LIB$FREE_EF cause local event flags to be allocated and deallocated at run time, so that your routine remains independent of other routines executing in the same process.
LIB$GET_EF provides your program with an arbitrary event flag number. You can obtain a specific event flag number by calling LIB$RESERVE_EF.

Note
Beware of running multiple images linked with /NOSYSSHR in the same process and having more than one image make calls to LIB$GET_EF. Each image contains its own copy of the event flag bit array that is designed to be process-wide and synchronize ownership of event flags. Multiple calls to LIB$GET_EF could cause the same event flag to be allocated more than once.

See the OpenVMS Programming Concepts Manual for more information.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_INSEF Insufficient event flags. There were no more event flags available for allocation.

LIB$GET_FOREIGN

The Get Foreign Command Line routine requests the calling image's command language interpreter (CLI) to return the contents of the "foreign command" line that activated the current image.

Format

LIB$GET_FOREIGN resultant-string [,prompt-string] [,resultant-length] [,flags]

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_FOREIGN uses to receive the foreign command line. The resultant-string argument is the address of a descriptor pointing to this string. If the foreign command text returned was obtained by a prompt to SYS$INPUT (see the description of flags), the text is translated to uppercase so as to be more consistent with text returned from the CLI.
prompt-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Optional user-supplied prompt for text that LIB$GET_FOREIGN uses if no command-line text is available. The prompt-string argument is the address of a descriptor pointing to the user prompt. If omitted, no prompting is performed. It is recommended that prompt-string be specified. If prompt-string is omitted and if no command-line text is available, a zero-length string will be returned.
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_FOREIGN, not counting padding in the case of a fixed-length resultant-string. The resultant-length argument is the address of an unsigned word into which LIB$GET_FOREIGN writes the number of bytes.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: modify

mechanism: by reference

Value that LIB$GET_FOREIGN uses to control whether or not prompting is to be performed. The flags argument is the address of an unsigned longword integer containing this value. If the low bit of flags is zero, or if flags is omitted, prompting is done only if the CLI does not return a command line. If the low bit is 1, prompting is done unconditionally. If specified, flags is set to 1 before returning to the caller.
The primary use of flags is to allow a utility program to be invoked once with subcommand text on the command line, and then to repeatedly prompt for further subcommands from SYS$INPUT. This is accomplished by calling LIB$GET_FOREIGN repeatedly, specifying in the call a prompt-string string and a flags variable that is initialized to zero at the beginning of the program. The first call gets the subcommand text from the command line, after which flags will be set to 1, causing further subcommands to be requested through prompts to SYS$INPUT.

Description

LIB$GET_FOREIGN returns the contents of the command line that you use to activate an image. It can be used to give your program access to the qualifiers of a foreign command or to prompt for further command line text.
A foreign command is a command that you can define and then use as if it were a DCL or MCR command in order to run a program. When you use the foreign command at command level, the CLI parses the foreign command only and activates the image. It ignores any options or qualifiers that you have defined for the foreign command. Once the CLI has activated the image, the program can call LIB$GET_FOREIGN to obtain and parse the remainder of the command line (after the command itself) for whatever options it may contain. See the OpenVMS User's Manual for information on how to define a foreign command.
If no command line is available, LIB$GET_FOREIGN can optionally call LIB$GET_INPUT to prompt the user for command text. If desired, LIB$GET_FOREIGN can be called repetitively, returning the command line on the first call, but prompting for further text on subsequent calls.
LIB$GET_FOREIGN can also be used for images invoked by the RUN command, for which further text must be obtained by prompting. Such an image can also be invoked by the DCL command MCR or by the MCR CLI. The text following the image name will be returned to the executing image.
The action of LIB$GET_FOREIGN depends on the environment in which the image is activated.

If you use a foreign command to invoke the image, you can call LIB$GET_FOREIGN to obtain the command qualifiers following the foreign command. You can also use LIB$GET_FOREIGN to prompt repeatedly for more qualifiers after the command. This technique is shown in the example.
If the image is in the SYS$SYSTEM: directory, the image can be invoked by the DCL command MCR or by the MCR CLI. In this case, LIB$GET_FOREIGN returns the command line text following the image name.
If the image is invoked by a DCL command RUN, LIB$GET_FOREIGN can be used to prompt for additional text.
If the image is not invoked by a foreign command or MCR, or if there is no information remaining on the command line, and the user-supplied prompt is present, LIB$GET_INPUT is called to prompt for a command line. If the prompt is not present, LIB$GET_FOREIGN returns a zero length string.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB A fatal internal error was detected.

LIB$_INPSTRTRU The input string was truncated. The resultant-string argument could not contain all of the characters. The resultant-length argument reflects the truncated length.

LIB$_INSVIRMEM Insufficient virtual memory.

LIB$_INVSTRDES Invalid string descriptor.

A condition value returned by OpenVMS RMS. SYS$INPUT was prompted for command text and RMS returned an error. The most typical error will be RMS$_EOF, end-of-file.

Example


EXAMPLE: ROUTINE OPTIONS (MAIN); %INCLUDE $STSDEF; /* Status-testing definitions / DECLARE COMMAND_LINE CHARACTER(80) VARYING, PROMPT_FLAG FIXED BINARY(31) INIT(0), LIB$GET_FOREIGN ENTRY (CHARACTER() VARYING, CHARACTER() VARYING, FIXED BINARY(15), FIXED BINARY(31)) OPTIONS(VARIABLE) RETURNS (FIXED BINARY(31)), RMS$_EOF GLOBALREF FIXED BINARY(31) VALUE; / Repeat forever calling LIB$GET_FOREIGN to obtain subcommand text and print the text. Exit when an end-of-file is found. / DO WHILE ('1'B); / Do while TRUE / STS$VALUE = LIB$GET_FOREIGN (COMMAND_LINE,'Input: ',, PROMPT_FLAG); IF STS$SUCCESS THEN PUT LIST (' Command was ',COMMAND_LINE); ELSE DO; IF STS$VALUE ^= RMS$_EOF THEN PUT LIST ('Error encountered'); RETURN; END; PUT SKIP; / Skip to next line / END; / End of DO WHILE loop */ END;

EXAMPLE: ROUTINE OPTIONS (MAIN); 
 
%INCLUDE $STSDEF; /* Status-testing definitions */ 
 
DECLARE COMMAND_LINE CHARACTER(80) VARYING, 
        PROMPT_FLAG FIXED BINARY(31) INIT(0), 
        LIB$GET_FOREIGN ENTRY (CHARACTER(*) VARYING, 
                               CHARACTER(*) VARYING, 
                               FIXED BINARY(15), 
                               FIXED BINARY(31)) 
          OPTIONS(VARIABLE) RETURNS (FIXED BINARY(31)), 
        RMS$_EOF GLOBALREF FIXED BINARY(31) VALUE; 
 
/* Repeat forever calling LIB$GET_FOREIGN to obtain 
   subcommand text and print the text. Exit when an 
   end-of-file is found. */ 
 
DO WHILE ('1'B); /* Do while TRUE */ 
  STS$VALUE = LIB$GET_FOREIGN 
                 (COMMAND_LINE,'Input: ',, 
                  PROMPT_FLAG); 
  IF STS$SUCCESS THEN 
    PUT LIST ('  Command was ',COMMAND_LINE); 
  ELSE DO; 
    IF STS$VALUE ^= RMS$_EOF THEN 
      PUT LIST ('Error encountered'); 
    RETURN; 
    END; 
  PUT SKIP; /* Skip to next line */ 
  END; /* End of DO WHILE loop */ 
END;

This PL/I example shows the use of the optional flags argument to permit repeated calls to LIB$GET_FOREIGN. The command line text is retrieved on the first pass only; after the first pass, the program prompts from SYS$INPUT.

Contents

Index

privacy and legal statement

5932PRO_023.HTML

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

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

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 Compaq.
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.

OpenVMS usage:	invo_context_blk
type:	structure
access:	write only
mechanism:	by reference

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

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.

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

SS$_NORMAL	Routine successfully completed.
LIB$_INSEF	Insufficient event flags. There were no more event flags available for allocation.

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