Data Register Query Functions

PCL Reference Manual > Results Postprocessing Functions > Data Register Query Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

These functions are used to query the data registers for information.


res_data_next	(location, register_type)


Description:
This function returns the next available unused register identifier of the specified location and type.
Input:
STRING	location[]	This value specifies the model entity with which the results data is associated. Valid values are: "C" = centroid, "N" = nodal, "EN" = element nodal, and "EL" = element.
STRING	register_type[]	This value specifies the register type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
Output:
INTEGER	<Return Value>	The return value is the next available unused register identifier.
Error Conditions:
None.

Remarks:

None.

Example:

Please see res_data_next.


res_data_defined	(register, location, register_type)


Description:
This function returns 0 or 1 depending on whether or not the register has been defined.
Input:
INTEGER	register	This value specifies the register identifier.
STRING	location[]	This value specifies the model entity with which the results data is associated. Valid values are: "C" = centroid, "N" = nodal, "EN" = element nodal, and "EL" = element.
STRING	register_type[]	This value specifies the register type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
Output:
LOGICAL	<Return Value>	This value returns TRUE when the input register identifier has an existing definition stored in the database, or FALSE otherwise.
Error Conditions:
None.

Remarks:

None.

Example:

Please see res_data_defined (p. 1048) in the PCL Reference Manual Examples.


res_data_dump	(register, location, register_type, file_name, file_options)


Description:
This function dumps the data of the specified register to a file.
Input:
INTEGER	register	This value specifies the register identifier.
STRING	location[]	This value specifies the model entity with which the results data is associated. Valid values are: "C" = centroid, "N" = nodal, "EN" = element nodal, and "EL" = element.
STRING	register_type[]	This value specifies the register type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
STRING	file_name[]	This value specifies the file name to dump a register’s data into.
STRING	file_options[]	This value specifies the file options controlling the types of read and write operations that may be done to the file. See the remarks below for more information.
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

The input value file_options can make use of the following values. This values can be concatenated together to specify more that one option at a time:


	Option	Description

	N	Use this option to create a new file.
	O	Use this option to open an existing file. If the “N” option is used with this option, the file will be created if it does not already exist.
	R	Use this option to open the file for read access.
	W	Use this option to open the file for write access. If the “R” option is used with this option, the file will be opened for both reading and writing.
	A	Use this option to open the file for appending at the end of the file. This option is available with the text_open() function only.
	V	Use this option to specify the use of version numbers for searching for or creating the file.
	P	Use this option to specify that the directories in the file utilities path in the environment variables should be searched to find the file.
	L	Use this option to specify that the file be locked for exclusive access. This option is currently not available.
	S	Use this option to specify that file is in the scratch directory. This option is only available with file names that have been created using the file_unique_name() function.
	D	Use this option to specify that the file should be deleted when it is closed. This option is valid only with functions that can close the file.

Example:

Please see res_data_dump (p. 1049) in the PCL Reference Manual Examples.


res_data_csys_dump	(file_name, file_options)


Description:
This function dumps the coordinate system information to a file from all defined registers.
Input:
STRING	file_name[]	This value specifies the file name to dump a register’s coordinate data into.
STRING	file_options[]	This value specifies the file options controlling the types of read and write operations that may be done to the file. See the remarks below for more information.
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

The input value file_options can make use of the following values. This values can be concatenated together to specify more that one option at a time:


	Option	Description

	N	Use this option to create a new file.
	O	Use this option to open an existing file. If the “N” option is used with this option, the file will be created if it does not already exist.
	R	Use this option to open the file for read access.
	W	Use this option to open the file for write access. If the “R” option is used with this option, the file will be opened for both reading and writing.
	A	Use this option to open the file for appending at the end of the file. This option is available with the text_open() function only.
	V	Use this option to specify the use of version numbers for searching for or creating the file.
	P	Use this option to specify that the directories in the file utilities path in the environment variables should be searched to find the file.
	L	Use this option to specify that the file be locked for exclusive access. This option is currently not available.
	S	Use this option to specify that file is in the scratch directory. This option is only available with file names that have been created using the file_unique_name() function.
	D	Use this option to specify that the file should be deleted when it is closed. This option is valid only with functions that can close the file.

Example:

Please see res_data_csys_dump.


res_data_pattern_dump	(file_name, file_options)


Description:
This function dumps the register data pattern information to a file from all defined registers.
Input:
STRING	file_name[]	This value specifies the file name to dump a register’s pattern data into.
STRING	file_options[]	This value specifies the file options controlling the types of read and write operations that may be done to the file. See the remarks below for more information.
Output:
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

The input value file_options can make use of the following values. This values can be concatenated together to specify more that one option at a time:


	Option	Description

	N	Use this option to create a new file.
	O	Use this option to open an existing file. If the “N” option is used with this option, the file will be created if it does not already exist.
	R	Use this option to open the file for read access.
	W	Use this option to open the file for write access. If the “R” option is used with this option, the file will be opened for both reading and writing.
	A	Use this option to open the file for appending at the end of the file. This option is available with the text_open() function only.
	V	Use this option to specify the use of version numbers for searching for or creating the file.
	P	Use this option to specify that the directories in the file utilities path in the environment variables should be searched to find the file.
	L	Use this option to specify that the file be locked for exclusive access. This option is currently not available.
	S	Use this option to specify that file is in the scratch directory. This option is only available with file names that have been created using the file_unique_name() function.
	D	Use this option to specify that the file should be deleted when it is closed. This option is valid only with functions that can close the file.

Example:

Please see res_data_pattern_dump.


