OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$CVT_xTB

The Convert Numeric Text to Binary routines return a binary representation of the ASCII text string representation of a decimal, hexadecimal, or octal number.

Format

LIB$CVT_DTB byte-count ,numeric-string ,result

LIB$CVT_HTB byte-count ,numeric-string ,result

LIB$CVT_OTB byte-count ,numeric-string ,result

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

byte-count

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by value

Byte count of the input ASCII text string. The byte-count argument is a signed longword integer containing the byte count of the input string.
numeric-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by reference

ASCII text string representation of a decimal, hexadecimal, or octal number that LIB$CVT_xTB converts to binary representation. The numeric-string argument is the address of a character string containing this input string to be converted.
The syntax of a valid ASCII text input string is as follows:
[ + | - ] <radix-characters>
LIB$CVT_xTB allows only an optional plus (+) or minus - sign followed by a string of decimal, hexadecimal, or octal characters appropriate to the routine being called.
result

OpenVMS usage: longword_signed

type: longword integer (signed)

access: write only

mechanism: by reference

Binary representation of the input string. The result argument is the address of a signed longword integer containing the converted string.

Description

LIB$CVT_DTB converts the ASCII text string representation of a decimal number into binary representation. LIB$CVT_HTB converts the ASCII text string representation of a hexadecimal number into binary representation. LIB$CVT_OTB converts the ASCII text string representation of an octal number into binary representation.

Note
LIB$CVT_DTB, LIB$CVT_HTB, and LIB$CVT_OTB are intended to be called primarily from BLISS and MACRO programs. Therefore, the routines expect input scalar arguments to be passed by value and strings by reference.

Condition Values Returned

1 Routine successfully completed.

0 Nonradix character in the input string or a sign in any position other than the first character. An overflow from 32 bits (unsigned) causes an error.

LIB$CVT_xTB_64 (Alpha Only)

The Convert Numeric Text to Binary routines return a binary representation of the ASCII text string representation of a decimal, hexadecimal, or octal number.

Format

LIB$CVT_DTB_64 byte-count ,numeric-string ,result

LIB$CVT_HTB_64 byte-count ,numeric-string ,result

LIB$CVT_OTB_64 byte-count ,numeric-string ,result

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

byte-count

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by value

Byte count of the input ASCII text string. The byte-count argument is a signed longword integer containing the byte count of the input string.
numeric-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by reference

ASCII text string representation of a decimal, hexadecimal, or octal number that LIB$CVT_xTB_64 converts to binary representation. The numeric-string argument is the address of a character string containing this input string to be converted.
The syntax of a valid ASCII text input string is as follows:
[ + | - ] <radix-characters>
LIB$CVT_xTB_64 allows only an optional plus (+) or minus (-) sign followed by a string of decimal, hexadecimal, or octal characters appropriate to the routine being called.

result

OpenVMS usage: quadword_signed

type: quadword integer (signed)

access: write only

mechanism: by reference

Binary representation of the input string. The result argument is the address of a signed quadword integer containing the converted string.

Description

LIB$CVT_DTB_64 converts the ASCII text string representation of a decimal number into binary representation. LIB$CVT_HTB_64 converts the ASCII text string representation of a hexadecimal number into binary representation. LIB$CVT_OTB_64 converts the ASCII text string representation of an octal number into binary representation.

Note
LIB$CVT_DTB_64, LIB$CVT_HTB_64, and LIB$CVT_OTB_64 are intended to be called primarily from BLISS and MACRO programs. Therefore, the routines expect input scalar arguments to be passed by value and strings by reference.

Condition Values Returned

1 Routine successfully completed.

0 Nonradix character in the input string or a sign in any position other than the first character. An overflow from 64 bits (unsigned) causes an error.

LIB$DATE_TIME

The Date and Time Returned as a String routine returns the OpenVMS system date and time in the semantics of a user-provided string.

Format

LIB$DATE_TIME date-time-string

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

date-time-string

OpenVMS usage: time_name

type: character string

access: write only

