|
HP OpenVMS Systems Documentation |
|
HP DECwindows Motif
|
| Previous | Contents | Index |
Tests the ready state of an LCN and returns when one of the tested states is set, a timeout occurs, or a specified OpenVMS event flag is set.
Format
DECW$LCN_SELECT_ONE lcn, read, write, except, [timeout], [efn], [efn_mask] |
VMS usage: type: longword (unsigned) access: write mechanism: by value
Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.
lcn
VMS usage: type: longword access: read only mechanism: by value
The value of the LCN.read, write, except
VMS usage: type: longword access: write only mechanism: by reference
Specifies whether to check the read, write, or exception status of an LCN. A non-zero value signifies that the status check be performed and the result stored in the referenced address on completion. A zero or null value indicates that no check be made.timeout
VMS usage: type: quadword access: read only mechanism: by reference
The time by which the select operation will timeout if no input is received. The time value is expressed in OpenVMS binary delta-time format. A null value indicates no timeout. A value of 0 indicates the operation is in polling mode and will timeout immediately if none of the specified status bits are set.efn
VMS usage: type: longword access: read only mechanism: by value
An event flag number (EFN) in the cluster to which the efn_mask argument applies. EFNs are typically used for single-threaded or inner-mode operations. In this environment, efn identifies an event flag for the wait operation.If no EFN value is provided in single-thread mode, SYS$HIBER and SYS$WAKE are used. In these instances, SYS$HIBER must not be used concurrently within the process. In particular, POSIX Threads must not be loaded into the image, even if not in use.
For multithreaded, user mode operations, this argument can be optional depending on whether an EFN has been provided previously to DECW$LCN_THREAD_INIT. If the EFN was specified and the value of efn_mask is 0, the argument is optional. Otherwise the value of this argument is required and will be used as if it had been provided to DECW$LCN_THREAD_INIT.
efn_mask
VMS usage: type: longword access: read only mechanism: by value
A mask of EFNs to be tested. Requires the efn argument.
Description
DECW$LCN_SELECT_ONE waits until one of the specified LCN ready states has been set, timed out, or until the event flag condition is met. This routine checks whether the selected LCN has been allocated and returns an error (DECW$_INVLCN) if the LCN has not been allocated or freed for reuse.
With multithreading enabled, this routine is thread-reentrant and callable from exec or lower modes. Calls from ASTs are not supported.
With single threading, the select routines can be called from user mode and exec mode ASTs. Note, however, that the only concurrent calls allowed are one call from user mode followed by one call from an AST in user mode.
Condition Values Returned
| SS$_NORMAL | Routine successfully completed. One or more LCNs have their ready bit set as indicated in the updated mask values. |
| SS$_EXQUOTA | A process quota has been exceeded, this can be due to the timer entry or AST limit quota. |
| SS$_INSFMEM | There is insufficient memory to perform the operation. |
| SS$_UNASEFC | The process is not associated with the cluster that contains the specified event flag. |
| DECW$_BAD_EFN_CLUSTER | An event flag was not provided to DECW$LCN_THREAD_INIT, or the specified flag resides in a different event flag cluster. |
| DECW$_INVARG | The timeout period or EFN is not accessible or within the range of valid values. |
| DECW$_INVLCN | The LCN has not been allocated or was freed during the operation. |
| DECW$_NOHIBER | This call was made from inner-mode with multithreading enabled. No EFN was specified. |
| DECW$_PTHREAD_INVALID | A POSIX Threads routine returned an unexpected error. |
| DECW$_TIMEDOUT | The end of the timeout period was reached. |
3.2.2.6 DECW$LCN_SET_x_READY
Signals that input from a read, write, or exception operation has been
received by changing the ready bit to the set state.
Format
DECW$LCN_SET_READ_READY lcn |
DECW$LCN_SET_WRITE_READY lcn |
DECW$LCN_SET_EXCEPT_READY lcn |
VMS usage: type: longword (unsigned) access: write mechanism: by value
Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.
lcn
VMS usage: type: longword access: read only mechanism: by value
The value of the LCN whose ready bit will be changed to the set state (1).
Description
DECW$LCN_SET_x_READY sets the read, write, or except ready bit of an LCN. This signals input has been received from the specified operations.
These routines are thread- and AST-reentrant and callable from exec and lower modes. When any of the DECW$LCN_SET_x_READY routines are called from exec mode with multithreading enabled, the call declares a user mode AST. This AST performs the signaling for any user-mode processes that are currently in a wait state.
The equivalent functions of DECW$LCN_SET_x_READY are also available as system services (DECW$XPORT_LCN_SET_x) from the set of transport-common routines (DECW$XPORT_SERVICES.EXE).
Condition Values Returned
| SS$_NORMAL | Routine successfully completed. |
| SS$_EXQUOTA | The current memory quota has been exceeded. |
| SS$_INSFMEM | There is insufficient memory to perform the operation. |
| DECW$_INVLCN | The LCN has not been allocated. |
| DECW$_NOT_INITIALIZED | The LCN has not been initialized; DECW$LCN_ALLOCATE must be called prior to this operation. |
3.2.2.7 DECW$LCN_THREAD_INIT
Initializes multithreading support for LCN operations.
Format
DECW$LCN_THREAD_INIT [efn] |
VMS usage: type: longword (unsigned) access: write mechanism: by value
Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.
efn
VMS usage: type: longword access: read only mechanism: by value
The value of the specified EFN. When multithreading is enabled, an EFN value must be specified when performing select operations (DECW$LCN_SELECT or DECW$LCN_SELECT_ONE) with event flag masks. The EFN is supplied either by DECW$LCN_THREAD_INIT or from the first select call that provides an efn argument.The value of the efn argument must match the value supplied for any previous select operations or calls to DECW$LCN_THREAD_INIT. The event flag must also be in the same event flag cluster as the efn value supplied to subsequent select or initialization operations.
Description
DECW$LCN_THREAD_INIT enables multithreaded LCN operations. This routine is only callable from user mode with user mode ASTs enabled and can be called multiple times by a single process.
Condition Values Returned
| SS$_NORMAL | Routine successfully completed. |
| DECW$_CHANGED_EFN | An event flag was specified that differs from that specified in a previous initialization or select call. |
| DECW$_INSFMEM | There is insufficient memory to perform the operation. |
| DECW$_NOPTHREADRTL | The POSIX Thread Library (PTHREAD$RTL) has not been loaded. |
| DECW$_NOTUSERMODE | This routine was not called from user mode. |
| DECW$_PTHREAD_INVALID | A POSIX Thread routine returned an unexpected error. |
3.3 X Window System Library (Xlib) Enhancements
As part of the core system upgrade to X11R6.6, the following new
functions listed in Table 3-3 have been added to the version of
Xlib available with HP DECwindows Motif for HP OpenVMS Alpha Version 1.3. Note that all functions are included
in the current version of the DECW$XLIBSHR image.
| Function Name | Description |
|---|---|
| _XAllocTemp | Thread-safe allocation of scratch data space for use by extension writers. |
| _XFreeTemp | Frees the scratch data space allocated by _XAllocTemp. |
| XCloseOM | Closes the specified output method. |
| XcmsSetCCCOfColormap | Sets the color conversion context for the specified colormap. |
| XAddConnectionWatch | Establishes a watch procedure callback for when internal connections are opened or closed. |
| XConvertCase | Obtains the uppercase and lowercase forms of a KeySym. |
| XContextualDrawing | Indicates whether text drawn with the current font set includes context-dependent drawing. |
| XCreateOC | Creates an output context within the specified output method. |
| XDestroyOC | Destroys an output context. |
| XDirectionalDependentDrawing | Indicates whether the drawing functions implement text directionality. |
| XDisplayOfOM | Returns the display associated with the specified output method. |
| XESetBeforeFlush | Defines a procedure that will be called just before data is sent to the X server. |
| XExtendedMaxRequestSize | Returns the maximum request size using extended length encoding (the BIG-REQUESTS extension). |
| XGetAtomNames | Returns the names associated with the specified X atoms. |
| XGetOCValues | Obtains the current output context values. |
| XGetOMValues | Obtains the current output method values. |
| XInitThreads | Initializes support for multiple threads. |
| XInternalConnectionNumbers | Returns a list of the internal connections open for a specified display. |
| XInternAtoms | Returns atoms for an array of names. |
| XLocaleOfOM | Returns the locale associated with the specified output method. |
| XLockDisplay | Locks a display to protect against concurrent access from multiple threads. |
| XOMOfOC | Returns the output method associated with the specified output context. |
| XOpenOM | Opens an X output method for the specified locale and modifiers. |
| XProcessInternalConnection | Processes input available on an internal connection. |
| XReadBitmapFileData | Reads a bitmap from a file and returns it as data. |
| XRegisterIMInstantiateCallback | Registers an input method callback. |
| XRemoveConnectionWatch | Removes a watch procedure established by XAddConnectionWatch. |
| XSetOCValues | Specifies one or more output context values. |
| XSetOMValues | Specifies one or more output method values. |
| XUnlockDisplay | Removes a lock established by XLockDisplay. |
| XUnregisterIMInstantiateCallback | Unregisters an input method instantiation callback. |
See the Xlib - C Language X Interface, X Consortium Standard, X
Version 11, Release 6.4 specification available from X.Org for
detailed information about each of these functions.
3.3.1 Updated Client-Side Extension Library
The client-side extension library (DECW$XEXTLIBSHR) has been updated to support multithreading and new header files for the following new extensions available as part of the upgrade to X11R6.6:
All extensions in the library (new and existing) have been made thread-safe (as described in Section 3.1). In addition, the minor version of the library has been updated from 2,2 to 2,3 to prevent images linked against the updated DECW$XEXTLIBSHR from loading the incorrect version of the library.
Also, function names longer than 31 characters have been replaced by macro definitions compatible with the current version of the OpenVMS Linker.
See Section 3.5 for an overview of each of these extensions. For
instructions on how to link to this library, see Section 6.1.2.
3.3.2 Support for LCNs
Xlib now provides an alternate means of obtaining connection numbers for connections to HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 servers. The logical connection number (LCN) interface was specifically designed to support the communication needs of X11R6 systems and is intended as a replacement for the EFN mechanism.
The following functions and macros are designed for use with the new LCN interface:
These Xlib functions and macros are described in the Xlib - C Language X Interface, X Consortium Standard, X Version 11, Release 6.4 specification available from X.Org.
Note for compatibility with DECwindows Motif for OpenVMS Version 1.2--6 and earlier clients, the existing event flag mechanism remains unchanged, and the XtAppAddInput function accepts both EFNs and LCNs. However, HP recommends that new applications, in particular ones that use multithreading, use LCNs. When Xlib has multithreading enabled, EFNs are not available. If a multithreaded application uses EFNs without multithreading enabled in Xlib, the EFN should be restricted to a single thread--the same thread used for all X calls.
For more information about the LCN interface and its available
routines, see Section 3.2.
3.3.3 Updated X11 Environment Variable Parsing
Xlib now accepts the equivalent X11 Release 6 (X11R6) POSIX-compliant forms of the following environment variables:
| OpenVMS Form | X11R6 Form |
|---|---|
| DECW$DISPLAY | DISPLAY |
| DECW$RESOURCE_NAME | RESOURCE_NAME 1 |
On connection to the X display server, Xlib checks the variable name. If the OpenVMS variable is not defined, Xlib checks for the X11R6 equivalent before returning a status value.
3.3.4 Additional Non-C Language Bindings
Non-C lanuage bindings (such as Fortran and Pascal) for the following
new Xlib functions have been added to HP DECwindows Motif for HP OpenVMS Alpha Version 1.3. These bindings are
in addition to those documented in the DECwindows Motif for OpenVMS Guide to Non-C Bindings.
OpenVMS Format
status_return = X$CLOSE_OM |
(om) |
Argument Information
| Argument | Usage | Data Type | Access | Mechanism |
|---|---|---|---|---|
| status_return | longword | longword | write | value |
| om | identifier | uns longword | read | reference |
| Previous | Next | Contents | Index |