Priism's IOMENU Utility

Overview

The iomenu utility facilitates creation of graphical user interfaces for command-line applications. A computer program that uses the iomenu utility has the following structure:

Fill in a structure describing the command-line parameters.
Optionally call iomenu_set_region_controls() to limit the controls displayed for selecting a region to process.
Optionally configure the interaction with the queues.
Call iomenu(). iomenu() creates the user interface and waits for user interaction. Parts of the user interface are created automatically by iomenu(). Others are created by callback routines you provide. The controls created by iomenu() are handled internally by iomenu() though there are two hooks for calling your own code: one for handling when the application exits and the other for handling changes to the file parameters or the region selected.

BatchRegion.html describes for the end user what the controls automatically generated by iomenu() are. To summarize, the basic pattern of user interaction is:

The user selects the primary input file. This has the side effect of changing the region selected to cover the full size of the input and to change the names of the output files and script.
The user edits the other parameters. Except for the file and queuing parameters, these interactions will be directly handled by your code.
The user requests that the current parameters be written out as a script which the option of running that script immediately either on the local machine or through some sort of queueing system.

The iomenu utility has both C/C++ and Fortran interfaces. For details on how to use the C/C++ interface, consult the C Details section; for details on how to use the Fortran interface, consult the Fortran Details section.

In Priism 4.1.0 and later, there is an alternate way for providing both a command-line and graphical user interface via the IP Framework. The primary differences between that framework and iomenu are:

With the IP Framework, the graphical interface and command-line interface are handled by the same executable and it is the presence or absence of command-line parameters which causes the application to display the graphical user interface. With the iomenu utility, the graphical interface and the command-line program are typically separate.
The submission of jobs works differently in the two. With the IP framework, pressing "Do It" causes processing to be done by the same process that has displayed the graphical user interface; there is an alternate pathway, via the Options->Create batch job... menu entry, to write out a script and optionally run that script. With the iomenu utility, pressing "Do It" generates a script that, when run, will do the processing.
The IP framework is more complicated to use, primarily because it includes processing, display of the graphical interface, generating the script, and command-line parsing. The iomenu utility only handles the graphical interface and generating the script. The process of generating the script is easier with the iomenu utility since no additional code is needed other than that to define the command-line parameters: the IP framework requires an additional callback to write the application-specific parameters.
The IP framework automatically provides some capabilities that iomenu does not: the user can set the output data type and z step size and the result of processing can be appended to an existing data set. The Fortran interface to the iomenu utility imposes upper limits on the number of command-line parameters and related values that the IP framework does not.

Topics

Overview | C details | Fortran details | Release notes

C Details

Example

The file, sample_iomenu_c.c, in the EXAMPLE directory of the Priism distribution demonstrates how to use the iomenu utility from C. The makefile in the same directory includes a rule to build an executable from sample_iomenu_c.c.

Initializing the command-line parameter structure

The command line generated by the iomenu utility has the form

    application_name file1 ... filen \
        switch1_labelswitch1_values ... \
        switchn_labelswitchn_values

file1 through filen are the required input and output files for the application. Each switch consists of a label (customarily -name if the switch has no values or -name= if it has values) which may (depending on the type of switch) be followed by a colon separated list of values.

The contents of the command line are controlled by the entries in the Iomenu structure passed, via a pointer, to iomenu(). The Iomenu structure is defined in iomenu.h as

    typedef struct Iomenu {
        IomenuFile* files;
        IomenuParameter* parameters;
        void* closure;
        int file_count;
        int parameter_count;
        char xyztw_size[4 + IW_MAX_WAVE][16];
        int iparm, nxyztw[5], ixyztw[4 + IW_MAX_WAVE][3], mode;
        float dmin, dmax, dmean, delxyz[3];
    } Iomenu;

The elements of the structure that you need to initialize before calling iomenu() are:

files

Points to the first element of an array of IomenuFile structures. You set the length of the array by the file_count field. The array defines the required file arguments for the command-line application (i.e. file1 through filen). An IomenuFile structure contains four fields: filename, filter, label, and type. You must initialize the type field to one of the following values:

IOMENU_PRIMARY_IMAGE: The file will be treated as a primary input file. Before generating a script via the "Do It" button, the iomenu utility requires that the user specify the names of all primary input files and that those files must exist. When the user changes the name of a primary input file from the user interface, the iomenu utility resets the processing region to cover the entire range of the input and updates the corresponding controls in the graphical user interface. It resets the names of all the files of type IOMENU_OUTPUT_DEFAULT so that they have the same name as the primary input followed by an extension specified by the filter field for the IOMENU_OUTPUT_DEFAULT file. The iomenu utility also resets the directory where the log and script files are written to be the same as the name of the directory containing the primary input file. Because of those side effects, the typical case is to have exactly one primary input file (customarily the first one in the list). More than one is possible, but may lead to confusion on the part of user. Having zero primary input files is also possible, but the user interface is biased toward selecting a region from an existing file rather than specifying from scratch the bounds for a new file. In addition, there is no direct way to specify the default values for the size if you do not have a primary input file: as a crude hack, you could initialize the nxyztw, ixyztw, and xyztw_size fields of the Iomenu structure (see the description of the handle_file_proc callback for details about those fields) from within the menu_proc or special_menu_proc callbacks and then use WMUpdateGroup(1) to update the corresponding interface controls.
IOMENU_OTHER_INPUT: The file will be treated as a required input file (but not a primary input file which the iomenu utility uses to set the default region for processing and the default names for output and script files). Before generating a script via the "Do It" button, the iomenu utility requires that the user specify the names of all required input files and that those files must exist.
IOMENU_OUTPUT_DEFAULT: The file will be treated as a required output file whose default name is the name of the primary input file with the contents of the filter field for the output file appended. Before generating a script via the "Do It" button, the iomenu requires that all required output files have some sort of name specified.
IOMENU_OTHER_OUTPUT: The file will be treated as a required output file; the iomenu utility does not automatically generate a default name for the file when a new primary input file is selected. Before generating a script via the "Do It" button, the iomenu requires that all required output files have some sort of name specified.

