 |
OpenVMS RTL Library (LIB$) Manual
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.
|
