File: README_USERD_2.05

package info (click to toggle)
openfoam 4.1%2Bdfsg1-1
links: PTS, VCS
area: main
in suites: stretch
size: 163,028 kB
ctags: 58,990
sloc: cpp: 830,760; sh: 10,227; ansic: 8,215; xml: 745; lex: 437; awk: 194; sed: 91; makefile: 77; python: 18
file content (4543 lines) | stat: -rw-r--r-- 169,513 bytes
parent folder | download | duplicates (3)
README_USERD_2.05
=================
--------------------------------------
EnSight User Defined Reader Capability   ===> (API 2.05)
--------------------------------------
A user defined reader capability is included in EnSight which can allow
otherwise unsupported structured or unstructured data to be read.  The user
defined reader capability utilizes dynamic shared libraries composed of
routines defined in this document but produced by you, the user, (or some
third party). This capability is currently available for dec, ibm, hp, sgi,
sun, linux, alpha linux, and NT servers.

You should refer to beginning of README_USERD_2.0  and/or README_1.0_to_2.0
for a discussion of the differences between API 1.0 and API 2.*.

***>> API 2.05 additional capabilities (beyond API 2.04):
Routines to handle material species.
    USERD_get_number_of_species
    USERD_get_matsp_info

Routines to handle variable extraction parameters after a read, and then
update the variables accordingly.  Similar to the extra GUI capabilities
(which are processed before a read).  (Can actually be added to pre-2.05 readers)
    USERD_get_var_extract_gui_numbers
    USERD_get_var_extract_gui_defaults
    USERD_set_var_extract_gui_data

Routines to obtain rigid body values from a reader.
(Routines were added - EnSight is now using for Nastran and STL readers
                       with Dynasty rigid body motion data file)
    USERD_rigidbody_existence
    USERD_rigidbody_values

Routine that lets reader know when EnSight is getting the right side of a time
interval for variable interpolation between steps.  Not generally needed for
most readers - however, may be needed for those that implement rigid body, and
wish to cache left and right timespan information for interpolation within the
reader itself.  (Can actually be added to pre-2.05 readers)
    USERD_set_right_side


***>> API 2.04 additional capabilities (beyond API 2.03):
Routines to handle failed elements.  Basically 
a.One routine to return a flag indicating the existence of 
  failed elements in at least one part in at least one 
  timestep in the model.  
b.A second routine to return a matrix of flags indexed by part and
  element type indicating which parts and element types have failed
  elements at the current time step.
c.Finally a third routine to return an array of flags for a given
  part and element type that is number of elements of that type long
  indicating which elements have failed, and which have not failed.


***>> API 2.03 additional capabilities (beyond API 2.01):
1. Routines to handle materials
2. Routines to handle nsided and nfaced elements
3. Modified routine to handle structured ranges


****************************************************************************
Note: The dummy_gold reader, the Ensight Gold example reader, the
      ABAQUS_ODB reader and the LS-DYNA reader have been moved to 
      this 2.04 API level.
****************************************************************************


The process for producing a user defined reader is:
---------------------------------------------------
1. Write code for all pertinent routines in the library (Unless someone else
   has done this for you).

        This is of course where the work is done by the user.  The word
        "pertinent" is used because depending on the nature of the data, some
        of the routines in the library may be dummy routines.

        The source code for a dummy_gold library and for various other
        working or sample libraries is copied from the installation CD during
        installation.  These will be located in directories under:

        $CEI_HOME/ensight76/user_defined_src/readers

        examples:
        --------
        Basic dummy_gold routines provide skeleton for a new reader
          $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold

        Sample library which reads unstructured binary EnSight Gold data
          $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold

        You may find it useful to place your library source in this area as
        well, but are not limited to this location.

 * ===>	The descriptions of each library routine and the order that the
        routines are called, which is provided in this file, along with
        the example libraries, should make it possible for you to produce
        code for your own data reader.	


2. Produce the dynamic shared library.

   This is a compiling and loading process which varies according to
   the type of machine you are on.  In the user-defined-reader source
   tree we have tried to isolate the machine dependent parts of the
   build process using a set of files in the 'config' directory.  In this
   directory there is a configuration file for each platform on which
   EnSight is supported.  Before you can compile the installed readers
   you should run the script called 'init' in the config directory.

      i.e.  (for UNIX)
            cd config
            ./init sgi_6.5_n64
            cd ..
            make

   If you are compiling for Windows NT, there are two options.  If you
   have the Cygwin GNU utilities installed, you can use GNU make as for
   Unix.  Otherwise, there is a script called makeall.cmd which will
   build all of the readers using nmake.  The Makefiles in each reader
   directory will work using either make or nmake.

      i.e.  (WIN32 Cygwin)                 (using nmake)
            cd config                      cd config
            sh init win32                  cp win32 config
            cd ..                          cd ..
                                           mkdir lib
            make                           makeall.cmd

   If you have platform-specific portions of code in your reader, the
   build system defines a set of flags which can be used within
   #ifdef ... #endif regions in your source, as shown in the table
   below.

   Because the readers are now dynamically opened by EnSight, you may
   have to include dependent libraries on your link-line to avoid having
   unresolved symbols.  If you are having problems with a reader, start
   ensight as "ensight7 -readerdbg" and you will get feedback on any
   problems encountered in loading a reader.  If there are unresolved
   symbols, you need to find the library which contains the missing
   symbols and link it into your reader by adding it to the example
   link commands below.

   If you choose to use a different build environment for your reader,
   you should take care to use compatible compilation flags to ensure
   compatibilty with the EnSight executables, most notably on the SGI
   and HP-UX 11.0 platforms, which should use the following flags:

      sgi_6.2_o32: -mips2
      sgi_6.2_n64: -mips4 -64
      sgi_6.5_n32: -mips3
      sgi_6.5_n64: -mips4 -64
       hp_11.0_32: +DA2.0
       hp_11.0_64: +DA2.0W

    ______________________________________________________________________
   | MACHINE | OS flag               |  SHARED LIBRARY NAME PRODUCED      |
   |  TYPE   |------------------------------------------------------------|
   |         |         LD COMMAND USED IN MAKEFILE                        |
    ======================================================================
    ______________________________________________________________________
   | sgi     | -DSGI                 |  libuserd-X.so                     |
   |         |------------------------------------------------------------|
   |         | ld -shared -all -o libuserd-X.so libuserd-X.o              |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | hp      | -DHP                  |  libuserd-X.sl                     |
   |         |------------------------------------------------------------|
   |         | ld -b -o libuserd-X.sl libuserd-X.o                        |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | sun     | -DSUN                 |  libuserd-X.so                     |
   |         |------------------------------------------------------------|
   |         | ld -G -o libuserd-X.so libuserd-X.o                        |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | dec     | -DDEC                 |  libuserd-X.so                     |
   |         |------------------------------------------------------------|
   |         | ld -shared -all -o libuserd-X.so libuserd-X.o -lc          |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | linux   | -DLINUX               |  libuserd-X.so                     |
   |         |------------------------------------------------------------|
   |         | ld -shared -o libuserd-X.so libuserd-X.o -lc               |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | alpha   | -DALINUX              |  libuserd-X.so                     |
   | linux   |------------------------------------------------------------|
   |         | ld -shared -o libuserd-X.so libuserd-X.o -lc               |
    ----------------------------------------------------------------------
    ______________________________________________________________________
   | ibm     | -DIBM                 |  libuserd-X.so                     |
   |         |------------------------------------------------------------|
   |         | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
    ----------------------------------------------------------------------

   Once you have created your library, you should place it in a directory
   of your choice or in the standard reader location:

      $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers

   For example, if you created a reader for "mydata", you should create
   the reader libuserd-mydata.so and place the file in your own reader
   directory (see section 3 below) or in the standard location:

      $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so


3. By default EnSight will load all readers found in the directory:

      $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers

   Files with names "libuserd-X.so" (where X is a name unique to the reader)
   are assumed to be user-defined readers.

   There are two methods which can be used to supplement the default
   behavior.

   (1) A feature which is useful for site-level or user-level configuration
       is the optional environment variable $ENSIGHT7_READER.  This
       variable directs EnSight to load all readers in the specified reader
       directory (you should probably specify a full path) before loading
       the built-in readers.  If the same reader exists in both directories
       (as determined by the name returned by USERD_get_name_of_reader(),
       NOT by the filename), the locally configured reader will take
       precedence.

   (2) A useful feature for end-users is the use of the libuserd-devel
       reader.  EnSight will search for a reader named libuserd-devel.so
       (.sl for HP or .dll for NT).  This reader can exist anywhere in the
       library path (see below) of the user.  This is useful for an
       individual actively developing a reader because the existence of a
       libuserd-devel library will take precedence over any other library
       which returns the same name from USERD_get_name_of_reader().

   As an example, a site may install commonly used readers in a common
   location, and users can set the ENSIGHT7_READER variable to access them:

      setenv ENSIGHT7_READER /usr/local/lib/e7readers
  
   A user working on a new reader may compile the reader and place it in
   a directory specified by the library path:

      cp libuserd-myreader.so ~/lib/libuserd-devel.so
      setenv <librarypath> ~/lib:$<librarypath>

   The user is responsible for correctly configuring the library path
   variable in order to make use of the libuserd-devel feature.  The
   library environment variables used are:

        Machine type    Environment variable to set
        ------------    ---------------------------
        sgi             LD_LIBRARY_PATH
        dec             LD_LIBRARY_PATH
        sun             LD_LIBRARY_PATH
        linux           LD_LIBRARY_PATH
        alpha linux     LD_LIBRARY_PATH
        hp              SHLIB_PATH
        ibm             LIBPATH

As always, EnSight support is available if you need it.

-------------------------------
Quick Index of Library Routines
-------------------------------

Generally Needed for UNSTRUCTURED data
--------------------------------------
USERD_get_part_coords                 part's node coordinates
USERD_get_part_node_ids               part's node ids
USERD_get_part_elements_by_type       part's element connectivites
USERD_get_part_element_ids_by_type    part's element ids


Generally Needed for BLOCK data
--------------------------------------
USERD_get_block_coords_by_component   block coordinates
USERD_get_block_iblanking             block iblanking values
USERD_get_ghosts_in_block_flag        block ghost cell existence?
USERD_get_block_ghost_flags           block ghost cell flags

  These routines, which formerly were only for unstructured data, will now
  also be called for structured data if you specify that ids will be given
  in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
  ------------------------------------------------------------------------------ 
  USERD_get_part_node_ids               part's node ids
  USERD_get_part_element_ids_by_type    part's element ids


Generally needed for either or both kinds of data
-------------------------------------------------
USERD_get_name_of_reader              name of reader for GUI
USERD_get_reader_version              provide reader version number
USERD_get_reader_descrip              provide GUI more description (optional)

USERD_set_filenames                   filenames entered in GUI
USERD_set_server_number               server which of how many

USERD_get_number_of_timesets          number of timesets
USERD_get_timeset_description         description of timeset
USERD_get_geom_timeset_number         timeset # to use for geom

USERD_get_num_of_time_steps           number of time steps
USERD_get_sol_times                   solution time values
USERD_set_time_set_and_step           current timeset and time step

USERD_get_gold_part_build_info        Gets the info needed for part building process
USERD_get_changing_geometry_status    changing geometry?
USERD_get_node_label_status           node labels?
USERD_get_element_label_status        element labels?
USERD_get_model_extents               provide model bounding extents
USERD_get_number_of_files_in_dataset  number of files in model
USERD_get_dataset_query_file_info     info about each model file
USERD_get_descrip_lines               file associated description lines
USERD_get_number_of_model_parts       number of model parts
USERD_get_part_build_info             part/block type/descrip etc.
USERD_get_maxsize_info                part/block allocation maximums
USERD_get_ghosts_in_model_flag        model contains ghost cells?
USERD_get_nsided_conn                 Gets the element connectivities for nsided
                                        elements. (utilizes the number of nodes
                                        per element obtained in
                                        USERD_get_part_elements_by_type)
USERD_get_nfaced_nodes_per_face       Gets the number of nodes per face for nfaced
                                        elements (utilizes the number of faces
                                        per element obtained in
                                        USERD_get_part_elements_by_type)
USERD_get_nfaced_conn                 Gets the element connectivities for nfaced
                                        elements (utilizes the number of nodes
                                        per face obtained in
                                        USERD_get_nfaced_nodes_per_face)


USERD_get_border_availability         part border provided?
USERD_get_border_elements_by_type     part border conn and parent info

USERD_get_number_of_variables         number of variables
USERD_get_gold_variable_info          variable type/descrip etc.
USERD_get_var_by_component            part or block variable values
USERD_get_constant_val                constant variable's value
USERD_get_var_value_at_specific       node's or element's variable value over time
USERD_stop_part_building              cleanup after part build routine

USERD_get_number_of_material_sets     Gets the number of material sets
USERD_get_matf_set_info               Gets the material set indices and names
USERD_get_number_of_materials         Gets the number of materials
USERD_get_matf_var_info               Gets the material indices and descriptions
USERD_size_matf_data                  Gets the length of either the
                                        material ids list,
                                        mixed-material ids list, or
                                        mixed-material values list
USERD_load_matf_data                  Gets the material ids list,
                                        mixed-material ids list, or
                                        mixed-material values list

USERD_bkup                            archive routine

USERD_exit_routine                    cleanup upon exit routine


---------------------------
Optional Extra GUI Info
Adds Toggle(s), Pulldown(s) Field(s)
that can be used for additonal input
---------------------------
USERD_get_extra_gui_numbers          Gets the number of toggles, pulldowns and fields
USERD_get_extra_gui_defaults         Gets the default values for the GUI members
USERD_set_extra_gui_data             Returns the answers provided by the user

USERD_rigidbody_existence            Returns whether rigid body transformation
                                       data exists for the model.
USERD_rigidbody_values               Returns the euler and location values for a
                                       given part

USERD_set_right_side                 Simply informs the reader when the time set
                                     is for the right side of a time span during
                                     variable interpolation between time steps.

New at 2.04
-----------

/* ----------------------------------------------------------
 *
 *  Failure criteria in LS-DYNA 
 *  if fail flag == threshold_val1 (0.0) then element fails
 *    logic_criteria2 not used
 *    threshold_val2 not used
 *    threshold_operator2 not used
 *  Return (Z_ERR) if this is not used.
 * Return Z_OK if failed element feature should be used
 *
 *  threshold_operator1 & 2 can be one of the following
 *    Z_ELE_FAILED_NONE,           - disables checking
 *     Z_ELE_FAILED_GREATER,        - greater than
 *     Z_ELE_FAILED_LESS,           - less than
 *     Z_ELE_FAILED_EQUAL,          - equal
 *     Z_ELE_FAILED_NOT_EQUAL,      - not equal
 *     Z_ELE_FAILED_MANY            - not used
 *
 * logic_criteria2
 *      Z_ELE_FAILED_LOGIC_NONE,
 *      Z_ELE_FAILED_LOGIC_AND,
 *      Z_ELE_FAILED_LOGIC_OR,
 *      Z_ELE_FAILED_LOGIC_MANY
 *
 * ---------------------------------------------------------- */