The iomenu utility uses the label field in the user interface controls for the file. Each file has a button and a text field, and the contents of the label field are displayed as the label for the button. Initialize the label field with a null-terminated string that contains short name which indicates the the nature of the file to be selected. If the type field is IOMENU_PRIMARY_IMAGE or IOMENU_OTHER_INPUT, the iomenu utility uses the contents of the filter field as the selection pattern argument to WMAddGetFile, and you should initialize the filter field accordingly. If the type field is IOMENU_OUTPUT_DEFAULT, the iomenu utility appends the contents of the filter field to the name of the primary input file to form the default name of the file. If the type field is IOMENU_OTHER_OUTPUT, the iomenu utility ignores the filter field. The filename field holds the name of the file. You would normally initialize the filename field to an empty string except for IOMENU_OTHER_INPUT or IOMENU_OTHER_OUTPUT files for which you have a reasonable default.

parameters

Points to the first element of an array IomenuParameter structures. You set the length of the array by the parameter_count field. The array defines the command-line switches. An IomenuParameter structure contains three fields: label, v, and type. You must initialize the type field to one of the following values:

IOMENU_INTEGER: When the iomenu utility writes out the switch on the command line, it prints the switch as the contents of the label field followed by a colon-separated list of integers. The v.i.count field holds the number of integers, and the v.i.values field points to the first element of the array holding the values for the integers.
IOMENU_REAL: When the iomenu utility writes out the switch on the command line, it prints the switch as the contents of the label field followed by a colon-separated list of floating-point values. The v.r.count field holds the number of floating-point values, and the v.r.values field points to the first element of the array holding the values for the floating-point numbers.
IOMENU_ACTIVE_WHEN_NONZERO: When the iomenu utility writes out the switch on the command line, it prints out the contents of the label field if *(v.pb) is not zero; otherwise, it does not print out anything for the switch.
IOMENU_ACTIVE_WHEN_ZERO: When the iomenu utility writes out the switch on the command line, it prints out the contents of the label field if *(v.pb) is zero; otherwise, it does not print out anything for the switch.
IOMENU_STRING: When the iomenu utility write out the switch on the command line, it prints out the contents of the label field followed by a colon- separated list of character strings. Each element in the list is surrounded by double quotes. The v.c.count field holds the number of elements in the list. The v.c.values field is the array of null-terminated character strings holding the values.

The v field is a union. The elements and their meanings are described above for the different type codes; initialize v accordingly. The iomenu utility prints out the contents of the label field when printing the command-line switch. By convention, labels for IOMENU_INTEGER, IOMENU_REAL, and IOMENU_STRING switches have the form -name=. By convention, labels for the IOMENU_ACTIVE_WHEN_NONZERO and IOMENU_ACTIVE_WHEN_ZERO switches have the form -name.

closure

The closure field is not used internally by the iomenu utility but you can use it to pass along additional information to the callback routines.

file_count

Is the number of elements in the array whose first element is pointed to by the files field.

parameter_count

Is the number of elements in the array whose first element is pointed to by the parameters field.

Calling iomenu_set_region_controls()

To limit the region selection controls displayed, call iomenu_set_region_controls() before calling iomenu(). Calling iomenu_set_region_controls() after calling iomenu() has no effect.

The iomenu_set_region_controls() function is declared in iomenu.h as

    void iomenu_set_region_controls(int style)

style is expected to be one of the following constants which are declared in iomenu.h:

IOMENU_REG_CTRL_ALL: Display all region selection controls. This is the default behavior.
IOMENU_REG_CTRL_5D_SIZE: Only display an indicator with the size of the five dimensions of the primary image input file.
IOMENU_REG_CTRL_3D_SIZE: Only display an indicator with the size of the x dimension, size of the y dimension, and the number of sections for the primary image input file.

Configuring the interaction with the queues

It is possible to customize the selection of the default queue, which queues are listed as available, and whether or not to receive a callback when the user changes the destination queue. The related function calls are iomenu_set_int_property() and iomenu_set_queue_callback(). iomenu_set_int_property() is declared in iomenu.h as

    int iomenu_set_int_property(const char* prop, int i);

