|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$SIM_TRAP signal-arguments ,mechanism-arguments
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
SS$_RESIGNAL Resignal condition to next handler. The exception was one that LIB$SIM_TRAP could not handle.
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.
LIB$SKPC character-string ,source-string
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.
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.
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.
None.
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"
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.
LIB$SPANC source-string ,table-array ,byte-integer-mask
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.
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.
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.
None.
!+
! 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 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.
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.
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]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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