PCL Reference Manual > Results Postprocessing Functions > Data Register Definition Functions
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">   
Data Register Definition Functions
These functions define the manipulation methods and data or data source for data registers..
res_data_load_dbresult
(register, location, result_type, load_case, subcase, primary_result, secondary_result, layer, derivation, coordinate, averaging_method, averaging_domain, extrapolation, complex_form, complex_angle)
Description:
 
 
This function specifies a result to be extracted from the database and manipulated into a format for subsequent display. This description will be stored in the specified register.
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
result_type[]
This value specifies the results data type. Valid values are: "S" = scalar, "V" = vector, and "T" = tensor.
STRING
load_case[]
This value specifies the load case identifier.
STRING
subcase[]
This value specifies the subcase identifier.
STRING
primary_result[]
This value specifies the identifier of the primary result.
STRING
secondary_result[]
This value specifies the identifier of the secondary result.
STRING
layer[]
This value specifies the layer position identifier.
STRING
derivation[10]
This value specifies the derivation specifier if the results are to be derived. A null will leave the result as is. See the remarks below for more information.
STRING
coordinate[]
This value specifies the coordinate for transformations. Valid values are: ““ = as is, “Coord i” = Db coordinate system, "M" = material system, "IJK" = element ijk system, "N" = nodal system, and "G" = global.
STRING
averaging_method[]
This value specifies the averaging method: “derive-avg” to perform derivations and transformations, then average the results, “avg-derive” (transform to global, average, then derive/transform), “difference” (calculate the difference versus average, derivations performed first), and “sum” (sum all of the element nodal components at the nodes).
STRING
averaging_domain[]
This value specifies the averaging domain: “All”, “Matl”, “Prop”, “Target” (only consider entities in the target definition), and “Element”.
STRING
extrapolation[]
This value specifies the extrapolation method: “ShapeFunc”, “Average” (constant in element computed as the average), and “Centroid” (constant in element as computed centroidal value).
STRING
complex_form[]
This value specifies the complex form: “Real”, “Imaginary”, “Magnitude”, “Phase”, and “Angle”. Optional = NULL.
STRING
complex_angle[]
This value specifies the angle in radians to be used with the “Angle” form. Optional = 0.0.
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 for information on any error values returned by this function.
Remarks:
The input value derivation can have the following values:
 
Tensor to Scalar:
“VONM”
“OCT”
“HYDRO”,
 
 
“TRESCA”
“INV1”
“INV2”
 
 
“INV3”
“MAXSHR”
“MAXCMP”
 
 
“MINCMP”
“MAJOR”
“MINOR”
 
 
“INTER”
“XX”
“YY”
 
 
“ZZ”
“XY”
“YZ”
 
 
“ZX”
“MXSH2D”
“MXCP2D”
 
 
“MNCP2D”
“MJR2D”
“MNR2D”
 
 
“TRES2D”
 
 
 
 
 
 
 
 
Tensor to Vector:
“MAJORV”
“INTERV”
“MINORV”
 
 
“XX”
“YY”
“ZZ”
 
 
“MJRV2D”
“MNRV2D”
“NRMLCOMPS”
 
 
any six characters such as “XXYYZZ”
 
 
 
 
 
 
Tensor to Tensor
“TENS2D”
“TENS3D”
 
 
 
 
 
 
 
Vector to Scalar:
“XX”
“YY”
“ZZ”
 
 
“MAG”
“MAXCMP”
“MINCMP”
 
 
“AVG”
 
 
Example:
None.
.
res_data_load_elem_scalar
(reg, scalar_id)
Description:
 
 
Create an enodal scalar register to hold the specified element scalar data
Input:
 
 
INTEGER
reg
This value specifies the register identifier.
INTEGER
scalar_id
The scalar_id is a unique identifier that you supply to this call. It internally establishes a scalar container that you can load with data and then post process.
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 for information on any error values returned by this function.
Remarks:
.
res_data_title
(register, location, register_type, count, titles)
Description:
 
 
This function specifies a title string to be associated with the register. If this title is not specified, a default title based on the source of the data will be used.
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.
INTEGER
count
This value specifies the number of title lines.
STRING
titles[](count)
This value specifies the title lines to be associated with the data in the register.
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 for information on any error values returned by this function.
Remarks:
None.
Example:
None.
 
res_data_get_ntitles
(register, location, register_type, count)
Description:
 
 
This function gets the number of title lines stored in a register.
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:
 
 
INTEGER
count
This value returns the number of title lines associated to this register.
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_ntitles
.
res_data_get_titles
(register, location, register_type, count, titles)
Description:
 
 
This function returns the number of titles and the titles themselves stored in a register.
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:
 
 
INTEGER
count
This value returns the number of title lines associated with this register.
STRING
titles[](count)
This value returns the title lines associated with this register.
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_titles.
 
