HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Set Floating-Point Register routine writes the invocation context block floating-point registry entry corresponding to a floating-point register value.

Format

LIB$I64_SET_FR invo_context, index, fr_copy

RETURNS

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

Arguments

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	modify
mechanism:	by reference

Address of a valid invocation context block.

index

OpenVMS usage:	index
type:	longword
access:	read
mechanism:	by value

Index into the FREG array of the invocation context block.

fr_copy

OpenVMS usage:	floating-point value
type:	octaword
access:	write
mechanism:	by value

Address of an octaword that contains the floating-point value to be written to the invocation context block.

Description

Given an invocation context block, a floating-point register index, and a floating-point register value in fr_copy, writes the corresponding invocation context block FREG entry, and calls LIB$I64_PUT_INVO_REGISTERS to write the actual context. The invocation context block remains unchanged if the routine fails.

LIB$I64_SET_FR fails if LIB$I64_PUT_INVO_REGISTERS fails.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Copy Invocation Block General Register routine writes the invocation context block general register.

Format

LIB$I64_SET_GR invo_context, index, fr_copy

RETURNS

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

Arguments

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	modify
mechanism:	by reference

Address of a valid invocation context block.

index

OpenVMS usage:	index
type:	longword
access:	read
mechanism:	by value

Index into the IREG array of the invocation context block.

gr_copy

OpenVMS usage:	integer value
type:	quadword
access:	write
mechanism:	by value

Address of a quadword that contains the value to be written to the invocation context block.

Description

Given an invocation context block, a general register index such that 1 <= index < 128, and a quadword value gr_copy, LIB$I64_SET_GR writes the corresponding invocation context block general register, clears the corresponding NaT bit and uses LIB$I64_PUT_INVO_REGISTERS to write to the actual context. The invocation context block remains unchanged if the routine fails.

LIB$I64_SET_GR fails if LIB$I64_PUT_INVO_REGISTERS fails.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Write Context Block and Quadword PC Value routine writes invocation context block PC.

Format

LIB$I64_SET_PC invo_context, pc_copy

RETURNS

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

Arguments

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	modify
mechanism:	by reference

Address of a valid invocation context block.

pc_copy

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a quadword that contains the PC value to be written to the invocation context block.

Description

Given an invocation context block and a quadword PC value in pc_copy, LIB$I64_SET_PC writes the pc_copy value to the invocation context block PC and then uses LIB$I64_PUT_INVO_REGISTERS to write to the actual context. The invocation context block remains unchanged if the routine fails.

LIB$I64_SET_PC fails if LIB$I64_PUT_INVO_REGISTERS fails.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Convert First Character of String to Integer routine converts the first character of a source string to an 8-bit ASCII integer extended to a longword.

Format

LIB$ICHAR source-string

RETURNS

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

First character of the source string. This character is returned by LIB$ICHAR as an 8-bit ASCII value extended to a longword. If the source string has zero length, LIB$ICHAR returns a zero.

Argument

source-string

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

Source string whose first character is converted to an integer by LIB$ICHAR. The source-string argument is the address of a descriptor pointing to this source string.

Description

Although Fortran users can call LIB$ICHAR, it is more efficient to use the Fortran intrinsic function ICHAR, which generates equivalent code in line.

Condition Values Returned

None.

Example

PROGRAM ICHAR(INPUT, OUTPUT);

