HP OpenVMS systems documentation

The Stop Execution and Signal the Condition routine generates a signal that indicates that an exception condition has occurred in your program. Exception conditions signaled by LIB$STOP cannot be continued from the point of the signal.

Format

LIB$STOP condition-value [,number-of-arguments] [,FAO-argument...]

RETURNS

LIB$STOP generates a signal and stops execution of the calling program. No condition values are returned.

Arguments

condition-value

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

OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value.

The HP OpenVMS Programming Concepts Manual explains the format of a condition value.

number-of-arguments

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

Number of FAO arguments associated with condition-value. The optional number-of-arguments argument is a signed longword integer that contains this number. If omitted or specified as zero, no FAO arguments follow.

FAO-argument

OpenVMS usage:	varying_arg
type:	unspecified
access:	read only
mechanism:	by value

Optional FAO (formatted ASCII output) argument that is associated with the specified condition value.

The HP OpenVMS Programming Concepts Manual explains the message format.

Description

LIB$STOP is called whenever your program must indicate an exception condition because it is impossible to continue execution or return a status code to the calling program.

LIB$STOP scans the stack frame by frame, starting with the most recent frame, calling each established handler (see the HP OpenVMS Programming Concepts Manual). LIB$STOP guarantees that control will not return to the caller.

The LIB$STOP argument list, the Program Counter (PC) and Processor Status Longword (PSL on OpenVMS VAX systems, PS on OpenVMS Alpha and I64 systems) of the caller are appended to build the signal argument vector.

The severity of condition-value is forced to SEVERE before each call to a handler.

If any handler attempts to continue by returning a success completion code, the error message ATTEMPT TO CONTINUE FROM STOP is printed and your program exits.

If the handler called by LIB$STOP in turn calls system service $UNWIND, control will not return to LIB$STOP's caller, thus changing the program flow. A handler can also modify the saved copy of R0/R1 in the mechanism vector, changing registers R0 and R1 after the stack has been unwound. If a handler does neither of these things, then all registers including R0/R1 and the hardware condition codes are preserved.

Note On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform the equivalent operation.

The only way a handler can prevent the image from exiting after a call to LIB$STOP is to unwind the stack using the $UNWIND system service.

Condition Values Returned

None.

Example

10 EXTERNAL LONG FUNCTION LIB$RESERVE_EF 
   DECLARE LONG RET_STATUS 
 
   RET_STATUS = LIB$RESERVE_EF( 2% ) 
   IF (RET_STATUS AND 1%) = 0% THEN 
       CALL LIB$STOP( RET_STATUS BY VALUE ) 
   END IF 
 
   PRINT "Event flag 2 reserved successfully" 
 
   END 
 
      

This BASIC example program uses LIB$STOP to stop executing if an error is signaled. This BASIC program tries to reserve an event flag that is not accessible to user programs, thus ensuring that an error will be signaled.

The output generated by this BASIC program is as follows:

%LIB-F-EF_ALRRES, event flag already reserved %TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line rel PC abs PC 2822XBLST$MAIN 2822XBLST$MAIN 6 00000044 00000644

The Multiple-Precision Binary Subtraction routine performs subtraction on signed two's complement integers of arbitrary length.

Format

LIB$SUBX minuend-array ,subtrahend-array ,difference-array [,array-length]

RETURNS

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

Arguments

minuend-array

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

Minuend; a multiple-precision, signed two's complement integer. The minuend-array argument is the address of an array of signed longword integers that contains the minuend.

subtrahend-array

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

Subtrahend; a multiple-precision, signed two's complement integer. The subtrahend-array argument is the address of an array of signed longword integers that contains the subtrahend.

difference-array

OpenVMS usage:	vector_longword_signed
type:	unspecified
access:	write only
mechanism:	by reference, array reference

Difference; a multiple-precision, signed two's complement integer result. The difference-array argument is the address of an array of signed longword integers that contains the difference.

array-length

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

Length in longwords of the arrays to be operated on by LIB$SUBX. The array-length argument contains the address of a signed longword integer that is this length. The array-length argument must not be negative. The default length is 2 units.

Description

LIB$SUBX performs subtraction on signed two's complement integers of arbitrary length. The integers are located in arrays of longwords. The higher addresses contain the higher-precision parts of the values. The highest-addressed longword contains the sign and 31 bits of precision. The remaining longwords contain 32 bits of precision in each. The number of longwords to be operated on is given by the optional argument, array-length. The default length is 2, which corresponds to the OpenVMS quadword data type.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_INTOVF	Integer overflow. The result is correct, except that the sign bit is lost.
LIB$_INVARG	Invalid argument. Length is negative. The output array is unchanged.

Example

C+ 
C This Fortran example program demonstrates the use of LIB$SUBX. 
C- 
        INTEGER A(2),B(2),C(2),RETURN 
C+ 
C Let "A" have the value 72057594037927937 = '1000000000000001'x. 
C Let "B" have the value 4294967295        = '00000000FFFFFFFF'x. 
C- 
        A(1) = '00000001'x 
        A(2) = '10000000'x 
        B(1) = 'FFFFFFFF'x 
        B(2) = '00000000'x 
C+ 
C Then "A" - "B" is 72057589742960642. 
C- 
        RETURN = LIB$SUBX(A,B,C) 
        TYPE *,' ' 
        TYPE *,'Let A = 72057594037927937 and B = 4294967295.' 
        TYPE *,'Then C = A - B = 72057589742960642.' 
        TYPE 2,C(2),C(1) 
2       FORMAT(' 72057589742960642 is represented as ',1H',Z8,Z8,3H'x.) 
        TYPE *, 51HThat is, C(2) = '0FFFFFFF'x and C(1) = '00000002'x. 
        END 
 
      

