Porting between IVE Versions

This document is an empirical result: it summarizes problems encountered in particular porting projects and doesn't address all possible problems. The different versions described are those available at UCSF.

navigation | top | IVE 2 -> IVE 3 | IVE 3 -> IVE 3.3 | IVE 3.3 -> IVE 4

IVE 2 to IVE 3

The issues listed below are drawn from the experience of porting the optical microscopy data collection software (Resolve3D, see /home2/lehua/IVE3/APPL/RESOLVE3D/OM1 for the result) which is C code and does not use the IM library for writing data files.

Change in function arguments (no function name change)

IWDecZoom and IWIncZoom now take the integer value for the stream attached to the window via IMOpen or imopen_ and not the number of the window.

The window event handling and display change functions which took the window number as a parameter now take the number of the stream attached to the window. The affected functions are (WMCancelEventHandlers is also affected but it's name was changed to WMCancelEventHandler):

Simple function name changes

isalcshm, isalcnamedshm, isfreeshm, and isrtnamedshmaddr are replaced by IWAlcSHM, IWAlcNamedSHM, IWFreeSHM, and IWRtNamedSHMAdd respectively. IWSharedAlloc should be replaced by IWAlcSHM.

Function name changes and changes in arguments

Functions which operated on an image window and took the window number as an argument (or a pointer to it for the FORTRAN interface) have been replaced by functions which take the integer value for the stream attached to the window via IMOpen or imopen_ (the FORTRAN interface takes a pointer to the stream value). Here's a list of some of the old functions with the new versions listed second

In Resolve3D, it wasn't necessary to carry over the isalcrl_bkg_ calls at all (one after changing the scratch size was replaced with IWClearWin). The combination of isgetbuttpressinfo_ and iswintodata_ can be replaced by IWXEvtToData.

For calls to isrtnextdlwin_ used to implement loops over all open windows, the functions IWDLDecZoom and IWDLIncZoom (to step the zoom on all windows) or IWDLPrevSec and IWDLNextSec (to step the currently viewed section in all windows) could replace the loop in application code.

The functionality of iscopydisimgbox_ (except for the greater freedom in the choice of the destination type) is the same as that of IMRdPas. There is no equivalent for iscopysclimgbox_. Getting the scale with IWRtScl or IWRtSecScl, the data values with IMRdPas, and then scaling the values with IWScaleImage is one approach though it won't match what the monitor displays in all cases (one of these is that the monitor employs a special algorithm when the minimum and maximum value for the scale are the same).

Functions not present in IVE 3

WMToggleScroll or an equivalent is not available in IVE 3.

Compiling and linking changes

The IVE include and library directories are no longer in the APPL subdirectory of the IVE directory tree; they are now siblings of the APPL directory.

Changes in library behavior

The image window in IVE 2 handles calls to change the window position differently than IVE 3; in Resolve3D the effect was to nicely adjust the size of the window for the image size. Here's the essence of the IVE 2 code from Resolve3D:

     int istream;
     int xstart;
     int ystart;
     int width;
     int height;

     iwrtwinpos_(&istream, &xstart, &ystart, &width, &height);
     width = 540;
     height = 540;
     iwalwinpos_(&istream, &xstart, &ystart, &width, &height);

and what was done to mimic the effect under IVE 3 (nx and ny are the image dimensions after compensating for zoom):

         Magic numbers for IVE3 to get the window to display specified size
         without trimming.
     const int padding[2] = { 24, 78 };
     int istream;
     int xstart;
     int ystart;
     int width;
     int height;
     int nx;
     int ny;

     IWRtWinPos(istream, &xstart, &ystart, &width, &height);
     IWAlWinPos(istream, xstart, ystart-padding[1]+height-ny,
       nx+padding[0], ny+padding[1]);

Changing the contents of a variable which was passed to WMAddScrolledChoices as the list of available choices and then calling WMUpdateWidget or WMUpdateGroup to update the scrolled choices widget does not cause the widget to change in IVE 3.

If your application calls the WMInitApp function (WM library internal function) and you expect to not have the window manager add a title bar, you'll need to add a call to WMNoTitleBar before the WMInitApp call.

The calls to alter the scaling of a single section tickled a bug in the IVE 3 library (it was also present in IVE 3.3). This bug was fixed at UCSF (11 March 1998), but if you have an older version of the library, IKAlSecScl in IMKS/IWL/IWImsubDisp.c should be modified to lock the memory while making the call to IKRmImgMem - analogous to what is done in IKAlScl.

Useful new functions

There are now C interfaces for functions that had a FORTRAN style interface. There are differences in the signatures (due to C passing by value and FORTRAN passing by reference and due to differences in string handling). Here's a list of some of the C functions with the equivalent FORTRAN call:

navigation | top | IVE 2 -> IVE 3 | IVE 3 -> IVE 3.3 | IVE 3.3 -> IVE 4

IVE 3 to IVE 3.3

The issues listed below are largely drawn from the experience of porting the EM bead alignment and reconstruction software, mostly FORTRAN with some C, to use IVE 3.3.

Compiling and linking changes

IVE 3.3 uses a different object / executable format than IVE 3. This has a variety of implications. Compiling, linking, and running must be done under IRIX 6.2 or higher. The compilers for the format used with IVE 3 (o32) and the compilers for the format used with IVE 3.3 (n32) are distinct: they have different behaviors especially regarding the choice of command line arguments and the types of errors and warnings caught (in this respect the compilers for n32 are generally pickier and more thorough).

The most common problem is generating executables or libraries in the correct format to use with the IVE libraries. Perhaps the easiest way to do this is to specify -n32 on the command line when linking and compiling. There are other methods: see the cc or pe_environ man pages. Another common problem is that the system library names are different from what you may have in your makefile. For instance, graphics and windowing libraries which had _s in their name should be referred to without the _s (i.e. Xm_s, Xt_s, X11_s, and gl_s would be Xm, Xt, X11, and gl). If you're linking FORTRAN source with something other than f77, you'll probably find that many of the libraries that you included in the link to satisfy the FORTRAN code can not be found and are no longer needed.

For linking FORTRAN code against the IP library, if you see errors because the linker can not find find ippostinfo_, ipaddinput_, ipsetmenutitle_, or ipaddoutput_, you'll need to link against ipintermed.o as well.

Changes in library behavior

For programs using the FORTRAN call interface, the handling of string termination has changed. In general, any string passed to the IW or WM libraries from FORTRAN needs to be terminated with a NULL character (\0 or char(0)). For applications using the WM library, a common symptom of incorrectly terminated strings (if it doesn't just dump core) is beeping as the application creates graphical interfaces.

In IVE 3, the mx parameter to IMWrPas (iwrpas in Fortran) had to be multiplied by two when writing complex data (i.e. to write 7 columns of complex data the mx parameter would be 14). This is no longer true in IVE 3.3. Confusingly, the same correction does not apply to IMRdPas (irdpas) in IVE 3.

navigation | top | IVE 2 -> IVE 3 | IVE 3 -> IVE 3.3 | IVE 3.3 -> IVE 4

IVE 3.3 To IVE 4

Consult the IM library documentation, IW library documentation, WM library documentation, and IP library documentation for lists of changes and incompatibilities for those libraries.

navigation | top | IVE 2 -> IVE 3 | IVE 3 -> IVE 3.3 | IVE 3.3 -> IVE 4

IVE/Priism home page | Programming interfaces | Sample applications

modified November 17, 2003

IVE Development Team (ive-web@msg.ucsf.edu)
Macromolecular Structure Group, UCSF (http://msg.ucsf.edu)