 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$ANALYZE_SDESC_64 (Alpha and I64 Only)
The Analyze String Descriptor routine extracts the length and the
address at which the data starts for a variety of 32-bit and 64-bit
string descriptor classes.
Format
LIB$ANALYZE_SDESC_64 input-descriptor ,data-length ,data-address
[,descriptor-type]
Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2
Refer to the LIB$ANALYZE_SDESC routine for information about the JSB entry
point, LIB$ANALYZE_SDESC_R2. This JSB entry point returns 64-bit
results on Alpha and I64 systems.
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
input-descriptor
| OpenVMS usage: |
descriptor |
| type: |
longword (unsigned) or quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Input descriptor from which LIB$ANALYZE_SDESC_64 extracts the length of
the data and the address at which the data starts. The
input-descriptor argument is the address of a
descriptor pointing to the input data. The input descriptor can be a
longword (unsigned) or a quadword (unsigned).
data-length
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the data; LIB$ANALYZE_SDESC_64 extracts this length value
from the input descriptor. The data-length argument is
the address of an unsigned quadword integer into which
LIB$ANALYZE_SDESC_64 writes the length.
data-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting address of the data; LIB$ANALYZE_SDESC_64 extracts this
address from the input descriptor. The data-address
argument is the address of an unsigned quadword into which
LIB$ANALYZE_SDESC_64 writes the starting address of the data.
descriptor-type
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Flag value indicating the type of input descriptor. The
descriptor-type argument contains the address of an
unsigned longword integer to which LIB$ANALYZE_SDESC_64 writes a 0 for
a 32-bit input descriptor or a 1 for a 64-bit descriptor.
This argument is optional.
Description
LIB$ANALYZE_SDESC_64 extracts the length and the address at which the
data starts for a variety of 32-bit and 64-bit string descriptor
classes. Following is a description of the classes of string
descriptors: 216, or 65,536, bytes. For 64-bit descriptors,
DSC64$Q_ARSIZE must be less than 264 bytes.)
| Class |
Description |
Restrictions/Notes |
|
A
|
Array
|
For 32-bit descriptors, DSC$L_ARSIZE must be less than
|
|
D
|
Decimal string
|
Treated as class S.
|
|
NCA
|
Noncontiguous array
|
Same as class A.
|
|
S
|
Scalar, string
|
None.
|
|
SD
|
Decimal scalar
|
Treated as class S.
|
|
VS
|
Varying string
|
Length returned is CURLEN.
|
|
Z
|
Unspecified
|
Treated as class S.
|
See STR$ANALYZE_SDESC_64 for a similar routine that signals an error
rather than returning a status.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. An array descriptor has an ARSIZE greater
than 65,535 bytes, or the class is unsupported.
|
LIB$ASN_WTH_MBX
The Assign Channel with Mailbox routine assigns a channel to a
specified device and associates a mailbox with the device. It returns
both the device channel and the mailbox channel.
Format
LIB$ASN_WTH_MBX device-name [,maximum-message-size] [,buffer-quota]
,device-channel ,mailbox-channel
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
device-name
| OpenVMS usage: |
device_name |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Device name that LIB$ASN_WTH_MBX passes to the $ASSIGN service. The
device-name argument is the address of a descriptor
pointing to the device name.
maximum-message-size
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Maximum message size that can be sent to the mailbox; LIB$ASN_WTH_MBX
passes this argument to the $CREMBX service. The
maximum-message-size argument is the address of a
signed longword integer containing this maximum message size.
buffer-quota
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of system dynamic memory bytes that can be used to buffer
messages sent to the mailbox; LIB$ASN_WTH_MBX passes this argument to
the $CREMBX service. The buffer-quota argument is the
address of a signed longword integer containing this buffer quota.
device-channel
| OpenVMS usage: |
word_unsigned |
| type: |
word integer (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Device channel that LIB$ASN_WTH_MBX receives from the $ASSIGN service.
The device-channel argument is the address of an
unsigned word integer into which $ASSIGN writes the device channel.
mailbox-channel
| OpenVMS usage: |
channel |
| type: |
word integer (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Mailbox channel that LIB$ASN_WTH_MBX receives from the $CREMBX service.
The mailbox-channel argument is the address of an
unsigned word integer into which $CREMBX writes the mailbox channel.
Description
A mailbox is a virtual device used for communication between processes.
A channel is the communication path that a process uses to perform I/O
operations to a particular device. LIB$ASN_WTH_MBX assigns a channel to
a device and associates a mailbox with the device. It returns both the
device channel and the mailbox channel to the mailbox.
Normally, a process calls the $CREMBX system service to create a
mailbox and assign a channel and logical name to it. Any process
running in the same job and using the same logical name uses the same
mailbox.
LIB$ASN_WTH_MBX associates the physical mailbox name with the channel
assigned to the device. To create a temporary mailbox for itself and
other processes cooperating with it, your program calls
LIB$ASN_WTH_MBX. The Run-Time Library routine assigns the channel and
creates the temporary mailbox by using the system services $GETDVIW,
$ASSIGN, and $CREMBX. Instead of a logical name, the mailbox is
identified by a physical device name of the form MBcu. The
physical device name MBcu is made up of the following elements:
|
MB
|
Indicates that the device is a mailbox
|
|
c
|
Is the controller
|
|
u
|
Is the unit number
|
The routine returns the channel for this device name to the calling
program, which then must pass the mailbox channel to the other programs
with which it cooperates. In this way, the cooperating processes access
the mailbox by its physical name, instead of by a logical name.
The calling program passes the routine a device name, which specifies
the device to which the channel is to be assigned. For this argument
(called device-name), you may use a logical name. If
you do so, the routine attempts one level of logical name translation.
The privilege restrictions and process quotas required for using this
routine are those required by the $GETDVIW, $CREMBX, and $ASSIGN system
services.
Note
This routine calls LIB$GET_EF. Please read the note in the
Description section of that routine.
|
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
Any condition value returned by the called system services $ASSIGN,
$CREMBX, $GETDVI, or the RTL routines LIB$GET_EF and LIB$FREE_EF.
|
LIB$AST_IN_PROG
The AST in Progress routine indicates whether an AST is currently in
progress.
Format
LIB$AST_IN_PROG
RETURNS
| OpenVMS usage: |
boolean |
| type: |
boolean |
| access: |
write only |
| mechanism: |
by value |
Truth value that indicates whether an AST is currently in progress
(value = 1) or not (value = 0).
Arguments
None.
Description
An asynchronous system trap (AST) is an OpenVMS mechanism for providing
a software interrupt when an external event occurs, such as the user
pressing Ctrl/C. When an external event occurs, the OpenVMS operating
system interrupts the execution of the current process and calls a
routine that you supply. While that routine is active, the AST is said
to be in progress, and the process is said to be executing at AST
level. When your AST routine returns control to the original process,
the AST is no longer active, and execution continues where it left off.
LIB$AST_IN_PROG indicates to the calling program whether an AST is
currently in progress. Your program can call LIB$AST_IN_PROG to
determine whether it is executing at AST level and then take
appropriate action. This routine is useful if you are writing
AST-reentrant code, which takes different actions depending on whether
an AST is in progress. For example, the routine might have two separate
statically allocated storage areas, one for AST level and one for
non-AST level.
LIB$AST_IN_PROG calls the RTL routines LIB$FREE_EF and LIB$GET_EF, and
the $GETJPI system service. If LIB$AST_IN_PROG or any of these routines
encounters an error, LIB$AST_IN_PROG calls LIB$STOP.
Condition Values Returned
None.
Example
|
PROGRAM AST_IN_PROGRESS(INPUT, OUTPUT);
FUNCTION LIB$AST_IN_PROG : INTEGER; EXTERN;
VAR
ASTVALUE : INTEGER;
BEGIN
ASTVALUE := LIB$AST_IN_PROG;
CASE ASTVALUE OF
0 : WRITELN('AN AST IS NOT IN PROGRESS');
1 : WRITELN('AN AST IS IN PROGRESS');
END { of the case statement }
END.
|
This Pascal program determines whether or not an AST is in progress.
LIB$ATTACH
The Attach Terminal to Process routine requests the calling process's
command language interpreter (CLI) to detach the terminal of the
calling process and to reattach it to a different process.
Format
LIB$ATTACH process-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
process-id
| OpenVMS usage: |
process_id |
| type: |
longword integer (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Identification of the process to which LIB$ATTACH requests the calling
process to attach its terminal. The process-id
argument is the address of an unsigned longword integer containing the
process identification. The specified process must be currently
detached (by means of a SPAWN or ATTACH command or by a call to
LIB$SPAWN or LIB$ATTACH) and must be part of the caller's job.
Description
LIB$ATTACH requests the calling process's command language interpreter
(CLI) to detach the terminal of the calling process and reattach it to
a different process. The calling process then hibernates. LIB$ATTACH
provides the same function as the DCL command ATTACH. For more
information on ATTACH, see the HP OpenVMS DCL Dictionary.
LIB$ATTACH is supported for use with the DCL CLI. If used with the
Monitor Control Routine (MCR) CLI, the error status LIB$_NOCLI is
returned. If an image is run directly as a subprocess or detached
process, no CLI is present to perform this function. In such cases, the
error status LIB$_NOCLI is returned.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_NONEXPR
|
Nonexistent process. The process specified by
process-id does not exist.
|
|
LIB$_ATTREQREF
|
Attach request refused. The specified process could not be attached to.
Either it was not detached or it did not belong to the caller's job.
|
|
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 CLI, please report the problem to
your HP support representative.
|
LIB$BBCCI
The Test and Clear Bit with Interlock routine tests and clears a
selected bit under memory interlock. LIB$BBCCI makes the VAX BBCCI
instruction available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$BBCCI position ,bit-zero-address
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
State of the bit before it was cleared by LIB$BBCCI: 1 if the bit was
previously set, and 0 if the bit was previously clear.
Arguments
position
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Bit position, relative to bit-zero-address, of the bit
that LIB$BBCCI tests and clears. The position argument
is the address of a signed longword integer containing the bit
position. A position of zero denotes the low-order bit of the byte
base. The bit position is equal to the offset of the bit chosen from
the base position. This offset may span the entire range of a signed
longword integer; negative offsets access bits in lower addressed bytes.
bit-zero-address
| OpenVMS usage: |
unspecified |
| type: |
address |
| access: |
read only |
| mechanism: |
by value |
Address of the byte containing bit 0 of the field that LIB$BBCCI
references. The bit-zero-address argument is the
location of the base position. The bit that LIB$BBCCI tests and clears
is position bits offset from the low bit of
bit-zero-address.
Description
The single bit specified by position and
bit-zero-address is tested, the previous state of the
bit remembered, and the bit cleared. The reading of the state of the
bit and its clearing are interlocked against similar operations by
other processors or devices in the system. The remembered previous
state of the bit is then returned as the function value of LIB$BBCCI.
Condition Values Returned
None.
Example
|
C+
C This Fortran program demonstrates the use of
C LIB$BBCCI.
C-
INTEGER*4 STATES(4) ! 128 shared state bits
COMMON /STATES/ STATES ! Could be shared memory
LOGICAL*4 LIB$BBCCI
IF (LIB$BBCCI (42, STATES)) THEN
TYPE *,'State bit 42 was set'
ELSE
TYPE *,'State bit 42 was clear'
END IF
END
|
This Fortran example tests and clears bit 42 of array STATES, which is
in a COMMON area (possibly shared between two processors).
The output generated by this program is as follows:
$ RUN STATE
State bit 42 was clear.
|
LIB$BBSSI
The Test and Set Bit with Interlock routine tests and sets a selected
bit under memory interlock. LIB$BBSSI makes the VAX BBSSI instruction
available as a callable routine.
Note
On Alpha and I64 systems, OpenVMS Alpha and I64 instructions perform
the equivalent operation.
|
Format
LIB$BBSSI position ,bit-zero-address
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The state of the bit before it was set by LIB$BBSSI: 1 if it was
previously set, and 0 if it was previously clear.
Arguments
position
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Bit position, relative to bit-zero-address, of the bit
that LIB$BBSSI tests and sets. The position argument
is the address of a signed longword integer containing the bit
position. A position of zero denotes the low-order bit of the byte
base. The bit position is equal to the offset of the bit chosen from
the base position. This offset may span the entire range of a signed
longword integer; negative offsets access bits in lower addressed bytes.
bit-zero-address
| OpenVMS usage: |
unspecified |
| type: |
address |
| access: |
read only |
| mechanism: |
by value |
Address of the byte containing bit 0 of the field that LIB$BBSSI
references. The bit-zero-address argument is the
location of the base position. The bit that LIB$BBSSI tests and sets is
position bits offset from the low bit of
bit-zero-address.
Description
The single bit specified by position and
bit-zero-address arguments is tested, the previous
state of the bit remembered, and the bit set. The reading of the state
of the bit and its setting are interlocked against similar operations
by other processors or devices in the system. The remembered previous
state of the bit is then returned as the function value of LIB$BBSSI.
Condition Values Returned
None.
Example
|
C+
C This Fortran example program demonstrates
C the use of LIB$BBSSI.
C-
INTEGER*4 STATES(4) ! 128 shared state bits
COMMON /STATES/ STATES ! Could be shared memory
LOGICAL*4 LIB$BBSSI
IF (LIB$BBSSI (104, STATES)) THEN
TYPE *,'State bit 104 was set'
ELSE
TYPE *,'State bit 104 was clear'
END IF
END
|
This Fortran example tests and sets bit 104 of array STATES, which is
in a COMMON storage area (possibly shared between two processors).
The output generated by this program is as follows:
$ RUN STATEB
State bit 104 was clear.
|
|
