Document revision date: 30 March 2001

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

> - 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;

> 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

| privacy and legal statement |
5932PRO_023.HTML