hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


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

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.


LIB$GET_FULLNAME_OFFSET

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

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.

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:

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.


LIB$GET_INPUT

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.

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.


Previous Next Contents Index