The DFPAL Library, version 2.20
© Copyright IBM Corporation, 2007. All rights reserved.
[previous | contents | next] [printer friendly]

DFPAL management functions

DFPAL management API consists of routines required for DFPAL initialization, error handling, status checking, and termination.

char * dfpalVersion(void)

Return version number of DFPAL. This function can be called before dfpalInit().

uint32_t dfpalMemSize(void)

Returns amount of memory needed (in bytes) for thread specific context information. DFPAL purposefully does not allocate any dynamic memory to avoid interfering with any application specific memory management paradigm, e.g. certain application do not utilize standard malloc() for the application memory allocation. Instead, such applications have their own memory management layer based on shared memory, for example. This function shall be called before dfpalInit() to determine amount of memory needed by the DFPAL.

int32_t dfpalInit(void *context)

DFPAL must be initialized using dfpalInit() before any of its service is accessed. The input context is pointer to allocated memory. This function either returns DFPAL_ERR_NO_ERROR or an error code indicating error condition. List of possible errors and error codes can be found in dfpalerr.h. For multi-threaded application, each thread using DFPAL service must initialize using this service. Additionally, application is responsible for making sure that memory passed as an argument is thread safe.

The dfpalInit() reads environment variable DFPAL_EXE_MODE. Possible values for this environment variable are DNSW (force DFPAL to use decNumber software mode), PPCHW (force DFPAL to use PowerPC hardware mode; dfpalInit() will return error if no hardware support available), or AUTO (auto detect). Default value, in absence of the environment variable or undefined value, is AUTO.

dfpalCSFlag *dfpalGetFlagHandle(void)

Returns handle to global status flags, traps, and rounding mode control structure. The status flags, traps, and rounding mode are switched based on whether DFPAL is operating in hardware or software. This routine is useful when using DFPAL with runtime linking and loading using dlopen()/dlsym(). Applications not using runtime linking and loading do not have to use this.

void dfpalEnd(void (*memfree)(void *))

Frees memory used by DFPAL, passed down to DFPAL by the dfpalInit() call earlier. It takes a pointer to function performing memory de-allocation. Typically, memory de-allocation function is corresponding to one used to allocate memory for the dfpalInit().

enum dfpalExeMode dfpalGetExeMode(void)

Returns current mode of execution. Returns DNSW (decNumber Software) if DFPAL is using decNumber software implementation for the decimal floating point arithmetic. Returns PPCHW (Power PC Hardware) if DFPAL is using hardware decimal floating point arithmetic.

void dfpalResetContext(void) [deprecated]

Reset decNumber context structure. Avoid using this function.

int32_t dfpalGetError(int32_t *dfpalErr, int32_t *osErr, char **dfpalErrTxt)

Returns last DFPAL error code. Also, DFPAL error code, operating system error code (if any) and DFPAL descriptive error text, respectively, is placed into function input parameters.

void dfpalClearError(void)

Clear DFPAL error codes. Calling the dfpalGetError() after this function call will return “No error”.

int32_t dfpalErrorFlag(void)

Similar to dfpalGetError() but only returns DFPAL error code.

void dfpalInitProcessContext(void)

Note: this is Windows specific function. Unix platforms shall never use this.
Initialize a process context. The process context is shared by all threads in read-only mode. This function is automatically called by the dfpalInit() on Unix platforms. On Windows platform, if DFPAL is integrated into some other container module, use that container module’s DllMain() equivalent facility to call dfpalInitProcessContext() for DLL_PROCESS_ATTACH event. Refer to How to compile DFPAL? for more details.
[previous | contents | next]

DFPAL is authored by Punit Shah (punit@us.ibm.com).
Please send any corrections, comments or questions to dfpal-l@austin.ibm.com.
This page was updated on 21 Dec 2007.