OpenVMS RTL Library (LIB$) Manual

Document revision date: 19 July 1999

OpenVMS RTL Library (LIB$) Manual

Contents

Index

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- INTEGER4 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/ CHARACTER32 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

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

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. !- INTEGER4 STR$UPCASE ! Translate to upper case INTEGER4 LIB$SCANC ! Look for characters INTEGER4 LIB$SPANC ! Skip over characters !+ ! Declare the alphabet from which "words" are constructed. !- CHARACTER(38) ALPHABET DATA ALPHABET /'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789$_'/ !+ ! Local variable declarations !- INTEGER4 WORD_COUNT /0/ ! Count of words found INTEGER4 WORD_LENGTH /0/ ! Length of a word INTEGER4 TOTAL_LENGTH /0/ ! Sum of word lengths INTEGER4 START_POS /0/ ! Position of start of word INTEGER4 END_POS /0/ ! Position of end of word REAL4 AVERAGE_LENGTH /0.0/ ! Average length of words CHARACTER80 LINE ! Line to examine for words BYTE MATCH_TABLE(0:255) /2560/ ! 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 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.

Contents

Index

privacy and legal statement

5932PRO_040.HTML

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

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

OpenVMS usage:	structure
type:	unspecified
access:	read only
mechanism:	by reference

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.

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

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

OpenVMS usage:	mask_byte
type:	byte (unsigned)
access:	read only
mechanism:	by reference