 |
OpenVMS RTL Library (LIB$) Manual
This C example demonstrates the use of a condition handler to capture
the signal generated by LIB$SIGNAL. The output is as follows:
$ CC SIGNAL.C
$ LINK SIGNAL
$ RUN SIGNAL
*** Caught signal:
00000006
00000014
0000000C
00000002
0000FACE
000201A0
0000001B
%SYSTEM-F-BADPARAM, bad parameter value
-SYSTEM-F-ACCVIO, access violation, reason mask=02,
virtual address=000000000000FACE, PC=00000000000201A0, PS=0000001B
%TRACE-F-TRACEBACK, symbolic stack dump follows
image module routine line rel PC abs PC
SIGNAL SIGNAL main 5961 00000000000001A0 00000000000201A0
SIGNAL SIGNAL __main 0 0000000000000050 0000000000020050
0 FFFFFFFF82204914 FFFFFFFF82204914
|
LIB$SIG_TO_RET
The Signal Converted to a Return Status routine converts any signaled
condition value to a value returned as a function. The signaled
condition is returned to the caller of the user routine that
established the handler that is calling LIB$SIG_TO_RET. This routine
may be established as or called from a condition handler.
Format
LIB$SIG_TO_RET signal-arguments ,mechanism-arguments
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 argument vector. The signal-arguments argument
contains the address of an array that is this signal argument vector
stack.
See the OpenVMS Programming Concepts Manual for a description of the signal argument vector.
mechanism-arguments
| OpenVMS usage: |
structure |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Mechanism arguments vector. The mechanism-arguments
argument contains the address of a structure that is this mechanism
argument vector stack.
See the OpenVMS Programming Concepts Manual for a description of the mechanism argument
vector.
Description
LIB$SIG_TO_RET is called with the argument list that was passed to a
condition handler by the OpenVMS Condition Handling Facility. The
signaled condition is converted to a value returned to the routine that
called the routine that established the handler. That action is
performed by unwinding the stack to the caller of the establisher of
the condition handler. The condition code is returned as the value in
R0. See the OpenVMS Programming Concepts Manual for more information on condition handling.
LIB$SIG_TO_RET causes the stack to be unwound to the caller of the
routine that established the handler which was called by the signal.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed; SS$_UNWIND completed. Otherwise, the
error code from SS$_UNWIND is returned.
|
Example
|
C+
C This Fortran example demonstrates how to use LIB$SIG_TO_RET.
C
C This function subroutine inverts each entry in an array. That is,
C a(i,j) becomes 1/a(i,j). The subroutine has been declared as an integer
C function so that the status of the inversion may be returned. The status
C should be success, unless one of the a(i,j) entries is zero. If one of
C the a(i,j) = 0, then 1/a(i,j) is division by zero. This division by zero
C does not cause a division by zero error, rather, the routine will return
C signal a failure.
C-
INTEGER*4 FUNCTION FLIP(A,N)
DIMENSION A(N,N)
EXTERNAL LIB$SIG_TO_RET
CALL LIB$ESTABLISH (LIB$SIG_TO_RET)
FLIP = .TRUE.
C+
C Flip each entry.
C-
DO 1 I = 1, N
DO 1 J = 1, N
1 A(I,J) = 1.0/A(I,J)
RETURN
END
C+
C This is the main code.
C-
INTEGER STATUS, FLIP
REAL ARRAY_1(2,2),ARRAY_2(3,3)
DATA ARRAY_1/1,2,3,4/,ARRAY_2/1,2,3,5,0,5,6,7,2/
CHARACTER*32 TEXT(2),STRING
DATA TEXT(1)/' This array could be flipped. '/,
1 TEXT(2)/' This array could not be flipped.'/
STRING = TEXT(1)
STATUS = FLIP(ARRAY_1,2)
IF ( .NOT. STATUS) STRING = TEXT(2)
TYPE '(a)', STRING
STRING = TEXT(1)
STATUS = FLIP(ARRAY_2,3)
IF ( .NOT. STATUS) STRING = TEXT(2)
TYPE '(a)', STRING
END
|
This Fortran example program inverts each entry in an array. The output
generated by this program is as follows:
This array could be flipped.
This array could not be flipped.
|
LIB$SIG_TO_STOP
The Convert a Signaled Condition to a Signaled Stop routine converts a
signaled condition to a signaled condition that cannot be continued.
Format
LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments
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: |
modify |
| mechanism: |
by reference, array reference |
Signal argument vector. The signal-arguments argument
contains the address of an array that is this signal argument vector
stack.
See the OpenVMS Programming Concepts Manual for a description of the signal argument vector.
mechanism-arguments
| OpenVMS usage: |
structure |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
Mechanism argument vector. The mechanism-arguments
argument contains the address of a structure that is this mechanism
argument vector stack.
See the OpenVMS Programming Concepts Manual for a description of the mechanism argument
vector.
Description
LIB$SIG_TO_STOP causes a signal to appear as though it had been
signaled by a call to LIB$STOP. When a signal is generated by LIB$STOP,
the severity code is forced to SEVERE and control cannot return to the
routine that signaled the condition. LIB$SIG_TO_STOP may be enabled as
a condition handler for a routine or it may be called from a condition
handler.
If the condition value in signal-arguments is
SS$_UNWIND, then LIB$SIG_TO_STOP returns the error condition
LIB$_INVARG.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed; SS$_UNWIND completed. Otherwise, the
error code from SS$_UNWIND is returned.
|
|
LIB$_INVARG
|
Invalid argument. The condition code in
signal-arguments is SS$_UNWIND.
|
LIB$SIM_TRAP
The Simulate Floating Trap routine converts floating faults to floating
traps. It can be enabled as a condition handler or can be called by one.
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$SIM_TRAP signal-arguments ,mechanism-arguments
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: |
modify |
| mechanism: |
by reference, array reference |
Signal argument vector. The signal-arguments argument
contains the address of an array that is this signal argument vector
stack.
See the OpenVMS Programming Concepts Manual for a description of the signal argument vector.
mechanism-arguments
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference, array reference |
Mechanism argument vector. The mechanism-arguments
argument contains the address of an array that is this mechanism
argument vector stack.
See the OpenVMS Programming Concepts Manual for a description of the mechanism argument
vector.
Description
LIB$SIM_TRAP converts floating faults to floating traps. It can be
enabled as a condition handler or can be called by one.
LIB$SIM_TRAP intercepts floating overflow, underflow, and
divide-by-zero faults. It simulates the instruction causing the
condition up to the point where a fault should be signaled, then
signals the corresponding floating trap.
Since LIB$SIM_TRAP nullifies the condition handling for the original
fault condition, the final condition signaled by the routine will be
from the context of the instruction itself, rather than from the
condition handler. The signaling path is identical to that of a
hardware-generated trap. The signal argument vector is placed so the
last entry in the vector will be the user's stack pointer at the
completion of the instruction (for a trap), or at the beginning of the
instruction (for a fault).
See the VAX Architecture Reference Manual for more information on faults and traps.
Condition Values Returned
|
SS$_RESIGNAL
|
Resignal condition to next handler. The exception was one that
LIB$SIM_TRAP could not handle.
|
LIB$SKPC
The Skip Equal Characters routine compares each character of a given
string with a given character and returns the relative position of the
first nonequal character as an index. LIB$SKPC makes the VAX SKPC
instruction available as a callable routine.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent
operation.
|
Format
LIB$SKPC character-string ,source-string
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The relative position in the source string of the first unequal
character. LIB$SKPC returns a zero if the source string was of zero
length or if every character in source-string was
equal to character-string.
Arguments
character-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String whose initial character is to be used by LIB$SKPC in the
comparison. The character-string argument contains the
address of a descriptor pointing to this string. Only the first
character of character-string is used, and the length
of character-string is not checked.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String to be searched by LIB$SKPC. The source-string
argument contains the address of a descriptor pointing to this string.
Description
LIB$SKPC compares the initial character of
character-string with successive characters of
source-string until it finds an inequality or reaches
the end of the source-string. It returns the relative
position of this unequal character as an index, which is the relative
position of the first occurrence of a substring in the source string.
Condition Values Returned
None.
Example
|
C+
C This Fortran example program shows the use of LIB$SKPC.
C LIB$SKPC compares each character of a given string with a given character.
C It returns the relative position of the first nonequal character as an index.
C-
I = LIB$SKPC (' ', ' ABC')
TYPE 1, I
1 FORMAT(' The blank character matches the',I2,'nd character in')
TYPE *,'the string " ABC"'
J = LIB$SKPC ('A', 'AAA')
TYPE 2, J
2 FORMAT(' The character "A" matches the',I2,'th character in')
TYPE *,'the string " AAA"'
END
|
This Fortran example generates the following output:
The blank character matches the 2nd character in
the string " ABC"
The character "A" matches the 0th character in
the string " AAA"
|
LIB$SPANC
The Skip Selected Characters routine is used to skip a specified set of
characters in the source string. LIB$SPANC makes the VAX SPANC
instruction available as a callable routine.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent
operation.
|
Format
LIB$SPANC source-string ,table-array ,byte-integer-mask
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The relative position in the source string of the character that
terminated the operation is returned if such a character is found.
Otherwise, zero is returned. If the source string has a zero length,
then a zero is returned.
Arguments
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string used by LIB$SPANC to index into
table-array. The source-string
argument contains the address of a descriptor pointing to this source
string.
table-array
| OpenVMS usage: |
vector_mask_byte |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Table that LIB$SPANC indexes into and performs an AND operation with
the byte-integer-mask byte. The
table-array argument contains the address of an
unsigned byte array that is this table.
byte-integer-mask
| OpenVMS usage: |
mask_byte |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Mask that an AND operation is performed with bytes in
table-array. The byte-integer-mask
argument contains the address of an unsigned byte that is this mask.
Description
LIB$SPANC uses successive bytes of the string specified by
source-string to index into a table. An AND operation
is performed on the byte selected from the table and the mask byte.
The operation is terminated when the result of the AND operation is
zero.
Condition Values Returned
None.
Example
|
!+
! This Fortran program demonstrates how to use
! LIB$SCANC and STR$UPCASE.
!
! Declare the Run-Time Library routines to be used.
!-
INTEGER*4 STR$UPCASE ! Translate to upper case
INTEGER*4 LIB$SCANC ! Look for characters
INTEGER*4 LIB$SPANC ! Skip over characters
!+
! Declare the alphabet from which "words" are constructed.
!-
CHARACTER*(38) ALPHABET
DATA ALPHABET /'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789$_'/
!+
! Local variable declarations
!-
INTEGER*4 WORD_COUNT /0/ ! Count of words found
INTEGER*4 WORD_LENGTH /0/ ! Length of a word
INTEGER*4 TOTAL_LENGTH /0/ ! Sum of word lengths
INTEGER*4 START_POS /0/ ! Position of start of word
INTEGER*4 END_POS /0/ ! Position of end of word
REAL*4 AVERAGE_LENGTH /0.0/ ! Average length of words
CHARACTER*80 LINE ! Line to examine for words
BYTE MATCH_TABLE(0:255) /256*0/ ! Match table for scanning
!+
! The routines LIB$SCANC and LIB$SPANC require a table with an entry
! for each possible character. Create a match table from ALPHABET
! with an entry of 1 if the character is in ALPHABET, 0 otherwise.
! MATCH_TABLE has already been initialized to zeros.
!-
DO I = 1, LEN(ALPHABET)
MATCH_TABLE(ICHAR(ALPHABET(I:I))) = 1
END DO
!+
! Loop forever finding words in LINE. When LINE is exhausted,
! indicated by a START_POS of zero, read another one. Upon
! end-of-file, leave the loop and print the statistics.
!-
OPEN( UNIT = 1, FILE = 'TEST.DAT', TYPE = 'OLD' )
DO WHILE (.TRUE.)
DO WHILE (START_POS .EQ. 0) ! Get a new line
READ (1,'(A)',END=900) LINE ! If EOF, skip to 900
CALL STR$UPCASE (LINE,LINE) ! Convert to upper
! case for matching
START_POS = LIB$SCANC (LINE,MATCH_TABLE,1) ! Find beginning
END DO ! of first word
!+
! START_POS now points to the beginning of a word. Call LIB$SPANC to
! find the first character that is not part of the word. Set
! START_POS to beginning of next word. If LIB$SPANC does not
! find a non-word character, it returns zero.
!-
END_POS =
1 START_POS + LIB$SPANC (LINE(START_POS:), MATCH_TABLE,1) - 1
IF (END_POS .LT. START_POS) THEN ! Word goes to end of line
WORD_LENGTH = (LEN(LINE) + 1) - START_POS
START_POS = 0 ! Indicate line exhausted
ELSE
WORD_LENGTH = END_POS - START_POS
START_POS =
1 END_POS + LIB$SCANC (LINE(END_POS:),MATCH_TABLE,1) - 1
IF (START_POS .LT. END_POS) START_POS = 0 ! No more words on line
END IF
!+
! Update count and length statistics.
!-
WORD_COUNT = WORD_COUNT + 1
TOTAL_LENGTH = TOTAL_LENGTH + WORD_LENGTH
END DO
900 CONTINUE
!+
! Compute average word length and display statistics.
!-
IF (WORD_COUNT .NE. 0)
1 AVERAGE_LENGTH = FLOAT(TOTAL_LENGTH) / FLOAT(WORD_COUNT)
TYPE 901,WORD_COUNT,AVERAGE_LENGTH
901 FORMAT (1X,I10,' words found, average length was ',
1 F4.1,' letters.')
CLOSE (1)
END
|
This Fortran program reads text from the default input unit and looks
for words. A word is defined as a string containing only the characters
A through Z (uppercase or lowercase), 0 through 9, and the dollar sign
($) and underscore (_) symbols. The program reports the total number of
words found and their average length.
The program uses three Run-Time Library routines: STR$UPCASE,
LIB$SCANC, and LIB$SPANC.
- The string is converted to uppercase using STR$UPCASE so that the
search for words will ignore the case of letters.
- LIB$SCANC searches through the string for one of a set of
characters, the set being specified as nonzero elements in a 256-byte
table.
- Similarly, LIB$SPANC uses the VAX SPANC instruction to search
through a string for a character whose table entry is not zero.
Note
On Alpha systems, OpenVMS Alpha instructions perform the equivalent
operation.
|
The value returned by each routine is the index into the string where
the first matching (or nonmatching) character was found, or zero if no
match was found.
The output generated by this Fortran program is as follows:
12 words found, average length was 4.2 letters.
|
|