res_data_dbres_list
(register, location, register_type, count, load_cases, subcases, primary_result, secondary_result, layers)
Description:
 
 
This function specifies a series of database result specifiers to be associated with a specific register.
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.
INTEGER
count
This value specifies a count of the number of results.
STRING
load_cases[](count)
This value specifies an value of load case identifiers.
STRING
subcases[](count)
This value specifies an value of subcase identifiers.
STRING
primary_result[](count)
This value specifies an value of primary results identifiers.
STRING
secondary_result[](count)
This value specifies an value of secondary results identifiers.
STRING
layers[](count)
This value specifies an value of layer position identifiers.
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 for information on any error values returned by this function.
Remarks:
This register must have previously be loaded with the res_data_load_dbresult() function and all of the results must be of the same type.
The list of results can be subsequently used for animation, interpolation, summation, and minimum or maximum value extraction.
Example:
Please see res_data_dbres_list (p. 1027) in the PCL Reference Manual Examples.
 
res_data_register_list
(register, location, register_type, count, register_list)
Description:
 
 
This function specifies a series of registers to be associated with a specific register.
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.
INTEGER
count
This value specifies the number of registers.
INTEGER
register_list(count)
This value specifies an value of register identifiers.
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 list of registers can be subsequently used for animation, interpolation, summation, and minimum or maximum value extraction.
Example:
Please see res_data_register_list.
 
res_data_list_sum
(register, location, register_type, count, weights)
Description:
 
 
This function specifies that the data specified by a register list should be summed.
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.
INTEGER
count
This values specifies the first count result cases.
REAL
weights(count)
This value specifies the optional weighting values for the summation. Optional=NULL.
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 register list must have been previously defined using the res_data_dbres_list() or res_data_register_list() functions.
Example:
Please see res_data_list_sum.
 
res_data_list_max
(register, location, register_type, method, derivation)
Description:
 
 
This function specifies that the data specified by a register list should be scanned for the maximum values.
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
method[]
This value specifies the averaging method: “derive-avg” (perform derivations/transformations, then average), “avg-derive” (transform to global, average, then derive/transform), “difference” (calculate the difference versus average, derivations performed first), and “sum” (sum all of the element nodal components at the nodes).
STRING
derivation[10]
This value specifies the derivation specifier if the results are to be derived. A null will leave the result as is. 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 register list must have been previously defined using the res_data_dbres_list() or res_data_register_list() functions.
The register will maintain both the result and source for each FEM entity.
The input value derivation can have the following values:
 
Tensor to Scalar:
“VONM”
“OCT”
“HYDRO”,
 
 
“TRESCA”
“INV1”
“INV2”
 
 
“INV3”
“MAXSHR”
“MAXCMP”
 
 
“MINCMP”
“MAJOR”
“MINOR”
 
 
“INTER”
“XX”
“YY”
 
 
“ZZ”
“XY”
“YZ”
 
 
“ZX”
“MXSH2D”
“MXCP2D”
 
 
“MNCP2D”
“MJR2D”
“MNR2D”
 
 
“TRES2D”
 
 
 
 
 
 
 
 
Tensor to Vector:
“MAJORV”
“MINORV”
“INTERV”
 
 
“XX”
“YY”
“ZZ”
 
 
“MJRV2D”
“MNRV2D”
 
 
 
any six characters such as “XXYYZZ”
 
 
 
 
 
 
Tensor to Tensor
“TENS2D”
“TENS3D”
 
 
 
 
 
 
 
Vector to Scalar:
“XX”
“YY”
“ZZ”
 
 
“MAG”
“MAXCMP”
“MINCMP”
 
 
“AVG”
 
 
Example:
Please see res_data_list_max.
 
res_data_list_min
(register, location, register_type, method, derivation)
Description:
 
 
This function specifies that the data specified by a register list should be scanned for the minimum values.
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
method[]
This value specifies the averaging method: “derive-avg” (perform derivations/transformations, then average), “avg-derive” (transform to global, average, then derive/transform), “difference” (calculate the difference versus average, derivations performed first), and “sum” (sum all of the element nodal components at the nodes).
STRING
derivation[10]
This value specifies the derivation specifier if the results are to be derived. A null will leave the result as is. 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 register list must have been previously defined using the res_data_dbres_list() or res_data_register_list() functions.
The register will maintain both the result and source for each FEM entity.
The input value derivation can have the following values:
 
Tensor to Scalar:
“VONM”
“OCT”
“HYDRO”,
 
 
“TRESCA”
“INV1”
“INV2”
 
 
“INV3”
“MAXSHR”
“MAXCMP”
 
 
“MINCMP”
“MAJOR”
“MINOR”
 
 
“INTER”
“XX”
“YY”
 
 
“ZZ”
“XY”
“YZ”
 
 
“ZX”
“MXSH2D”
“MXCP2D”
 
 
“MNCP2D”
“MJR2D”
“MNR2D”
 
 
“TRES2D”
 
 
 
 
 
 
 
 
Tensor to Vector:
“MAJORV”
“MINORV”
“INTERV”
 
 
“XX”
“YY”
“ZZ”
 
 
“MJRV2D”
“MNRV2D”
 
 
 
any six characters such as “XXYYZZ”
 
 
 
 
 
 
Tensor to Tensor
“TENS2D”
“TENS3D”
 
 
 
 
 
 
 
