HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

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

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.

The Get the Offset to the Starting Position of the Most Significant Part of a Full Name routine returns the offset to the starting position of the most significant part of a full name.+ The most significant part of a full name is determined by the underlying network services.

Format

LIB$GET_FULLNAME_OFFSET fullname, offset

RETURNS

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

Arguments

fullname

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Full name. The fullname argument contains the address of the descriptor pointing to this full name string.

The error LIB$_INVARG is returned if fullname contains an invalid full name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if fullname is an invalid descriptor.

offset

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

The offset in bytes of the starting position of the most significant part of fullname. The offset argument is the address of an unsigned word that contains this offset.

The offset argument contains an unusable result when LIB$GET_FULLNAME_OFFSET returns in error.

Description

This routine returns the byte offset of the starting position of the most significant part of the input full name. The returned offset can be used to position the display of a full name in a fixed-size output region, for example, scroll regions in DECwindows applications. The most significant part of a full name is determined by the underlying network services.

You must validate fullname by expanding it with LIB$EXPAND_NO DENAME before calling LIB$GET_FULLNAME_OFFSET. LIB$GET_FULLNAME_OFFSET returns the error LIB$_INVARG if fullname is invalid.

In a DECnet for OpenVMS environment, processing a DECnet-Plus for OpenVMS full name using LIB$GET_FULLNAME_OFFSET results in the error condition LIB$_INVARG.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument: fullname is invalid. fullname points to a null string. The length of the full name is more than 1024 characters. Processing a DECnet-Plus for OpenVMS node name in a DECnet for OpenVMS environment is invalid.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.

Any condition value returned by the $IPC DECnet service.

Examples

The following table gives some examples of the results of LIB$GET_FULLNAME_OFFSET:

Full Name	Offset
NODE	0
DEC:.FOO.NODE	9

LIB$GET_HOSTNAME

The Get Host Node Name routine returns the host node name of the local system.

Note No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$GET_HOSTNAME hostname [,resultant-length] [,flags]

RETURNS

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

Arguments

hostname

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

The host node name. The hostname argument contains the address of a descriptor pointing to the host node name. LIB$GET_HOSTNAME writes the host node-name string into the buffer pointed to by the hostname descriptor.

The error LIB$_INVSTRDES is returned if hostname is an invalid descriptor.

The length field of the hostname descriptor is not updated unless hostname is a dynamic descriptor with a length less than the host node name to be returned. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.

The hostname argument contains an unusable result when LIB$GET_HOSTNAME returns in error.

resultant-length

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Length of the host node name. The resultant-length argument is the address of an unsigned word that contains this length in bytes.

The resultant-length argument contains an unusable result when LIB$GET_HOSTNAME returns in error.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

The value LIB$GET_HOSTNAME uses to control the form of the host node name that it returns in the output descriptor hostname. If flags is equal to 0, or if flags is omitted, the host node name returned is in the network usable form. If flags is equal to 1, the host node name returned is in the parsable form.

Unused bits in flags must be 0. Nonzero unused bits result in the error condition LIB$_INVARG.

Description

This routine returns the host node name. The routine searches for the first host node name using the following order:

1. Get host node name from $GETSYI system service.
2. Translate the executive mode logical SYS$NODE_FULLNAME once.
3. Translate the executive mode logical SYS$NODE once.

The error LIB$_NOHOSNAM is returned if no host node name is found.

LIB$GET_HOSTNAME can return the host node name in the following two forms:

• Network usable form --- The form that can be passed directly to the network. This form does not contain unnecessary double quotation marks (double quotation marks ["] that are not part of the node name) and also does not contain trailing double colons, for example: DEC:.FOO."simple name with spaces" .
• Parsable form --- The form that can be passed directly to the part of the system that does node-name syntax parsing, for example, $FILESCAN and DCL command parsing. This form contains trailing double colons and is fully quoted if there are special characters. Individual double quotation marks (") that are part of a simple name are doubled (""), for example: "DEC:.FOO.""simple name with spaces""":: .
  You must use double quotation marks for a node name with special characters to facilitate correct parsing.

If the returned node name overflows the buffer pointed to by hostname, the host node name is truncated at the end, and the alternate success status LIB$_STRTRU is returned.

The resultant-length argument, if supplied, is set to the length of the node-name string copied to the output buffer pointed to by hostname.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Routine successfully completed. Characters are truncated in the output buffer pointed to by hostname.
LIB$_INVARG	Invalid input argument. Unused bits in flags are not set to 0.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments.
LIB$_NOHOSNAM	No host node name found.

Any condition value returned by LIB$SCOPY_R_DX, or the $FILESCAN system service.

The Get Line from SYS$INPUT routine gets one record of ASCII text from the current controlling input device, specified by SYS$INPUT.

Format

LIB$GET_INPUT 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_INPUT gets from the input device. The resultant-string argument is the address of a descriptor pointing to the character string into which LIB$GET_INPUT writes the text received from the current input device.

prompt-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Prompt message that is displayed on the controlling terminal. The prompt-string argument is the address of a descriptor containing the prompt. Any string can be a valid prompt. By convention however, a prompt 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_INPUT, not counting padding in the case of a fixed string. The resultant-length argument is the address of an unsigned word containing this number. 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_INPUT uses the OpenVMS RMS $GET service to get one record of ASCII text from the current controlling input device, specified by SYS$INPUT. (For more information about the RMS $GET service, see the OpenVMS Record Management Services Reference Manual.)

When you log in, the OpenVMS operating system creates three files as default I/O control streams for your process.

• SYS$INPUT, your default input device
• SYS$OUTPUT, your default output device
• SYS$COMMAND, the device that supplies the commands to 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 names 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_INPUT opens file SYS$INPUT on the first call. The RMS internal stream identifier (ISI) is stored in the routine's static storage for subsequent calls.

If prompt-string is provided and the SYS$INPUT device is a terminal, LIB$GET_INPUT displays the prompt message. If the device is not a terminal, the prompt-string argument is ignored.

If you want to get input from some source other than the current input stream, use LIB$GET_COMMAND.

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.