![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 19 July 1999 | |
|
|
|
|
|
|
| Previous | Contents | Index |
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 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 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.
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: 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.
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 systems, OpenVMS Alpha 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: 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.
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.
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.
LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs] [,secondary-nodename] [,nodespec-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 5932PRO_002.HTML | ||