|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
|||
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$ANALYZE_SDESC_64 input-descriptor ,data-length ,data-address [,descriptor-type]
Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2Refer 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.
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$ASN_WTH_MBX device-name [,maximum-message-size] [,buffer-quota] ,device-channel ,mailbox-channel
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
The AST in Progress routine indicates whether an AST is currently in progress.
LIB$AST_IN_PROG
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).
None.
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.
None.
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.
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.
LIB$ATTACH process-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$BBCCI position ,bit-zero-address
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.
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.
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.
None.
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.
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.
LIB$BBSSI position ,bit-zero-address
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.
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.
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.
None.
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.
| Previous | Next | Contents | Index |