 |
HP OpenVMS RTL Library (LIB$) Manual
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.
- 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.
|
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.
|