{+}
{ This program demonstrates how to call LIB$ICHAR
{ to convert the first character of  string to an
{ integer value.
{-}

FUNCTION LIB$ICHAR(SRCSTR : VARYING [A] OF CHAR) : INTEGER;
         EXTERN;

{+}
{  Declare the variables to be used.
{-}

VAR
  CHARSTR       : VARYING [256] OF CHAR;
  RET_STATUS    : INTEGER;

{+}
{ Begin the main program.  Read the character string,
{ call LIBN$ICHAR, and print the result.
{-}

BEGIN
  WRITELN('Enter string: ');
  READLN(CHARSTR);
  RET_STATUS := LIB$ICHAR(CHARSTR);
  WRITELN(RET_STATUS);
END.

      

The output generated by this Pascal program is as follows:

$ RUN ICHAR Enter string: Pencil sharpener 80 $ RUN ICHAR Enter string: pencil sharpener 112

Notice that this routine changes any uppercase characters to lowercase.

The Index to Relative Position of Substring routine returns an index, which is the relative position of the first occurrence of a substring in the source string.

Format

LIB$INDEX source-string ,sub-string

RETURNS

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

The relative position of the first character of the substring if found, or zero if not found.

On Alpha and I64 systems, if the relative position of the substring can exceed 2³² - 1, assign the return value to a quadword to ensure that you retrieve the correct relative position.

Arguments

source-string

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

Source string to be searched by LIB$INDEX. The source-string argument is the address of a descriptor pointing to this source string.

sub-string

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

Substring to be found. The sub-string argument is the address of a descriptor pointing to this substring.

Description

The relative character positions returned by LIB$INDEX are numbered 1, 2, ..., n. Zero means that the substring was not found.

If the substring has a zero length, LIB$INDEX returns the value 1, indicating success, no matter how long the source string is. If the source string has a zero length and the substring has a nonzero length, zero is returned, indicating that the substring was not found.

Fortran users may use the built-in INDEX function rather than calling LIB$INDEX directly.

Condition Values Returned

None.

The Initialize the Context Area Used in Formatting Dates and Times for Input or Output routine allows the user to initialize the context area used by LIB$FORMAT_DATE_TIME or LIB$CONVERT_DATE_STRING with specific strings, instead of through logical name translation.

Format

LIB$INIT_DATE_TIME_CONTEXT user-context ,component ,init-string

RETURNS

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

Arguments

user-context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

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

component

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

The component of the context that is being initialized. The component argument is the address of a signed longword that indicates this component. Only one component can be initialized per call to LIB$INIT_DATE_TIME; these component codes are shown in the following list.

• LIB$K_MONTH_NAME
• LIB$K_MONTH_NAME_ABB
• LIB$K_FORMAT_MNEMONICS
• LIB$K_WEEKDAY_NAME
• LIB$K_WEEKDAY_NAME_ABB
• LIB$K_RELATIVE_DAY_NAME

• LIB$K_MERIDIEM_INDICATOR
• LIB$K_OUTPUT_FORMAT
• LIB$K_INPUT_FORMAT
• LIB$K_LANGUAGE

init-string

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

The characters that are to be used in formatting dates and times for input or output. The init-string argument is the address of a descriptor pointing to this string.

Description

The LIB$INIT_DATE_TIME_CONTEXT routine allows the user to initialize the context area used by either LIB$CONVERT_DATE_STRING or LIB$FORMAT_DATE_TIME with specific strings instead of through logical name translations. This routine is therefore useful when the application is formatting either input or output strings that are used only by other computer applications and are not intended for presentation to users.

When the text will be parsed by another program, you must specify all of the context (including spellings). For applications where the context specifies a user's preferred format style, spellings can be looked up from the logical name tables.

Therefore, when the text will be parsed by another program, the minimum effort required to initialize the necessary format strings would be a call to LIB$INIT_DATE_TIME_CONTEXT specifying the input or output format strings to be used. If the specified format requires spelled items, such as month names or day names, then additional calls to LIB$INIT_DATE_TIME_CONTEXT are required to provide the spellings of these items. Applications where the context specifies a user's preferred format style can specify only the language name, and allow the strings to be looked up from logical name tables.

The format of the strings used by this routine is as follows:

[delim][string-1][delim] [string-2][delim]... [delim][string-n][delim]

In this format, [delim] is any character that is not in any of the strings, and [string-x] is the spelling of that instance of the component.

For example, a string passed to this routine to specify the English spellings of the month names might be as follows:

|JAN|FEB|MAR|APR|MAY|JUN |JUL|AUG|SEP|OCT|NOV|DEC|

Note that the string starts and ends with a delimiter. Thus, there is one more delimiter than there are string elements. Each type of component has a natural number of elements associated. The string must contain exactly that number of elements.

Month names (full or abbreviated)	12
Format mnemonics	9
Day names (full or abbreviated)	7
Relative day names	3
Meridiem indicators	2
Output format strings	2
Input format string	1
Language	1

In order to specify the input format mnemonics using LIB$INIT_DATE_TIME_CONTEXT, the user must initialize the component LIB$K_FORMAT_MNEMONICS with the appropriate values. The following table lists in order the 9 fields that must be initialized, along with their default (English) values.

Order	Format Field	Legible Mnemonic (Defaults)
1	Year	YYYY
2	Numeric month	MM
3	Numeric day	DD
4	Hours (12- or 24-hour)	HH
5	Minutes	MM
6	Seconds	SS
7	Fractional seconds	CC
8	Meridiem indicator	AM/PM
9	Alphabetic month	MONTH

For example, the following would be a valid definition of LIB$K_FORMAT_MNEMONICS using Austrian as the natural language:

|JJJJ|MM|TT|SS|MM|SS|HH| |MONAT|

To specify an output format using LIB$INIT_DATE_TIME_CONTEXT, the user must initialize the variable LIB$K_OUTPUT_FORMAT. There are two elements associated with this output format string. One describes the date format fields, the other the time format fields. The order in which they appear in the string determines the order in which they are output. A single space is inserted into the output stream between the two elements, if the call to LIB$FORMAT_DATE_TIME specifies that both be output. In the following example, the two elements associated with the output format string are delimited by vertical bars.

|!DB-!MAAU-!Y4|!H04:!M0:!S0.!C2|

This output format string represents the format used by the $ASCTIM system service for outputting times. Note that the middle delimiter is replaced by a space in the resultant output.

See the HP 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$_ILLCOMPONENT	Illegal value for the component.
LIB$_ILLINISTR	Illegally formed init-string.
LIB$_NUMELEMENTS	Incorrect number of elements for the component.
LIB$_UNRFORCOD	Unrecognized format code.

Any condition value returned by LIB$GET_VM or LIB$ANALYZE_SDESC.

The Initialize Times and Counts routine stores the current values of specified times and counts for use by LIB$SHOW_TIMER or LIB$STAT_TIMER.

Format

LIB$INIT_TIMER [context]

RETURNS

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

Argument

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Context variable that retains the values of the times and counts. The context argument contains the address of an unsigned longword that is this context. When you call LIB$INIT_TIMER, you must use the optional context argument only if you want to maintain several sets of statistics simultaneously.

• If context is omitted, the control block is allocated in static storage. This method is not AST reentrant.
• If context is zero, a control block is allocated in dynamic heap storage. The times and counts will be stored in that block and the address of the block returned in context. This method is fully reentrant and modular.
• If context is nonzero, it is considered to be the address of a control block previously allocated by a call to LIB$INIT_TIMER. If so, the control block is reused, and fresh times and counts are stored in it.

When LIB$INIT_TIMER returns, the block of storage referred to by context will contain the times and counts.

Description

LIB$INIT_TIMER stores the current values of specified times and counts in one of three places, depending on the value of the optional context argument.

You need to call LIB$FREE_TIMER only if you have specified context in LIB$INIT_TIMER and you want to deallocate all heap storage resources.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INSVIRMEM	The context argument is zero, and there is insufficient virtual memory to allocate a storage block.
LIB$_INVARG	Invalid argument; context is nonzero and the block to which it refers was not initialized on a previous call to LIB$INIT_TIMER.