 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$REVERT
The Revert to the Handler of the Routine Activator routine deletes the
condition handler established by LIB$ESTABLISH by clearing the address
pointing to the condition handler from the activated routine's stack
frame.
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 and I64 programs
but is recognized and handled appropriately by most HP high-level
language compilers.
Format
LIB$REVERT
RETURNS
| OpenVMS usage: |
address |
| type: |
address |
| access: |
write only |
| mechanism: |
by value |
Previous contents of SF$A_HANDLER (longword 0) of the caller's stack
frame. This is the address of the condition handler previously in
effect. If no condition handler was in effect, zero is returned.
Arguments
None.
Description
LIB$REVERT returns the address that it clears from the calling
routine's stack frame. LIB$REVERT is used only if your routine is to
establish and then cancel a condition handler for a portion of its
execution.
LIB$REVERT is provided primarily for use with languages without
built-in error-handling facilities, such as Fortran. Do not use
LIB$REVERT from BASIC, COBOL, Pascal, or PL/I. See the documentation
for the language you are using for information about how that language
handles errors.
In VAX MACRO, you merely use the following instruction rather than
calling LIB$REVERT:
CLRL (FP) ; set handler address to 0
; in current stack frame
|
Condition Values Returned
None.
LIB$RUN_PROGRAM
The Run New Program routine causes the current program to stop running
and begins execution of another program.
Format
LIB$RUN_PROGRAM program-name
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
program-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File name of the program to be run in place of the current program. The
program-name argument contains the address of a
descriptor pointing to this file name string.
The maximum length of the file name is 255 characters. The default file
type is .EXE.
Description
LIB$RUN_PROGRAM stops execution of the current program and begins
execution of another program.
- If successful, control does not return to the calling program.
Instead, the $EXIT system service is called, the new program image
replaces the old image in the user process, and the command language
interpreter (CLI) gives control to the new image.
- If unsuccessful, control returns to the command interpreter.
This routine is supported for use with the DCL and MCR CLIs. If an
image is run directly as a subprocess or as a detached process, there
is no CLI present to perform this function. In those cases, the error
status LIB$_NOCLI is returned.
LIB$RUN_PROGRAM causes the current image to exit at the point of the
call and directs the CLI, if one is present, to start running another
program. If LIB$RUN_PROGRAM executes successfully, control passes to
the second program; if not, control passes to the CLI. The calling
program cannot regain control. This technique is called chaining.
This routine is provided primarily for compatibility with PDP-11
systems, where chaining is used to extend the address space of a system.
This routine may also be useful in an OpenVMS environment where address
space is severely limited and large images are not possible. For
example, you might use chaining to perform system generation on a small
virtual address space, for a large page file.
With LIB$RUN_PROGRAM, the calling program can pass arguments to the
next program in the chain only by using the common storage area. One
way to do this is for the calling program to call LIB$PUT_COMMON to
pass the information into the common storage area. Then the called
program calls LIB$GET_COMMON to retrieve the data.
In general, this practice is not recommended. There is no convenient
way to specify the order and type of arguments passed into the common
storage area; so programs that pass arguments in this way must know
about the format of the data before it is passed. When you use common
storage, it is very difficult to keep your program modular and
AST-reentrant; a method of arbitration must be designated to define
which program can modify common storage and when.
Further, LIB$RUN_PROGRAM cannot be used if no command language
interpreter is present, as in the case of image subprocesses and
detached subprocesses.
If you want control to return to the caller, use LIB$SPAWN instead.
Condition Values Returned
|
LIB$_INVARG
|
Invalid argument.
|
|
LIB$_NOCLI
|
No CLI present to perform function. The calling process did not have a
CLI to perform the function or the CLI did not support the request
type. Note that an image run as a subprocess or detached process does
not have a CLI.
|
|
LIB$_UNECLIERR
|
Unexpected CLI error. The CLI returned an error status which was not
recognized. This error may be caused by use of a nonstandard CLI. If
this error occurs while using the DCL or MCR CLIs, please report the
problem to your HP support representative.
|
LIB$SCANC
The Scan for Characters and Return Relative Position routine is used to
find a specified set of characters in the source string. LIB$SCANC
makes the VAX SCANC instruction available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$SCANC source-string ,table-array ,byte-integer-mask
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Relative position in the source string of the character that terminated
the operation, or zero if the terminator character is not found. 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$SCANC to index into a table. 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$SCANC indexes into and performs a logical 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 on which a logical 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$SCANC uses successive bytes of the string specified by
source-string to index into a table. The byte selected
from the table is the byte on which a logical AND operation is
performed with the mask byte. The operation is terminated when the
result of the AND operation is equal to 1.
Condition Values Returned
None.
LIB$SCOPY_DXDX
The Copy Source String Passed by Descriptor to Destination routine
copies a source string passed by descriptor to a destination string.
Format
LIB$SCOPY_DXDX source-string ,destination-string
Corresponding JSB Entry Point
LIB$SCOPY_DXDX6
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Source string to be copied to the destination string by LIB$SCOPY_DXDX.
The source-string argument contains the address of a
descriptor pointing to this source string. The descriptor class can be
unspecified, fixed-length, decimal string, array, noncontiguous array,
varying, or dynamic.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
The following actions occur depending on the class of the destination
string's descriptor:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space-fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor. If the area specified is not
large enough, return the previous space allocation (if any) and then
dynamically allocate the amount of space needed. Copy the source string
and set the new length and address in the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
descriptor MAXSTRLEN field with no padding. Readjust the current length
(CURLEN) field to the actual number of bytes copied.
|
Description
LIB$SCOPY_DXDX returns all condition values as a status; truncation is
a qualified success condition value (bit 0 set to 1).
In addition, an equivalent JSB entry point is available, with R0
containing the first argument and R1 containing the second.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your HP support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
LIB$SCOPY_R_DX
The Copy Source String Passed by Reference to Destination String
routine copies a source string passed by reference to a destination
string, passed by descriptor.
Format
LIB$SCOPY_R_DX word-integer-source-length ,source-string
,destination-string
Corresponding JSB Entry Point
LIB$SCOPY_R_DX6
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
word-integer-source-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Length of the source string in bytes. The
word-integer-source-length argument is the address of an
unsigned word that contains the length of the source string.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
Source string to be copied to the destination string by LIB$SCOPY_R_DX.
The source-string argument is the address of this
source string.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
Description
LIB$SCOPY_R_DX copies a source string, passed by reference, to a
destination string, passed by descriptor. It returns the status as a
condition value. Truncation is a qualified success; LIB$SCOPY_R_DX sets
bit 0 of the condition value to 1.
The actions taken by LIB$SCOPY_R_DX depend on the descriptor class of
the destination string. The following table describes these actions for
each descriptor class:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor.
|
|
|
If the area specified is not large enough, return the previous space
allocation, if any, and then dynamically allocate the amount of space
needed. Copy the source string and set the new length and address in
the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
decsriptor's MAXSTRLEN field with no padding. Readjust the string's
current length (CURLEN) field to the actual number of bytes copied.
|
An equivalent JSB entry is available, with R0 being the first argument,
R1 the second, and R2 the third. The length argument is passed in bits
15:0 of R0.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your HP support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
LIB$SCOPY_R_DX_64 (Alpha and I64 Only)
The Copy Source String Passed by Reference to Destination String
routine copies a source string passed by reference to a destination
string, passed by descriptor.
Format
LIB$SCOPY_R_DX_64 quad-integer-source-length ,source-string
,destination-string
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
quad-integer-source-length
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Length of the source string in bytes. The
quad-integer-source-length argument is the address of
an unsigned quadword that contains the length of the source string.
source-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by reference |
Source string to be copied to the destination string by
LIB$SCOPY_R_DX_64. The source-string argument is the
address of this source string.
destination-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Destination string to which the source string is copied. The
destination-string argument contains the address of a
descriptor pointing to this destination string.
Description
LIB$SCOPY_R_DX_64 copies a source string, passed by reference, to a
destination string, passed by descriptor. It returns the status as a
condition value. Truncation is a qualified success; LIB$SCOPY_R_DX_64
sets bit 0 of the condition value to 1.
The actions taken by LIB$SCOPY_R_DX_64 depend on the descriptor class
of the destination string. The following table describes these actions
for each descriptor class:
| Descriptor Class |
Action |
|
S, Z, SD, A, NCA
|
Copy the source string. If needed, space fill or truncate on the right.
|
|
D
|
If the area specified by the destination descriptor is large enough to
contain the source string, copy the source string and set the new
length in the destination descriptor.
|
|
|
If the area specified is not large enough, return the previous space
allocation, if any, and then dynamically allocate the amount of space
needed. Copy the source string and set the new length and address in
the destination descriptor.
|
|
VS
|
Copy source string to destination string up to the limit of the
descriptor's MAXSTRLEN field with no padding. Readjust the string's
current length (CURLEN) field to the actual number of bytes copied.
|
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed. All characters in the input string were
copied to the destination string.
|
|
LIB$_STRTRU
|
Routine successfully completed. String truncated. The destination
string could not contain all of the characters copied from the source
string.
|
|
LIB$_FATERRLIB
|
Fatal internal error. An internal consistency check has failed. This
usually indicates an internal error in the Run-Time Library and should
be reported to your HP support representative.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. Your program has exceeded the image quota
for virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. A string descriptor has an invalid value in
its CLASS field.
|
|