iomenu_set_int_property() associates the given integer value, i, with the name, prop. It returns zero when successful and a non-zero value when not successful. The property names that are relevant for customizing the queue behavior are:

DEFAULT_QUEUE_TYPE: If the related integer value is zero, the default destination is the local machine. If the related integer value is one, the default destination is the queue that has been designated as the default destination for serial (single processor) jobs. If the related integer value is two, the default destination is the queue that has been designated as the default destination for parallel (multiprocessor) jobs. If the related integer value is three, the default destination is the queue that has been designated as the default destination for GPU jobs. The default value of this property is one. Modifying this property after calling iomenu() will have no effect on the internal behavior of the iomenu library.
QUEUE_SUBSET: The related integer value, v, defines which queues to include in the list in the user interface. A queue will be included if the bitwise-and of the queue's value (a bitwise-or of one (if the queue accepts parallel jobs), two (if the queue accepts serial jobs), and four (if the queue accepts GPU jobs)) with the ones-complement of v is non-zero. The default value of this property is five. Modifying this property after calling iomenu() will have no effect on the internal behavior of the iomenu library.

iomenu_set_queue_callback() is declared in iomenu.h as

    void iomenu_set_queue_callback(void (*func)(Iomenu*));

iomenu_set_queue_callback() instructs the IOMENU library to call func when the user changes the destination queue. func may be zero and then the IOMENU library does not perform a callback when the user changes the destination queue. The IOMENU library passes a single argument, a pointer to the Iomenu structure that was passed to iomenu(), to the callback. To get a handle to the properties of the current queue (from within the callback for a queue change or any other time after iomenu() has been called), use iomenu_get_current_queue(). iomenu_get_current_queue() is declared in iomenu.h as

    IVEQDMember iomenu_get_current_queue(void);

To get the properties from the handle, use the functions described in the iveqd.h header file. When a queue changes, you may want to change the number of processors to use when submitting a job. To do so use iomenu_set_int_property() with "QUEUE_NPROC" as the name and the number of processors as the integer value; a value of zero or less for the number of processors will select the default number of processors for that queue.

Calling iomenu()

The iomenu() function is declared in iomenu.h as

    void iomenu(
        const char* title,
        const char* submenu_title,
        const char* app_name,
        Iomenu* iom,
        void (*menu_proc)(Iomenu*),
        void (*special_menu_proc)(Iomenu*),
        void (*handle_file_proc)(Iomenu*),
        void (*handle_exit_proc)(Iomenu*)
    );

The arguments are:

title: title is the name that will appear on the title bar of the main dialog.
submenu: The iomenu utility can display a button in the main dialog that will open a child dialog. The most common use for this is to group rarely changed parameters in this child dialog. submenu is the name that will appear on the button in the main dialog to open the child dialog. If submenu is zero or points to an empty string, the button to open the child dialog will not be created.
app_name: app_name is the name of the command-line application to run. If app_name does not begin with / and the environment variable IVE_ENV_SETUP is not set, the iomenu utility will prepend app_name with the name of the Priism executable directory when writing the script file. app_name is also used as the base for the default names of the script and log files as well as the base for the name used when saving or restoring the current contents of the dialog via the Save and Restore buttons.
iom: Points to the Iomenu structure (defined in iomenu.h) describing the command line parameters.
menu_proc: Is the routine the iomenu utility will call to add application-specific controls to the main dialog. See the Callbacks section below for more details. menu_proc may be zero and is ignored in that case.
special_menu_proc: If submenu is not zero and does not point to an empty string, special_menu_proc is the routine the iomenu utility will call to add application-specific controls to the child dialog. See the Callbacks section below for more details. If submenu is zero or points to an empty string, special_menu_proc is ignored. special_menu_proc may be zero and is ignored in that case.
handle_file_proc: Is the routine the iomenu utility will call when the user changes the name of one of the required files or changes the bounds of the region to process. See the Callbacks section below for more details. handle_file_proc may be zero and is ignored in that case.
handle_exit_proc: Is the routine the iomenu utility will call when the user exits the application via the button labeled "Exit" in the main dialog or via the window manager. See the Callbacks section below for more details. handle_exit_proc may be zero and is ignored in that case.

Callbacks

For the C/C++ interface to the iomenu utility, you set the callbacks via the last four arguments to iomenu().

If the menu_proc argument to iomenu() is not zero, the iomenu utility calls the function pointed to by menu_proc after it has initialized the WM library (with WMInit), and added the controls for the required files and the region bounds to the main dialog. After calling the function pointed to by menu_proc, the iomenu utility will complete the main dialog by adding an optional button to open a child dialog (see the description of the submenu_title argument to iomenu() for more information) and a series of buttons, labeled "Exit", "Save", "Restore", "Options, and "Do It", at the bottom of the dialog. The iomenu utility passes personal() a single argument, the pointer to an Iomenu structure that you passed to iomenu(). Normally, you would use the menu_proc callback to add the graphical user interface components to the main dialog that are necessary to control the command-line switches you defined in the Iomenu structure.