int USERD_get_uns_failed_params(
                char *fail_var_name,           /* variable name to be used in failure
                                            must be scalar, per elem      */
                float *threshold_val1,     /* number to compare for failure */
                float *threshold_val2,     /* number to compare for failure */
                int *threshold_operator1,   /* Z_GREATER_THAN, Z_LESS_THAN,
                                            Z_EQUAL_TO */
                int *threshold_operator2,   /* Z_GREATER_THAN, Z_LESS_THAN,
                                            Z_EQUAL_TO */
		int *logic_criteria2


-------------------------
Order Routines are called
-------------------------

The various main operations are given basically in the order they will
be performed.  Within each operation, the order the routines will be
called is given.  

1. Setting name in the gui, and specifying one or two input fields

        USERD_get_name_of_reader
        USERD_get_reader_descrip        (optional)
        USERD_get_extra_gui_numbers     (optional)
	USERD_get_extra_gui_defaults    (optional)

2. Getting the reader version (also distinguishes between API's)

        USERD_get_reader_version

3. Setting filenames and getting timeset and time info

        USERD_set_server_number
	USERD_set_extra_gui_data        (optional)
        USERD_set_filenames
        USERD_get_number_of_timesets
        USERD_get_geom_timeset_number

        for each timeset:
          USERD_get_timeset_description
          USERD_get_num_of_time_steps
          USERD_get_sol_times

        USERD_set_time_set_and_step

4. Gathering info for part builder

        USERD_set_time_set_and_step
        USERD_get_changing_geometry_status
        USERD_get_node_label_status
        USERD_get_element_label_status
        USERD_get_number_of_files_in_dataset
        USERD_get_dataset_query_file_info
        USERD_get_descrip_lines                 (for geometry)
        USERD_get_number_of_model_parts
        USERD_get_uns_failed_model_flag  
        USERD_get_gold_part_build_info
        USERD_get_uns_failed_etype_flags
        USERD_get_ghosts_in_model_flag
        USERD_get_maxsize_info
        USERD_get_get_ghosts_in_block_flag      (if any ghost cells in model)
        USERD_get_model_extents     OR          (for model extents)
             USERD_get_part_coords  AND/OR
             USERD_get_block_coords_by_component

5. Gathering Variable info

        USERD_get_number_of_variables
        USERD_get_gold_variable_info
              
6. Part building (per part created)

        both unstructured and structured:
        --------------------------------
        USERD_set_time_set_and_step

        if unstructured part:
        --------------------
        USERD_get_part_element_ids_by_type
        USERD_get_part_elements_by_type

        If any nsided elements:

          USERD_get_nsided_conn

        If any nfaced elements:

          USERD_get_nfaced_nodes_per_face
          USERD_get_nfaced_conn

        USERD_get_part_coords
        USERD_get_part_node_ids
        USERD_get_uns_failed_elist_flags

        else if structured part:
        -----------------------
        USERD_get_block_iblanking
        USERD_get_block_coords_by_component
        USERD_get_block_ghost_flags          (If ghost cells in part)
        USERD_get_part_node_ids              (If node ids given)
        USERD_get_part_element_ids_by_type   (If element ids given)

        both again:
        ----------
        USERD_get_border_availability        (If border representation
        USERD_get_border_elements_by_type     is selected)

        USERD_stop_part_building      (only once when part builder
                                       dialog is closed)

7. Loading Variables
          
        constants:
        ---------
        USERD_set_time_set_and_step
        USERD_get_constant_val
          
        scalars/vectors/tensors:
        ------------------------
        USERD_get_descrip_lines
        USERD_set_time_set_and_step
        USERD_get_var_by_component

8. Changing geometry

        changing coords only (per part):
        --------------------
        USERD_set_time_set_and_step
        USERD_get_descrip_lines
        USERD_get_part_coords
	USERD_get_uns_failed_model_flag
	USERD_get_uns_failed_etype_flags
	USERD_get_uns_failed_elist_flags
        USERD_get_block_coords_by_component

        changing connectivity (per part):
        ---------------------
        USERD_set_time_set_and_step
        USERD_get_descrip_lines
        USERD_get_number_of_model_parts
        USERD_get_uns_failed_model_flag
        USERD_get_gold_part_build_info
        USERD_get_uns_failed_etype_flags
        USERD_get_ghosts_in_model_flag
        USERD_get_get_ghosts_in_block_flag      (if any ghost cells in model)
        USERD_get_model_extents   OR
           USERD_get_part_coords  AND/OR
           USERD_get_block_coords_by_component
        USERD_get_part_element_ids_by_type
        USERD_get_part_elements_by_type
        USERD_get_part_coords
        USERD_get_part_node_ids
        USERD_get_uns_failed_elist_flags
        USERD_get_block_iblanking
        USERD_get_block_coords_by_component
        USERD_get_block_ghost_flags          (If ghost cells in part)
        USERD_get_part_node_ids              (If node ids given)
        USERD_get_part_element_ids_by_type   (If element ids given)

        USERD_get_border_availability        (If border representation
        USERD_get_border_elements_by_type     is selected)

  
9. Node or Element queries over time

        USERD_get_var_value_at_specific

10. To see if materials in the model

        USERD_get_number_of_material_sets
        USERD_get_matf_set_info

        If any material sets in the model (calls these once per material set):
          USERD_get_number_of_materials
          USERD_get_matf_var_info

        For each elment type of each part containing material ids, calls:
          USERD_size_matf_data
          USERD_load_matf_data

        If there are any elements with mixed materials, when a domain or
        interface is created, calls these again per part:

          USERD_size_matf_data
          USERD_load_matf_data

11. To modify the variable extraction parameters and have the variables
    update accordingly.

        USERD_get_var_extract_gui_numbers
        USERD_get_var_extract_gui_defaults
        USERD_set_var_extract_gui_data



-----------------------
Detailed Specifications
-----------------------

Include files:
--------------
The following header file is required in any file containing these library
routines. 

       #include "global_extern.h"

And it references:

       #include "global_extern_proto.h"



*******************************************************************************
****************************** Special Note ***********************************
*******************************************************************************

Make sure you use the proper define in the global_extern.h header file, namely:
#define USERD_API_204

Also, Make sure the api version in the USERD_get_reader_version routine is set
to "2.04" or larger.

Make sure your reader has access to the global_extern_proto.h   This is a new
file which is accessed from the new global_extern.h

*******************************************************************************
*******************************************************************************


Basis of arrays:
---------------
Unless explicitly stated otherwise, all arrays are zero based - in true C
fashion.


Global variables:
----------------
You will generally need to have a few global variables which are shared by
the various library routines. The detailed specifications below have assumed
the following are available.  (Their names describe their purpose, and they
will be used in helping describe the details of the routines below).

static int Numparts_available         = 0;
static int Num_unstructured_parts     = 0;
static int Num_structured_blocks      = 0;

/* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */

static int Num_timesets               = 1;
static int Current_timeset            = 1;
static int Geom_timeset_number        = 1;

static int Num_time_steps[Z_MAXSETS]  = 1;
static int Current_time_step          = 0;
static int Num_variables              = 0;
static int Num_dataset_files          = 0;

static int Server_Number              = 1;    Which server of
static int Tot_Servers                = 1;    the total number of servers



_________________________________________
-----------------------------------------
Library Routines (in alphabetical order):
_________________________________________
-----------------------------------------

--------------------------------------------------------------------
USERD_bkup

   Description:
   -----------
   This routine is called during the EnSight archive process.  You can
   use it to save or restore info relating to your user defined reader.

   Specification:
   -------------
   int USERD_bkup(FILE *archive_file,
                  int backup_type)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  archive_file         = The archive file pointer

   (IN)  backup_type          = Z_SAVE_ARCHIVE for saving archive
                                Z_REST_ARCHIVE for restoring archive

   Notes:
   -----
   * Since EnSight's archive file is saved in binary form, you should
     also do any writing to it or reading from it in binary.

   * You should archive any variables, which will be needed for
     future operations, that will not be read or computed again
     before they will be needed.  These are typically global
     variables.

   * Make sure that the number of bytes that you write on a save and
     the number of bytes that you read on a restore are identical!!

   * If any of the variables you save are allocated arrays, you must
     do the allocations before restoring into them.

--------------------------------------------------------------------
USERD_exit_routine

   Description:
   -----------
   This routine is called as EnSight is exiting. It can be used to clean
   up anything needed - such as removing temporary files, etc. - or can simply
   be a dummy.

   Specification:
   -------------
   void USERD_exit_routine( void )

   Arguments:
   ---------
   none

--------------------------------------------------------------------
USERD_get_block_coords_by_component

   Description:
   -----------
   Get the coordinates of a given structured block, a component at a time.

   Specification:
   -------------
   int USERD_get_block_coords_by_component(int block_number,
                                           int which_component,
                                           float *coord_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  block_number            = The block part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (IN)  which_component         = Z_COMPX if x component wanted
                                 = Z_COMPY if y component wanted
                                 = Z_COMPZ if z component wanted

   (OUT) coord_array             = 1D array containing x,y, or z
                                   coordinate component of each node

                                  (Array will have been allocated
                                   i*j*k for the block long)

   Notes:
   -----
   * Not called unless Num_structured_blocks is > 0

   * Will be based on Current_time_step



--------------------------------------------------------------------
USERD_get_block_iblanking

   Description:
   -----------
   Get the iblanking value at each node of a block (if the block is
   iblanked).

   Specification:
   -------------
   int USERD_get_block_iblanking(int block_number,
                                 int *iblank_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  block_number            = The block part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (OUT) iblank_array            = 1D array containing iblank value
                                   for each node.

                                  (Array will have been allocated
                                   i*j*k for the block long)

          possible values are:   Z_EXT     = exterior
                                 Z_INT     = interior
                                 Z_BND     = boundary
                                 Z_INTBND  = internal boundary
                                 Z_SYM     = symmetry plane

   Notes:
   -----
   * Not called unless Num_structured_blocks is > 0  and you have
     some iblanked blocks

   * Will be based on Current_time_step



----------------------------------------------------------------------
USERD_get_block_ghost_flags

   Description:
   -----------
   Get the ghost_flags value at each element of a block containing ghost cells.

   Specification:
   -------------
   int USERD_get_block_ghost_flags(int block_number,
                                   int *ghost_flags)
   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  block_number            = The block number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (OUT) ghost_flags             = 1D array containing ghost flag value
                                     for each block cell.
  
                                    (Array will have been allocated
                                     (i-1)*(j-1)*(k-1) for the block long)
  
            possible values are:    0  = non-ghost cell  (normal cell)
                                   >0  = ghost cell
  
    Notes:
    -----
    * This routine is new in the 2.01 API

    * This will be based on Current_time_step
  
    * Only called for structured "block" parts that have some ghost cells
      as indicated by the USERD_get_ghost_in_block_flag.  The model must
      of course also have been indicated to have some ghost cells in the
      USERD_get_ghost_in_model_flag routine.
  
    * It is sufficient to set the value to be 1 to flag as a ghost cell,
      but the value can be any non-zero value, so you could use it to
      indicate which block or which server (for Server-of-server use) the
      cell is actually in.



--------------------------------------------------------------------
USERD_get_border_availability

   Description:
   -----------
   Finds out if border elements are provided by the reader for the
   desired part, or will need to be computed internally by EnSight.

   Specification:
   -------------
   int USERD_get_border_availability(int part_number,
                                     int number_of_elements[Z_MAXTYPE])

   Returns:
   -------
   Z_OK  if border elements will be provided by the reader.
          (number_of_elements array will be loaded and
           USERD_get_border_elements_by_type will be called)

   Z_ERR if border elements are not available - thus EnSight must compute.
          (USERD_get_border_elements_by_type will not be called)


   Arguments:
   ---------
   (IN)  part_number             = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (OUT) number_of_elements     = 2D array containing number of
                                  each type of border element in
                                  the part.
                                  ------------
                                  Possible types are:

                                Z_POINT   =  point
                                Z_BAR02   =  2-noded bar
                                Z_BAR03   =  3-noded bar
                                Z_TRI03   =  3-noded triangle
                                Z_TRI06   =  6-noded triangle
                                Z_QUA04   =  4-noded quadrilateral
                                Z_QUA08   =  8-noded quadrilateral

   Notes:
   -----
   * Only called if border representation is used.

   * Will be based on Current_time_step



--------------------------------------------------------------------
USERD_get_border_elements_by_type

   Description:
   -----------
   Provides border element connectivity and parent information. 

   Specification:
   -------------
   int USERD_get_border_elements_by_type(int part_number,
                                         int element_type,
                                         int **conn_array,
                                         short *parent_element_type,
                                         int *parent_element_num)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number           = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (IN)  element_type          = One of the following (See global_extern.h)
                                 Z_POINT    node point element
                                 Z_BAR02    2 node bar
                                 Z_BAR03    3 node bar
                                 Z_TRI03    3 node triangle
                                 Z_TRI06    6 node triangle
                                 Z_QUA04    4 node quad
                                 Z_QUA08    8 node quad

   (OUT) conn_array            = 2D array containing connectivity
                                 of each border element of the type.

                                (Array will have been allocated
                                 num_of_elements of the type by
                                 connectivity length of the type)

                       ex) If number_of_elements[Z_TRI03] = 25
                              number_of_elements[Z_QUA04] = 100
                              number_of_elements[Z_QUA08] = 30
                           as obtained in:
                            USERD_get_border_availability

                           Then the allocated dimensions available
                           for this routine will be:
                              conn_array[25][3]   when called with Z_TRI03

                              conn_array[100][4]  when called with Z_QUA04

                              conn_array[30][8]   when called with Z_QUA08

   (OUT) parent_element_type   = 1D array containing element type of the
                                 parent element (the one that the border
                                 element is a face/edge of).

                                (Array will have been allocated
                                 num_of_elements of the type long)

   (OUT) parent_element_num   = 1D array containing element number of the
                                 parent element (the one that the border
                                 element is a face/edge of).

                                (Array will have been allocated
                                 num_of_elements of the type long)

   
   Notes:
   -----
   * Not called unless USERD_get_border_availability returned Z_OK

   * Will be based on Current_time_step



--------------------------------------------------------------------
USERD_get_changing_geometry_status

   Description:
   -----------
   Gets the changing geometry status for the model

   Specification:
   -------------
   int USERD_get_changing_geometry_status( void )

   Returns:
   -------
   Z_STATIC        if geometry does not change
   Z_CHANGE_COORDS if changing coordinates only
   Z_CHANGE_CONN   if changing connectivity

   Arguments:
   ---------
   none

   Notes:
   -----
   * EnSight does not support changing number of parts.  But the
     coords and/or the connectivity of the parts can change.  Note that
     a part is allowed to be empty (number of nodes and elements equal
     to zero).


--------------------------------------------------------------------
USERD_get_constant_val

   Description:
   -----------
   Get the value of a constant at a time step

   Specification:
   -------------
   float USERD_get_constant_value(int which_var,
                                  int imag_data)

   Returns:
   -------
   Value of the requested constant variable

   Arguments:
   ---------
   (IN)  which_var            = The variable number

   (IN)  imag_data            = TRUE if want imaginary data value.
                                FALSE if want real data value.

   Notes:
   -----
   * Will be based on Current_time_step



--------------------------------------------------------------------
USERD_get_dataset_query_file_info

   Description:
   -----------
   Get the information about files in the dataset.  Used for the
   dataset query option within EnSight.

   Specification:
   -------------
   int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) qfiles   = Structure containing information about each file
                    of the dataset. The Z_QFILES structure is defined
                    in the global_extern.h file

                   (The structure will have been allocated
                    Num_dataset_files long, with 10 description
                    lines per file).

      qfiles[].name        = The name of the file
                             (Z_MAXFILENP is the dimensioned length
                              of the name)

      qfiles[].sizeb       = The number of bytes in the file
                             (Typically obtained with a call to the
                              "stat" system routine) (Is a long)

      qfiles[].timemod     = The time the file was last modified 
                             (Z_MAXTIMLEN is the dimensioned length
                              of this string)
                             (Typically obtained with a call to the
                              "stat" system routine)

      qfiles[].num_d_lines = The number of description lines you
                              are providing from the file. Max = 10

      qfiles[].f_desc[]    = The description line(s) per file,
                              qfiles[].num_d_lines of them
                              (Z_MAXFILENP is the allocated length of
                               each line)

   Notes:
   -----
   * If Num_dataset_files is 0, this routine will not be called.
     (See USERD_get_number_of_files_in_dataset)


--------------------------------------------------------------------
USERD_get_descrip_lines

   Description:
   -----------
   Get two description lines associated with geometry per time step,
   or one description line associated with a variable per time step.

   Specification:
   -------------
   int USERD_get_descrip_lines(int which_type,
                               int which_var,
                               int imag_data,
                               char line1[Z_BUFL],
                               char line2[Z_BUFL])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  which_type           = Z_GEOM for geometry (2 lines)
                              = Z_VARI for variable (1 line)

   (IN)  which_var            = If it is a variable, which one.
                                Ignored if geometry type.

   (IN)  imag_data            = TRUE if want imaginary data file.
                                FALSE if want real data file.

   (OUT) line1                = The 1st geometry description line,
                                or the variable description line.

   (OUT) line2                = The 2nd geometry description line
                                Not used if variable type.

   Notes:
   -----
   * Will be based on Current_time_step

   * These are the lines EnSight can echo to the screen in
     annotation mode.



--------------------------------------------------------------------
USERD_get_element_label_status

   Description:
   -----------
   Answers the question as to whether element labels will be provided.

   Specification:
   -------------
   int USERD_get_element_label_status( void )

   Returns:
   -------
   TRUE        if element labels will be provided
   FALSE       if element labels will NOT be provided

   Arguments:
   ---------
   none

   Notes:
   -----
   * element lables are needed in order to do any element querying, or
     element labeling on-screen within EnSight.

   * Prior to API 2.01:
     -----------------
       For unstructured parts, you can read them from your file if
       available, or can assign them, etc. They need to be unique
       per part, and are often unique per model.

       API 1.0:
         USERD_get_element_ids_for_part is used to obtain the ids,
         on a part by part basis, if TRUE status is returned here.

       API 2.0:
         USERD_get_part_element_ids_by_type is used to obtain the ids,
         on a per part, per type basis, if TRUE status is returned here.

       For structured parts, EnSight will assign ids if you return a
         status of TRUE here.  You cannot assign them youself!!

   * Starting at API 2.01:
     --------------------
       For both unstructured and structured parts, you can read them
       from your file if available, or can assign them, etc. They need
       to be unique per part, and are often unique per model (especially
       if you are dealing with a decomposed dataset).

       USERD_get_part_element_ids_by_type is used to obtain the ids,
       on an element type by part basis, if TRUE status is returned here.

   * Will call USERD_get_part_element_ids_by_type for each type of
     of each part if this routine returns TRUE.
--------------------------------------------------------------------
USERD_get_geom_timeset_number -

   Description:
   -----------
    Gets the timeset number to be used for geometry

   Specification:
   -------------
   int USERD_get_geom_timeset_number( void )

   Returns:
   -------
   Geom_timeset_number = The timeset number that will be used for geometry.   
                         For example, if USERD_get_number_of timesets
                         returns 2, the valid timeset numbers would be
                         1 or 2.

   Arguments:
   ---------
   none

   Notes:
   -----
   *  If your model is static, which you indicated by returning a zero
      in USERD_get_number_of_timesets, you can return a zero here as well.



--------------------------------------------------------------------
USERD_get_gold_part_build_info

   Description:
   -----------
   Gets the info needed for the part building process.

   Specification:
   -------------
   int USERD_get_gold_part_build_info(int *part_id,
                                      int *part_types,
                                      char *part_description[Z_BUFL],
                                      int *number_of_nodes,
                                      int *number_of_elements[Z_MAXTYPE],
                                      int *ijk_dimensions[9],
                                      int *iblanking_options[6])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
    (OUT) part_id                = Array containing the external part
                                   ids for each of the model parts.

                                   IMPORTANT:
                                    Parts numbers must be >= 1, because
                                    of the way they are used in the GUI

               *******************************************
                The ids provided here are the numbers by
                which the parts will be referred to in the
                GUI (if possible). They are basically
                labels as far as you are concerned.

                Note: The part numbers you pass to routines
                which receive a part_number or block_number
                or which_part as an argument are the 1-based
                table index of the parts!

                example:  If Numparts_available = 3

                          Table index        part_id
                          -----------        -------
                           1                  13
                           2                  57
                           3                  125

                           ^                   ^
                           |                   |
                           |                    These are placed in:
                           |                      part_id[0] = 13
                           |                      part_id[1] = 57
                           |                      part_id[2] = 125
                           |                    for GUI labeling purposes.
                           |
                            These implied table indices are the part_number,
                            block_number, or which_part numbers that you would
                            pass to routines like:

                           USERD_get_part_coords(int part_number,...
                           USERD_get_part_node_ids(int part_number,...
                           USERD_get_part_elements_by_type(int part_number,...
                           USERD_get_part_element_ids_by_type(int part_number,...
                           USERD_get_block_coords_by_component(int block_number,...
                           USERD_get_block_iblanking(int block_number,...
                           USERD_get_block_ghost_flags(int block_number,...
                           USERD_get_ghosts_in_block_flag(int block_number)
                           USERD_get_border_availability(int part_number,...
                           USERD_get_border_elements_by_type(int part_number,...
                           USERD_get_var_by_component(int which_variable,
                                                      int which_part,...
                           USERD_get_var_value_at_specific(int which_var,
                                                           int which_node_or_elem,
                                                           int which_part,...
               ********************************************

                                    (Array will have been allocated
                                     Numparts_available long)

   (OUT) part_types             = Array containing one of the
                                  following for each model part:

                                       Z_UNSTRUCTURED or
                                       Z_STRUCTURED  or
                                       Z_IBLANKED

                                  (Array will have been allocated
                                   Numparts_available long)

   (OUT) part_description       = Array containing a description
                                  for each of the model parts

                                  (Array will have been allocated
                                   Numparts_available by Z_BUFL
                                   long)

   (OUT) number_of_nodes        = Number of unstructured nodes in the part
 
                                   (Array will have been allocated
                                    Numparts_available long)

   (OUT) number_of_elements     = 2D array containing number of
                                  each type of element for each
                                  unstructured model part.
                                  ------------
                                  Possible types are:

                                Z_POINT   =  point
                                Z_BAR02   =  2-noded bar
                                Z_BAR03   =  3-noded bar
                                Z_TRI03   =  3-noded triangle
                                Z_TRI06   =  6-noded triangle
                                Z_QUA04   =  4-noded quadrilateral
                                Z_QUA08   =  8-noded quadrilateral
                                Z_TET04   =  4-noded tetrahedron
                                Z_TET10   = 10-noded tetrahedron
                                Z_PYR05   =  5-noded pyramid
                                Z_PYR13   = 13-noded pyramid
                                Z_PEN06   =  6-noded pentahedron
                                Z_PEN15   = 15-noded pentahedron
                                Z_HEX08   =  8-noded hexahedron
                                Z_HEX20   = 20-noded hexahedron

                                Z_G_POINT =  ghost node point element
                                Z_G_BAR02 =  2 node ghost bar
                                Z_G_BAR03 =  3 node ghost bar
                                Z_G_TRI03 =  3 node ghost triangle
                                Z_G_TRI06 =  6 node ghost triangle
                                Z_G_QUA04 =  4 node ghost quad
                                Z_G_QUA08 =  8 node ghost quad
                                Z_G_TET04 =  4 node ghost tetrahedron
                                Z_G_TET10 = 10 node ghost tetrahedron
                                Z_G_PYR05 =  5 node ghost pyramid
                                Z_G_PYR13 = 13 node ghost pyramid
                                Z_G_PEN06 =  6 node ghost pentahedron
                                Z_G_PEN15 = 15 node ghost pentahedron
                                Z_G_HEX08 =  8 node ghost hexahedron
                                Z_G_HEX20 = 20 node ghost hexahedron

                               (Ignored unless Z_UNSTRUCTURED type)

                                  (Array will have been allocated
                                   Numparts_available by
                                   Z_MAXTYPE long)

   (OUT) ijk_dimensions         = 2D array containing ijk dimension info
                                  for structured blocks

                                  For Z_UNSTRUCTURED - is ignored

                                  For Z_STRUCTURED or Z_IBLANKED

        Prior to version 2.03:
        ----------------------
                                   (Array will have been allocated
                                    Numparts_available by 3 long)

                              ijk_dimensions[][0] = I dimension
                              ijk_dimensions[][1] = J dimension
                              ijk_dimensions[][2] = K dimension


        Starting at version 2.03:
        ------------------------
                                   (Array will have been allocated
                                    Numparts_available by 9 long)

                              There are two ways to do this:
                              ------------------------------
                              1. The simple one, without ranges.

                                   This is good for all structured models
                                   that will NOT be used in EnSight's
                                   Server of Servers

                                   Simply provide the ijk dimensions in the
                                   first three slots and place a -1 in
                                   the 4th slot.  (The remaining slots will
                                   be ignored).

                              Thus,
                              ijk_dimensions[][0] = I dimension of block
                              ijk_dimensions[][1] = J dimension of block
                              ijk_dimensions[][2] = K dimension of block
                              ijk_dimensions[][3] = -1

                        (J planes)
                            4 *-------*-------*
                              |       |       |    ijk_dimension[0][0] = 3
                              |       |       |    ijk_dimension[0][1] = 4
                              |       |       |    ijk_dimension[0][2] = 1
                            3 *-------*-------*
                              |       |       |    ijk_dimension[0][4] = -1
                              |       |       |
                              |       |       |
                            2 *-------*-------*
                              |       |       |
                              |       |       |
                              |       |       |
                            1 *-------*-------*
                              1       2       3  (I planes)



                              2. Using ranges.

                                  This one can be used anytime, but MUST
                                  be used if EnSight's Server of Servers
                                  is to be used!

                                  The first 3 slots contain the ijk dimension
                                  of the complete block (of which this may be
                                  a portion).  The last 6 slots contain the
                                  ijk min and max ranges within the complete.

                              Thus,
                              ijk_dimensions[][0] = I dim of complete block
                              ijk_dimensions[][1] = J dim of complete block
                              ijk_dimensions[][2] = K dim of complete block

                              ijk_dimensions[][3] = Imin of portion (1-based)
                              ijk_dimensions[][4] = Imax of portion (1-based)
                              ijk_dimensions[][5] = Jmin of portion (1-based)
                              ijk_dimensions[][6] = Jmax of portion (1-based)
                              ijk_dimensions[][7] = Kmin of portion (1-based)
                              ijk_dimensions[][8] = Kmax of portion (1-based)


                              example1: (Model has one part, a simple 2D block,
                                         and want whole thing)

                        (J planes)
                            4 *-------*-------*
                              |       |       |    ijk_dimension[0][0] = 3
                              |       |       |    ijk_dimension[0][1] = 4
                              |       |       |    ijk_dimension[0][2] = 1
                            3 *-------*-------*
                              |       |       |    ijk_dimension[0][3] = 1
                              |       |       |    ijk_dimension[0][4] = 3
                              |       |       |    ijk_dimension[0][5] = 1
                            2 *-------*-------*    ijk_dimension[0][6] = 4
                              |       |       |    ijk_dimension[0][7] = 1
                              |       |       |    ijk_dimension[0][8] = 1
                              |       |       |
                            1 *-------*-------*
                              1       2       3  (I planes)


                              example2: (Want to have the block represented
                                         in two portions - 2 parts)

                        (J planes)                 top portion
                            4 *-------*-------*
                              |       |       |    ijk_dimension[0][0] = 3
                              |       |       |    ijk_dimension[0][1] = 4
                              |       |       |    ijk_dimension[0][2] = 1
                            3 *-------*-------*
                              .       .       .    ijk_dimension[0][3] = 1
                              .       .       .    ijk_dimension[0][4] = 3
                              .       .       .    ijk_dimension[0][5] = 3
                            2 .................    ijk_dimension[0][6] = 4
                              .       .       .    ijk_dimension[0][7] = 1
                              .       .       .    ijk_dimension[0][8] = 1
                              .       .       .
                            1 .................
                              1       2       3  (I planes)


                        (J planes)                 bottom portion
                            4 .................
                              .       .       .    ijk_dimension[1][0] = 3
                              .       .       .    ijk_dimension[2][1] = 4
                              .       .       .    ijk_dimension[3][2] = 1
                            3 *-------*-------*
                              |       |       |    ijk_dimension[1][3] = 1
                              |       |       |    ijk_dimension[1][4] = 3
                              |       |       |    ijk_dimension[1][5] = 1
                            2 *-------*-------*    ijk_dimension[1][6] = 3
                              |       |       |    ijk_dimension[1][7] = 1
                              |       |       |    ijk_dimension[1][8] = 1
                              |       |       |
                            1 *-------*-------*
                              1       2       3  (I planes)


        And note that if you were partioning this block for
        EnSight's Server of Servers, you would only have one part,
        instead of two.  Each SOS server would return its appropriate
        ranges in the last 6 slots. The first 3 slots would remain constant.


   (OUT) iblanking_options      = 2D array containing iblanking
                                  options possible for each
                                  structured model part.
                                  ----------
                                  (Ignored unless Z_IBLANKED type)

                                  (Array will have been allocated
                                   Numparts_available by 6 long)

      iblanking_options[][Z_EXT]     = TRUE if external (outside)
                       [][Z_INT]     = TRUE if internal (inside)
                       [][Z_BND]     = TRUE if boundary
                       [][Z_INTBND]  = TRUE if internal boundary
                       [][Z_SYM]     = TRUE if symmetry surface


   Notes:
   -----
   * If you haven't built a table of pointers to the different parts,
     you might want to do so here as you gather the needed info.

   * Will be based on Current_time_step


--------------------------------------------------------------------
USERD_get_gold_variable_info

   Description:
   -----------
   Get the variable descriptions, types and filenames

   Specification:
   -------------
   int USERD_get_gold_variable_info(char **var_description,
                                    char **var_filename,
                                    int *var_type,
                                    int *var_classify,
                                    int *var_complex,
                                    char **var_ifilename,
                                    float *var_freq,
                                    int *var_contran,
                                    int *var_timeset)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) var_description      = Variable descriptions

                                (Array will have been allocated
                                 Num_variables by Z_BUFL long)

           variable description restrictions:
           ----------------------------------
           1. Only first 19 characters used in EnSight.
           2. Leading and trailing whitespace will be removed by EnSight.
           3. Illegal characters will be replaced by underscores.
           4. Thay may not start with a numeric digit.
           4. No two variables may have the same description.


   (OUT) var_filename         = Variable real filenames

                                (Array will have been allocated
                                 Num_variables by Z_BUFL long)

   (OUT) var_type             = Variable type

                                (Array will have been allocated
                                 Num_variables long)

                                types are:  Z_CONSTANT
                                            Z_SCALAR
                                            Z_VECTOR
                                            Z_TENSOR
                                            Z_TENSOR9

   (OUT) var_classify         = Variable classification

                                (Array will have been allocated
                                 Num_variables long)

                                types are:  Z_PER_NODE
                                            Z_PER_ELEM

   (OUT) var_complex          = TRUE if complex, FALSE otherwise
 
                                (Array will have been allocated
                                 Num_variables long)
 
   (OUT) var_ifilename        = Variable imaginary filenames (if complex)
 
                                (Array will have been allocated
                                 Num_variables by Z_BUFL long)

   (OUT) var_freq             = complex frequency  (if complex)
 
                                (Array will have been allocated
                                 Num_variables long)
 
   (OUT) var_contran          = TRUE if constant changes per time step
                                FALSE if constant truly same at all time steps
 
                                (Array will have been allocated
                                 Num_variables long)

   (OUT) var_timeset          = Timeset the variable will use (1 based).
                                (For static models, set it to 1)

                                (Array will have been allocated
                                 Num_variables long)

                                 For example:  If USERD_get_number_of_timesets
                                               returns 2, the valid
                                               timeset_number's would be 1 or 2


   Notes:
   -----
   * The implied variable numbers apply, but be aware that the
     arrays are zero based.
     So for variable 1, will need to provide   var_description[0]
                                               var_filename[0]
                                               var_type[0]
                                               var_classify[0]
                                               var_complex[0]
                                               var_ifilename[0]
                                               var_freq[0]
                                               var_contran[0]
                                               var_timeset[0]


        for variable 2, will need to provide   var_description[1]
                                               var_filename[1]
                                               var_type[1]
                                               var_classify[1]
                                               var_complex[1]
                                               var_ifilename[1]
                                               var_freq[1]
                                               var_contran[1]
                                               var_timeset[1]
              etc.




--------------------------------------------------------------------
USERD_get_ghosts_in_block_flag

   Description:
   -----------
   Gets whether ghost cells present in block or not

   Specification:
   -------------
  int USERD_get_ghosts_in_block_flag(int block_number)

   Returns:
   -------
   TRUE  if any ghost cells in this structured part
   FALSE if no ghost cells in this structured part

   Arguments:
   ---------
   (IN) block_number      = The block part number
                              (1-based index of part table, namely:

                                1 ... Numparts_available.

                              It is NOT the part_id that
                              is loaded in USERD_get_gold_part_build_info)

   Notes:
   -----
    * This routine is new in the 2.01 API
    * This will be based on Current_time_step
  
    * Intended for structured parts only, value will be ignored for
      unstructured parts



--------------------------------------------------------------------
USERD_get_ghosts_in_model_flag

   Description:
   -----------
   Answers the question as to whether any ghost cells in the model.

   Specification:
   -------------
  int USERD_get_ghosts_in_model_flag( void )

   Returns:
   -------
   TRUE  if any ghost cells in the model
   FALSE if no ghost cells in the model

   Arguments:
   ---------
  
   Notes:
   -----
    * This routine is new in the 2.01 API

-------------------------------------------------------------------------
USERD_get_matf_set_info

   Description:
   -----------
   Get the material set ids and names

   Specification:
   -------------
   int USERD_get_matf_set_info(int *mat_set_ids,
                               char **mat_set_name)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) mat_set_ids  = 1D material set ids array

                               (Array will have been allocated
                                Num_material_sets long)

   (OUT) mat_set_name = 2D material set name array

                               (Array will have been allocated
                                Num_material_sets by Z_BUFL long)

   Notes:
   -----
   * Will not be called if Num_material_sets is zero
   * See USERD_get_number_of_material_sets header for explanatory example


--------------------------------------------------------------------
USERD_get_matf_var_info

   Description:
   -----------
   Gets the material ids and descriptions for the material set

   Specification:
   -------------
   int USERD_get_matf_var_info(int set_index,
                               int *mat_ids,
                               char **mat_desc)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  set_index               = the material set index (zero based)

   (OUT) mat_ids[set_index]      = 1D integer array containing the material
                                   ids to associated with each material

                                    (Array will have been allocated
                                     Num_materials[set_index] long)

   (OUT) mat_desc[set_index]     = 2D char array containing the material
                                   descriptions to associated with each material

                                    (Array will have been allocated
                                     Num_materials[set_index] by Z_BUFL long)

   Notes:
   -----
  * See USERD_get_number_of_material_sets header for explanatory example
  * Will not be called if Num_material_sets is zero, or
     Num_materials[set_index] is zero




--------------------------------------------------------------------
USERD_get_maxsize_info

   Description:
   -----------
   Gets maximum part sizes for efficient memory allocation.

   Transient models (especially those that increase in size) can cause
   reallocations, at time step changes, to keep chewing up more and
   more memory.   The way to avoid this is to know what the maximum
   size of such memory will be, and allocate for this maximum initially.

   Accordingly, if you choose to provide this information (it is optional),
   EnSight will take advantage of it.


   Specification:
   -------------
   int USERD_get_maxsize_info(int *max_number_of_nodes,
                              int *max_number_of_elements[Z_MAXTYPE],
                              int *max_ijk_dimensions[3])

   Returns:
   -------
   Z_OK  if supplying maximum data
   Z_ERR if not supplying maximum data, or some error occurred
           while trying to obtain it.

   Arguments:
   ---------
   (OUT) max_number_of_nodes    = Maximum number of unstructured nodes
                                  in the part (over all time).
 
                                   (Array will have been allocated
                                    Numparts_available long)

   (OUT) max_number_of_elements = 2D array containing maximum number of
                                  each type of element for each
                                  unstructured model part (over all time).
                                  ------------
                                  Possible types are:

                                Z_POINT   =  point
                                Z_BAR02   =  2-noded bar
                                Z_BAR03   =  3-noded bar
                                Z_TRI03   =  3-noded triangle
                                Z_TRI06   =  6-noded triangle
                                Z_QUA04   =  4-noded quadrilateral
                                Z_QUA08   =  8-noded quadrilateral
                                Z_TET04   =  4-noded tetrahedron
                                Z_TET10   = 10-noded tetrahedron
                                Z_PYR05   =  5-noded pyramid
                                Z_PYR13   = 13-noded pyramid
                                Z_PEN06   =  6-noded pentahedron
                                Z_PEN15   = 15-noded pentahedron
                                Z_HEX08   =  8-noded hexahedron
                                Z_HEX20   = 20-noded hexahedron

                                Z_G_POINT =  ghost node point element
                                Z_G_BAR02 =  2 node ghost bar
                                Z_G_BAR03 =  3 node ghost bar
                                Z_G_TRI03 =  3 node ghost triangle
                                Z_G_TRI06 =  6 node ghost triangle
                                Z_G_QUA04 =  4 node ghost quad
                                Z_G_QUA08 =  8 node ghost quad
                                Z_G_TET04 =  4 node ghost tetrahedron
                                Z_G_TET10 = 10 node ghost tetrahedron
                                Z_G_PYR05 =  5 node ghost pyramid
                                Z_G_PYR13 = 13 node ghost pyramid
                                Z_G_PEN06 =  6 node ghost pentahedron
                                Z_G_PEN15 = 15 node ghost pentahedron
                                Z_G_HEX08 =  8 node ghost hexahedron
                                Z_G_HEX20 = 20 node ghost hexahedron

                               (Ignored unless Z_UNSTRUCTURED type)

                                  (Array will have been allocated
                                   Numparts_available by
                                   Z_MAXTYPE long)

   (OUT) max_ijk_dimensions  = 2D array containing maximum ijk dimensions
                               for each structured model part (over all time).
                                           ----------
                                (Ignored if Z_UNSTRUCTURED type)

                                (Array will have been allocated
                                 Numparts_available by 3 long)

                             max_ijk_dimensions[][0] = maximum I dimension
                             max_ijk_dimensions[][1] = maximum J dimension
                             max_ijk_dimensions[][2] = maximum K dimension

   Notes:
   -----
   * You need to have first called USERD_get_number_of_model_parts and
     USERD_get_gold_part_build_info, so Numparts_available is known and
     so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
     or Z_IBLANKED) of each part.

   * This will NOT be based on Current_time_step - it is to be the maximum
     values over all time!!

   * This information is optional.  If you return Z_ERR, Ensight will still
     process things fine, reallocating as needed, etc.  However, for
     large transient models you will likely use considerably more memory
     and take more processing time for the memory reallocations. So, if it
     is possible to provide this information "up front", it is recommended
     to do so.


--------------------------------------------------------------------
USERD_get_model_extents

   Description:
   -----------
   Gets the model bounding box extents.  If this routine supplys them
   EnSight will not have to spend time doing so.  If this routine
   returns Z_ERR, EnSight will have to take the time to touch all the
   nodes and gather the extent info.

   Specification:
   -------------
   int USERD_get_model_extents(float extents[6])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful  (whereupon EnSight will determine by reading
                             all coords of all parts)

   Arguments:
   ---------
   (OUT) extents[0]   = min x
                [1]   = max x
                [2]   = min y
                [3]   = max y
                [4]   = min z
                [5]   = max z

   Notes:
   -----
   * This will be based on Current_time_step


--------------------------------------------------------------------
USERD_get_name_of_reader

   Description:
   -----------
   Gets the name of your user defined reader.  The user interface will
   ask for this and include it in the available reader list.

   Specification:
   -------------
   int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
				int *two_fields)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) reader_name          = the name of the your reader or data format.
                              (max length is Z_MAX_USERD_NAME, which is 20)

   (OUT) two_fields          = FALSE if only one data field is      
                                      required.                      
                                TRUE if two data fields required     
 
                                -1   if one field (Geom) required 
                                     and one field (Param) is optional
                                     Param field can contain any text
                                     for example a file name, modifiers,
                                     etc. that can be used to modify the
                                     reader's behavior.
 

   Notes:
   -----
   * Always called.  Please be sure to provide a name for your custom
     reader format.

--------------------------------------------------------------------
USERD_get_nfaced_conn

   Description:
   -----------
   Gets the array containing the connectivity of nsided faces of nfaced elements

   Specification:
   -------------int
   int USERD_get_nfaced_conn(int part_number,
                             int *nfaced_conn_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number        = the part number

   (OUT) nfaced_conn_array  = 1D array of nsided face connectivies of nfaced
                              elements

                              (int array will have been allocated long enough to
                               hold all the nsided face connectivities. Which is
                               the sum of all the nodes per face values in the
                               nfaced_npf_array of USERD_get_nfaced_nodes_per_face)

   Notes:
   -----
 * Will not be called unless there are some nfaced elements in the part

 * Providing nfaced information to Ensight:

     1. In USERD_get_gold_part_build_info, provide the number of nfaced
        polyhedral elements in the part.

     2. In USERD_get_part_elements_by_type, provide (in the conn_array),
        the number of faces per nfaced element. (as if connectivity
        length of an nfaced element is one)

     3. In this routine, provide the streamed number of nodes per face
        for each of the faces of the nfaced elements.


     Simple example:         11        10   12
                            +--------+-----+
     2 nfaced elements:    /|        |\   /|
     (1 7-faced           / |        | \ / |
      1 5-sided)         /  |        |  +9 |
                        /   |        | /|  |
                       /7   |      8 /  |  |
                      +-----------+/ |  |  |
                      |     |5    |  |4 |  |6
                      |     +-----|--+--|--+
                      |    /      |   \ | /
                      |   /       |    \|/3
                      |  /        |     +
                      | /         |    /
                      |/1         |2 /
                      +-----------+/

      1. In USERD_get_gold_part_build_info:
              number_of_elements[Z_NFACED] = 2
                                             .
                                            /|\
                                             |
      2. In USERD_get_part_elements_by_type:
          length of conn_array will be:      2 x 1
          for element_type of Z_NFACED:
              conn_array[0][0] = 7           (for the 7-faced element)
              conn_array[1][0] = 5           (for the 5-faced element)

                                ==
                           Sum  12    <---------+
                                                |
      3. In USERD_get_faced_nodes_per_face:     |
           length of nfaced_npf_array will be:  12

            nfaced_npf_array[0]  = 5  (5-noded top face of 7-faced element)
            nfaced_npf_array[1]  = 5  (5-noded bot face of 7-faced element)
            nfaced_npf_array[2]  = 4  (4-noded front face of 7-faced element)
            nfaced_npf_array[3]  = 4  (4-noded left face of 7-faced element)
            nfaced_npf_array[4]  = 4  (4-noded back face of 7-faced element)
            nfaced_npf_array[5]  = 4  (4-noded right front face of 7-faced element)
            nfaced_npf_array[6]  = 4  (4-noded right back face of 7-faced element)

            nfaced_npf_array[7]  = 3  (3-noded top face of 5-faced element)
            nfaced_npf_array[8]  = 3  (3-noded bot face of 5-faced element)
            nfaced_npf_array[9]  = 4  (4-noded back face of 5-faced element)
            nfaced_npf_array[10] = 4  (4-noded right face of 5-faced element)
            nfaced_npf_array[11] = 4  (4-noded left front face of 5-faced element)

                                   ==
                             Sum   48   <-------------+
                                                      |
      4. In this function:                            |
            length of the nfaced_conn_array will be:  48

            nsided_conn_array[0] = 7   (conn of 5-noded top face of 7-faced elem)
            nsided_conn_array[1] = 8
            nsided_conn_array[2] = 9
            nsided_conn_array[3] = 10
            nsided_conn_array[4] = 11

            nsided_conn_array[5] = 1   (conn of 5-noded bot face of 7-faced elem)
            nsided_conn_array[6] = 5
            nsided_conn_array[7] = 4
            nsided_conn_array[8] = 3
            nsided_conn_array[9] = 2

            nsided_conn_array[10] = 1  (conn of 4-noded front face of 7-faced elem)
            nsided_conn_array[11] = 2
            nsided_conn_array[12] = 8
            nsided_conn_array[13] = 7

            nsided_conn_array[14] = 5  (conn of 4-noded left face of 7-faced elem)
            nsided_conn_array[15] = 1
            nsided_conn_array[16] = 7
            nsided_conn_array[17] = 11

            nsided_conn_array[18] = 4  (conn of 4-noded back face of 7-faced elem)
            nsided_conn_array[19] = 5
            nsided_conn_array[20] = 11
            nsided_conn_array[21] = 10

            nsided_conn_array[22] = 2  (conn of 4-noded right front face of 7-faced)
            nsided_conn_array[23] = 3
            nsided_conn_array[24] = 9
            nsided_conn_array[25] = 8

            nsided_conn_array[26] = 3  (conn of 4-noded right back face of 7-faced)
            nsided_conn_array[27] = 4
            nsided_conn_array[28] = 10
            nsided_conn_array[29] = 9

            nsided_conn_array[30] = 9  (conn of 3-noded top face of 5-faced elem)
            nsided_conn_array[32] = 12
            nsided_conn_array[32] = 10

            nsided_conn_array[33] = 3  (conn of 3-noded bot face of 5-faced elem)
            nsided_conn_array[34] = 4
            nsided_conn_array[35] = 6

            nsided_conn_array[36] = 6  (conn of 4-noded back face of 5-faced elem)
            nsided_conn_array[37] = 4
            nsided_conn_array[38] = 10
            nsided_conn_array[39] = 12

            nsided_conn_array[40] = 3  (conn of 4-noded right face of 5-faced elem)
            nsided_conn_array[41] = 6
            nsided_conn_array[42] = 12
            nsided_conn_array[43] = 9

            nsided_conn_array[44] = 4  (conn of 4-noded left front face of 5-faced)
            nsided_conn_array[45] = 3
            nsided_conn_array[46] = 9
            nsided_conn_array[47] = 10



--------------------------------------------------------------------
USERD_get_nfaced_nodes_per_face -

   Description:
   -----------
   Gets the array containing the number of nodes per face for each face
   of the nfaced elements.

   Specification:
   -------------
   int USERD_get_nfaced_nodes_per_face(int part_number,
                                       int *nfaced_npf_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number       = the part number

   (OUT) nfaced_npf_array  = 1D array of nodes per face for all faces of
                             nfaced elements

                             (int array will have been allocated long enough
                              to hold all the nodes_per_face values. Which is
                              the sum of all the number of faces per element
                              values in the conn_array of
                              USERD_get_part_elements_by_type)

   Notes:
   -----
   * Will not be called unless there are some nfaced elements in the
     the part

   * Providing nfaced information to Ensight:

     1. In USERD_get_gold_part_build_info, provide the number of nfaced
        polyhedral elements in the part.

     2. In USERD_get_part_elements_by_type, provide (in the conn_array),
        the number of faces per nfaced element. (as if connectivity
        length of an nfaced element is one)

     3. In this routine, provide the streamed number of nodes per face
        for each of the faces of the nfaced elements.


     Simple example:         11        10   12
                            +--------+-----+
     2 nfaced elements:    /|        |\   /|
     (1 7-faced           / |        | \ / |
      1 5-sided)         /  |        |  +9 |
                        /   |        | /|  |
                       /7   |      8 /  |  |
                      +-----------+/ |  |  |
                      |     |5    |  |4 |  |6
                      |     +-----|--+--|--+
                      |    /      |   \ | /
                      |   /       |    \|/3
                      |  /        |     +
                      | /         |    /
                      |/1         |2 /
                      +-----------+/

      1. In USERD_get_gold_part_build_info:
              number_of_elements[Z_NFACED] = 2
                                             .
                                            /|\
                                             |
      2. In USERD_get_part_elements_by_type:
          length of conn_array will be:      2 x 1
          for element_type of Z_NFACED:
              conn_array[0][0] = 7           (for the 7-faced element)
              conn_array[1][0] = 5           (for the 5-faced element)

                                ==
                           Sum  12    <---------+
                                                |
      3. In this routine:                       |
           length of nfaced_npf_array will be:  12

            nfaced_npf_array[0]  = 5  (5-noded top face of 7-faced element)
            nfaced_npf_array[1]  = 5  (5-noded bot face of 7-faced element)
            nfaced_npf_array[2]  = 4  (4-noded front face of 7-faced element)
            nfaced_npf_array[3]  = 4  (4-noded left face of 7-faced element)
            nfaced_npf_array[4]  = 4  (4-noded back face of 7-faced element)
            nfaced_npf_array[5]  = 4  (4-noded right front face of 7-faced element)
            nfaced_npf_array[6]  = 4  (4-noded right back face of 7-faced element)

            nfaced_npf_array[7]  = 3  (3-noded top face of 5-faced element)
            nfaced_npf_array[8]  = 3  (3-noded bot face of 5-faced element)
            nfaced_npf_array[9]  = 4  (4-noded back face of 5-faced element)
            nfaced_npf_array[10] = 4  (4-noded right face of 5-faced element)
            nfaced_npf_array[11] = 4  (4-noded left front face of 5-faced element)

                                   ==
                             Sum   48   <-------------+
                                                      |
      4. In USERD_get_nfaced_conn:                    |
            length of the nfaced_conn_array will be:  48

            nsided_conn_array[0] = 7   (conn of 5-noded top face of 7-faced elem)
            nsided_conn_array[1] = 8
            nsided_conn_array[2] = 9
            nsided_conn_array[3] = 10
            nsided_conn_array[4] = 11

            nsided_conn_array[5] = 1   (conn of 5-noded bot face of 7-faced elem)
            nsided_conn_array[6] = 5
            nsided_conn_array[7] = 4
            nsided_conn_array[8] = 3
            nsided_conn_array[9] = 2

            nsided_conn_array[10] = 1  (conn of 4-noded front face of 7-faced elem)
            nsided_conn_array[11] = 2
            nsided_conn_array[12] = 8
            nsided_conn_array[13] = 7

            nsided_conn_array[14] = 5  (conn of 4-noded left face of 7-faced elem)
            nsided_conn_array[15] = 1
            nsided_conn_array[16] = 7
            nsided_conn_array[17] = 11

            nsided_conn_array[18] = 4  (conn of 4-noded back face of 7-faced elem)
            nsided_conn_array[19] = 5
            nsided_conn_array[20] = 11
            nsided_conn_array[21] = 10

            nsided_conn_array[22] = 2  (conn of 4-noded right front face of 7-faced)
            nsided_conn_array[23] = 3
            nsided_conn_array[24] = 9
            nsided_conn_array[25] = 8

            nsided_conn_array[26] = 3  (conn of 4-noded right back face of 7-faced)
            nsided_conn_array[27] = 4
            nsided_conn_array[28] = 10
            nsided_conn_array[29] = 9

            nsided_conn_array[30] = 9  (conn of 3-noded top face of 5-faced elem)
            nsided_conn_array[32] = 12
            nsided_conn_array[32] = 10

            nsided_conn_array[33] = 3  (conn of 3-noded bot face of 5-faced elem)
            nsided_conn_array[34] = 4
            nsided_conn_array[35] = 6

            nsided_conn_array[36] = 6  (conn of 4-noded back face of 5-faced elem)
            nsided_conn_array[37] = 4
            nsided_conn_array[38] = 10
            nsided_conn_array[39] = 12

            nsided_conn_array[40] = 3  (conn of 4-noded right face of 5-faced elem)
            nsided_conn_array[41] = 6
            nsided_conn_array[42] = 12
            nsided_conn_array[43] = 9

            nsided_conn_array[44] = 4  (conn of 4-noded left front face of 5-faced)
            nsided_conn_array[45] = 3
            nsided_conn_array[46] = 9
            nsided_conn_array[47] = 10




--------------------------------------------------------------------
USERD_get_node_label_status

   Description:
   -----------
   Answers the question as to whether node labels will be provided.

   Specification:
   -------------
   int USERD_get_node_label_status( void )

   Returns:
   -------
   TRUE        if node labels will be provided
   FALSE       if node labels will NOT be provided

   Arguments:
   ---------
   none

   Notes:
   -----
   * Node ids are needed in order to do any node querying, or node
     labeling on-screen within EnSight.

   * Prior to API 2.01:
     -----------------
       For unstructured parts, you can read them from your file if
       available, or can assign them, etc. They need to be unique
       per part, and are often unique per model.  They must also be
       positive numbers greater than zero.

         USERD_get_part_node_ids is used to obtain the ids, if the
         status returned here is TRUE.

         (Unlike API 1.0, where the connectivity of elements had to be
          according to the node ids - API 2.0's element connectivities
          are not affected either way by the status here.)

       For structured parts, EnSight will assign ids if you return a
         status of TRUE here.  You cannot assign them yourself!!

   * Starting at API 2.01:
     --------------------
       For both unstructured and structured parts, you can read them
       from your file if available, or can assign them, etc. They need
       to be unique per part, and are often unique per model. They must
       also be positive numbers greater than zero.

       USERD_get_part_node_ids is used to obtain the ids, if the
       status returned here is TRUE.

   * Will call USERD_get_part_node_ids for each part if this routine
     returns TRUE.

--------------------------------------------------------------------
USERD_get_nsided_conn -

   Description:
   -----------
   Gets the array containing the connectivity of nsided elements

   Specification:
   -------------
   int USERD_get_nsided_conn(int part_number,
                             int *nsided_conn_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number         = the part number

   (OUT) nsided_conn_array   = 1D array of nsided connectivies

                               (int array will have been allocated long enough
                                to hold all the nsided connectivities. Which is
                                the sum of all the nodes_per_element values in
                                the conn_array of USERD_get_part_elements_by_type)


   Notes:
   -----
   * Will not be called unless there are some nsided elements in the the part.

   * Providing nsided information to Ensight:

     1. In USERD_get_gold_part_build_info, provide the number of nsided
        elements in the part.

     2. In USERD_get_part_elements_by_type, provide (in the conn_array),
        the number of nodes per nsided element. (as if connectivity
        length of an nsided element is one)

     3. In this routine, provide the streamed connectivities for each of the
        nsided elements.


     Simple example:         5        6
                            +--------+
     3 nsided elements:    /|         \
     (1 4-sided           / |          \
      1 3-sided          /  |           \
      1 7-sided)        /   |            \ 7
                       /3   |4            +
                      +-----+             |
                      |     |             |
                      |     |             |8
                      |     |             +
                      |     |            /
                      |     |           /
                      |     |          /
                      |1    |2        /9
                      +-----+--------+

      1. In USERD_get_gold_part_build_info:
              number_of_elements[Z_NSIDED] = 3
                                             .
                                            /|\
                                             |
      2. In USERD_get_part_elements_by_type:
          length of conn_array will be:      3 x 1

          for element_type of Z_NSIDED:
              conn_array[0][0] = 4           (for the 4-sided element)
              conn_array[1][0] = 3           (for the 3-sided element)
              conn_array[2][0] = 7           (for the 7-sided element)

                           Sum  ===
                                 14    <---------+
                                                 |
      3. In this routine:                        |
           length of nsided_conn_array will be:  14

              nsided_conn_array[0]  = 1      (connectivity of 4-sided element)
              nsided_conn_array[1]  = 2
              nsided_conn_array[2]  = 4
              nsided_conn_array[3]  = 3

              nsided_conn_array[4]  = 3      (connectivity of 3-sided element)
              nsided_conn_array[5]  = 4
              nsided_conn_array[6]  = 5

              nsided_conn_array[7]  = 2      (connectivity of 7-sided element)
              nsided_conn_array[8]  = 9
              nsided_conn_array[9]  = 8
              nsided_conn_array[10] = 7
              nsided_conn_array[11] = 6
              nsided_conn_array[12] = 5
              nsided_conn_array[13] = 4




--------------------------------------------------------------------
USERD_get_num_of_time_steps

   Description:
   -----------
   Gets the number of time steps of data available for desired timeset.

   Specification:
   -------------
   int USERD_get_num_of_time_steps( int timeset_number )

   Returns:
   -------
   Number of time steps in timeset  (>0 if okay, <=0 if problems).

   Arguments:
   ---------
   (IN) timeset number = the timeset number

                         For example: If USERD_get_number_of_timesets
                                      returns 2, the valid
                                      timeset_number's would be 1 and 2

   Notes:
   -----
   * This should be >= 1       1 indicates a static model
                              >1 indicates a transient model

   * Num_time_steps[timeset_number] would be set here



--------------------------------------------------------------------
USERD_get_number_of_files_in_dataset

   Description:
   -----------
   Get the total number of files in the dataset.  Used for the
   dataset query option within EnSight.

   Specification:
   -------------
   int USERD_get_number_of_files_in_dataset( void )

   Returns:
   -------
   The total number of files in the dataset.

   Arguments:
   ---------
   none

   Notes:
   -----
   * You can be as complete as you want about this.  If you don't
     care about the dataset query option, return a value of 0
     If you only want certain files, you can just include them. But,
     you will need to supply the info in USERD_get_dataset_query_file_info
     for each file you include here.

   * Num_dataset_files would be set here


--------------------------------------------------------------------
USERD_get_number_of_material_sets -

   Description:
   -----------
   Get the number of material sets in the model

   Specification:
   -------------
   int USERD_get_number_of_material_sets( void )


   Returns:
   -------
   Num_material_sets = number of material sets
                       (Zero would indicate that you have no materials
                        to deal with in the model)

                       or

                       -1 if an error condition

   Arguments:
   ---------
   none

   Notes:
   -----
  * You may want to keep this as a global for use in other routines.

   ###############################################################
   NOTE:  For EnSight 7.6, only one material set is supported
          within EnSight.
          Thus the only valid returns here are:
               0 (no materials)
               1 (for the one material set allowed)
          or  -1 (if an error)

          If the casefile has more than this, this reader will
          read them, but EnSight will issue an error message and
          choke on them!
   ###############################################################

  ================================================================
  A very simple explanatory example, to use as a reference for the
  materials routines:

  Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
  Most of the model is material 1, but the top left corner is material 9 -
  basically as shown:


        *--------*--------*--------*
        |        |   /    |        |
        |     Mat 9 /     |        |
        |        | /      |        |
        |        |/       |        |
        |  e7    /   e8   |   e9   |
        |       /|        |        |
        |      / |        |        |
        |     /  |        |        |
        *----/---*--------*--------*
        |   /    |        |        |
        |  /     |        |        |
        | /      |      Mat 1      |
        |/       |        |        |
        |   e4   |   e5   |   e6   |
        |        |        |        |
        |        |        |        |
        |        |        |        |
        *--------*--------*--------*
        |        |        |        |
        |        |        |        |
        |        |        |        |
        |        |        |        |
        |   e1   |   e2   |   e3   |
        |        |        |        |
        |        |        |        |
        |        |        |        |
        *--------*--------*--------*


  Thus, in this routine, set:
    Num_material_sets = 1

  In USERD_get_matf_set_info, set:
    mat_set_ids[0]    = 1
    mat_set_name[0]   = "Material Set 1"  (or whatever name desired)

  In USERD_get_number_of_materials, input would be set_index = 0, and
  would need to set:
    Num_materials[0] = 2

  For simplicity, the ids and descriptions that would be returned in
  USERD_get_matf_var_info could be:
    mat_ids[0] = 1
    mat_ids[1] = 9
    mat_desc[0] = "mat 1"   (or whatever desired)
    mat_desc[2] = "mat 9"

  The per element material ids list would need to be:

     material ids:
     -------------
     ids_list[0] = 1  (material id 1, for elem e1)
     ids_list[1] = 1  (     "                  e2)
     ids_list[2] = 1  (     "                  e3)
     ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
     ids_list[5] = 1  (material id 1, for elem e5)
     ids_list[5] = 1  (     "                  e6)
     ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
     ids_list[5] = -9 (     "                  e8)
     ids_list[5] = 1  (material id 1, for elem e9)

  Finally we need the mixed material ids list and the mixed materials values list,
  which would need to be:

       mixed-material ids:
       -------------------
   ==> 1  ids_list[0]  =  2  (the -1 in the material variable points here,
                                      2 indicates that two materials are present)
       2  ids_list[1]  =  1  (1st material is 1)
       3  ids_list[2]  =  9  (2nd material is 9)
       4  ids_list[3]  = -1  (negative of index into mixed-material val_list)
   ==> 5  ids_list[4]  =  2  (the -5 in the material variable points here,
                                      2 indicates that two materials are present)
       6  ids_list[5]  =  1  (1st material is 1)
       7  ids_list[6]  =  9  (2nd material is 9)
       8  ids_list[7]  = -3  (negative of index into mixed-material val_list)
   ==> 9  ids_list[8]  =  2     etc.
       10 ids_list[9]  =  1
       11 ids_list[10] =  9
       12 ids_list[11] = -5

       mixed-material values:
       ----------------------
   ==> 1 val_list[0] = 0.875 (the -1 in the  mixed-material ids_list points here,
                                       and this is the value for material 1)
       2 val_list[1] = 0.125 (the value for material 9)
   ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
       4 val_list[3] = 0.875
   ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
       6 val_list[5] = 0.125

  So, USERD_size_matf_data would need to return
       matf_size = 8, when called with set_id    = 1
                                       part_id   = 1
                                       wtyp      = Z_QUA04
                                       mat_type  = Z_MAT_INDEX

       matf_size = 12, when called with set_id   = 1
                                        part_id  = 1
                                        mat_type = Z_MIX_INDEX

                 = 6, when called with set_id   = 1
                                       part_id  = 1
                                       mat_type = Z_MIX_VALUE

  And, USERD_load_matf_data would need to return:
    the int array ids_list as shown above when called with:
       set_id   = 1
       part_id  = 1
       wtyp     = Z_QUA04
       mat_type = Z_MAT_INDEX (indicating id list).

    the int array ids_list as shown above when called with:
       set_id   = 1
       part_id  = 1
       mat_type = Z_MIX_INDEX (indicating id list).

    the float array val_list as shown above when called with:
       set_id   = 1
       part_id  = 1
       mat_type = Z_MIX_VALUE (indicating val list).


-------------------------------------------------------------------------
USERD_get_number_of_materials

   Description:
   -----------
   Gets the number of materials in the material set

   Specification:
   -------------
   int USERD_get_number_of_materials( int set_index )

   Returns:
   -------
   Num_materials[set_index]   = Number of materials in the set
                                 0 indicates no materials information present
                                -1 indicates an error
   Arguments:
   ---------
   (IN) set_index             = the material set index (zero based)

   Notes:
   -----
  * See USERD_get_number_of_material_sets header for explanatory example
  * Will not be called if Num_material_sets is zero
  * You may want to keep this as a global for use in other routines.



--------------------------------------------------------------------
USERD_get_number_of_model_parts

   Description:
   -----------
   Gets the total number of unstructured and structured parts
   in the model, for which you can supply information.

   Specification:
   -------------
   int USERD_get_number_of_model_parts( void )

   Returns:
   -------
   Number of parts  (>0 if okay, <=0 if problems).

   Arguments:
   ---------
   none

   Notes:
   -----
   * If going to have to read down through the parts in order to
     know how many, you may want to build a table of pointers to
     the various parts, so you can easily get to particular parts in
     later processes.  If you can simply read the number of parts
     at the head of the file, then you would probably not build the
     table at this time.

   * This routine would set Numparts_available, which is equal to
     Num_unstructured_parts + Num_structured_blocks.



--------------------------------------------------------------------
USERD_get_number_of_timesets

   Description:
   -----------
    Gets the number of timesets used in the model.

   Specification:
   -------------
   int USERD_get_number_of_timesets( void )

   Returns:
   -------
   Number of timesets in the model

   Arguments:
   ---------
   none

   Notes:
   -----
   * Num_timesets would be set here

   * If you have a static model, both geometry and variables, you should
     return a value of zero.
 
   * If you have a transient model, then you should return one or more.
 
   For example:
 
      Geometry    Variables                                 No. of timesets
      ---------   ------------------------------            ---------------
      static      static                                      0
      static      transient, all using same timeset           1
 
      transient   transient, all using same timeset as geom   1
 
      static      transient, using 3 different timesets       3
 
      transient   transient, using 3 different timesets and
                             none of them the same as the
                             geometry timeset                 4
          etc.
 
   NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
                                                   the timeset number to use
                                                   for geometry in:
                                               USERD_get_geom_timeset_number
 
         Variables can use the same timeset as the geometry, or can use
         other timesets. More than one variable can use the same timeset.
 
   example:  changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
             variable 1 provided at these same five steps
             variable 2 provided at 3 steps, 0.5, 1.25, 3.33
 
        This routine should return a value of 2, because only
        two different timesets are needed. Timeset 1 would be for the
        geometry and variable 1 (they both use it). Timeset 2 would
        be for variable 2, which needs its own in this case.





--------------------------------------------------------------------
USERD_get_number_of_variables

   Description:
   -----------
   Get the number of variables for which you will be providing info.

   Specification:
   -------------
   int USERD_get_number_of_variables( void )

   Returns:
   -------
   Number of variables (includes constant, scalar, vector and tensor types)
                       (>=0 if okay, <0 if problem)

   Arguments:
   ---------
   none

   Notes:
   -----
    *****************************************************************
   * Variable numbers, by which references will be made, are implied
     here. If you say there are 3 variables, the variable numbers
     will be 1, 2, and 3.
    *****************************************************************

   * Num_variables would be set here



--------------------------------------------------------------------
USERD_get_part_coords

   Description:
   -----------
   Gets the coordinates for an unstructured part.

   Specification:
   -------------
   int USERD_get_part_coords(int part_number, float **coord_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number             = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (OUT) coord_array             = 2D float array which contains,
                                   x,y,z coordinates of each node
                                   in the part.

       (IMPORTANT: The second dimension of this aray is 1-based!!!)

                                (Array will have been allocated
                                 3 by (number_of_nodes + 1) for the part
                                 long - see USERD_get_gold_part_build_info)


                       ex) If number_of_nodes = 100
                           as obtained in:
                             USERD_get_gold_part_build_info

                           Then the allocated dimensions of the
                           pointer sent to this routine will be:
                             coord_array[3][101]

                           Ignore the coord_array[0][0]
                                      coord_array[1][0]
                                      coord_array[2][0] locations and start
                           the node coordinates at:
                             coord_array[0][1]
                             coord_array[1][1]
                             coord_array[2][1]

                             coord_array[0][2]
                             coord_array[1][2]
                             coord_array[2][2]

                                   etc.

   Notes:
   -----
   * Not called unless Num_unstructured_parts is > 0

   * Will be based on Current_time_step


--------------------------------------------------------------------
USERD_get_part_element_ids_by_type

   Description:
   -----------
   Gets the ids for the elements of a particular type for an unstructured
   or structured part.

   Specification:
   -------------
   int USERD_get_part_element_ids_by_type(int part_number,
                                          int element_type,
                                          int *elemid_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number             = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (IN)  element_type            = One of the following (See global_extern.h)
                                   Z_POINT      node point element
                                   Z_BAR02      2 node bar
                                   Z_BAR03      3 node bar
                                   Z_TRI03      3 node triangle
                                   Z_TRI06      6 node triangle
                                   Z_QUA04      4 node quad
                                   Z_QUA08      8 node quad
                                   Z_TET04      4 node tetrahedron
                                   Z_TET10     10 node tetrahedron
                                   Z_PYR05      5 node pyramid
                                   Z_PYR13     13 node pyramid
                                   Z_PEN06      6 node pentahedron
                                   Z_PEN15     15 node pentahedron
                                   Z_HEX08      8 node hexahedron
                                   Z_HEX20     20 node hexahedron

                                   Z_G_POINT    ghost node point element
                                   Z_G_BAR02    2 node ghost bar
                                   Z_G_BAR03    3 node ghost bar
                                   Z_G_TRI03    3 node ghost triangle
                                   Z_G_TRI06    6 node ghost triangle
                                   Z_G_QUA04    4 node ghost quad
                                   Z_G_QUA08    8 node ghost quad
                                   Z_G_TET04    4 node ghost tetrahedron
                                   Z_G_TET10   10 node ghost tetrahedron
                                   Z_G_PYR05    5 node ghost pyramid
                                   Z_G_PYR13   13 node ghost pyramid
                                   Z_G_PEN06    6 node ghost pentahedron
                                   Z_G_PEN15   15 node ghost pentahedron
                                   Z_G_HEX08    8 node ghost hexahedron
                                   Z_G_HEX20   20 node ghost hexahedron

   (OUT) elemid_array            = 1D array containing id of each
                                   element of the type.

                                  (Array will have been allocated
                                   number_of_elements of the type long)

                       ex) If number_of_elements[Z_TRI03] = 25
                              number_of_elements[Z_QUA04] = 100
                              number_of_elements[Z_HEX08] = 30
                           as obtained in:
                            USERD_get_gold_part_build_info

                           Then the allocated dimensions available
                           for this routine will be:
                              conn_array[25]   when called with Z_TRI03

                              conn_array[100]  when called with Z_QUA04

                              conn_array[30]  when called with Z_HEX08

   Notes:
   -----
   * Not called unless element label status is set to TRUE in
     USERD_get_element_label_status

   * Will be based on Current_time_step



--------------------------------------------------------------------
USERD_get_part_elements_by_type

   Description:
   -----------
   Gets the connectivities for the elements of a particular type in an
   unstructured part

   Specification:
   -------------
   int USERD_get_part_elements_by_type(int part_number,
                                       int element_type,
                                       int **conn_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number           = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (IN)  element_type          = One of the following (See global_extern.h)
                                 Z_POINT      node point element
                                 Z_BAR02      2 node bar
                                 Z_BAR03      3 node bar
                                 Z_TRI03      3 node triangle
                                 Z_TRI06      6 node triangle
                                 Z_QUA04      4 node quad
                                 Z_QUA08      8 node quad
                                 Z_TET04      4 node tetrahedron
                                 Z_TET10     10 node tetrahedron
                                 Z_PYR05      5 node pyramid
                                 Z_PYR13     13 node pyramid
                                 Z_PEN06      6 node pentahedron
                                 Z_PEN15     15 node pentahedron
                                 Z_HEX08      8 node hexahedron
                                 Z_HEX20     20 node hexahedron

                                 Z_G_POINT    ghost node point element
                                 Z_G_BAR02    2 node ghost bar
                                 Z_G_BAR03    3 node ghost bar
                                 Z_G_TRI03    3 node ghost triangle
                                 Z_G_TRI06    6 node ghost triangle
                                 Z_G_QUA04    4 node ghost quad
                                 Z_G_QUA08    8 node ghost quad
                                 Z_G_TET04    4 node ghost tetrahedron
                                 Z_G_TET10   10 node ghost tetrahedron
                                 Z_G_PYR05    5 node ghost pyramid
                                 Z_G_PYR13   13 node ghost pyramid
                                 Z_G_PEN06    6 node ghost pentahedron
                                 Z_G_PEN15   15 node ghost pentahedron
                                 Z_G_HEX08    8 node ghost hexahedron
                                 Z_G_HEX20   20 node ghost hexahedron


   (OUT) conn_array            = 2D array containing connectivity
                                 of each element of the type.

                                (Array will have been allocated
                                 num_of_elements of the type by
                                 connectivity length of the type)

                       ex) If number_of_elements[Z_TRI03] = 25
                              number_of_elements[Z_QUA04] = 100
                              number_of_elements[Z_HEX08] = 30
                           as obtained in:
                            USERD_get_gold_part_build_info

                           Then the allocated dimensions available
                           for this routine will be:
                              conn_array[25][3]   when called with Z_TRI03

                              conn_array[100][4]  when called with Z_QUA04

                              conn_array[30][8]   when called with Z_HEX08
   
   Notes:
   -----
   * Not called unless Num_unstructured_parts is > 0

   * Will be based on Current_time_step


--------------------------------------------------------------------
USERD_get_part_node_ids

   Description:
   -----------
   Gets the node ids of an unstructured or structured part.

   Specification:
   -------------
   int USERD_get_part_node_ids(int part_number, int *nodeid_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  part_number             = The part number
                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

   (OUT) nodeid_array            = 1D array containing node ids of
                                    each node in the part.

           (IMPORTANT: This array is 1-based!!!)

                                   (Array will have been allocated
                                    (number_of_nodes + 1) for the part long
                                    see USERD_get_gold_part_build_info)

                       ex) If number_of_nodes = 100
                           as obtained in:
                             USERD_get_gold_part_build_info

                           Then the allocated dimensions of the
                           pointer sent to this routine will be:
                             nodeid_array[101]

                           Ignore the nodeid_array[0] location and start
                           the node ids at:
                             nodeid_array[1]

                             nodeid_array[2]

                                   etc.

   Notes:
   -----
   * Not called unless node label status is TRUE, as returned from
     USERD_get_node_label_status

   * Will be based on Current_time_step

   * The ids are purely labels, used when displaying or querying node ids.
     However, any node id < 0 will never be displayed


--------------------------------------------------------------------
USERD_get_reader_descrip

   Description:
   -----------
   Gets the description of the reader, so gui can give more info

   Specification:
   -------------
   int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) descrip  = the description of the reader (max length is MAXFILENP,
                                                   which is 255)

   Notes:
   -----
   * OPTIONAL ROUTINE!   You can have it or not.



--------------------------------------------------------------------
USERD_get_reader_version

   Description:
   -----------
   Gets the version number of the user defined reader

   Specification:
   -------------
   int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful (and will assume is version 1.0)

   Arguments:
   ---------
   (OUT) version_number       = the version number of the reader
                                (max length is Z_MAX_USERD_NAME, which
                                 is 20)

   Notes:
   -----
   * This needs to be "2.000" or greater. Otherwise EnSight will assume
     this reader is API 1.0

   * should set it to "2.010" for this version of the API




--------------------------------------------------------------------
USERD_get_sol_times

   Description:
   -----------
   Get the solution times associated with each time step for 
   desired timeset.

   Specification:
   -------------
   int USERD_get_sol_times(int timeset_number,
                           float *solution_times)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  timeset_number     = the timeset number
 
                              For example: If USERD_get_number_of_timesets
                                           returns 2, the valid
                                           timeset_number's would be 1 and 2

   (OUT) solution_times       = 1D array of solution times per time step

                                  (Array will have been allocated
                                   Num_time_steps[timeset_number] long)

   Notes:
   -----
   * The solution times must be non-negative and increasing.



--------------------------------------------------------------------
USERD_get_timeset_description -

   Description:
   -----------
   Get the description to associate with the desired timeset.

   Specification:
   -------------
   int USERD_get_timeset_description(int timeset_number,
                                     char timeset_description[Z_BUFL])

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  timeset_number     = the timeset number
 
                              For example: If USERD_get_number_of_timesets
                                           returns 2, the valid
                                           timeset_number's would be 1 and 2

   (OUT) timeset_description  = timeset description string


   Notes:
   -----
   * A string of NULLs is valid for timeset_description




--------------------------------------------------------------------
USERD_get_var_by_component

   Description:
   -----------
   Gets the values of a variable component.  Both unstructured and structured
   parts use this routine.

   if Z_PER_NODE:
     Get the component value at each node for a given variable in the part.

   or if Z_PER_ELEM:
     Get the component value at each element of a specific part and type
     for a given variable.

   Specification:
   -------------
   int USERD_get_var_by_component(int which_variable,
                                  int which_part,
                                  int var_type,
                                  int which_type,
                                  int imag_data,
                                  int component,
                                  float *var_array)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   or:  Z_UNDEF, in which case you need not load any values into var_array


   Arguments:
   ---------
   (IN)  which_variable          = The variable number

   (IN)  which_part                 Since EnSight Version 7.4
                                    -------------------------
                                  = The part number

                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

                                    Prior to EnSight Version 7.4
                                    ----------------------------
                                  = The part id   This is the part_id label loaded
                                                  in USERD_get_gold_part_build_info.
                                                  It is NOT the part table index.

   (IN)  var_type                = Z_SCALAR
                                   Z_VECTOR
                                   Z_TENSOR   (symmetric tensor)
                                   Z_TENSOR9  (asymmetric tensor)

   (IN)  which_type

            if Z_PER_NODE:         Not used

            if Z_PER_ELEM:       = The element type
                                   Z_POINT      node point element
                                   Z_BAR02      2 node bar
                                   Z_BAR03      3 node bar
                                   Z_TRI03      3 node triangle
                                   Z_TRI06      6 node triangle
                                   Z_QUA04      4 node quad
                                   Z_QUA08      8 node quad
                                   Z_TET04      4 node tetrahedron
                                   Z_TET10     10 node tetrahedron
                                   Z_PYR05      5 node pyramid
                                   Z_PYR13     13 node pyramid
                                   Z_PEN06      6 node pentahedron
                                   Z_PEN15     15 node pentahedron
                                   Z_HEX08      8 node hexahedron
                                   Z_HEX20     20 node hexahedron

                                   Z_G_POINT    ghost node point element
                                   Z_G_BAR02    2 node ghost bar
                                   Z_G_BAR03    3 node ghost bar
                                   Z_G_TRI03    3 node ghost triangle
                                   Z_G_TRI06    6 node ghost triangle
                                   Z_G_QUA04    4 node ghost quad
                                   Z_G_QUA08    8 node ghost quad
                                   Z_G_TET04    4 node ghost tetrahedron
                                   Z_G_TET10   10 node ghost tetrahedron
                                   Z_G_PYR05    5 node ghost pyramid
                                   Z_G_PYR13   13 node ghost pyramid
                                   Z_G_PEN06    6 node ghost pentahedron
                                   Z_G_PEN15   15 node ghost pentahedron
                                   Z_G_HEX08    8 node ghost hexahedron
                                   Z_G_HEX20   20 node ghost hexahedron

   (IN)  imag_data               = TRUE if imag component
                                   FALSE if real component
 
   (IN)  component               = The component: (0       if Z_SCALAR)
                                                  (0 - 2   if Z_VECTOR)
                                                  (0 - 5   if Z_TENSOR)
                                                  (0 - 8   if Z_TENSOR9)
 
                                 * 6 Symmetric Indicies, 0:5    *
                                 * ---------------------------- *
                                 *     | 11 12 13 |   | 0 3 4 | *
                                 *     |          |   |       | *
                                 * T = |    22 23 | = |   1 5 | *
                                 *     |          |   |       | *
                                 *     |       33 |   |     2 | *
 

                                 * 9 General   Indicies, 0:8    *
                                 * ---------------------------- *
                                 *     | 11 12 13 |   | 0 3 4 | *
                                 *     |          |   |       | *
                                 * T = | 21 22 23 | = | 6 1 5 | *
                                 *     |          |   |       | *
                                 *     | 31 32 33 |   | 7 8 2 | *

   (OUT) var_array 

      -----------------------------------------------------------------------
      (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
      -----------------------------------------------------------------------

            if Z_PER_NODE:    = 1D array containing variable component value
                                for each node.

                                (Array will have been allocated
                                 (number_of_nodes + 1) long)

                      Info stored in this fashion:
                            var_array[0] = not used
                            var_array[1] = var component for node 1 of part
                            var_array[2] = var_component for node 2 of part
                            var_array[3] = var_component for node 3 of part
                            etc.

            if Z_PER_ELEM:    = 1D array containing variable component
                                value for each element of a particular
                                part and type.
                                    
                              (Array will have been allocated
                               (number_of_elements[which_part][which_type] + 1)
                                long.  See USERD_get_gold_part_build_info)

                  Info stored in this fashion:
                    var_array[1] = var component for elem 1 (of part and type)
                    var_array[2] = var component for elem 2 (of part and type)
                    var_array[3] = var component for elem 3 (of part and type)
                    etc.

   Notes:
   -----
   * Not called unless Num_variables is > 0

   * The per_node or per_elem classification must be obtainable from the
     variable number (a var_classify array needs to be retained)

   * Will be based on Current_time_step

   * If the variable is not defined for this part, simply return with a
     value of Z_UNDEF.  EnSight will treat the variable as undefined for
     this part.


--------------------------------------------------------------------
USERD_get_var_value_at_specific

   Description:
   -----------
   if Z_PER_NODE:
     Get the value of a particular variable at a particular node in a
     particular part at a particular time.

   or if Z_PER_ELEM:
     Get the value of a particular variable at a particular element of
     a particular type in a particular part at a particular time.


   Specification:
   -------------
   int USERD_get_var_value_at_specific(int which_var,
                                       int which_node_or_elem,
                                       int which_part,
                                       int which_elem_type,
                                       int time_step,
                                       float values[3],
                                       int imag_data)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN)  which_var   = The variable number

   (IN)  which_node_or_elem

              If Z_PER_NODE:
                = The node number.  This is not the id, but is
                                    the index of the global node 
                                    list (1 based), or the block's
                                    node list (1 based).

                  Thus,  coord_array[1]
                         coord_array[2]
                         coord_array[3]
                              .      |
                              .      |which_node_or_elem index
                              .             ----


              If Z_PER_ELEM:
                = The element number.  This is not the id, but is
                                       the element number index
                                       of the number_of_element array
                                       (see USERD_get_gold_part_build_info),
                                        or the block's element list (1 based).

                  Thus,  for which_part:
                         conn_array[which_elem_type][0]
                         conn_array[which_elem_type][1]
                         conn_array[which_elem_type][2]
                              .                      |
                              .          which_node_or_elem index
                              .                        ----


   (IN)  which_part                 Since EnSight Version 7.4
                                    -------------------------
                                  = The part number

                                    (1-based index of part table, namely:

                                       1 ... Numparts_available.

                                     It is NOT the part_id that
                                     is loaded in USERD_get_gold_part_build_info)

                                    Prior to EnSight Version 7.4
                                    ----------------------------
                                  = The part id   This is the part_id label loaded
                                                  in USERD_get_gold_part_build_info.
                                                  It is NOT the part table index.


   (IN)  which_elem_type

              If Z_PER_NODE, or block part:
                = Not used

              If Z_PER_ELEM:
                = The element type.    This is the element type index
                                       of the number_of_element array
                                       (see USERD_get_gold_part_build_info)

   (IN)  time_step   = The time step

   (IN)  imag_data   = TRUE if want imaginary value.
                       FALSE if want real value.

   (OUT) values      = scalar or vector component value(s)
                        values[0] = scalar or vector[0]
                        values[1] = vector[1]
                        values[2] = vector[2]


   Notes:
   -----
   * This routine is used in node querys over time (or element querys over
     time for Z_PER_ELEM variables).  If these operations are not critical
     to you, this can be a dummy routine.

   * The per_node or per_elem classification must be obtainable from the
     variable number (a var_classify array needs to be retained)

   * The time step given is for the proper variable timeset.


----------------------------------------------------------------------
USERD_load_matf_data

   Description:
   -----------
   Get the material id list, mixed-material id list, or
   mixed-material values list for the given material set and part (and
   element type if material id list)

   Specification:
   -------------
   int USERD_load_matf_data( int set_index,
                             int part_id,
                             int wtyp,
                             int mat_type,
                             int *ids_list,
                             float *val_list)


   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
  (IN)  set_index         = the material set index (zero based)

  (IN)  part_id           = the part number desired

  (IN)  wtyp              = the element type        (used for Z_MAT_INDEX only)

                                  Z_POINT    node point element
                                  Z_BAR02    2 node bar
                                  Z_BAR03    3 node bar
                                  Z_TRI03    3 node triangle
                                  Z_TRI06    6 node triangle
                                  Z_QUA04    4 node quad
                                  Z_QUA08    8 node quad
                                  Z_TET04    4 node tetrahedron
                                  Z_TET10   10 node tetrahedron
                                  Z_PYR05    5 node pyramid
                                  Z_PYR13   13 node pyramid
                                  Z_PEN06    6 node pentahedron
                                  Z_PEN15   15 node pentahedron
                                  Z_HEX08    8 node hexahedron
                                  Z_HEX20   20 node hexahedron
                                  Z_NSIDED  nsided polygon
                                  Z_NFACED  nfaced polyhedron

                                  Z_G_POINT    ghost node point element
                                  Z_G_BAR02    2 node ghost bar
                                  Z_G_BAR03    3 node ghost bar
                                  Z_G_TRI03    3 node ghost triangle
                                  Z_G_TRI06    6 node ghost triangle
                                  Z_G_QUA04    4 node ghost quad
                                  Z_G_QUA08    8 node ghost quad
                                  Z_G_TET04    4 node ghost tetrahedron
                                  Z_G_TET10   10 node ghost tetrahedron
                                  Z_G_PYR05    5 node ghost pyramid
                                  Z_G_PYR13   13 node ghost pyramid
                                  Z_G_PEN06    6 node ghost pentahedron
                                  Z_G_PEN15   15 node ghost pentahedron
                                  Z_G_HEX08    8 node ghost hexahedron
                                  Z_G_HEX20   20 node ghost hexahedron
                                  Z_G_NSIDED  ghost nsided polygon
                                  Z_G_NFACED  ghost nfaced polyhedron

  (IN)  mat_type          = Z_MAT_INDEX for material ids list
                            Z_MIX_INDEX for mixed-material ids list
                            Z_MIX_VALUE for mixed-material values list

  (OUT) ids_list          = If mat_type is Z_MAT_INDEX:
                            ---------------------------
                             1D material id list
                               (Int array will have been allocated
                                the appropriate size, as returned in
                                 USERD_size_matf_data for mat_type Z_MAT_INDEX)

                            If mat_type is Z_MIX_INDEX:
                            ---------------------------
                             1D mixed-material id list
                               (Int array will have been allocated
                                the appropriate size, as returned in
                                 USERD_size_matf_data for mat_type Z_MIX_INDEX)

  (OUT) val_list          = 1D mixed-materials values list
                            (only used if mat_type is Z_MIX_VALUE)

                               (Float array will have been allocated
                                the appropriate size, as returned in
                                USERD_size_matf_data for mat_type Z_MIX_VALUE)

   Notes:
   -----
  * See USERD_get_number_of_material_sets header for explanatory example
  * Will not be called if Num_material_sets is zero,
     or Num_materials[set_index] is zero,
     or the appropriate size from USERD_size_matf_data is zero



--------------------------------------------------------------------
USERD_set_filenames

   Description:
   -----------
   Receives the geometry and result filenames entered in the data
   dialog.  The user written code will have to store and use these
   as needed. The user written code must manage its own files!!

   Specification:
   -------------
   int USERD_set_filenames(char filename_1[],
                           char filename_2[],
                           char the_path[],
                           int swapbytes)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (IN) filename_1   = the filename entered into the geometry
                         field of the data dialog.

   (IN) param_2      = The usage of this string depends on
                       'two_fields' in USERD_get_name_of_reader.
 
                       If two_fields is FALSE then it's empty.
 
                       If two_fields is TRUE, this is the 
                       manditory results file entered 
                       into the result field of the data dialog.
 
                       If two_fields is -1, then this contains
                       optional text (filenames, modifiers, etc.)
                       that can be parsed and used to modify 
                       reader 

   (IN) the_path     = the path info from the data dialog.
                       Note: filename_1 and filename_2 have already
                            had the path prepended to them.  This
                            is provided in case it is needed for
                            filenames contained in one of the files

   (IN) swapbytes    = TRUE if should swap bytes when reading data.
                     = FALSE normally.

   Notes:
   -----
   * Since you must manage everything from the input that is entered in
     these data dialog fields, this is an important routine!

   * It may be that you will need to have an executive type file that contains
     info and other filenames within it, like EnSight6's case file.


--------------------------------------------------------------------
USERD_set_server_number

   Description:
   -----------
   Receives the server number of how many total servers.

   Specification:
   -------------
   int USERD_set_server_number(int cur_serv,
                               int tot_servs)

   Returns:
   -------
   nothing

   Arguments:
   ---------
   (IN) cur_serv    = the current server.

   (IN) tot_servs   = the total number of servers.

   Notes:
   -----
   * Only useful if your user defined reader is being used with EnSight's
     Server-of-Server capability.  And even then, it may or may not be
     something that you can take advantage of.  If your data is already
     partitioned in some manner, such that you can access the proper
     portions using this information.
 
     For all non-SOS uses, this will simply be 1 of 1



--------------------------------------------------------------------
USERD_set_time_set_and_step

   Description:
   -----------
   Set the current time step in the desired timeset.  All functions that
   need time, and that do not explicitly pass it in, will use the timeset
   and step set by this routine, if needed.

   Specification:
   -------------
   void USERD_set_time_set_and_step(int timeset_number,
                                    int time_step)

   Returns:
   -------
   nothing

   Arguments:
   ---------
   (IN) timeset_number  = the timeset number (1 based).
 
                          For example:  If USERD_get_number_of_timesets
                                        returns 2, the valid timeset_number's
                                        would be 1 and 2.

   (IN) time_step       = The current time step to set

   Notes:
   -----
   * Current_time_step and Current_timeset would be set here


--------------------------------------------------------------------
USERD_size_matf_data

   Description:
   -----------
   Get the length of the material id list, mixed-material id list, or
   mixed-material values list for the given material set and part (and
   element type if material id list)

   Specification:
   -------------
   int USERD_size_matf_data( int set_index,
                             int part_id,
                             int wtyp,
                             int mat_type,
                             int *matf_size)


   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
  (IN)  set_index         = the material set index (zero based)

  (IN)  part_id           = the part number desired

  (IN)  wtyp              = the element type        (used for Z_MAT_INDEX only)

                                  Z_POINT    node point element
                                  Z_BAR02    2 node bar
                                  Z_BAR03    3 node bar
                                  Z_TRI03    3 node triangle
                                  Z_TRI06    6 node triangle
                                  Z_QUA04    4 node quad
                                  Z_QUA08    8 node quad
                                  Z_TET04    4 node tetrahedron
                                  Z_TET10   10 node tetrahedron
                                  Z_PYR05    5 node pyramid
                                  Z_PYR13   13 node pyramid
                                  Z_PEN06    6 node pentahedron
                                  Z_PEN15   15 node pentahedron
                                  Z_HEX08    8 node hexahedron
                                  Z_HEX20   20 node hexahedron
                                  Z_NSIDED  nsided polygon
                                  Z_NFACED  nfaced polyhedron

                                  Z_G_POINT    ghost node point element
                                  Z_G_BAR02    2 node ghost bar
                                  Z_G_BAR03    3 node ghost bar
                                  Z_G_TRI03    3 node ghost triangle
                                  Z_G_TRI06    6 node ghost triangle
                                  Z_G_QUA04    4 node ghost quad
                                  Z_G_QUA08    8 node ghost quad
                                  Z_G_TET04    4 node ghost tetrahedron
                                  Z_G_TET10   10 node ghost tetrahedron
                                  Z_G_PYR05    5 node ghost pyramid
                                  Z_G_PYR13   13 node ghost pyramid
                                  Z_G_PEN06    6 node ghost pentahedron
                                  Z_G_PEN15   15 node ghost pentahedron
                                  Z_G_HEX08    8 node ghost hexahedron
                                  Z_G_HEX20   20 node ghost hexahedron
                                  Z_G_NSIDED  ghost nsided polygon
                                  Z_G_NFACED  ghost nfaced polyhedron

  (IN)  mat_type          = Z_MAT_INDEX for material ids list
                            Z_MIX_INDEX for mixed-material ids list
                            Z_MIX_VALUE for mixed-material values list

  (OUT) matf_size         = the length of the material id list, or
                            mixed-material id list, or
                            mixed-material values list
                            for the given material set and part number
                            (and element type if Z_MAT_INDEX)

   Notes:
   -----
  * See USERD_get_number_of_material_sets header for explanatory example
  * Will not be called if Num_material_sets is zero, or
     Num_materials[set_index] is zero




--------------------------------------------------------------------
USERD_stop_part_building

   Description:
   -----------
   This routine called when the part building dialog is closed.  It is
   provided in case you desire to release memory, etc. that was only needed
   during the part building process.

   Specification:
   -------------
   void USERD_stop_part_building( void )

   Returns:
   -------
   nothing

   Arguments:
   ---------
   none

   Notes:
   -----

--------------------------------------------------------------------
USERD_rigidbody_existence

   Description:
   -----------
   Gets the existence of rigid body values or not in the model

   Specification:
   -------------
   int USERD_rigidbody_existence( void )

   Returns:
   -------
   Z_OK    if rigid body values exist for the model
   Z_UNDEF if no rigid body values exist
   Z_ERR   if an error

   Arguments:
   ---------
   none

   Notes:
   -----
   * This will be based on Current_time_step


--------------------------------------------------------------------
USERD_rigidbody_values

   Description:
   -----------
   Gets the rigid body values for each part

   Specification:
   -------------
   int USERD_rigidbody_values(int part_number,
                              float values[7])

   Returns:
   -------
   Z_OK    if rigid body values exist for the model
   Z_UNDEF if no rigid body values exist
   Z_ERR   if an error

   Arguments:
   ---------
   (IN)  part_number        = The part number
 
                              (1-based index of part table, namely:
 
                                 1 ... Numparts_available.
 
                               It is NOT the part_id that
                               is loaded in USERD_get_gold_part_build_info)
 
   (OUT) values             values[0] = IX   (x location)
                            values[1] = IY   (y location)
                            values[2] = IZ   (z location)
                            values[3] = E0   (e0 euler value)
                            values[4] = E1   (e1 euler value)
                            values[5] = E2   (e2 euler value)
                            values[6] = E3   (e3 euler value)


   Notes:
   -----
   * This will be based on Current_time_step
   * It will not be called unless USERD_rigidbody_existence indicates
       that there are some values in the model by returning Z_OK.


--------------------------------------------------------------------
USERD_set_right_side

   Description:
   -----------
   Informs the reader that the time currently set is the right side of a time
   span used for variable interpolation between time steps

   Specification:
   -------------
   void USERD_set_right_side( void )

   Returns:
   -------

   Arguments:
   ---------
   none

   Notes:
   -----
   * Applies to Current_time_step





------------------------------------------------------------------
	ENHANCED GUI ROUTINES

--------------------------------------------------------------------
USERD_get_extra_gui_numbers

   Description:
   -----------
   The Enhanced GUI routines are added to allow
   the user to customize a portion of the Data
   Reader dialog to pass in options to their
   user defined reader.

   Specification:
   -------------
   void USERD__get_extra_gui_numbers(int *num_Toggles,
                                     int *num_pulldowns,
                                     int *num_fields)

   Returns:
   -------

   Arguments:
   ---------
   (OUT) num_Toggles    = number of toggles that will be provided
   
         num_pulldowns  = number of pulldowns that will be provided

         num_fields     = number of fields that will be provided

   Notes:
   -----
     There are three routines that work together:
     USERD_get_extra_gui_numbers
     USERD_get_extra_gui_defaults
     USERD_set_extra_gui_data

     The existence of these routine indicates that
     you wish to add customize entries to the
     Data Reader dialog.

     If you don't want the extra GUI features,
     simply delete these routines, or change their
     names to something such as
     USERD_DISABLED_get_extra_gui_defaults
 
     The presence of these routines
     will ensure that EnSight will call them and
     use their data to modify the extraction parameters set
     with some or all of the following:
     toggles, pulldown menu and fields.
 
     The user can then interact with the enhanced
     GUI and then send their choices to
     USERD_set_extra_gui_data
  
     Therefore if USERD_get_extra_gui_numbers
     exists then the other two must exist.
 
     If none exist, then the GUI will be unchanged.
 
     Toggle data will return an integer
                               TRUE if checked
                               FALSE if unchecked
 
     Pulldown menu will return an integer representing
                               the menu item selected
 
     Field will return a string Z_LEN_GUI_FIELD_STR long.
 
     If all the enhanced GUI features are enabled it
     might look something like this

    ===================================================
    [] Title 1  [X] Title 3
    [X]Title 2  [X] Title 4
 
    Pulldown Menu ->
        Menu Choice 1
        Menu Choice 2
        Menu Choice 3
 
    Data Field Title 1 ____________________________
 
    Data Field Title 2 ____________________________
    =====================================================

    This routine defines the numbers of toggles, pulldowns & fields
 
    The following are defined in the global_extern.h
           Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
           Z_LEN_GUI_PULL_STR  max length of GUI pulldown string
           Z_LEN_GUI_FIELD_STR  max length of field string
           Z_LEN_GUI_TITLE_STR   max length of title string
 
    The library is loaded, this routine is
     called, then the library is unloaded.
 
    Do not define globals in this routine
     as when the library is unloaded, you'll
     lose them.
 

--------------------------------------------------------------------
USERD_get_extra_gui_defaults

   Description:
   -----------
   This routine defines the Titles, status,
   List choices, strings, etc that are fed
   up to the GUI.

   Specification:
   -------------
   int USERD_get_extra_gui_defaults(char **toggle_Title,
                                    int *toggle_default_status,
                                    char **pulldown_Title,
                                    int *pulldown_number_in_list,
                                    int *pulldown_default_selection,
                                    char ***pulldown_item_strings,
                                    char **field_Title,
                                    char **field_user_string)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) toggle_Title               = title for each toggle
                                      array dimension is [num_toggles] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         toggle_default_status      = Setting for each toggle (TRUE or FALSE)
                                      array dimension is [num_toggles] long 

         pulldown_Title             = title for each pulldown
                                      array dimension is [num_pulldowns] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         pulldown_number_in_list    = number of items in each pulldown
                                      array dimension is [num_pulldowns] long 

         pulldown_default_selection = pulldown item selection for each pulldown
                                      array dimension is [num_pulldowns] long 

         pulldown_item_strings      = pulldown item strings
                                      array is [num_pulldowns] by
                                               [Z_MAX_NUM_GUI_PULL_ITEMS] by
                                               [Z_LEN_GUI_PULL_STR] long

         field_Title                = title for each field
                                      array dimension is [num_fields] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         field_user_string          = content of the field
                                      array dimension is [num_fields] by
                                                         [Z_LEN_GUI_TITLE_STR] long



   Notes:
   -----
   * The library is loaded, this routine is called, then the library is unloaded.
 
   * Do not define globals in this routine as when the library is unloaded, you'll
     lose them.



--------------------------------------------------------------------
USERD_set_extra_gui_data

   Description:
   -----------
   This routine sets the new values for the toggles, pulldowns, and fields.

   Specification:
   -------------
   void USERD_set_extra_gui_data(
               int *toggle,       /* [num_toggle] */
               int *pulldown,     /* [num_pulldown] */
               char **field_text  /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)

   Returns:
   -------

   Arguments:
   ---------
   (IN) toggle               = setting for each toggle.  TRUE or FALSE
                               array dimension is [num_toggles] long

        pulldown             = item chosen in each pulldown. (0 based)
                               array dimension is [num_pulldowns] long

        field_text           = content of the field
                               array dimension is [num_fields] by
                                                  [Z_LEN_GUI_TITLE_STR] long


   Notes:
   -----
   * This routine is called when the library is permanently
     loaded to the EnSight session, so define your globals
     in this and later routines.
 
   * It's up to you to change your reader behavior according to
     user entries!



--------------------------------------------------------------------
USERD_get_var_extract_gui_numbers

   Description:
   -----------
   The Var_Extract_GUI routines are added to allow
   the user to customize a extraction parameters
   for variables "after" the file has been read.
   These things can be modified and the variables will
   be update/refreshed according to the new parameters set

   Specification:
   -------------
   void USERD_get_var_extract_gui_numbers(int *num_Toggles,
                                          int *num_pulldowns,
                                          int *num_fields)


   Returns:
   -------

   Arguments:
   ---------
   (OUT) num_Toggles    = number of toggles that will be provided
   
         num_pulldowns  = number of pulldowns that will be provided

         num_fields     = number of fields that will be provided

   Notes:
   -----
     There are three routines that work together:
     USERD_get_var_extract_gui_numbers
     USERD_get_var_extract_gui_defaults (this one)
     USERD_set_var_extract_gui_data

     The existence of these routine indicates that
     you wish to have the Var Extract Parameters dialog.

     If you don't want the extra GUI features,
     simply delete these routines, or change their
     names to something such as
     USERD_DISABLED_get_var_extract_gui_defaults
 
     The presence of these routines
     will ensure that EnSight will call them and
     use their data to modify the extraction parameters set
     with some or all of the following:
     toggles, pulldown menu and fields.
 
     The user can then interact with the enhanced
     GUI and then send their choices to
     USERD_set_extra_gui_data
  
     Therefore if USERD_get_var_extract_gui_numbers
     exists then the other two must exist.
 
     If none exist, then the GUI will be unchanged.
 
     Toggle data will return an integer
                               TRUE if checked
                               FALSE if unchecked
 
     Pulldown menu will return an integer representing
                               the menu item selected
 
     Field will return a string Z_LEN_GUI_FIELD_STR long.
 
     If all the enhanced GUI features are enabled it
     might look something like this

    ===================================================
    [] Title 1  [X] Title 3
    [X]Title 2  [X] Title 4
 
    Pulldown Menu ->
        Menu Choice 1
        Menu Choice 2
        Menu Choice 3
 
    Data Field Title 1 ____________________________
 
    Data Field Title 2 ____________________________
    =====================================================

    This routine defines the numbers of toggles, pulldowns & fields
 
    The following are defined in the global_extern.h
           Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
           Z_LEN_GUI_PULL_STR  max length of GUI pulldown string
           Z_LEN_GUI_FIELD_STR  max length of field string
           Z_LEN_GUI_TITLE_STR   max length of title string
 
    The library is loaded, this routine is
     called, then the library is unloaded.
 
    Do not define globals in this routine
     as when the library is unloaded, you'll
     lose them.
 

--------------------------------------------------------------------
USERD_get_var_extract_gui_defaults

   Description:
   -----------
   This routine defines the Titles, status,
   List choices, strings, etc that are fed
   up to the GUI.

   Specification:
   -------------
   int USERD_get_var_extract_gui_defaults(char **toggle_Title,
                                          int *toggle_default_status,
                                          char **pulldown_Title,
                                          int *pulldown_number_in_list,
                                          int *pulldown_default_selection,
                                          char ***pulldown_item_strings,
                                          char **field_Title,
                                          char **field_user_string)

   Returns:
   -------
   Z_OK  if successful
   Z_ERR if not successful

   Arguments:
   ---------
   (OUT) toggle_Title               = title for each toggle
                                      array dimension is [num_toggles] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         toggle_default_status      = Setting for each toggle (TRUE or FALSE)
                                      array dimension is [num_toggles] long 

         pulldown_Title             = title for each pulldown
                                      array dimension is [num_pulldowns] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         pulldown_number_in_list    = number of items in each pulldown
                                      array dimension is [num_pulldowns] long 

         pulldown_default_selection = pulldown item selection for each pulldown
                                      array dimension is [num_pulldowns] long 

         pulldown_item_strings      = pulldown item strings
                                      array is [num_pulldowns] by
                                               [Z_MAX_NUM_GUI_PULL_ITEMS] by
                                               [Z_LEN_GUI_PULL_STR] long

         field_Title                = title for each field
                                      array dimension is [num_fields] by
                                                         [Z_LEN_GUI_TITLE_STR] long

         field_user_string          = content of the field
                                      array dimension is [num_fields] by
                                                         [Z_LEN_GUI_TITLE_STR] long



   Notes:
   -----
   * The library is loaded, this routine is called, then the library is unloaded.
 
   * Do not define globals in this routine as when the library is unloaded, you'll
     lose them.



--------------------------------------------------------------------
USERD_set_var_extract_gui_data

   Description:
   -----------
   This routine sets the new values for the toggles, pulldowns, and fields.

   Specification:
   -------------
   void USERD_set_var_extract_gui_data(
               int *toggle,       /* [num_toggle] */
               int *pulldown,     /* [num_pulldown] */
               char **field_text  /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)

   Returns:
   -------

   Arguments:
   ---------
   (IN) toggle               = setting for each toggle.  TRUE or FALSE
                               array dimension is [num_toggles] long

        pulldown             = item chosen in each pulldown. (0 based)
                               array dimension is [num_pulldowns] long

        field_text           = content of the field
                               array dimension is [num_fields] by
                                                  [Z_LEN_GUI_TITLE_STR] long


   Notes:
   -----
   * This routine is called when the library is permanently
     loaded to the EnSight session, so define your globals
     in this and later routines.
 
   * It's up to you to change your reader behavior according to
     user entries!





-----------------------------------------------------------------------------------
/* ----------------------------------------------------------
 *  New in EnSight 8 is the capability to remove (fail) elements
 *   based on variable threshold values.  Basically the variable
 *   name, a couple of thresholds, a couple of values and a logic 
 *   criteria are read in from this routine.  Every element that
 *   satisfies the failure criteria is removed and not used in
 *   EnSight calculations.
 *   
 *  Example Failure criteria 
 *     Let fail_var_name = "fail_flag"
 *         threshold_val1 = 0
 *         threshold_operator1 = Z_EQUAL_TO  
 *         logic_criteria2 not used
 *         threshold_val2 not used
 *         threshold_operator2 not used
 *     For each value of "fail_flag" at each element, 
 *         if fail flag == threshold_val1 (0.0) then element fails
 *   Return (Z_ERR) if this is not used.
 *   Return (Z_OK) if failed element feature should be used
 *
 *  threshold_operator1 & 2 can be one of the following
 *    Z_ELE_FAILED_NONE,           - disables checking
 *     Z_ELE_FAILED_GREATER,        - greater than
 *     Z_ELE_FAILED_LESS,           - less than
 *     Z_ELE_FAILED_EQUAL,          - equal
 *     Z_ELE_FAILED_NOT_EQUAL,      - not equal
 *     Z_ELE_FAILED_MANY            - not used
 *
 * logic_criteria2
 *      Z_ELE_FAILED_LOGIC_NONE,
 *      Z_ELE_FAILED_LOGIC_AND,
 *      Z_ELE_FAILED_LOGIC_OR,
 *      Z_ELE_FAILED_LOGIC_MANY
 *
 * ---------------------------------------------------------- */
int USERD_get_uns_failed_params(
                char *fail_var_name,           /* variable name to be used in failure
                                             must be scalar, per elem      */
                float *threshold_val1,     /* number to compare for failure */
                float *threshold_val2,     /* number to compare for failure */
                int *threshold_operator1,   /* Z_GREATER_THAN, Z_LESS_THAN,
                                            Z_EQUAL_TO */
                int *threshold_operator2,   /* Z_GREATER_THAN, Z_LESS_THAN,
                                            Z_EQUAL_TO */
		int *logic_criteria2




---- end of document ----