[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual


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


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; 
 
      

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.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5932PRO_022.HTML