Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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.

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.

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 Digital 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 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:	modify
mechanism:	by reference

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.

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:	modify
mechanism:	by reference

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.

The Build a Node-Name Specification routine builds a node-name specification from the primary node name. The output node-name specification can be used for other node-name parsing operations.

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.

Format

LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs] [,secondary-nodename] [,nodespec-length]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

primary-nodename

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Primary node name. The primary-nodename argument contains the address of a descriptor pointing to this node-name string. The primary node name should not contain unnecessary quotation marks (that is, quotation marks (" ") that are not part of a simple name within the node name).

The error LIB$_INVARG is returned if primary-nodename points to a null string. The error LIB$_INVSTRDES is returned if primary-nodename is an invalid descriptor.

nodespec

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Node-name specification. The nodespec argument contains the address of a descriptor pointing to this output node-name specification string. LIB$BUILD_NODESPEC writes the output node-name specification into the buffer pointed to by the nodespec descriptor.

The error LIB$_INVSTRDES is returned if nodespec is an invalid descriptor.

The length field of the nodespec descriptor is not updated unless nodespec is a dynamic descriptor with a length less than the resultant node-name specification. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.

The nodespec argument contains an unusable result when LIB$BUILD_NODESPEC returns in error.

acs

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Access control string. The acs argument contains the address of a descriptor pointing to this access control string. The access control string must be a quoted string.

The error LIB$_INVSTRDES is returned if acs is an invalid descriptor.

secondary-nodename

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Secondary node name. The secondary-nodename argument contains the address of a descriptor pointing to this secondary node-name string.

The error LIB$_INVSTRDES is returned if secondary-nodename is an invalid descriptor.

nodespec-length

OpenVMS usage:	unsigned_word
type:	word (unsigned)
access:	write only
mechanism:	by reference

Length of the output node-name specification. The nodespec-length argument is the address of an unsigned word that contains this length in bytes.

The nodespec-length argument contains an unusable result when LIB$BUILD_NODESPEC returns in error.

Description

This routine builds the parsable form of a node name as the output node-name specification from the network usable form. Refer to LIB$GET_HOSTNAME for the definitions of both the parsable form and the network usable form.

The network usable form is specified by the argument primary-nodename. If primary-nodename contains special characters, it is enclosed in quotation marks (" ") to build the node-name specification. The quotation marks prevent the special characters from being recognized as terminator characters and enables correct parsing of the node-name syntax.

If you enclose primary-nodename in quotation marks, any quotation marks that are part of any simple names within primary-nodename are doubled (that is, each quotation mark (") is turned into two quotation marks ("")). LIB$BUILD_NODESPEC checks if the fully quoted primary node name exceeds 1024 characters. The error condition LIB$_NODTOOLNG is returned if this is the case.

To form the output node-name specification, the fully quoted primary node name is concatenated with the access control string (if supplied) and the double colons and is followed by the secondary node name (if supplied).

This routine does not validate any of the input arguments to ensure they can form a syntactically valid node name when they are concatenated.

If the routine overflows the output buffer pointed to by nodespec, the output node-name specification is truncated, and the alternate successful status LIB$_STRTRU is returned.

The nodespec-length argument, if supplied, is always set to the length of the node-name specification that is written into the output buffer pointed to by nodespec.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_INVARG	Invalid argument. The primary-nodename argument points to a null string.
LIB$_INVSTRDES	Invalid string descriptor.
LIB$_NODTOOLNG	The primary node name after quoting exceeds 1024 characters.
LIB$_STRTRU	Routine successfully completed. Characters are truncated in the output buffer pointed to by the nodespec argument.
LIB$_WRONUMARG	Wrong number of arguments.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_002.HTML