Function
Determines whether an Object can be converted to a specific value type and, if so, returns the value in the user-provided buffer.
Syntax
#include <dx/dx.h>
Object DXExtractParameter(Object o, Type t, int dim, int count, Pointer p)
Functional Details
If Object o can be converted to Type t with dimensionality dim and count elements, this routine performs the conversion and returns the data in the buffer pointed to by p.
For a successful conversion, Object o must be either an Array or a String. If o is an Array, then its Category must be CATEGORY_REAL, its rank must be either 0 or 1, and it must have count items contained within.
If dim is greater than 1, then o's rank must be 1 and its shape must match dim in order for this conversion to be successful. If dim is either 0 or 1, then both rank 0 and rank 1 shape 1 Arrays will match in size.
Once it is known that the sizes match, the Array's Type is examined to determine whether it can be converted to the Type specified by t. In general, smaller signed (or unsigned) types can be converted to larger signed (or unsigned) types as follows:
TYPE_BYTE => TYPE_SHORT => TYPE_INT => TYPE_FLOAT => TYPE_DOUBLE
and
TYPE_UBYTE => TYPE_USHORT => TYPE_UINT
Signed and unsigned versions of the same type cannot be converted between each other (e.g., TYPE_BYTE and TYPE_UBYTE). However, unsigned types can be converted to larger signed types (e.g., TYPE_UBYTE => TYPE_SHORT).
If the Types are identical, the data contained in o is copied to the buffer pointed to by p. If (without violating any of the rules just given) o can be converted to the Type specified in t, it is, and the converted data is copied to the buffer (p).
If o is a String, then t must be TYPE_STRING and dim must be either 0 or 1. If dim is 0, then the string contained in o must consist only of a single character.
Return Value
Returns o if the conversion is valid; otherwise, returns NULL without setting an error code.
See Also
DXExtractFloat, DXExtractInteger, DXExtractNthString, DXExtractString, DXQueryArrayConvert, DXQueryArrayConvertV, DXQueryParameter
12.8 , "Extracting Module Parameters".
[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]