If the special_menu_proc argument to iomenu() is not zero and the submenu_title argument to iomenu() is not zero and does not point to an empty string, the iomenu utility calls the function pointed to by special_menu_proc after it has created the main dialog and initialized an empty child dialog. After calling the function pointed to by special_menu_proc, the iomenu utility will add a button, labeled, "OK", for closing the child dialog; the iomenu utility will then enter the loop to process user interactions. The iomenu utility passes the function pointed to by special_menu_proc a single argument, the pointer to an Iomenu structure that you passed to iomenu(). Normally, you would use the special_menu_proc callback to add the graphical user interface components that you did not put in the main dialog.

If the handle_file_proc argument to iomenu() is not zero, the iomenu_utility calls the function pointed to by handle_file_proc when the user changes the name of one of the required files or changes the bounds of the region to process. The iomenu utility passes the function pointed to by handle_file_proc a single argument, the pointer to an Iomenu structure that you passed to iomenu(). Before calling the function pointed to by handle_file_proc, the iomenu utility changes the value of the iparm field in the Iomenu structure. If the function pointed to by handle_file_proc is to be called because the user changed one of the names of the required files, the iomenu_utility sets iparm to one plus the index of that file in the files array of the Iomenu structure. If the file changed was a primary input file, the iomenu utility will also read the header of that field and reset the following fields of the Iomenu structure:

ixyztw: ixyztw holds the bounds of the region to process. ixyztw[0][0] is the first x pixel, and ixyztw[0][1] is the last x pixel. After changing a primary input file, ixyztw[0][0] will be zero and ixyztw[0][1] will be the size of the x dimension in pixels minus one. ixyztw[1][0] is the first y pixel, and ixyztw[1][1] is the last y pixel. After changing a primary input file, ixyztw[1][0] will be zero and ixyztw[1,1] will be the size of the y dimension in pixels minus one. ixyztw[2][0] is the first z section, and ixyztw[2][1] is the last z section. After changing a primary input file, ixyztw[2][0] will be zero and ixyztw[2][1] will be the number of z sections minus one. ixyztw[3][0] is the first time point, ixyztw[3][1] is the last time point, and ixyztw[3][2] is the time point increment. After changing a primary input file, ixyztw[3][0] will be zero, ixyztw[3][1] will be the number of time points minus one, and ixyztw[3][2] will be one. ixyztw[j][0] where j is greater than three is the wavelength for the (j-3)rd channel. ixyztw[j][1] where j is greater than three is zero if the (j-3)rd channel has been selected for processing and is otherwise non-zero. After changing a primary input file, the wavelengths will match the values in the header (to the nearest integer) and all wavelengths will be selected for processing (in the current implementation an exception is made for cases where the wavelength is less than or equal to 100 or greater than or equal to 999; in that case ixyztw[j][0] and ixyztw[j][1] are set to zero).
nxyztw: Holds the dimensions of the file. nxyztw[0] is the number of x pixels minus one. nxyztw[1] is the number of y pixels minus one. nxyztw[2] is the number of z sections minus one. nxyztw[3] is the number of time points minus one. nxyztw[4] is the number of wavelengths.
xyztw_size: Holds printable versions of the full range of the file and the wavelengths. xyztw_size[0] is the x range printed as 0:n where n is the number of x pixels minus one. xyztw_size[1] is the y range printed as 0:n where n is the number of y pixels minus one. xyztw_size[2] is the z range printed as 0:n where n is the number of z sections minus one. xyztw_size[3] is the time range printed as 0:n where n is the number of time points minus one. xyztw_size[j] where j is greater than three is the printed version of the wavelength for the (j-3)rd wavelength (if the wavelength is less than or equal to 100 and greater than or equal to 999, the current implementation sets xyztw_size[j] to " ").
mode: Holds the pixel type of the file.
dmin, dmax, and dmean: Holds the minimum, maximum, and mean value, respectively, recorded for the first wavelength in the file's header.
delxyz: Holds the pixel spacing recorded in the file's header.

If the function pointed to by handle_file_proc is to be called because the user changed the bounds of the region, iparm will be negative one if the x range changed, negative two if the y range changed, negative three if the z range changed, negative four if the time range changed, or negative five if the wavelengths selected changed. The ixyztw field of the Iomenu structure (see above for details) will hold the current region bounds.

If the handle_exit_proc argument to iomenu() is not zero, The iomenu utility calls the function pointed to by handle_exit_proc when the user presses the button labeled "Exit" in the main dialog or when the user force the application to exit via the window manager. The iomenu utility passes the function pointed to by handle_exit_proc a single argument, the pointer to an Iomenu structure that you passed to iomenu().

Compiling and linking

