hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


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. 


Previous Next Contents Index