X11/Motif portability concerns, Unix -> OpenVMS Version 1.0 4-JUN-1997 David Mathog, Biology Division, Caltech comments/corrections/additions to mathog@seqaxp.bio.caltech.edu This is a list of all known areas where a compatibility problems _may_ occur when porting an X11/Motif application from Unix to OpenVMS. The specific sections indicating operating system dependencies are indicated with a "*". ( A valuable reference, if you can find it: X/Open Portability Guide ) 1. XSetFontPath 2. XReadBitmapFile 3. WM_CLASS Property 4. XtResolvePathname 5. XtFindFile 6. XtAppAddInput 7. Exiting from an Application 8. use of select() 9. use of ConnectionNumber(); 1. XSetFontPath "X Window System 6.5.3" "The XSetFontPath function defines the directory search path for font lookup. There is only one search path per * X server, not one per client. The interpretation of the * strings is operating system dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system dependent and are not intended to be used by client applications." 2. XReadBitmapFile "X Window System 10.10" "int XReadBitmapFile(display, d, filename, width_return, height_return, bitmap_return, x_hot_return , y_hot_return ) * filename Specifies the file name to use. The format of the file * name is operating system dependent. " 3. WM_CLASS Property "X Window System 4.1.2.5" "The WM_CLASS property (of type STRING without control characters) contains two consecutive null- terminated strings. These specify the Instance and Class names to be used by both the client and the win- dow manager for looking up resources for the applica- tion or as identifying information. This property must be present when the window leaves the Withdrawn state and may be changed only while the window is in the Withdrawn state. Window managers may examine the property only when they start up and when the window leaves the Withdrawn state, but there should be no need for a client to change its state dynamically. The two strings, respectively, are: A string that names the particular instance of the application to which the client that owns this window belongs. Resources that are specified by instance name override any resources that are specified by * class name. Instance names can be specified by the * user in an operating-system specific manner. On POSIX-conformant systems, the following conven- tions are used:" 4. XtResolvePathname "X Window System Toolkit 2.2" "also, Personal communication: Dom Maddalone, dgm@cronus.colorado.edu" "The application-specific class resource file name is con- structed from the language string and class name of the application. It points to a site-specific resource file that usually is installed by the site manager when the appli- cation is installed. The file is found by calling XtResol- vePathname with the parameters (display, app- defaults, NULL , NULL , NULL , NULL , 0, NULL ); see Sec- tion 11.11. This file is expected to be provided by the developer of the application and may be required for the application to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with XtAppSet FallbackResources. The application-specific user resource file name is con- structed from the language string and class name of the application and points to a user-specific resource file. This file is owned by the application and typically stores user customizations. Its name is found by calling XtResolvePathname with the parameters (display, NULL , NULL , NULL , path, NULL , 0, NULL ) where path * is defined in an operating-system-specific way. On * POSIX-based systems, path is defined to be the value of the environment variable XUSERFILESEARCHPATH if this is defined. If XUSERFILESEARCHPATH is not defined but the environment variable XAPPLRESDIR is defined, path is $XAPPLRESDIR/%L/%N:$XAPPLRESDIR/%l/%N:$XAPPLRESDIR/%N:$HOME/%N where $XAPPLRESDIR is replaced by the value of that environment variable and $HOME is replaced by the user's home directory. If XAPPLRESDIR is not defined, path is $HOME/%L/%N:$HOME/%l/%N:$HOME/%N " From the above we can see that ":" is a delimiter for each path to check, but ":" has other uses on OpenVMS, and so it must be escaped to work properly. Example: filename = XtResolvePathname(XtDisplay(toplevel),NULL,"TED", #ifdef __VMS ".HELP","SYS$HELP%:%N%S",NULL,0,NULL); #else ".HELP",NULL,NULL,0,NULL); #endif 5. XtFindFile "X Window System Toolkit 11.11" "XtFindFile(path, substitutions, num_substitutions, predicate) * path Specifies a path of file names, including * substitution characters. " Path should be treated as in XtResolvePathName 6. XtAppAddInput "X Window System Toolkit 7.1.1" "To register a new file as an input source for a given application context, use XtAppAddInput. XtInputId XtAppAddInput(app_context, source, condition, proc, client_data) XtAppContext app_context; int source; XtPointer condition; XtInputCallbackProc proc; XtPointer client_data; app_context Specifies the application context that identifies the application. * source Specifies the source file descriptor on a * POSIX-based system or other * operating-system-dependent device * specification. * condition Specifies the mask that indicates a read, * write, or exception condition or some * other operating-system-dependent condition." From "VMS DECwindows Motif Guide to Application Programming 3.7" Source and condition on OpenVMS are "2. An event flag to monitor. When the intrinsics notices that this flag is set, it calls the XtInputCallbackProc routine you specify. Event flag numbers are restricted to cluster 0, which contains event flag numbers 0 to 31. (See the VMS System Services Reference Manual for more information.) Note that event flag 0 cannot be used as the XtAddInput event flag. 3. An I/O status byte (IOSB) for the condition return code. This argument can be zero. Your application needs a way to set the event flag to indicate that input is available. The most common method of setting the event flag is by using an AST completion routine. For example, in Example 3-13, the START_READ routine starts a $QIO read and specifies CompletionAst as the AST completion routine. CompletionAst sets the event flag." 7. Exiting from an Application "X Window System Toolkit 2.8" "All X Toolkit applications should terminate by calling * XtDestroyApplicationContext and then exiting using * the standard method for their operating system (typi- * cally, by calling exit for POSIX -based systems). The quickest way to make the windows disappear while exiting is to call XtUnmapWidget on each top-level shell widget. The X Toolkit has no resources beyond those in the program image, and the X server will free its resources when its connection to the application is broken." 8. use of select() "James Cameron, cameron@stl.dec.com" "Not a problem as such, but on Unix it is often assumed that communication with an X server is implemented in the X library via a socket file descriptor, which can be obtained from X using the DISPLAY structure or a specific function/macro. I'm not sure what X as such thinks of this, but in my personal opinion it is delving too deeply into things that are X's domain. So Unix code that then goes and uses the file descriptor on a call to select() so as to be told when X events arrive is difficult to port to OpenVMS's implementation of X." Here is some example code showing how to work around the select() problem (look at VMSUTILS.C and INPUT.C and X11WINDOW.C) ftp://ftp.risc.uni-linz.ac.at/pub/netrek/cow/COW.2.02pl1.tar.gz 9. use of ConnectionNumber() "DECwindows Motif for OpenVMS Guide to Non-C Bindings "CONNECTION NUMBER returns an integer that identifies the connection. This routine is defined to be operating system specific by MIT, and there is no direct analogue to the UNIX file descriptor in OpenVMS." This is related to select(), above. Some X11 applications use ConnectionNumber() to retrieve a file descriptor that they then pass to a select() statement. This will not work on OpenVMS, since ConnectionNumber() returns an event flag, and select() cannot be used.