[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


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 or I64 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 HP 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 HP 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 and I64 systems, OpenVMS Alpha and I64 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 and I64 systems, OpenVMS Alpha and I64 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 and I64 systems, OpenVMS Alpha and I64 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.

LIB$SPAWN

The Spawn Subprocess routine requests the command language interpreter (CLI) of the calling process to spawn a subprocess for executing CLI commands. LIB$SPAWN provides the same function as the DCL command SPAWN.

Format

LIB$SPAWN [command-string] [,input-file] [,output-file] [,flags] [,process-name] [,process-id] [,completion-status-address] [,byte-integer-event-flag-num] [,AST-address] [,varying-AST-argument] [,prompt-string] [,cli] [,table]


RETURNS


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


Arguments

command-string


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

CLI command to be executed by the spawned subprocess. The command-string argument is the address of a descriptor pointing to this CLI command string. If command-string is omitted, commands are taken from the file specified by input-file.

input-file


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

Equivalence name to be associated with the logical name SYS$INPUT in the logical name table for the subprocess. The input-file argument is the address of a descriptor pointing to this equivalence string. If input-file is omitted, the default is the caller's SYS$INPUT.

output-file


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

Equivalence name to be associated with the logical names SYS$OUTPUT and SYS$ERROR in the logical name table for the subprocess. The output-file argument is the address of a descriptor pointing to this equivalence string. If output-file is omitted, the default is the caller's SYS$OUTPUT.

flags


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

Flag bits that designate optional behavior. The flags argument is the address of an unsigned longword that contains these flag bits. By default, all flags are clear.

These flags are defined as follows:

Bit Symbol Meaning
0 NOWAIT If this bit is set, the calling process continues executing in parallel with the subprocess. If this bit is clear, the calling process hibernates until the subprocess completes.
1 NOCLISYM If this bit is set, the spawned subprocess does not inherit CLI symbols from its caller. If this bit is clear, the subprocess inherits all currently defined CLI symbols. You may want to specify NOCLISYM to help prevent commands redefined by symbol assignments from affecting the spawned commands.
2 NOLOGNAM If this bit is set, the spawned subprocess does not inherit process logical names from its caller. If this bit is clear, the subprocess inherits all currently defined process logical names. You may want to specify NOLOGNAM to help prevent commands redefined by logical name assignments from affecting the spawned commands.
3 NOKEYPAD If this bit is set, the keypad symbols and state are not passed to the subprocess. If this bit is not set, the keypad settings are passed to the subprocess.
4 NOTIFY If this bit is set, a message is broadcast to SYS$OUTPUT when the subprocess completes or aborts. If this bit is not set, no message is broadcast. This bit should not be set unless the NOWAIT bit is also set.
5 NOCONTROL If this bit is set, no carriage-return/line-feed is prefixed to any prompt string. If this bit is not set, a carriage-return/line-feed is prefixed to any prompt string specified.
6 TRUSTED If this bit is set, it indicates a SPAWN command on behalf of the application. If this bit is not set, it indicates that the SPAWN command originates from user. SPAWN commands originating from users are disallowed in captive accounts (DCL).
7 AUTHPRIV If this bit is set, the subprocess inherits the caller's authorized privileges. If this bit is clear, the spawned processes' authorized mask is set equal to the caller's current (active) privilege mask.
8 SUBSYSTEM If this bit is set, a spawned process inherits protected subsystem IDs for the duration of LOGINOUT.EXE (used to map the CLI). The IDs will be removed in the process of transferring control to the CLI (as a user mode $RUNDWN is performed). If this bit is clear, LOGINOUT does not execute under the subsystem IDs.

Bits 9 through 31 are reserved for future expansion and must be zero. Symbolic flag names are defined in libraries supplied by HP in module $CLIDEF. They are CLI$M_NOWAIT, CLI$M_NOCLISYM, CLI$M_NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_NOTIFY, CLI$M_NOCONTROL, CLI$M_TRUSTED, CLI$M_AUTHPRIV, and CLI$M_SUBSYSTEM.

process-name


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

Name defined for the subprocess. The process-name argument is the address of a descriptor pointing to this name string. If process-name is omitted, a unique process name will be generated. If you supply a name and it is not unique, LIB$SPAWN will return the condition value SS$_DUPLNAM.

The DCL_CTLFLAGS is a bitmask used to alter default behavior for certain commands on a systemwide basis. Currently, only the low bit of the bitmask is defined. The low bit controls the default process-name assignment for a subprocess created using the LIB$SPAWN routine.

Prior to OpenVMS Version 7.3-1, if no process name was supplied, the system constructed a name by appending _n to the username, where n was the next available non-duplicate integer for any process currently in the system. For example, the first spawned process from user SYSTEM would be called SYSTEM_1, the second, SYSTEM_2, and so on. The next available number was chosen, as soon as a gap was found.

Beginning in OpenVMS Version 7.3-1, the default constructed process name for subprocesses has changed. Instead of incrementally searching for the next unique number, a random number is chosen to append to the username. Therefore, the first processes that are spawned from user SYSTEM might be SYSTEM_154, SYSTEM_42, SYSTEM_87, and so on. This procedure results in a very high probability of finding a unique number on the first try since it is unlikely the same number is already in use.

However, some applications might rely on the previous method of assigning subprocess names. The DCL_CTLFLAGS parameter is available to allow you to configure the system as necessary.

Bit 0 of DCL_CTLFLAGS selects the behavior for assigning default subprocess names, as explained in the following:

  • If clear, the new behavior is used. If the process name is not specified, it will be the username with a random number suffix. This is the default setting.
  • If set, the previous behavior is used. If the process name is not specified, it will be the username with the next available number suffix.

process-id


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

Process identification of the spawned subprocess. The process-id argument is the address of an unsigned longword that contains this process identification value.

This process identification value is meaningful only if the NOWAIT flags bit is set.

completion-status-address


OpenVMS usage: address
type: address
access: read only
mechanism: by value

The final completion status of the subprocess. The completion-status-address argument contains the address of the status. The system writes the value of the final completion status of the subprocess into completion-status-address when the subprocess completes. If the subprocess returns a status code of 0, the system writes SS$_NORMAL into this address.

If the NOWAIT flags bit is set, the completion-status-address is updated asynchronously when the subprocess completes. Use the byte-integer-event-flag-num or AST-address arguments to determine when the subprocess has completed. Your program must ensure that the address is still valid when the value is written.

byte-integer-event-flag-num


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

The number of a local event flag to be set when the spawned subprocess completes. The byte-integer-event-flag-num argument is the address of an unsigned byte that contains this event flag number. If byte-integer-event-flag-num is omitted, no event flag is set.

Specifying byte-integer-event-flag-num is meaningful only if the NOWAIT flags bit is set.

AST-address


OpenVMS usage: procedure
type: procedure value
access: call without stack unwinding
mechanism: by value

Routine to be called by means of an AST when the subprocess completes.

Specifying AST-address is meaningful only if the NOWAIT flags bit is set.

varying-AST-argument


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

A value to be passed to the AST routine. Typically, the varying-AST-argument argument is the address of a block of storage the AST routine will use.


Previous Next Contents Index