This Fortran example demonstrates how to call LIB$SUBX. The output generated by this program is as follows:

Let A = 72057594037927937 and B = 4294967295. Then C = A - B = 72057589742960642. 72057589742960642 is represented as ' FFFFFFF 2'x. That is, C(2) = '0FFFFFFF'x and C(1) = '00000002'x.

The Subtract Two Quadword Times routine subtracts two OpenVMS internal-time-format times.

Format

LIB$SUB_TIMES time1 ,time2 ,resultant-time

RETURNS

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

Arguments

time1

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

First time, from which LIB$SUB_TIMES subtracts the second time. The time1 argument is the address of an unsigned quadword containing this time. The time1 argument must represent a later or equal time or a longer or equal time interval than time2. The time1 argument may be either absolute time or delta time as long as time2 is of the same type. If time1 and time2 are of different types, time1 must be the absolute time.

time2

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

Second time, which LIB$SUB_TIMES subtracts from the first time. The time2 argument is the address of an unsigned quadword containing this time. The time2 argument must represent an earlier or equal time or a shorter or equal time interval than time1. The time2 argument may be either absolute time or delta time as long as time1 is of the same type. If time2 and time1 are of different types, time2 must be the delta time.

resultant-time

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

The result of subtracting time2 from time1. The resultant-time argument is the address of an unsigned quadword containing the result. If both time1 and time2 are delta times, then resultant-time is a delta time. If both time1 and time2 are absolute times, then resultant-time is a delta time. If time1 is an absolute time and time2 is a delta time, then resultant-time is an absolute time.

Description

LIB$SUB_TIMES subtracts two OpenVMS internal times. The second time, specified by time2, is subtracted from time1. The following table shows the only combinations of times you can subtract:

Time1	Time2	Subtraction	Resultant-Time
delta	delta	time1 - time2	delta
absolute	absolute	time1 - time2	delta
absolute	delta	time1 - time2	absolute

Delta time values cannot be a zero and always reflect ime in the future. Binary format number will always be negative. Therefore, if time1 and time2 are equal, resultant-time cannot be 0. Instead, resultant-time is represented by .1 of one microsecond (the smallest interval of time recognized by the OpenVMS operating system). This interval is shown as "0 00:00:00.00" when formatted by the standard techniques.

Condition Values Returned

LIB$_NORMAL	Routine successfully completed.
LIB$_INVARGORD	Invalid ordering of arguments.
LIB$_IVTIME	Invalid time.
LIB$_NEGTIM	Negative time computed.
LIB$_WRONUMARG	Incorrect number of arguments.

The Invoke $ASCTIM to Convert Binary Time to ASCII String routine calls the system service $ASCTIM to convert a binary date and time value, returning the ASCII string using the semantics of the caller's string.

Format

LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time] [,flags]

RETURNS

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

Arguments

resultant-length

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

Number of bytes written into time-string, not counting padding in the case of a fixed-length string. The resultant-length argument contains the address of an unsigned word integer that is this number.

If the input string is truncated to the size specified in the time-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 time-string.

time-string

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

Destination string into which LIB$SYS_ASCTIM writes the ASCII time string. The time-string argument contains the address of a descriptor pointing to the destination string.

user-time

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

Value that LIB$SYS_ASCTIM converts to ASCII string form. The user-time argument contains the address of a signed quadword integer that is this value.

If 0 or no address is specified, the current system date and time are returned. A positive value represents an absolute time. A negative value represents a delta time. Delta times must be less than 10,000 days.

flags

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

Conversion indicator specifying which date and time fields LIB$SYS_ASCTIM should return. The flags argument is the address of an unsigned bit mask that contains this conversion indicator.

A value of 1 causes only the hour, minute, second, and hundredths of a second to be returned, depending on the length of the buffer. A value of 0 (the default) causes the full date and time to be returned, depending on the length of the buffer.

The results of specifying some possible combinations for the values of the flags and time-string arguments are shown below:

Time Value	Time-String Length	Flags Value	Information Returned
Absolute	23	0	Date and time
Absolute	12	0	Date
Absolute	11	1	Time
Delta	16	0	Days and time
Delta	11	1	Time

The flags argument is passed to LIB$SYS_ASCTIM by reference and is changed to value for use by $ASCTIM.

Description

See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $ASCTIM.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_IVTIME	The specified delta time is greater than or equal to 10,000 days.
LIB$_FATERRLIB	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your HP support representative.
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.
LIB$_STRTRU	Routine successfully completed, but the source string was truncated on copy.

The Invoke $FAO System Service to Format Output routine calls the $FAO system service, returning a string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs.

Format

LIB$SYS_FAO character-string, [resultant-length] ,resultant-string [,directive-argument ,...]

RETURNS

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

Arguments

character-string

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

ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string.

resultant-length

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

Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length.

resultant-string

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

Fully formatted output string returned by LIB$SYS_FAO. The resultant-string argument contains the address of a descriptor pointing to this output string.

directive-argument

OpenVMS usage:	varying_arg
type:	unspecified
access:	read only
mechanism:	unspecified

Directive argument contained in longwords. Depending on the directive, a directive-argument argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAO system service.

Description

See the HP OpenVMS System Services Reference Manual: A--GETUAI for a complete description of $FAO.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_BADPARAM	An invalid directive was specified in the FAO control string.
SS$_BUFFEROVF	Successfully completed, but the formatted output string overflowed the output buffer and was truncated.
LIB$_STRTRU	Success, but the source string was truncated on copy.
LIB$_INSVIRMEM	Insufficient virtual memory to allocate dynamic string.
LIB$_INVSTRDES	Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.