Vector to Scalar:
“XX”
“YY”
“ZZ”
 
 
“MAG”
“MAXCMP”
“MINCMP”
 
 
“AVG”
 
 
Example:
Please see res_data_list_min
.
res_data_list_interp_gv
(register, location, register_type, global_name, value, interpolation, extrapolation)
Description:
 
 
This function specifies the method for interpolating/extrapolating data values between values in the specified register list.
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
global_name[]
This value specifies the name of the global variable.
REAL
value
This value specifies the value of the global variable.
STRING
interpolation[]
This value specifies the interpolation method: “Linear” to perform linear interpolation between the two closest data sets, ”Cubic” to perform a cubic spline fit across the closest four data sets, ”Closest” to use the data set with the global variable closest to the specified value, ”Ceiling” to use the data set with the next higher global variable value, and ”Floor” to use the data set with the next lower global variable value.
STRING
extrapolation[]
This value specifies the extrapolation method: “Error” to do nothing, “Constant” to use the closest data set, and “Linear” to extrapolate out at the ending slope.
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 register list must have been previously defined using the res_data_dbres_list() or res_data_register_list() functions.
Only the data which is associated to the specified global variable will be considered during this operation.
The extrapolation specifier controls what action is taken when the global variable value is outside of the range spanned by the list.
Example:
Please see res_data_list_interp_gv.
 
res_data_list_interp_factor
(register, location, register_type, factor, interpolation, extrapolation)
Description:
 
 
This function specifies the method for interpolating data values between values in the specified register list.
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.
REAL
factor
A factor from 0.0 to 1.0.
STRING
interpolation[]
This value specifies the interpolation method: “Linear” to perform linear interpolation between the two closest data sets, ”Cubic” to perform a cubic spline fit across the closest four data sets, ”Closest” to use the data set with the global variable closest to the specified value, ”Ceiling” to use the data set with the next higher global variable value, and ”Floor” to use the data set with the next lower global variable value.
STRING
extrapolation[]
This value specifies the extrapolation method: “Error” to do nothing, “Constant” to use the closest data set, and “Linear” to extrapolate out at the ending slope.
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 register list must have been previously defined using the res_data_dbres_list() or res_data_register_list() function. This function simply performs a linear interpolation of a list.
The factor may be varied from 0.0 to 1.0. Each data set in the list will be treated as evenly spaced
data sets with the first set having a factor of 0.0 and the last having a factor of 1.0.
This type of interpolation is useful for data not having associated global variables
Example:
Please see res_data_list_interp_factor
 
res_data_function
(register, location, register_type, function)
Description:
 
 
This function specifies a format function used to determine the data values of a register.
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
function[]
This value specifies a PCL function such as “ ($1 + $2 / $4) * $5”. The $n specifiers are register identifiers.
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 for information on any error values returned by this function.
Remarks:
The registers specified in the function must be of the same location and type and must have been previously loaded with a res_data_load() function.
Example:
Please see res_data_function.
.
res_data_scalar_to_vector
(vector_register, location, coordinate, scalar_regsisters)
Description:
 
 
This function specifies three scalar registers whose data are to make up the components of a vector data set.
Input:
 
 
INTEGER
vector_register
This value specifies the register identifier that will hold the vector data.
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
coordinate[]
This value specifies the coordinate system for the orientation definition of the vector. Valid values are: ““ = global, “Coord i” = Db coordinate system, "M" = material system, "IJK" = element ijk system, "N" = nodal system, and "G" = global.
INTEGER
scalar_regsisters(3)
This value specifies the identifiers for the three registers holding the scalar data for each component of the vector data.
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:
All data registers must be of the same location.
The specified coordinate system is used to define the orientation of the vector data.
Example:
Please see res_data_scalar_to_vector.
 
res_data_scalar_to_tensor
(tensor_register, location, coordinate, scalar_regsisters)
Description:
 
 
This function specifies six scalar registers whose data are to make up the components of a tensor data set.
Input:
 
 
INTEGER
tensor_register
This value specifies the register identifier that will hold the tensor data.
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
coordinate[]
This value specifies the coordinate system for the orientation definition of the tensor. Valid values are: ““ = global, “Coord i” = Db coordinate system, "M" = material system, "IJK" = element ijk system, "N" = nodal system, and "G" = global.
INTEGER
scalar_regsisters(6)
This value specifies the identifiers for the six registers holding the scalar data for each component of the tensor data.
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:
All data registers must be of the same location.
The specified coordinate system is used to define the orientation of the tensor data.
Example:
Please see res_data_scalar_to_tensor.
 
res_data_complex_form
(register, location, register_type, form, angle)
Description:
 
 
This function specifies the method for determining the output format of complex data.
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
form[]
This value specifies the complex form to use. Valid values are: “Real”, “Imaginary”, “Magnitude”, “Phase”, and “Angle”.
REAL
angle
This value specifies the angle in radians to be used with the “Angle” form. Optional=0.0.
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:
If the complex form is not explicitly set with this call, “Real” will be used as a default. See the description for the input value form.
Example:
Please see res_data_complex_form.