mechanism: by descriptor

Destination string into which LIB$DATE_TIME writes the system date and time. The date-time-string argument is the address of a descriptor pointing to the destination string. This string is 23 characters long; its format is as follows:
dd-mmm-yyyy hh:mm:ss.hh
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$_STRTRU Success, but destination string was truncated.

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.

Example


10 !+ ! This BASIC program demonstrates the use of LIB$DATE_TIME. !- CALL LIB$DATE_TIME(DSTSTR$) PRINT DSTSTR$ 99 END

This BASIC program uses LIB$DATE_TIME to display the current system date and time. The output generated by one run of this program follows:

26-JUL-1995 13:41:22.67

LIB$DAY

The Day Number Returned as a Longword Integer routine returns the number of days since the system zero date of November 17, 1858, or the number of days from November 17, 1858, to a user-supplied date.

Format

LIB$DAY number-of-days [,user-time] [,day-time]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

number-of-days

OpenVMS usage: longword_signed

type: longword integer (signed)

access: write only

mechanism: by reference

Number of days since the system zero date. The number-of-days argument is the address of a signed longword integer containing the day number.
user-time

OpenVMS usage: date_time

type: quadword (unsigned)

access: read only

mechanism: by reference

User-supplied time, in 100-nanosecond units. The user-time argument is the address of a signed quadword integer containing the user time. A positive value indicates an absolute time, while a negative value indicates a delta time. This is an optional argument. If user-time is omitted, the default is the current system time. This quadword time value is obtained by calling the $BINTIM system service.
If time is passed as zero by value, the numeric value for the current day is returned. If time is passed as a zero by reference, the number returned represents the day of November 17, 1858, rather than the current day.
day-time

OpenVMS usage: longword_signed

type: longword integer (signed)

access: write only

mechanism: by reference

Number of 10-millisecond units since midnight of the user-time argument. The day-time argument is the address of a signed longword integer into which LIB$DAY writes this number of units.

Description

LIB$DAY returns the number of days since the system zero date of November 17, 1858. Optionally, the caller can supply a time in system time format to be used instead of the current system time. In this case, LIB$DAY returns the number of days from November 17, 1858, to the user-supplied date.
The number of 10-millisecond units since midnight is an optional return argument.

Note
If the caller supplies a quadword time, it is not verified. If it is negative (bit 63 on), the number-of-days value returned is negative.

The Run-Time Library provides the date/time utility routines for languages that do not have built-in time and date functions and for particular applications that require the time or date in a different format from the one that the language supplies. In general, it is simpler to call the Run-Time Library routines for the system date and time than to call a system service.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_INTOVF The optional argument user-time is present and represents a date and time well beyond the year 9999.

Example


