IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

DXExtractParameter

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".


[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]


[IBM Home Page | Order | Search | Contact IBM | Legal ]