Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## LIB$ANALYZE_SDESC_64 (Alpha 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 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:

> Class | Description | Restrictions/Notes
> --- | --- | ---
> A | Array | For 32-bit descriptors, DSC$L_ARSIZE must be less than 2 16, or 65,536, bytes. For 64-bit descriptors, DSC64$Q_ARSIZE must be less than 2 64 bytes.
> 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 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 Compaq 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 systems, OpenVMS Alpha 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 systems, OpenVMS Alpha 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

| privacy and legal statement |
5932PRO_002.HTML