For compilation, iomenu.h is located in the INCLUDE directory of the Priism distribution (i.e. Linux/x86/INCLUDE for x86 Linux systems, Linux/x86_64/INCLUDE for x86_64 Linux systems, and Darwin/INCLUDE for Mac OS X systems). For linking, you will need to link against the libraries, libiomenu.a and either libive.a or libive.so, in addition to the WM library (for details about linking with the WM library, see the Compiling and Linking section of the WM library documentation) and IM or IWL libraries (for details about linking with the IM and IWL libraries, see the Compiling and Linking section of the IM library documentation. For x86 Linux, the libraries are in the Linux/x86/LIB directory of the Priism distribution. For x86_64 Linux, the libraries are in the Linux/x86_64/LIB directory of the Priism distribution. For Mac OS X systems, the libraries are in the Darwin/LIB directory of the Priism distribution.

Topics

Overview | C details | Fortran details | Release notes

Fortran Details

Example

The file, sample_iomenu_f.f, in the EXAMPLE directory of the Priism distribution demonstrates how to use the iomenu utility from Fortran. The makefile in the same directory includes a rule to build an executable from sample_iomenu_f.f.

Initializing the command-line parameter structure

The command line generated by the iomenu utility has the form

    application_name file1 ... filen \
        switch1_labelswitch1_values ... \
        switchn_labelswitchn_values

The contents of the command line are controlled by the entries in the iomenu_struct structure passed to iomenu(). The iomenu_struct structure is defined in iomenu.inc as

       structure /iomenu_struct/
           integer*4     itypes(2,20), ivals(40), ifiletype(11), iuser(20)
           real*4        rvals(20), ruser(20)
           character*256 cvals(10)
           character*80  labels(20), filelabels(10)
           character*256 filenames(10)
           character*80  filefilter(10)
           character*10  xyztw_size(9)
           integer*4     iparm, nxyztw(5), ixyztw(3, 9), mode
           real*4        dmin, dmax, dmean, delxyz(3)
       end structure

The elements of the structure that you need to initialize before calling iomenu() are:

ifiletype

Sets the number and type (input or output) of the required files. ifiletype(i) sets the type of the ith file and must be one of the following values:

0: Marks the end of the list, i.e. if ifiletype(i) is zero and no earlier element of ifiletype is zero, then there will be i minus one files printed at the start of the command line.
1: Specifies that the file is a primary input file. Before generating a script via the "Do It" button, the iomenu utility requires that the user specify the names of all primary input files and that those files must exist. When the user changes the name of a primary input file from the user interface, the iomenu utility resets the processing region to cover the entire range of the input and updates the corresponding controls in the graphical user interface. It resets the names of all the output files of type 3 so that they have the same name as the primary input followed by an extension specified by the element of the filefilter field for that output file. The iomenu utility also resets the directory where the log and script files are written to be the same as the name of the directory containing the primary input file. Because of those side effects, the typical case is to have exactly one primary input file (customarily the first one in the list). More than one is possible, but may lead to confusion on the part of user. Having zero primary input files is also possible, but the user interface is biased toward selecting a region from an existing file rather than specifying from scratch the bounds for a new file. In addition, there is no direct way to specify the default values for the size if you do not have a primary input file: as a crude hack, you could initialize the nxyztw, ixyztw, and xyztw_size fields (see the description of the custom_ifile() callback for details about those fields) from within the personal() or special_parameters() callbacks and then use WMUpdateGroup(1) to update the corresponding interface controls.
2: Specifies that the file is a required input file (but not a primary input file which the iomenu utility uses to set the default region for processing and the default names for output and script files). Before generating a script via the "Do It" button, the iomenu utility requires that the user specify the names of all required input files and that those files must exist.
3: Specifies that the file is an output file. When ifiletype(i) is three, the default name for that output file will be the name of the primary input file with the contents of filefilter(i) appended. Before generating a script via the "Do It" button, the iomenu utility requires that all the files of type three have some sort of name specified.
4: Specifies that the file is an output file but, unlike files of type three, the iomenu utility does not automatically generate a default name when the user selects a primary input file. Before generating a script via the "Do It" button, the iomenu utility requires the all the files of type four have some sort of name specified.

filenames

filenames(i) holds the name of the ith required file. You would normally initialize the names for the files you use to be all spaces (or use an appropriate compiler switch to do so for you) except for input files of type two and output files of type three for which you have a reasonable default.

filelabels

In the user interface, each required file has a corresponding button and text field; these controls appear at the top of the main dialog. filelabels(i) sets the label on the button for the i button. You should initialize the labels for the files you use to some short names indicating the nature of the file to be selected.

filefilter

If ifiletype(i) is one or two, filefilter(i) is used as the selection pattern argument to WMAddGetFile and should be initialized accordingly. If ifiletype(i) is three, filefilter(i) is appended to the name of the primary input file to form the default name for the ith file. If ifiletype(i) is four, the value of filefilter(i) is ignored.

itypes

Defines the type and number of values associated with each command-line switch. itypes(1,i) sets the number of parameters associated with the switch; the first value j where itypes(1,j) is less than zero terminates the list of switches (i.e. there will be j minus one switches printed on the command line). itypes(2,i) is the type of the switch and must be one of the following:

1: The switch has itypes(1,i) integer values (the next itypes(1,i) values from the ivals field) associated with it. When the switch is printed out for the command line, the integers are printed out in a colon-separated list immediately after the switch label.
2: The switch has itypes(1,i) floating-point values (the next itypes(1,i) values from the rvals field) associated with it. When the switch is printed out for the command line, the floating-point values are printed out in a colon-separated list immediately after the switch label.
3: The switch has one integer (the next element from the ivals field) associated with it. If that value is not zero when the command line is printed, then labels(i) will be printed on the command line (without any values following it); if that value is zero when the command line is printed, then labels(i) will not be printed.
-3: The switch has one integer (the next element from the ivals field) associated with it. If that value is zero when the command line is printed, then labels(i) will be printed on the command line (without any values following it); if that value is not zero when the command line is printed, then labels(i) will not be printed.
4: The switch has itypes(1,i) character arrays (the next itypes(1,i) elements from the cvals field) associated with it. When the switch is printed out for the command line, the contents of those character arrays (for each array the trailing spaces and null characters are trimmed and the result is then enclosed in double quotes) will be printed out as a colon-separated list immediately after the switch label.

labels

labels(i) specifies the switch name printed on the command line for the ith switch. If itypes(2,i) is one, two, or four, the switch name, by convention, would have the form -name=. If itypes(2,i) is three or negative three, a conventional switch name would have the form -name.

ivals

Holds the values associated with switches of types one, three, and negative three. Because ivals has forty elements, you are limited to at most forty integer values for the command line.

rvals

Holds the values associated with switches of type two. Because rvals has twenty elements, you are limited to at most twenty floating-point values for the command line.

cvals

Holds the values associated with switches of type three. Because cvals has ten elements, you are limited to at most ten character array values for the command line.

ixyztw

Unless you compile your application so that the structure values are initialized to zero, set ixyztw(1,i) and ixyztw(2,i) to zero for values of i from one to nine. For more details about the ixyztw field, see the description of the custom_ifile callback.

nxyztw

Unless you compile your application so that the structure values are initialized to zero, set nxyztw(i) to zero for values of i from one to five. For more details about the nxyztw field, see the description of the custom_ifile callback.

Calling iomenu_set_region_controls()

To limit the region selection controls displayed, call iomenu_set_region_controls() before calling iomenu(). Calling iomenu_set_region_controls() after calling iomenu() has no effect.

The iomenu_set_region_controls() function is declared as

    subroutine iomenu_set_region_controls(istyle)
    integer istyle

istyle is expected to be one of the following constants which are declared in iomenu.inc:

IOMENU_REG_CTRL_ALL: Display all region selection controls. This is the default behavior.
IOMENU_REG_CTRL_5D_SIZE: Only display an indicator with the size of the five dimensions of the primary image input file.
IOMENU_REG_CTRL_3D_SIZE: Only display an indicator with the size of the x dimension, size of the y dimension, and the number of sections for the primary image input file.

Configuring the interaction with the queues

    integer function iomenu_set_int_property(prop, i)
    character*(*) prop
    integer i

DEFAULT_QUEUE_TYPE: If the related integer value is zero, the default destination is the local machine. If the related integer value is one, the default destination is the queue that has been designated as the default destination for serial (single processor) jobs. If the related integer value is two, the default destination is the queue that has been designated as the default destination for parallel (multiprocessor) jobs. If the related integer value is three, the default destination is the queue that has been designated as the default destination for GPU jobs. The default value of this property is one. Modifying this property after calling iomenu() will have no effect on the internal behavior of the iomenu library.
QUEUE_SUBSET: The related integer value, v, defines which queues to include in the list in the user interface. A queue will be included if the bitwise-and of the queue's value (a bitwise-or of one (if the queue accepts parallel jobs), two (if the queue accepts serial jobs), and four (if the queue accepts GPU jobs)) with the ones-complement of v is non-zero. The default value of this property is five. Modifying this property after calling iomenu() will have no effect on the internal behavior of the iomenu library.

iomenu_set_queue_callback() is declared as

    subroutine iomenu_set_queue_callback(func);
    external func

iomenu_set_queue_callback() instructs the IOMENU library to call the subroutine func when the user changes the destination queue. The IOMENU library passes a single argument, a reference to the same iomenu_struct that was passed to iomenu(), to the callback. To get a handle to the properties of the current queue (from within the callback for a queue change or any other time after iomenu() has been called), use iomenu_get_current_queue(). iomenu_get_current_queue() is declared as

    integer function iomenu_get_current_queue()

Calling iomenu()

The iomenu() subroutine is declared as

       subroutine iomenu(title, submenu, iroot, iom)
       character title*(*), submenu*(*), iroot*(*)
       record /iomenu_struct/ iom

The arguments are:

title: title is the name that will appear on the title bar of the main dialog.
submenu: The iomenu utility can display a button in the main dialog that will open a child dialog. The most common use for this is to group rarely changed parameters in this child dialog. submenu is the name that will appear on the button in the main dialog to open the child dialog. If submenu is a character array which only contains spaces or null characters or %LOC(submenu) is equal to zero, the button to open the child dialog will not be created.
iroot: iroot is the name of the command-line application to run. If iroot does not begin with / and the environment variable IVE_ENV_SETUP is not set, the iomenu utility will prepend iroot with the name of the Priism executable directory when running the script file. iroot is also used as the base for the default names of the script and log files as well as the base for the name used when saving or restoring the current contents of the dialog via the Save and Restore buttons.
iom: Is a instance of the iomenu_struct structure (defined in iomenu.inc) which defines the command-line parameters.

Callbacks

The Fortran interface to the iomenu utility expects you to define four other subroutines: personal(), special_parameters(), custom_ifile(), and call_exit().

The iomenu utility calls personal() after it has initialized the WM library (with WMInit), and added the controls for the required files and the region bounds to the main dialog. After calling personal(), the iomenu utility will complete the main dialog by adding an optional button to open a child dialog (see the description of the submenu argument to iomenu() for more information) and a series of buttons, labeled "Exit", "Save", "Restore", "Options, and "Do It", at the bottom of the dialog. The iomenu utility passes personal() a single argument, the instance of the iomenu_struct structure that you passed to iomenu(). If you need to pass additional information to the personal() subroutine you can use the iuser and and ruser elements of the iomenu_struct structure or use common blocks. Normally, you would use personal() to add the graphical user interface components to the main dialog that are necessary to control the command-line switches you defined in the iomenu_struct structure.

special_parameters() is only called if the submenu argument to iomenu() was a character array that did not contain only spaces or null characters. The iomenu utility calls special_parameters() after if has created the main dialog and initialized an empty child dialog. After calling special_parameters(), the iomenu utility will add a button, labeled "OK", for closing the child dialog; the iomenu utility will then enter the loop to process user interactions. The iomenu utility passes special_parameters() a single argument, the instance of the iomenu_struct structure that you passed to iomenu(). If you need to pass additional information to the special_parameters() subroutine you can use the iuser and and ruser elements of the iomenu_struct structure or use common blocks. Normally, you would use special_parameters() to add the graphical user interface components that you did not put in the main dialog.

The iomenu utility calls custom_ifile() when the user changes the name of one of the required files or changes the bounds of the region to process. The iomenu utility passes custom_ifile() a single argument, the instance of the iomenu_struct structure that you passed to iomenu(). If you need to pass additional information to the custom_ifile() subroutine you can use the iuser and and ruser elements of the iomenu_struct structure or use common blocks. Before calling custom_ifile(), the iomenu utility changes the value of the iparm field in the iomenu_struct structure. If custom_ifile() is to be called because the user changed one of the names of the required files, the iomenu utility sets iparm to the index of that file in the ifiletype and filenames array. If the file changed was a primary input file, the iomenu utility will also read the header of that file and reset the following fields of the iomenu_struct structure:

ixyztw: ixyztw holds the bounds of the region to process. ixyztw(1,1) is the first x pixel, and ixyztw(2,1) is the last x pixel. After changing a primary input file, ixyztw(1,1) will be zero and ixyztw(2,1) will be the size of the x dimension in pixels minus one. ixyztw(1,2) is the first y pixel, and ixyztw(2,2) is the last y pixel. After changing a primary input file, ixyztw(1,2) will be zero and ixyztw(2,2) will be the size of the y dimension in pixels minus one. ixyztw(1,3) is the first z section, and ixyztw(2,3) is the last z section. After changing a primary input file, ixyztw(1,3) will be zero and ixyztw(2,3) will be the number of z sections minus one. ixyztw(1,4) is the first time point, ixyztw(2,4) is the last time point, and ixyztw(3,4) is the time point increment. After changing a primary input file, ixyztw(1,4) will be zero, ixyztw(2,4) will be the number of time points minus one, and ixyztw(3,4) will be one. ixyztw(1,j) where j is greater than four is the wavelength for the (j-4)th channel. ixyztw(2,j) where j is greater than four is zero if the (j-4)th channel has been selected for processing and is otherwise non-zero. After changing a primary input file, the wavelengths will match the values in the header (to the nearest integer) and all wavelengths will be selected for processing (in the current implementation an exception is made for cases where the wavelength is less than or equal to 100 or greater than or equal to 999; in that case ixyztw(1,j) and ixyztw(2,j) are set to zero).
nxyztw: Holds the dimensions of the file. nxyztw(1) is the number of x pixels minus one. nxyztw(2) is the number of y pixels minus one. nxyztw(3) is the number of z sections minus one. nxyztw(4) is the number of time points minus one. nxyztw(5) is the number of wavelengths.
xyztw_size: Holds printable versions of the full range of the file and the wavelengths. xyztw_size(1) is the x range printed as 0:n where n is the number of x pixels minus one. xyztw_size(2) is the y range printed as 0:n where n is the number of y pixels minus one. xyztw_size(3) is the z range printed as 0:n where n is the number of z sections minus one. xyztw_size(4) is the time range printed as 0:n where n is the number of time points minus one. xyztw_size(j) where j is greater than four is the printed version of the wavelength for the (j-4)th wavelength (if the wavelength is less than or equal to 100 and greater than or equal to 999, the current implementation sets xyztw_size(j) to "___").
mode: Holds the pixel type of the file.
dmin, dmax, and dmean: Holds the minimum, maximum, and mean value, respectively, recorded for the first wavelength in the file's header.
delxyz: Holds the pixel spacing recorded in the file's header.

If custom_ifile() is to be called because the user changed the bounds of the region, iparm will be negative one if the x range changed, negative two if the y range changed, negative three if the z range changed, negative four if the time range changed, or negative five if the wavelengths selected changed. The ixyztw field of the iomenu_struct structure (see above for details) will hold the current region bounds.

The iomenu utility calls call_exit() when the user presses the button labeled "Exit" in the main dialog. The iomenu utility passes call_exit() a single argument, the instance of the iomenu_struct structure that you passed to iomenu(). If you need to pass additional information to the call_exit() subroutine you can use the iuser and and ruser elements of the iomenu_struct structure or use common blocks. In the current implementation, call_exit() is not called when the user exits the application via the window manager (you would have to call WMSetExitFunction from within the personal() or special_parameters() routines if you wanted to trap that case).

Compiling and linking your application

For compilation, iomenu.inc is located in the INCLUDE directory of the Priism distribution (i.e. Linux/x86/INCLUDE for x86 Linux systems and Darwin/INCLUDE for Mac OS X systems). For linking, you will need to link against the libraries, libiomenu.a, libimcompat.a and either libive.a or libive.so in addition to the WM library (for details about linking with the WM library, see the Compiling and Linking section of the WM library documentation) and IM or IWL libraries (for details about linking with the IM and IWL libraries, see the Compiling and Linking section of the IM library documentation. For x86 Linux systems, two versions of libiomenu.a and libimcompat.a are available. The versions in the Linux/x86/LIB directory of the Priism distribution were compiled with the Portland Group Fortran compiler. The versions in the Linux/x86/LIB/intel directory were compiled with version 7 of the Intel Fortran compiler. The versions for the Intel compiler require that you also link with Intel's Posix and Vax compatibility libraries (i.e. include -posixlib -vaxlib in the linker options after the reference to libimcompat.a). For x86_64 Linux systems, libiomenu.a and libimcompat.a are in the Linux/x86_64/LIB directory of the Priism distribution. Those libraries were compiled with version 9 of the Intel Fortran compiler; if you link against them, you will also need to link against Intel's libifport (i.e. include -lifport in the linker options after the reference to libimcompat.a). For Mac OS X systems, two versions of libiomenu.a and libimcompat.a are available. The versions in the Darwin/LIB directory of the Priism distribution are for the Absoft compiler (if you are using a PowerPC system) or the Intel compiler (if you are using an Intel system). When using the Absoft compiler, you will need to specify the -N15 and -f compiler options which force external names to be all lower case with an underscore appended. You will also need to link with Absoft's U77 library when linking with libimcompat.a (i.e. with a -lU77 in the linker options after the reference to libimcompat.a). When using the Intel compiler, you will need to link against Intel's libifport when linking with libimcompat.a (i.e. include -lifport -lifcore -limf -lirc in the linker options after the reference to libimcompat.a). The versions in the Darwin/LIB/xlf directory of the Priism distribution are for the IBM XL Fortran compiler. To use them, you will need to compile with the IBM XL Fortran compiler with the -qextname option.

Topics

Overview | C details | Fortran details | Release notes

Release Notes

Added iomenu_get_current_queue(), iomenu_set_int_property(), and iomenu_set_queue_callback() in 4.2.2.

Versions from IVE 4.2.2 and later no longer provide an iomenu.o for backwards compatibility with IVE 3.3; link against libiomenu.a instead.

Fortran applications linking to the library in IVE 4.2.2 or later will also have to link against libive.a or libive.so.

Added iomenu_set_region_controls() in 4.2.0.

The C interface was added in IVE 4.1.8. Prior versions had a different version of iomenu.h but only a Fortran subroutine interface.

In IVE 4.1.2, expanded the cvals and filenames arrays in the iomenu_struct structure to have elements that are 256 characters long. Previous IVE 4 versions and all IVE 3.3 versions have elements that are eighty characters long.

The location of the libraries and include files is different than in IVE 3.3 (in IVE 3.3 the libraries are in the LIB directory of the Priism distribution and the include files are in the INCLUDE directory of the Priism distribution). Older versions of IVE 3.3 (prior to March 2004) do not have libiomenu.a: the Fortran interface is in iomenu.o.

Use of the QDEFAULT environment variable, described in the Queue section of BatchRegion.html, was added in 4.1.2. Use of QUECOM environment variable, also described in the Queue section of BatchRegion.html, was added in the August 2000 version of IVE 3.3 and has always been in the IVE 4 version. Use of the IVE_ENV_SETUP environment variable was added in the June 1999 versions of IVE 3.3 and has always been in the IVE 4 version.

Topics

Overview | C details | Fortran details | Release notes

Priism's IOMENU Utility

Overview

Topics

Related Priism Topics

C Details

Example

Initializing the command-line parameter structure

Calling iomenu_set_region_controls()

Configuring the interaction with the queues

Calling iomenu()

Callbacks

Compiling and linking

Topics

Fortran Details

Example

Initializing the command-line parameter structure

Calling iomenu_set_region_controls()

Configuring the interaction with the queues

Calling iomenu()

Callbacks

Compiling and linking your application

Topics

Release Notes

Topics