OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$FLT_UNDER

The Floating-Point Underflow Detection routine enables or disables floating-point underflow detection for the calling routine activation. The previous setting is returned as a function value.

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.

This routine is available on OpenVMS Alpha systems in translated form and is applicable to translated VAX images only.

Format

LIB$FLT_UNDER new-setting

RETURNS

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by value

The old floating-point underflow enable setting (the previous contents of the SF$W_PSW[PSW$V_FU] in the caller's frame).

Argument

new-setting

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

New floating-point underflow enable setting. The new-setting argument is the address of an unsigned byte containing the new setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable.

Description

LIB$FLT_UNDER affects only the current routine activation and does not affect any of its callers or any routines that it may call. However, the setting does remain in effect for any routines entered through a JSB entry point.
The caller's stack frame will be modified by this routine.

Condition Values Returned

None.

Example


C+ C This Fortran example program shows C the use of LIB$FLT_UNDER. C- INTEGER4 NEW_SETTING REAL4 X , Y , Z NEW_SETTING = 0 X = 1E-20 Y = 1E20 CALL LIB$FLT_UNDER( NEW_SETTING ) TYPE ,'First Case: This should not have an underflow exception' Z = X / Y TYPE , 'If this lines prints then the underflow exception 1 was disabled.' TYPE * NEW_SETTING = 1 X = 1E-20 Y = 1E20 CALL LIB$FLT_UNDER( NEW_SETTING ) TYPE * , 'Second Case: This should have an underflow exception 1 and then stop.' Z = X / Y TYPE * , 'If this line prints, then the underflow exception 1 was disabled.' END

C+ 
C This Fortran example program shows 
C the use of LIB$FLT_UNDER. 
C- 
 
        INTEGER*4  NEW_SETTING 
        REAL*4  X , Y , Z 
 
        NEW_SETTING = 0 
        X = 1E-20 
        Y = 1E20 
 
        CALL LIB$FLT_UNDER( NEW_SETTING ) 
 
        TYPE *,'First Case: This should not have an underflow exception' 
 
        Z = X / Y 
 
        TYPE *, 'If this lines prints then the underflow exception 
     1  was disabled.' 
        TYPE * 
 
        NEW_SETTING = 1 
        X = 1E-20 
        Y = 1E20 
 
        CALL LIB$FLT_UNDER( NEW_SETTING ) 
 
        TYPE * , 'Second Case: This should have an underflow exception 
     1  and then stop.' 
 
        Z = X / Y 
 
        TYPE * , 'If this line prints, then the underflow exception 
     1  was disabled.' 
 
        END

In this Fortran example, floating-point underflow detection is disabled the first time X is divided by Y. The second time, underflow detection is enabled, and the program stops because of the error generated.

LIB$FORMAT_DATE_TIME

The Format Date and/or Time routine allows the user to select at run time a specific output language and format for a date or time, or both.

Format

LIB$FORMAT_DATE_TIME date-string [,date] [,user-context] [,date-length] [,flags]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

date-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Receives the requested date or time, or both, that has been formatted for output according to the currently selected format and language. The date-string argument is the address of a descriptor pointing to this string.
date

OpenVMS usage: date_time

type: quadword (unsigned)

access: read only

mechanism: by reference

The date or time, or both, to be formatted for output. The date argument is the address of an unsigned quadword that contains the absolute date or time, or both to be formatted. If you omit this argument, or if you supply a zero passed by value, then the current system time is used. Note that the date argument must represent an absolute time, not a delta time.
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.
The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$FORMAT_DATE_TIME 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.
date-length

OpenVMS usage: longword_signed

type: longword (signed)

access: write only

mechanism: by reference

Number of bytes of text written to the date-string argument. The date-length argument is the address of a signed longword that receives this string length. Note that date-length specifies the number of bytes of text, not the number of characters, written to date-string.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

Bit mask that allows the user to specify whether the date, time, or both are output. The flags argument is the address of an unsigned bit mask containing the specified values. Valid values are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS.
Default values are determined as follows:

If the flags argument is omitted, LIB$FORMAT_DATE_TIME determines which fields to format according to the current definition of LIB$DT_FORMAT.
If the flags argument is specified, LIB$FORMAT_DATE_TIME uses the flags value to determine which fields to format. That is, the flags argument can be used to override the definition of LIB$DT_FORMAT when specifying which fields should be formatted for output. If the field specified by flags was not assigned a format through the definition of LIB$DT_FORMAT, the standard OpenVMS format is used.

Description

The LIB$FORMAT_DATE_TIME routine formats an OpenVMS internal format date-time quadword into a textual string of some predefined format. The language to be used and the format in which to output the information are programmable using either of the following methods.

The language and format are programmable at compile time through the use of the routine LIB$INIT_DATE_TIME_CONTEXT.
The language and format are determined at run time through the translation of the logical names SYS$LANGUAGE and LIB$DT_FORMAT.

In general, if an application is formatting text for internal storage or transmission, the language and format should be specified at compile time. If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and format of your choice.
If an application is formatting text for presentation to a user, the logical name method of specifying language and format should be used. In this method, the user assigns equivalence names to the logical names SYS$LANGUAGE and LIB$DT_FORMAT, thereby selecting the language and format of the date and time at run time.
If the logical name method is used, the translations of the logical names SYS$LANGUAGE and LIB$DT_FORMAT specify one or more executive mode logicals, which in turn must be translated to determine the actual format string. These additional logicals supply such things as the names of the days of the week and the months in the selected language (determined by SYS$LANGUAGE). All of these logicals are predefined, so that a non-privileged user can select any one of these languages and formats. A user can create his or her own languages and formats; however, the CMEXEC, SYSNAME, and SYSPRV privileges are required.
With the exception of SYS$LANGUAGE and LIB$DT_FORMAT, all logical names used by this routine must be defined from the executive mode.
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$_ABSTIMREQ Absolute time required.

LIB$_DEFFORUSE Default format used; unable to determine the desired format.

LIB$_ENGLUSED English used; unable to determine or use the specified language.

LIB$_REENTRANCY Reentrant invocation with same context variable.

LIB$_STRTRU Output string truncated.

LIB$_UNRFORCOD Unrecognized format code.

Any condition values returned by the $NUMTIM system service, or RTL routines LIB$GET_VM, LIB$GET_VM_64, LIB$ANALYZE_SDESC, or LIB$ANALYZE_SDESC_64.

LIB$FORMAT_SOGW_PROT

The Format Protection Mask routine translates a protection mask into a formatted string.

Format

LIB$FORMAT_SOGW_PROT protection-mask, [access-names], [ownership-names], [ownership-separator], [list-separator], protection-string, [protection-length]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

protection-mask

OpenVMS usage: protection

type: word (unsigned)

access: read only

mechanism: by reference

The address of a word that holds a 16-bit protection mask to be translated.
access-names

OpenVMS usage: access_names

type: array [0..31] of quadword string descriptor

access: read only

mechanism: by reference

The address of the access name table for the associated object class. For example, it is the value returned in accnam by LIB$GET_ACCNAM. This parameter defaults to the access name table for the FILE object class.
ownership-names

OpenVMS usage: char_string

type: array [0..3] of quadword string descriptor

access: read only

mechanism: by reference

The address of a vector of 4 quadword descriptors that points to the ownership name. The default value is the full ownership category names (System, Owner, Group, World).
ownership-separator

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

The address of a descriptor that points to the ownership separator string. The separator string is inserted after the ownership name to introduce a nonempty set of access names. By default, the value is ": " (the colon and space characters).
list-separator

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

The address of a descriptor that points to the list separator string. The list separator string is inserted between ownership-access type pairs. By default, the value is ", " (the comma and space characters).
protection-string

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by descriptor

The address of a character-string descriptor that receives the output of the routine call. The protection-string argument points to the formatted protection string at the end of a call. The protection string has the following components repeated for each of: System, Owner, Group, World:
ownership-name[ownership-separator][access-types][list-separator]
An example of a formatted protection string is
System: RWED, Owner: RWED, Group: RW, World: R
protection-length

OpenVMS usage: word_signed

type: word (signed)

access: write only

mechanism: by reference

The address of a word that receives the length of the string returned in the protection-string argument.

Description

LIB$FORMAT_SOGW_PROT translates a 16-bit protection mask into a formatted string. This routine works for any protected object class by specifying the correct access name table. The address of the access name table can be obtained from the LIB$GET_ACCNAM routine.
Several formatting options are available. The caller can specify ownership names, ownership separators, or list separators.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_INVARG Required parameter missing.

LIB$_WRONGNUMARG Wrong number of arguments.

STR$_TRU String truncation warning.

LIB$FREE_DATE_TIME_CONTEXT

The Free the Context Area Used When Formatting Dates and Times for Input or Output routine frees the virtual memory associated with the context area used by the date/time input and output formatting routines.

Format

LIB$FREE_DATE_TIME_CONTEXT [user-context]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

user-context

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by reference

User context that retains the translation context over multiple calls to the date/time input and output formatting routines. The user-context argument is the address of an unsigned longword that contains this context. If the user-context argument was not specified in the call to LIB$FORMAT_DATE_TIME, LIB$CONVERT_DATE_STRING, or LIB$GET_MAXIMUM_DATE_LENGTH, then no argument should be supplied when calling this routine.

Description

The LIB$FREE_DATE_TIME_CONTEXT routine frees the virtual memory associated with the context area used by the date/time input and output formatting routines. A call to this routine is optional, since the same functions are performed at image exit.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

Any condition value returned by LIB$FREE_VM. If one of these condition values is returned, it indicates either an internal coding error or that memory was corrupted by the user's program.

LIB$FREE_EF

The Free Event Flag routine frees a local event flag previously allocated by LIB$GET_EF or by LIB$RESERVE_EF. LIB$FREE_EF is the complement of LIB$GET_EF.

Format

LIB$FREE_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 integer (unsigned)

access: read only

mechanism: by reference

Event flag number to be deallocated by LIB$FREE_EF. The event-flag-number argument is the address of a signed longword integer that contains the event flag number, which is the value allocated to the user by LIB$GET_EF or LIB$RESERVE_EF.

Description

When a local event flag allocated by calling LIB$GET_EF or LIB$RESERVE_EF is no longer needed, LIB$FREE_EF should be called to free the event flag for use by other routines.
See the OpenVMS Programming Concepts Manual for more information.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_EF_ALRFRE Event flag already free.

LIB$_EF_RESSYS Event flag reserved to system. This error occurs if the event flag number is outside the ranges of 1 to 23 and 32 to 63.

LIB$FREE_LUN

The Free Logical Unit Number routine releases a logical unit number allocated by LIB$GET_LUN to the pool of available numbers. LIB$FREE_LUN is the complement of LIB$GET_LUN.

Format

LIB$FREE_LUN logical-unit-number

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

logical-unit-number

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Logical unit number to be deallocated. The logical-unit-number argument is the address of a signed longword integer that contains this logical unit number, which is the value previously returned by LIB$GET_LUN.

Description

When a logical unit number allocated by calling LIB$GET_LUN is no longer needed, it should be released for use by other routines.
This routine is useful only in BASIC or Fortran programs.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_LUNALRFRE Logical unit number is already free.

LIB$_LUNRESSYS Logical unit number reserved to system. This occurs if the specified logical unit number is outside the range of 100 through 299.

Contents

Index

privacy and legal statement

5932PRO_019.HTML

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

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

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

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

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

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

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

SS$_NORMAL	Routine successfully completed.
LIB$_ABSTIMREQ	Absolute time required.
LIB$_DEFFORUSE	Default format used; unable to determine the desired format.
LIB$_ENGLUSED	English used; unable to determine or use the specified language.
LIB$_REENTRANCY	Reentrant invocation with same context variable.
LIB$_STRTRU	Output string truncated.
LIB$_UNRFORCOD	Unrecognized format code.

OpenVMS usage:	protection
type:	word (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	access_names
type:	array [0..31] of quadword string descriptor
access:	read only
mechanism:	by reference

OpenVMS usage:	word_signed
type:	word (signed)
access:	write only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Required parameter missing.
LIB$_WRONGNUMARG	Wrong number of arguments.
STR$_TRU	String truncation warning.

OpenVMS usage:	ef_number
type:	longword integer (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_EF_ALRFRE	Event flag already free.
LIB$_EF_RESSYS	Event flag reserved to system. This error occurs if the event flag number is outside the ranges of 1 to 23 and 32 to 63.

SS$_NORMAL	Routine successfully completed.
LIB$_LUNALRFRE	Logical unit number is already free.
LIB$_LUNRESSYS	Logical unit number reserved to system. This occurs if the specified logical unit number is outside the range of 100 through 299.