res_data_get_source_type	(register, location, register_type, source_type)


Description:
This function outputs the register’s data source type.
Input:
INTEGER	register	This value specifies the register identifier.
STRING	location[]	This value specifies the model entity with which the results data is associated. Valid values are: "C" = centroid, "N" = nodal, "EN" = element nodal, and "EL" = element.
STRING	register_type[]	This value specifies the register type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
Output:
STRING	source_type[]	This value returns the source type. Valid values are: “Db”, “LBC”, “FEMAttrib”, “EProp”, “User”, and “Derived”.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

The data source type for a register corresponds to the load method used for that register. If the register data is not from a single source, the type will be derived.

Example:

Please see res_data_get_source_type.


res_data_get_dbresult	(register, location, register_type, load_case, subcase, primary_result, secondary_result, layer, derivation, coordinate, average_method, average_domain, extrapolation, list_flag, layer_flag, data_form, complex_angle)


Description:
This function outputs the stored information regarding a register containing a database result.
Input:
INTEGER	register	This value specifies the register identifier.
STRING	location[]	This value specifies the model entity with which the results data is associated. Valid values are: "C" = centroid, "N" = nodal, "EN" = element nodal, and "EL" = element.
STRING	register_type[]	This value specifies the register type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
Output:
STRING	load_case[]	This value returns the load case identifier.
STRING	subcase[]	This value returns the subcase identifier.
STRING	primary_result[]	This value returns the primary result identifier.
STRING	secondary_result[]	This value returns the secondary result identifier.
STRING	layer[]	This value returns the layer position identifier.
STRING	derivation[10]	This value returns the derivation specifier.
STRING	coordinate[]	This value returns the coordinate system for transformations.
STRING	average_method[]	This value returns the defined averaging method.
STRING	average_domain[]	This value returns the defined averaging domain.
STRING	extrapolation[]	This value returns the defined extrapolation method.
LOGICAL	list_flag	This value returns a value of TRUE if the register has an associated list.
LOGICAL	layer_flag	This value returns TRUE if the register has an associated layer.
STRING	data_form[]	This value returns the data form (real, imaginary, etc.). Optional = NULL.
REAL	complex_angle	This value returns the complex angle. Optional = NULL.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_dbresult.


res_data_get_subcase_name	(load_case, subcase, subcase_name)


Description:
This function returns a subcase name given the load case and subcase identifiers. It returns the name of a subcase including any extension added to distinguish it from other subcases with the same name. ("_nn")
Input:
INTEGER	load_case	This value specifies the load case identifier.
INTEGER	subcase	This value specifies the subcase identifier.
Output:
STRING	subcase_name[]	This value returns the subcase name.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_subcase_name.


res_data_get_subcase_id	(load_case, subcase, subcase_id)


Description:
This function returns the subcase identifier given the load case and subcase names.
Input:
STRING	load_case[]	This value specifies the load case name.
STRING	subcase[]	This value specifies the subcase name.
Output:
INTEGER	subcase_id	This value returns the subcase identifier.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (Ch. 11) for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_subcase_id.


res_data_get_result_names	(primary_result, secondary_result, primary_name, secondary_name)


Description:
The function returns the primary and secondary result names given their identifiers.
Input:
INTEGER	primary_result	This value specifies the primary result identifier.
INTEGER	secondary_result	This value specifies the secondary result identifier.
Output:
STRING	primary_name[]	This value returns the primary result name.
STRING	secondary_name[]	This value returns the secondary result name.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_result_names.


res_data_get_result_ids	(primary_name, secondary_name, primary_result, secondary_result)


Description:
This function returns the primary and secondary results identifiers given their names.
Input:
STRING	primary_name[]	This value specifies the primary result name.
STRING	secondary_name[]	This value specifies the secondary result name.
Output:
INTEGER	primary_result	This value returns the primary result identifier.
INTEGER	secondary_result	This value returns the secondary result identifier.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_result_ids.


res_data_get_layerpos_name	(layer_id, layer_name)


Description:
This function returns the layer position name given layer identifier.
Input:
INTEGER	layer_id	This value specifies the layer position identifier.
Output:
STRING	layer_name[]	This value returns the layer position name.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages (p. 1875) in the PCL Reference Manual for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_layerpos_name.


res_data_get_layerpos_id	(layer_name, layer_id)


Description:
This function returns the layer position identifier given its name.
Input:
STRING	layer_name[]	This value specifies the layer position name.
Output:
INTEGER	layer_id	This value returns the layer position identifier.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_layerpos_id.


res_data_bulk_get_loadcases	(count, load_case_ids, subcase_ids, coordinates, load_case)


Description:
This function retrieves the number of load cases and all their load case, subcase, and coordinate identifiers that exist in the database and the names associated to them.
Input:
Output:
INTEGER	count	This value returns the number of load cases.
INTEGER	load_case_ids(count)	This value returns the load case identifiers.
INTEGER	subcase_ids(count)	This value returns the subcase identifiers.
INTEGER	coordinates(count)	This value returns the coordinate identifiers associated with the load cases.
STRING	load_case[](count)	This value returns the load case names.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_bulk_get_loadcases.


res_data_get_restype_ids	(restype_id, primary_result, secondary_result)


Description:
This function returns the primary and secondary result identifiers given the results type identifier.
Input:
INTEGER	restype_id	This value specifies the results type identifier.
Output:
INTEGER	primary_result	This value returns the primary result identifier.
INTEGER	secondary_result	This value returns the secondary result identifier.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
See the Status Messages for information on any error values returned by this function.

Remarks:

None.

Example:

Please see res_data_get_restype_ids.