Data File Utilities

Macros
#define	ex_create(path, mode, comp_ws, io_ws)    ex_create_int(path, mode, comp_ws, io_ws, EX_API_VERS_NODOT)
#define	ex_open(path, mode, comp_ws, io_ws, version)    ex_open_int(path, mode, comp_ws, io_ws, version, EX_API_VERS_NODOT)

Functions
int	ex_close (int exoid)
int	ex_copy (int in_exoid, int out_exoid)
int	ex_copy_transient (int in_exoid, int out_exoid)
int	ex_create_int (const char *rel_path, int cmode, int *comp_ws, int *io_ws, int run_version)
int	ex_open_int (const char *rel_path, int mode, int *comp_ws, int *io_ws, float *version, int run_version)
int	ex_get_group_id (int parent_id, const char *group_name, int *group_id)
int	ex_get_group_ids (int parent_id, int *num_groups, int *group_ids)
int	ex_get_info (int exoid, char **info)
int	ex_get_qa (int exoid, char *qa_record[][4])
int	ex_put_info (int exoid, int num_info, char *const info[])
int	ex_put_qa (int exoid, int num_qa_records, char *qa_record[][4])
int	ex_update (int exoid)
int	ex_get_num_props (int exoid, ex_entity_type obj_type)
int	ex_large_model (int exoid)
size_t	ex_header_size (int exoid)
void	ex_err (const char *module_name, const char *message, int err_num)
void	ex_err_fn (int exoid, const char *module_name, const char *message, int err_num)
void	ex_set_err (const char *module_name, const char *message, int err_num)
const char *	ex_strerror (int err_num)
void	ex_get_err (const char **msg, const char **func, int *err_num)
int	ex_opts (int options)
int	ex_inquire (int exoid, ex_inquiry req_info, void_int *ret_int, float *ret_float, char *ret_char)
int64_t	ex_inquire_int (int exoid, ex_inquiry req_info)
unsigned	ex_int64_status (int exoid)
int	ex_set_int64_status (int exoid, int mode)
void	ex_print_config (void)
const char *	ex_config (void)
int	ex_set_max_name_length (int exoid, int length)
int	ex_set_option (int exoid, ex_option_type option, int option_value)
int	ex_cvt_nodes_to_sides (int exoid, void_int *num_elem_per_set, void_int *num_nodes_per_set, void_int *side_sets_elem_index, void_int *side_sets_node_index, void_int *side_sets_elem_list, void_int *side_sets_node_list, void_int *side_sets_side_list)
nc_type	nc_flt_code (int exoid)
int	exi_comp_ws (int exoid)
int	exi_is_parallel (int exoid)
int	ex_set_parallel (int exoid, int is_parallel)
void	exi_reset_error_status (void)
int	exi_check_file_type (const char *path, int *type)
void	exi_update_max_name_length (int exoid, int length)
int	exi_get_cpu_ws (void)
void	exi_iqsort (int v[], int iv[], size_t N)

Variables
const char	exodus_unused_symbol_dummy_ex_create_par

Detailed Description

This section describes data file utility functions for creating opening a file, initializing a file with global parameters, reading writing information text, inquiring on parameters stored in the data file, and error reporting.

Macro Definition Documentation

ex_create

#define ex_create	(		path,
			mode,
			comp_ws,
			io_ws )    ex_create_int(path, mode, comp_ws, io_ws, EX_API_VERS_NODOT)

Examples

/test/CreateEdgeFace.c, /test/create_mesh.c, /test/rd_wt_mesh.c, /test/test-empty.c, /test/test_nemesis.c, /test/test_ts_files.c, /test/test_ts_nvar.c, /test/test_ts_partial_nvar.c, /test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, /test/testcpd.c, /test/testrd1.c, /test/testrdwt.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nfaced.c, /test/testwt-nsided.c, /test/testwt-one-attrib.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-results.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, /test/testwtd.c, /test/testwtm.c, and /test/twod.c.

ex_open

#define ex_open	(		path,
			mode,
			comp_ws,
			io_ws,
			version )    ex_open_int(path, mode, comp_ws, io_ws, version, EX_API_VERS_NODOT)

Examples

/test/ReadEdgeFace.c, /test/rd_wt_mesh.c, /test/test-empty.c, /test/test_nemesis.c, /test/test_ts_nvar_rd.c, /test/test_ts_partial_nvar_rd.c, /test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, /test/testcpd.c, /test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_ss.c, /test/testrdd.c, /test/testrdwt.c, and /test/testwt-one-attrib.c.

Function Documentation

ex_close()

int ex_close ( int exoid )

extern

The function ex_close() updates and then closes an open exodus file.

Returns

In case of an error, ex_close() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open()

Parameters

exoid

exodus file ID returned from a previous call to ex_create() or ex_open().

The following code segment closes an open exodus file:

int error,exoid;
error = ex_close (exoid);

Examples