PROGRAM DAY(INPUT, OUTPUT); {+} { This is a VAX Pascal example program showing { the use of LIB$DAY. {-} VAR DAYNUMBER : INTEGER; routine LIB$DAY(VAR DAYNUM : INTEGER); EXTERN; BEGIN LIB$DAY(DAYNUMBER); WRITELN('The day number is ', DAYNUMBER); END.

PROGRAM DAY(INPUT, OUTPUT); 
 
{+} 
{ This is a VAX Pascal example program showing 
{ the use of LIB$DAY. 
{-} 
 
VAR 
  DAYNUMBER : INTEGER; 
 
routine LIB$DAY(VAR DAYNUM : INTEGER); 
  EXTERN; 
 
BEGIN 
  LIB$DAY(DAYNUMBER); 
  WRITELN('The day number is ', DAYNUMBER); 
END.

This Pascal program retrieves and prints the day number. A sample of the output generated by this program is as follows.
The day number is 46738

LIB$DAY_OF_WEEK

The Show Numeric Day of Week routine returns the numeric day of the week for an input time value. If 0 is the input time value, the current day of the week is returned. The days are numbered 1 through 7, with Monday as day 1 and Sunday as day 7.

Format

LIB$DAY_OF_WEEK [user-time,] day-number

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

user-time

OpenVMS usage: date_time

type: quadword (unsigned)

access: read only

mechanism: by reference

Time to be translated to a day of the week, or zero. The optional user-time argument is the address of an unsigned quadword containing the value of time. Time must be supplied as an absolute system time. To obtain this time value in proper quadword format, call the $BINTIM system service.
If time is passed as zero by value, the numeric value for the current day is returned. If time is passed as a zero by reference, the number returned represents the day of November 17, 1858. If the user-time argument is omitted, it is equivalent to passing a zero by value.
day-number

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by reference

Numeric day of week. The day-number argument is the address of a longword into which LIB$DAY_OF_WEEK writes the integer value representing the day of the week.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

Example


PROGRAM DAYOFWEEK(INPUT, OUTPUT); {+} { This is an example showing { the use of LIB$DAY_OF_WEEK. {-} VAR OUTDAT : INTEGER; routine LIB$DAY_OF_WEEK(TIM : INTEGER; %REF OUTDA : INTEGER); EXTERN; BEGIN LIB$DAY_OF_WEEK(%IMMED 0, OUTDAT); WRITELN(OUTDAT); END.

PROGRAM DAYOFWEEK(INPUT, OUTPUT); 
 
{+} 
{ This is an example showing 
{ the use of LIB$DAY_OF_WEEK. 
{-} 
 
VAR 
  OUTDAT : INTEGER; 
 
routine LIB$DAY_OF_WEEK(TIM : INTEGER; %REF OUTDA : INTEGER); EXTERN; 
 
BEGIN 
 
  LIB$DAY_OF_WEEK(%IMMED 0, OUTDAT); 
  WRITELN(OUTDAT); 
 
END.

This Pascal program shows the use of LIB$DAY_OF_WEEK. This example was tested on a Monday, and the output generated was 1.

LIB$DECODE_FAULT

The Decode Instruction Stream During Fault routine is a tool for building condition handlers that process instruction fault exceptions. It is called from a condition handler.

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 not available to native OpenVMS Alpha programs but is available to translated VAX images.

Format

LIB$DECODE_FAULT signal-arguments ,mechanism-arguments ,user-procedure [,unspecified-user-argument] [,instruction-definitions]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

signal-arguments

OpenVMS usage: vector_longword_unsigned

type: unspecified

access: read only

mechanism: by reference, array reference

Signal arguments array that was passed from the OpenVMS operating system to your condition handler. The signal-arguments argument is the address of the signal arguments array.
mechanism-arguments

OpenVMS usage: vector_longword_unsigned

type: unspecified

access: read only

mechanism: by reference, array reference

Mechanism arguments array that was passed from OpenVMS to your condition handler. The mechanism-arguments argument is the address of the mechanism arguments array.
user-procedure

OpenVMS usage: procedure

type: procedure value

access: call after stack unwind

mechanism: by descriptor, procedure descriptor

User-supplied action routine that LIB$DECODE_FAULT calls to handle the exception. The user-procedure argument is the address of a descriptor pointing to your user action routine. The user-procedure argument may be of type "procedure value" when called by languages with up-level addressing. If user-procedure is not of type "bound routine value," it is assumed to be the address of an entry mask.
For further information on the user action routine, see the section called Call Format for a User Action Routine in the Description section.
unspecified-user-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by value

Additional information passed from your handler without interpretation to your user action routine. The unspecified-user-argument argument contains the value of this additional information. The unspecified-user-argument argument is optional; if it is omitted, zero is used as the default.
instruction-definitions

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: read only

mechanism: by reference, array reference

Array of bytes specifying instruction opcodes and operand definitions that are to replace or supplement the standard instruction definitions. The instruction-definitions argument is the address of this array.
If instruction-definitions is omitted, only the standard instruction definitions are used. If supplied, instruction-definitions is searched first, followed by the standard definitions.
Each instruction definition consists of a series of bytes, the first one or two of which is the instruction opcode. If the instruction is a 2-byte opcode, the escape byte, which must be hex FD, FE, or FF, is placed in the first of the two bytes. Following the opcode may be from 0 to 16 operand definition bytes. These bytes indicate the operand's access type and data type.
The end of each instruction definition is denoted by a byte containing the value LIB$K_DCFOPR_END (zero). The list of instruction definitions is terminated by two bytes, each of which contains the value --1 (hexadecimal FF). For further information, see the section called Instruction Operand Definition Codes in the Description section.

Description

The Description section of the LIB$DECODE_FAULT routine is divided into the following parts:

Guidelines for Using LIB$DECODE_FAULT
Exceptions Recognized by LIB$DECODE_FAULT
Instruction Operand Definition Codes
Call Format for a User Action Routine
Call Format for a Signal Routine

Guidelines for Using LIB$DECODE_FAULT

LIB$DECODE_FAULT is a tool for building condition handlers that process instruction fault exceptions. Called from a condition handler, LIB$DECODE_FAULT performs the following actions:

Unwinds intermediate stack frames back to that of the exception
Decodes the instruction stream to determine the operation and its operands
Calls a user-supplied action routine and passes it a consistent and easy-to-access description of the instruction's context

Your user action routine performs whatever tasks are necessary to handle the fault and returns to LIB$DECODE_FAULT. LIB$DECODE_FAULT then restores the context as modified by your user action routine and continues execution.
Your condition handler must first decide whether or not it wants to handle the exception. The signal arguments list contains the exception code and the address of the program context (PC) that is usually sufficient for this determination. Once LIB$DECODE_FAULT is called, if the exception is a fault LIB$DECODE_FAULT can analyze, control does not return to the condition handler. Therefore, your handler must not depend on regaining control by a routine return once it has called LIB$DECODE_FAULT. With your user action routine, LIB$DECODE_FAULT makes the original fault disappear.

Note
Your user action routine is capable of generating a new exception, including one that looks identical to the original exception. Your user action routine may also resignal, but if the decision to resignal is made inside the user action routine, all post-signal stack frames are lost.

Once your condition handler has decided that it wants to handle the exception, it calls LIB$DECODE_FAULT, passing as arguments the addresses of the signal and mechanism argument lists and a descriptor for your user action routine entry point. LIB$DECODE_FAULT then performs the following actions:

Determines if the exception is a fault it understands. If not, it returns SS$_RESIGNAL.
Determines the context in which the exception occurred, including register and processor status longword (PSL) contents, and saves it.
Unwinds all stack frames back to that frame in which the exception occurred.
Evaluates each operand's addressing mode, computing the resulting location for the operand. Immediate mode operands are expanded into their full form. If an invalid addressing mode is found, an SS$_RADRMOD exception is generated.
Unless the original exception was SS$_ACCVIO, tests each operand for accessibility. If necessary, an access violation is signaled as if the instruction had tried to execute normally. See the paragraph following this list for more information.
Unless the original exception was SS$_ROPRAND, tests each floating-point operand that is to be read for a reserved floating operand. If necessary, a reserved operand fault is signaled. See the paragraph following this list for more information.
Determines the address of the next sequential instruction.
Calls your user action routine with arguments as described below.
Upon return from your user action routine, reflects changes to the registers and PSL and continues execution at the instruction address specified by your user action routine. Optionally, your user action routine may resignal the original exception.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

5932PRO_009.HTML

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

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

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

1	Routine successfully completed.
0	Nonradix character in the input string or a sign in any position other than the first character. An overflow from 32 bits (unsigned) causes an error.

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	write only
mechanism:	by reference

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

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Success, but destination string was truncated.
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.

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

SS$_NORMAL	Routine successfully completed.
SS$_INTOVF	The optional argument user-time is present and represents a date and time well beyond the year 9999.

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

OpenVMS usage:	vector_longword_unsigned
type:	unspecified
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	procedure
type:	procedure value
access:	call after stack unwind
mechanism:	by descriptor, procedure descriptor

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

OpenVMS usage:	vector_byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by reference, array reference