Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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-

            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.

> 1. The string is converted to uppercase using STR$UPCASE so that the search for words will ignore the case of letters.
> 2. 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.
> 3. 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.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_041.HTML