/test/CreateEdgeFace.c, /test/ReadEdgeFace.c, /test/create_mesh.c, /test/rd_wt_mesh.c, /test/test-empty.c, /test/test_nemesis.c, /test/test_ts_files.c, /test/test_ts_nvar.c, /test/test_ts_nvar_rd.c, /test/test_ts_partial_nvar.c, /test/test_ts_partial_nvar_rd.c, /test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, /test/testcpd.c, /test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_par.c, /test/testrd_ss.c, /test/testrdd.c, /test/testrdwt.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nfaced.c, /test/testwt-nsided.c, /test/testwt-one-attrib.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-results.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, /test/testwtd.c, /test/testwtm.c, and /test/twod.c.

ex_config()

const char * ex_config ( void )

extern

Undocumented

ex_copy()

int ex_copy ( int in_exoid, int out_exoid )

extern

Undocumented

efficiently copies all non-transient information (attributes, dimensions, and variables from an opened EXODUS file to another opened EXODUS file. Will not overwrite a dimension or variable already defined in the new file.

Parameters

in_exoid	exodus file id for input file
out_exoid	exodus file id for output file

Examples

/test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, and /test/testcpd.c.

ex_copy_transient()

int ex_copy_transient ( int in_exoid, int out_exoid )

extern

Undocumented

efficiently copies all non-transient and transient information (attributes, dimensions, and variables from an opened EXODUS file to another opened EXODUS file. Will not overwrite a dimension or variable already defined in the new file.

Parameters

in_exoid	exodus file id for input file
out_exoid	exodus file id for output file

Examples

/test/testcp_tran.c.

ex_create_int()

int ex_create_int ( const char * path, int cmode, int * comp_ws, int * io_ws, int run_version )

extern

Note

The ex_create_int() is an internal function called by ex_create(). The user should call ex_create() and not ex_create_int().

The function ex_create() creates a new exodus file and returns an ID that can subsequently be used to refer to the file.

All floating point values in an exodus file are stored as either 4-byte (float) or 8-byte (double) numbers; no mixing of 4- and 8-byte numbers in a single file is allowed. An application code can compute either 4- or 8-byte values and can designate that the values be stored in the exodus file as either 4- or 8-byte numbers; conversion between the 4- and 8-byte values is performed automatically by the API routines. Thus, there are four possible combinations of compute word size and storage (or I/O) word size.

Returns

In case of an error, ex_create() returns a negative number. Possible causes of errors include:

• Passing a file name that includes a directory that does not exist.
• Specifying a file name of a file that exists and also specifying a no clobber option.
• Attempting to create a file in a directory without permission to create files there.
• Passing an invalid file clobber mode.

Parameters

	path	The file name of the new exodus file. This can be given as either an absolute path name (from the root of the file system) or a relative path name (from the current directory).
	cmode	Mode. Use one of the following predefined constants: EX_NOCLOBBER To create the new file only if the given file name does not refer to a file that already exists. EX_CLOBBER To create the new file, regardless of whether a file with the same name already exists. If a file with the same name does exist, its contents will be erased. EX_64BIT_OFFSET To create a model that can store individual datasets larger than 2 gigabytes. This modifies the internal storage used by exodusII and also puts the underlying NetCDF file into the 64-bit offset' mode. See largemodel for more details on this mode. A large model file will also be created if the environment variable EXODUS_LARGE_MODEL is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_LARGE_MODEL is alias. EX_NORMAL_MODEL Create a standard model. EX_64BIT_DATA To create a model using the CDF5 format which uses the classic model but has 64-bit dimensions and sizes. This type will also be created if the environment variable EXODUS_NETCDF5 is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_NETCDF4 To create a model using the HDF5-based NetCDF-4 output. An HDF5-based NetCDF-4 file will also be created if the environment variable EXODUS_NETCDF4 is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_NOSHARE Do not open the underlying NetCDF file in share mode. See the NetCDF documentation for more details. EX_SHARE Do open the underlying NetCDF file in share mode. See the NetCDF documentation for more details.
[in,out]	comp_ws	The word size in bytes (0, 4 or 8) of the floating point variables used in the application program. If 0 (zero) is passed, the default sizeof(float) will be used and returned in this variable. WARNING: all exodus functions requiring floats must be passed floats declared with this passed in or returned compute word size (4 or 8).}
	io_ws	The word size in bytes (4 or 8) of the floating point data as they are to be stored in the exodus file.
	run_version	(internally generated) used to verify compatibility of library and include files.

The following code segment creates an exodus file called test.exo:

#include "exodusII.h"
int CPU_word_size, IO_word_size, exoid;
CPU_word_size = sizeof(float);      \comment{use float or double}
IO_word_size = 8;                   \comment{store variables as doubles}
 
\comment{create exodus file}
exoid = ex_create ("test.exo"       \comment{filename path}
                    EX_CLOBBER,     \comment{create mode}
                    &CPU_word_size, \comment{CPU float word size in bytes}
                    &IO_word_size); \comment{I/O float word size in bytes}

ex_cvt_nodes_to_sides()

int ex_cvt_nodes_to_sides ( int exoid, void_int * num_elem_per_set, void_int * num_nodes_per_set, void_int * side_sets_elem_index, void_int * side_sets_node_index, void_int * side_sets_elem_list, void_int * side_sets_node_list, void_int * side_sets_side_list )

extern

The function ex_cvt_nodes_to_sides() is used to convert a side set node list to a side set side list. This routine is provided for application programs that utilize side sets defined by nodes (as was done previous to release 2.0) rather than local faces or edges. The application program must allocate memory for the returned array of sides. The length of this array is the same as the length of the concatenated side sets element list, which can be determined with a call to ex_inquire() or ex_inquire_int().

Returns

In case of an error, ex_cvt_nodes_to_sides() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• a warning value is returned if no side sets are stored in the file.
• because the faces of a wedge require a different number of nodes to describe them (quadrilateral vs. triangular faces), the function will abort with a fatal return code if a wedge is encountered in the side set element list.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	num_elem_per_set	Array containing the number of sides for each set. The number of sides is equal to the number of elements for each set.
[in]	num_nodes_per_set	Array containing the number of nodes for each set.
[in]	side_sets_elem_index	Array containing indices into the side_sets_elem_list which are the locations of the first element for each set. These indices are 0-based. Unused.
[in]	side_sets_node_index	Array containing indices into the side_sets_node_list which are the locations of the first node for each set. These indices are 0-based. Unused.
[in]	side_sets_elem_list	Array containing the elements for all side sets. Internal element IDs are used in this list (see Section LocalElementIds).
[in]	side_sets_node_list	Array containing the nodes for all side sets. Internal node IDs are used in this list (see Section LocalNodeIds).
[out]	side_sets_side_list	Returned array containing the sides for all side sets.

The following code segment will convert side sets described by nodes to side sets described by local side numbers:

int error, exoid, ids[2], num_side_per_set[2],
    num_nodes_per_set[2], elem_ind[2], node_ind[2],
    elem_list[4], node_list[8], el_lst_len, *side_list;
 
ids[0] = 30             ; ids[1]  = 31;
num_side_per_set[0]  = 2; num_side_per_set[1] = 2;
num_nodes_per_set[0] = 4; num_nodes_per_set[1] = 4;
 
elem_ind[0] = 0; elem_ind[1] = 2;
node_ind[0] = 0; node_ind[1] = 4;
 
\comment{side set #1}
elem_list[0] = 2; elem_list[1] = 2;
node_list[0] = 8; node_list[1] = 5;
node_list[2] = 6; node_list[3] = 7;
 
\comment{side set #2}
elem_list[2] = 1; elem_list[3] = 2;
node_list[4] = 2; node_list[5] = 3;
node_list[6] = 7; node_list[7] = 8;
 
el_lst_len = ex_inquire_int(exoid, EX_INQ_SS_ELEM_LEN);
 
\comment{side set element list is same length as side list}
side_list = (int *) calloc (el_lst_len, sizeof(int));
 
ex_cvt_nodes_to_sides(exoid, num_side_per_set, num_nodes_per_set,
                      elem_ind, node_ind, elem_list,
                      node_list, side_list);

Algorithm:

  Read elem_block_ids --> elem_blk_id[array]

  Read element block parameters --> elem_blk_parms[array]

  Determine total number of elements in side set by summing num_elem_per_set

  Build side set element to side set node list index --> ss_elem_node_ndx[array]

  For each element in the side_set_elem_list  {
    If Jth element is not in current element block (e.g. J>elem_ctr) {
      get element block parameters (num_elem_in_blk, ...)
      elem_ctr += num_elem_in_blk

      free old connectity array space
      allocate connectivity array: size=num_elem_in_blk*num_nodes_per_elem
      get connectivity array
    }

    If Jth element is in current element block (e.g. J<=elem_ctr) {
      For each node in element (linear search of up to num_nodes_per_elem) {
        If side set element node[1] == element node[i] {
          Case element type = Hex {
            If side set element node[2] == element node[Hex_table[i,1]]
              Jth side = Hex_table[i,2]

             break
          }
          Case element type = Wedge {
            If side set element node[2] == element node[Wedge_table[i,1]]
              Jth side = Wedge_table[i,2]

            break
          }
        }
      }
    }
  }

Examples

/test/testwt1.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, and /test/testwtm.c.

ex_err()

void ex_err ( const char * module_name, const char * message, int err_num )

extern

The function ex_err(exoid, ...) logs an error to stderr. It is intended to provide explanatory messages for error codes returned from other exodus routines.

The passed in error codes and corresponding messages are listed in exodusII.h. The programmer may supplement the error message printed for standard errors by providing an error message. If the error code is provided with no error message, the predefined message will be used. The error code EX_MSG is available to log application specific messages.

Parameters

[in]	module_name	This is a string containing the name of the calling function.
[in]	message	This is a string containing a message explaining the error or problem. If EX_VERBOSE (see ex_opts()) is true, this message will be printed to stderr. Otherwise, nothing will be printed. Maximum length is MAX_ERR_LENGTH.
[in]	err_num	This is an integer code identifying the error. exodus C functions place an error code value in exerrval, an external integer. Negative values are considered fatal errors while positive values are warnings. There is a set of predefined values defined in exodusII.h. The predefined constant EX_PRTLASTMSG will cause the last error message to be output, regardless of the setting of the error reporting level (see ex_opts()).

The following is an example of the use of this function:

int exoid, CPU_word_size, IO_word_size, errval;
float version;
char errmsg[MAX_ERR_LENGTH];
 
CPU_word_size = sizeof(float);
IO_word_size = 0;
 
\comment{open exodus file}
if (exoid = ex_open ("test.exo", EX_READ, &CPU_word_size,
                     &IO_word_size, &version)) {
   errval = 999;
   snprintf(errmsg, MAX_ERR_LENGTH,"ERROR: cannot open file test.exo");
   ex_err(__func__, errmsg, errval);
}

Examples

/test/test_ts_errval.c.

ex_err_fn()

void ex_err_fn ( int exoid, const char * module_name, const char * message, int err_num )

extern

The function ex_err_fn() logs an error to stderr. It is intended to provide explanatory messages for error codes returned from other exodus routines. The main difference between ex_err_fn() and ex_err() is that ex_err_fn() will print the name of the exodus file that the error occurred on.

The passed in error codes and corresponding messages are listed in exodusII.h. The programmer may supplement the error message printed for standard errors by providing an error message. If the error code is provided with no error message, the predefined message will be used. The error code EX_MSG is available to log application specific messages.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	module_name	This is a string containing the name of the calling function.
[in]	message	This is a string containing a message explaining the error or problem. If EX_VERBOSE (see ex_opts()) is true, this message will be printed to stderr. Otherwise, nothing will be printed. Maximum length is MAX_ERR_LENGTH.
[in]	err_num	This is an integer code identifying the error. exodus C functions place an error code value in exerrval, an external integer. Negative values are considered fatal errors while positive values are warnings. There is a set of predefined values defined in exodusII.h. The predefined constant EX_PRTLASTMSG will cause the last error message to be output, regardless of the setting of the error reporting level (see ex_opts()).

The following is an example of the use of this function:

int exoid, CPU_word_size, IO_word_size, errval;
float version;
char errmsg[MAX_ERR_LENGTH];
 
CPU_word_size = sizeof(float);
IO_word_size = 0;
 
\comment{open exodus file}
if (exoid = ex_open ("test.exo", EX_READ, &CPU_word_size,
                     &IO_word_size, &version)) {
   errval = 999;
   snprintf(errmsg, MAX_ERR_LENGTH,"ERROR: cannot open file test.exo");
   ex_err_fn(exoid, __func__, errmsg, errval);
}

ex_get_err()

void ex_get_err ( const char ** msg, const char ** func, int * err_num )

extern

Undocumented

Examples

/test/test_ts_errval.c.

ex_get_group_id()

int ex_get_group_id ( int parent_id, const char * group_name, int * group_id )

extern

Given an exoid and group name (NULL gets root group), return id of that group. If the name is NULL, return the root group. If the name contains "/", then the name is assumed to be a full path name and all groups in the file are searched. Otherwise, the name is assumed to be the name of a child group of exoid

ex_get_group_ids()

int ex_get_group_ids ( int parent_id, int * num_groups, int * group_ids )

extern

Given a file or group 'parent' id, return the number of child groups and the ids of the child groups below the parent. If num_groups is NULL, do not return count; if group_ids is NULL, do not return ids.

ex_get_info()

int ex_get_info ( int exoid, char ** info )

extern

The function ex_get_info() reads information records from the database. The records are MAX_LINE_LENGTH character strings. Memory must be allocated for the information records before this call is made. The number of records can be determined by invoking ex_inquire() or ex_inquire_int().

Returns

In case of an error, ex_get_info() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open()
• a warning value is returned if no information records were stored.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[out]	info	Returned array containing the information records.

The following code segment will determine the number of information records and read them from an open exodus file :

int error, exoid, num_info;
char *info[MAXINFO];
 
\comment{read information records}
num_info = ex_inquire_int (exoid,EX_INQ_INFO);
for (i=0; i < num_info; i++) {
   info[i] = (char *) calloc ((EX_MAX_LINE_LENGTH+1), sizeof(char));
}
error = ex_get_info (exoid, info);

Examples

/test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_par.c, /test/testrdd.c, and /test/testrdwt.c.

ex_get_num_props()

int ex_get_num_props ( int exoid, ex_entity_type obj_type )

extern

Undocumented

ex_get_qa()

int ex_get_qa ( int exoid, char * qa_record[][4] )

extern

The function ex_get_qa() reads the QA records from the database. Each QA record contains four MAX_STR_LENGTH byte character strings. The character strings are:

• the analysis code name
• the analysis code QA descriptor
• the analysis date
• the analysis time

Memory must be allocated for the QA records before this call is made. The number of QA records can be determined by invoking ex_inquire().

Returns

In case of an error, ex_get_qa() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open()
• a warning value is returned if no QA records were stored.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[out]	qa_record	Returned array containing the QA records.

The following will determine the number of QA records and read them from the open exodus file:

int num_qa_rec, error, exoid
char *qa_record[MAX_QA_REC][4];
 
\comment{read QA records}
num_qa_rec = ex_inquire_int(exoid, EX_INQ_QA);
 
for (i=0; i<num_qa_rec; i++) {
    for (j=0; j<4; j++)
    qa_record[i][j] = (char *) calloc ((MAX_STR_LENGTH+1), sizeof(char));
}
error = ex_get_qa (exoid, qa_record);

Examples

/test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_par.c, /test/testrdd.c, and /test/testrdwt.c.

ex_header_size()

size_t ex_header_size ( int exoid )

extern

Deprecated

ex_inquire()

int ex_inquire ( int exoid, ex_inquiry req_info, void_int * ret_int, float * ret_float, char * ret_char )

extern

The function ex_inquire() is used to inquire values of certain data entities in an exodus file. Memory must be allocated for the returned values before this function is invoked.query database.

See also

ex_inquire_int(), ex_inquiry.

Returns

In case of an error, ex_inquire() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open().
• requested information not stored in the file.
• invalid request flag.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	req_info	A flag of type ex_inquiry which designates what information is requested. It must be one of the following constants in the table below.
[out]	ret_int	Returned integer, if an integer value is requested (according to req_info); otherwise, supply a dummy argument.
[out]	ret_float	Returned float, if a float value is requested (according to req_info); otherwise, supply a dummy argument. This argument is always a float even if the database IO and/or CPU word size is a double.
[out]	ret_char	Returned character string, if a character value is requested (according to req_info); otherwise, supply a dummy argument.

As an example, the following will return the number of element block properties stored in the exodus file :

#include "exodusII.h"
int error, exoid, num_props;
float fdum;
char *cdum;
 
\comment{determine the number of element block properties}
error = ex_inquire (exoid, EX_INQ_EB_PROP, &num_props,
                    &fdum, cdum);
 
\comment{...Another way to get the same information}
num_props = ex_inquire_int(exoid, EX_INQ_EB_PROP);

Examples

/test/ReadEdgeFace.c, /test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, /test/testcpd.c, /test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_par.c, /test/testrd_ss.c, and /test/testrdd.c.

ex_inquire_int()

int64_t ex_inquire_int ( int exoid, ex_inquiry req_info )

extern

A variant of ex_inquire() which queries integer-valued information only.

See also

ex_inquire().

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	req_info	A flag of type ex_inquiry which designates what information is requested. (See ex_inquire() documentation)

Returns

result of inquiry.

As an example, the following will return the number of nodes, elements, and element blocks stored in the exodus file :

#include "exodusII.h"
int exoid;
int num_nodes = ex_inquire_int(exoid, EX_INQ_NODES);
int num_elems = ex_inquire_int(exoid, EX_INQ_ELEM);
int num_block = ex_inquire_int(exoid, EX_INQ_ELEM_BLK);

Examples

/test/ReadEdgeFace.c, /test/rd_wt_mesh.c, /test/test_ts_nvar.c, /test/test_ts_nvar_rd.c, /test/test_ts_partial_nvar.c, /test/test_ts_partial_nvar_rd.c, /test/testrd-long-name.c, /test/testrd.c, /test/testrd_ss.c, /test/testrdwt.c, and /test/testwt-one-attrib.c.

ex_int64_status()

unsigned ex_int64_status ( int exoid )

extern

ex_int64_status() returns an int that can be tested against the defines listed below to determine which, if any, 'types' in the database are to be stored as int64 types and which, if any, types are passed/returned as int64 types in the API

Defines:
EX_MAPS_INT64_DB	All maps (id, order, ...) store int64_t values
EX_IDS_INT64_DB	All entity ids (sets, blocks, maps) are int64_t values
EX_BULK_INT64_DB	All integer bulk data (local indices, counts, maps); not ids
EX_ALL_INT64_DB	(EX_MAPS_INT64_DB | EX_IDS_INT64_DB | EX_BULK_INT64_DB)
EX_MAPS_INT64_API	All maps (id, order, ...) passed as int64_t values
EX_IDS_INT64_API	All entity ids (sets, blocks, maps) are passed as int64_t values
EX_BULK_INT64_API	All integer bulk data (local indices, counts, maps); not ids
EX_INQ_INT64_API	Integers passed to/from ex_inquire() are int64_t
EX_ALL_INT64_API	(EX_MAPS_INT64_API | EX_IDS_INT64_API | EX_BULK_INT64_API |

EX_INQ_INT64_API) |

ex_large_model()

int ex_large_model ( int exoid )

extern

Determine whether the new large model storage is being used in this file, or old method. Basically, the difference is whether the coordinates and nodal variables are stored in a blob (xyz components together) or as a variable per component per nodal_variable.

ex_open_int()

int ex_open_int ( const char * path, int mode, int * comp_ws, int * io_ws, float * version, int run_version )

extern

Note

The ex_open_int() is an internal function called by ex_open(). The user should call ex_open() and not ex_open_int().

The function ex_open() opens an existing exodus file and returns an ID that can subsequently be used to refer to the file, the word size of the floating point values stored in the file, and the version of the exodus database (returned as a float'', regardless of the compute or I/O word size). Multiple files may beopen'' simultaneously.

Returns

In case of an error, ex_open() returns a negative number. Possible causes of errors include:

• The specified file does not exist.
• The mode specified is something other than the predefined constant EX_READ or EX_WRITE.
• Database version is earlier than 2.0.

Parameters

	path	The file name of the exodus file. This can be given as either an absolute path name (from the root of the file system) or a relative path name (from the current directory).
	mode	Access mode. Use one of the following predefined constants: EX_READ To open the file just for reading. EX_WRITE To open the file for writing and reading.
[in,out]	comp_ws	The word size in bytes (0, 4 or 8) of the floating point variables used in the application program. If 0 (zero) is passed, the default size of floating point values for the machine will be used and returned in this variable. WARNING: all exodus functions requiring reals must be passed reals declared with this passed in or returned compute word size (4 or 8).
[in,out]	io_ws	The word size in bytes (0, 4 or 8) of the floating point data as they are stored in the exodus file. If the word size does not match the word size of data stored in the file, a fatal error is returned. If this argument is 0, the word size of the floating point data already stored in the file is returned.
[out]	version	Returned exodus database version number. Note that this is always a float, never a double.
[in]	run_version	Internally generated to verify library compatibility.

The following opens an exodus file named test.exo for read only, using default settings for compute and I/O word sizes:

int CPU_word_size,IO_word_size, exoid;
float version;
 
CPU_word_size = sizeof(float);   \co{float or double}
IO_word_size = 0;                \co{use what is stored in file}
 
\comment{open exodus files}
exoid = ex_open ("test.exo",     \co{filename path}
                 EX_READ,        \co{access mode = READ}
                 &CPU_word_size, \co{CPU word size}
                 &IO_word_size,  \co{IO word size}
                 &version);      \co{ExodusII library version}

ex_opts()

int ex_opts ( int options )

extern

The function ex_opts() is used to set message reporting options.

Returns

Returns previous value for the message reporting option.

Parameters

[in]

options

Integer option value. Current options are shown in the table below.

EX_ABORT	Causes fatal errors to force program exit. (Default is false.)
EX_DEBUG	Causes certain messages to print for debug use. (Default is false.)
EX_VERBOSE	Causes all error messages to print when true, otherwise no error messages will print. (Default is false.)

Note

Values may be OR'ed together to provide any combination of these capabilities.

For example, the following will cause all messages to print and will cause the program to exit upon receipt of fatal error:

#include "exodusII.h"
ex_opts(EX_ABORT|EX_VERBOSE);

Examples

/test/CreateEdgeFace.c, /test/create_mesh.c, /test/rd_wt_mesh.c, /test/test-empty.c, /test/test_ts_files.c, /test/test_ts_nvar_rd.c, /test/test_ts_partial_nvar.c, /test/test_ts_partial_nvar_rd.c, /test/testcp.c, /test/testcp_nl.c, /test/testcp_tran.c, /test/testcpd.c, /test/testrd-long-name.c, /test/testrd-nfaced.c, /test/testrd-nsided.c, /test/testrd.c, /test/testrd1.c, /test/testrd_nc.c, /test/testrd_par.c, /test/testrd_ss.c, /test/testrdd.c, /test/testrdwt.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nfaced.c, /test/testwt-nsided.c, /test/testwt-one-attrib.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-results.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, /test/testwtd.c, /test/testwtm.c, and /test/twod.c.

ex_print_config()

void ex_print_config ( void )

extern

ex_put_info()

int ex_put_info ( int exoid, int num_info, char *const info[] )

extern

The function ex_put_info() writes information records to the database. The records are MAX_LINE_LENGTH character strings.

In case of an error, ex_put_info() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open()
• data file opened for read only.
• information records already exist in file.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	num_info	The number of information records.
[in]	info	Array containing the information records. To only define the number of info records instead of defining and outputting, pass NULL for info argument.

The following code will write out three information records to an open exodus file -

int error, exoid, num_info;
char *info[3];
 
\comment{write information records}
num_info = 3;
 
info[0] = "This is the first information record.";
info[1] = "This is the second information record.";
info[2] = "This is the third information record.";
 
error = ex_put_info(exoid, num_info, info);

The following code will first tell the database that there are three information records, and then later actually output those records.

int error, exoid, num_info;
char *info[3];
 
\comment{Define the number of information records that will be written
later.}
num_info = 3;
 
error = ex_put_info(exoid, num_info, NULL);
 
\comment{Now, actually write the information records}
info[0] = "This is the first information record.";
info[1] = "This is the second information record.";
info[2] = "This is the third information record.";
error = ex_put_info(exoid, num_info, info);

Examples

/test/test_ts_files.c, /test/testrdwt.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nfaced.c, /test/testwt-nsided.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, /test/testwtd.c, and /test/testwtm.c.

ex_put_qa()

int ex_put_qa ( int exoid, int num_qa_records, char * qa_record[][4] )

extern

The function ex_put_qa() writes the QA records to the database. Each QA record contains four MAX_STR_LENGTH byte character strings. The character strings are:

• the analysis code name
• the analysis code QA descriptor
• the analysis date
• the analysis time

Returns

In case of an error, ex_put_qa() returns a negative number; a warning will return a positive number. Possible causes of errors include:

• data file not properly opened with call to ex_create() or ex_open()
• data file opened for read only.
• QA records already exist in file.

Parameters

[in]	exoid	exodus file ID returned from a previous call to ex_create() or ex_open().
[in]	num_qa_records	The number of QA records.
[in]	qa_record	Array containing the QA records. To only define the number of qa records instead of defining and outputting, pass NULL for qa_record argument.

The following code segment will write out two QA records:

int num_qa_rec, error, exoid;
char *qa_record[2][4];
 
\comment{write QA records}
num_qa_rec = 2;
 
qa_record[0][0] = "TESTWT1";
qa_record[0][1] = "testwt1";
qa_record[0][2] = "07/07/93";
qa_record[0][3] = "15:41:33";
qa_record[1][0] = "FASTQ";
qa_record[1][1] = "fastq";
qa_record[1][2] = "07/07/93";
qa_record[1][3] = "16:41:33";
 
error = ex_put_qa (exoid, num_qa_rec, qa_record);

Examples

/test/test_ts_files.c, /test/testrdwt.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nfaced.c, /test/testwt-nsided.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwt_ss.c, /test/testwtd.c, and /test/testwtm.c.

ex_set_err()

void ex_set_err ( const char * module_name, const char * message, int err_num )

extern

Undocumented

ex_set_int64_status()

int ex_set_int64_status ( int exoid, int mode )

extern

ex_set_int64_status() sets the value of the INT64_API flags which specify how integer types are passed/returned as int64 types in the API

Mode can be one of:
0	All integers are passed as int32_t values.
EX_MAPS_INT64_API	All maps (id, order, ...) passed as int64_t values
EX_IDS_INT64_API	All entity ids (sets, blocks, maps) are passed as int64_t values
EX_BULK_INT64_API	All integer bulk data (local indices, counts, maps); not ids
EX_INQ_INT64_API	Integers passed to/from ex_inquire() are int64_t
EX_ALL_INT64_API	(EX_MAPS_INT64_API | EX_IDS_INT64_API | EX_BULK_INT64_API |

EX_INQ_INT64_API) |

ex_set_max_name_length()

int ex_set_max_name_length ( int exoid, int length )

extern

Undocumented

Examples

/test/testrd-long-name.c, and /test/testwt-oned.c.

ex_set_option()

int ex_set_option ( int exoid, ex_option_type option, int option_value )

extern

Undocumented

Examples

/test/create_mesh.c, /test/testwt-compress.c, and /test/testwt-long-name.c.

ex_set_parallel()

int ex_set_parallel	(	int	exoid,
		int	is_parallel )

Note

Do not use this unless you know what you are doing and why you are doing it. One use is if calling ex_get_partial_set() in a serial mode (proc 0 only) on a file opened in parallel. Make sure to reset the value to original value after done with special case...

ex_set_parallel() sets the parallel setting for a file. returns 1 (true) or 0 (false) depending on the current setting.

Parameters

exoid	integer which uniquely identifies the file of interest.
is_parallel	1 if parallel, 0 if serial.

ex_strerror()

const char * ex_strerror ( int err_num )

extern

Undocumented

Returns a pointer to a string which gives a text description of the error code err_num. If the error code refers to a NetCDF error, then that string is returned.

std::ostringstream errmsg;
\comment{Create errmsg here so that the exerrval doesn't get cleared by}
\comment{the ex_close call.}
int status;
ex_get_err(nullptr, nullptr, &status);
fmt::print(errmsg, "Exodus error ({}) {} at line {} of file '{}' in function '{}'.", status,
           ex_strerror(status), lineno, filename, function);

ex_update()

int ex_update ( int exoid )

extern

updates an opened EXODUS file (or EXODUS history file)

Parameters

exoid

exodus file id

Examples

/test/test_ts_files.c, /test/testwt-compress.c, /test/testwt-groups.c, /test/testwt-long-name.c, /test/testwt-nface-nside.c, /test/testwt-nsided.c, /test/testwt-oned.c, /test/testwt-partial.c, /test/testwt-results.c, /test/testwt-zeroe.c, /test/testwt-zeron.c, /test/testwt.c, /test/testwt1.c, /test/testwt2.c, /test/testwt_clb.c, /test/testwt_nc.c, /test/testwt_nossnsdf.c, /test/testwtd.c, and /test/testwtm.c.

exi_check_file_type()

int exi_check_file_type	(	const char *	path,
		int *	type )

Undocumented

exi_comp_ws()

int exi_comp_ws

(

int

exoid

)

exi_comp_ws() returns 4 (i.e. sizeof(float)) or 8 (i.e. sizeof(double)), depending on the value of floating point word size used to initialize the conversion facility for this file id (exoid).

Parameters

exoid

integer which uniquely identifies the file of interest.

exi_get_cpu_ws()

int exi_get_cpu_ws

(

void

)

Undocumented

exi_iqsort()

void exi_iqsort	(	int	v[],
		int	iv[],
		size_t	N )

The following 'indexed qsort' routine is modified from Sedgewicks algorithm It selects the pivot based on the median of the left, right, and center values to try to avoid degenerate cases occurring when a single value is chosen. It performs a quicksort on intervals down to the EX_QSORT_CUTOFF size and then performs a final insertion sort on the almost sorted final array. Based on data in Sedgewick, the EX_QSORT_CUTOFF value should be between 5 and 20.

See Sedgewick for further details Define DEBUG_QSORT at the top of this file and recompile to compile in code that verifies that the array is sorted.

NOTE: The 'int' implementation below assumes that both the items being sorted and the number of items being sorted are both representable as 'int'.

exi_is_parallel()

int exi_is_parallel

(

int

exoid

)

exi_is_parallel() returns 1 (true) or 0 (false) depending on whether the file was opened in parallel or serial/file-per-processor mode. Note that in this case parallel assumes the output of a single file, not a parallel run using file-per-processor.

Parameters

exoid

integer which uniquely identifies the file of interest.

exi_reset_error_status()

void exi_reset_error_status

(

void

)

Undocumented

exi_update_max_name_length()

void exi_update_max_name_length	(	int	exoid,
		int	length )

Undocumented

nc_flt_code()

nc_type nc_flt_code

(

int

exoid

)

nc_flt_code() returns either NC_FLOAT or NC_DOUBLE, based on the parameters with which exi_conv_init() was called. nc_flt_code() is used as the nc_type parameter on ncvardef() calls that define floating point variables.

"exoid" is some integer which uniquely identifies the file of interest.

Variable Documentation

exodus_unused_symbol_dummy_ex_create_par

const char exodus_unused_symbol_dummy_ex_create_par

extern

Note

The ex_create_par_int() is an internal function called by ex_create_par(). The user should call ex_create_par() and not ex_create_par_int().

The function ex_create() creates a new exodus file and returns an ID that can subsequently be used to refer to the file.

All floating point values in an exodus file are stored as either 4-byte (float) or 8-byte (double) numbers; no mixing of 4- and 8-byte numbers in a single file is allowed. An application code can compute either 4- or 8-byte values and can designate that the values be stored in the exodus file as either 4- or 8-byte numbers; conversion between the 4- and 8-byte values is performed automatically by the API routines. Thus, there are four possible combinations of compute word size and storage (or I/O) word size.

Returns

In case of an error, ex_create() returns a negative number. Possible causes of errors include:

• Passing a file name that includes a directory that does not exist.
• Specifying a file name of a file that exists and also specifying a no clobber option.
• Attempting to create a file in a directory without permission to create files there.
• Passing an invalid file clobber mode.

Parameters

	path	The file name of the new exodus file. This can be given as either an absolute path name (from the root of the file system) or a relative path name (from the current directory).
	cmode	Mode. Use one of the following predefined constants: EX_NOCLOBBER To create the new file only if the given file name does not refer to a file that already exists. EX_CLOBBER To create the new file, regardless of whether a file with the same name already exists. If a file with the same name does exist, its contents will be erased. EX_64BIT_OFFSET To create a model that can store individual datasets larger than 2 gigabytes. This modifies the internal storage used by exodusII and also puts the underlying NetCDF file into the 64-bit offset' mode. See largemodel for more details on this mode. A large model file will also be created if the environment variable EXODUS_LARGE_MODEL is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_LARGE_MODEL is alias. EX_NORMAL_MODEL Create a standard model. EX_64BIT_DATA To create a model using the CDF5 format which uses the classic model but has 64-bit dimensions and sizes. This type will also be created if the environment variable EXODUS_NETCDF5 is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_NETCDF4 To create a model using the HDF5-based NetCDF-4 output. An HDF5-based NetCDF-4 file will also be created if the environment variable EXODUS_NETCDF4 is defined in the users environment. A message will be printed to standard output if this environment variable is found. EX_NOSHARE Do not open the underlying NetCDF file in share mode. See the NetCDF documentation for more details. EX_SHARE Do open the underlying NetCDF file in share mode. See the NetCDF documentation for more details.
[in,out]	comp_ws	The word size in bytes (0, 4 or 8) of the floating point variables used in the application program. If 0 (zero) is passed, the default sizeof(float) will be used and returned in this variable. WARNING: all exodus functions requiring floats must be passed floats declared with this passed in or returned compute word size (4 or 8).}
	io_ws	The word size in bytes (4 or 8) of the floating point data as they are to be stored in the exodus file.
	run_version	(internally generated) used to verify compatibility of library and include files.

The following code segment creates an exodus file called test.exo:

#include "exodusII.h"
int CPU_word_size, IO_word_size, exoid;
CPU_word_size = sizeof(float);      \comment{use float or double}
IO_word_size = 8;                   \comment{store variables as doubles}
 
\comment{create exodus file}
exoid = ex_create ("test.exo"       \comment{filename path}
                    EX_CLOBBER,     \comment{create mode}
                    &CPU_word_size, \comment{CPU float word size in bytes}
                    &IO_word_size); \comment{I/O float word size in bytes}