Optim Data Privacy Providers  11.7.0
 All Data Structures Files Functions Variables Macros Groups Pages
Data Structures | Macros | Functions
ODPPCmnAPI.h File Reference
#include "ODPPTokIdsH.h"
Include dependency graph for ODPPCmnAPI.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ODPP_ODBC_DATE
 
struct  ODPP_ODBC_TIME
 
struct  ODPP_ODBC_TIMESTAMP
 
struct  DP_TOKEN
 
struct  DP_ECB
 
struct  DP_FIELD_DATA_DEF
 
struct  DP_ROW_DEF
 
struct  DP_ROWSET_DEF
 
struct  DPFD_WC_SS
 
struct  DPFD_MC_SS
 
struct  DP_FIELD_DEF
 
struct  DPPRM_VAL_WC_SS
 
struct  DPPRM_VAL_MC_SS
 
struct  DP_INIT_OP_DEF
 
struct  DP_FRMW_PARAMS_DEF
 
struct  DP_SVC_DEF
 
struct  DPPD_WC_SS
 
struct  DPPD_MC_SS
 
struct  DP_PRV_DETAILS
 
struct  DP_PRV_DEF
 
struct  DPEM_WC_SS
 
struct  DPEM_MC_SS
 
struct  DP_ERR_MSG
 
struct  DP_KVPAIR_DEF
 
struct  DPPS_WC_SS
 
struct  DPPS_MC_SS
 
struct  DP_PARAMS_DEF
 
struct  DP_PARMGEN_DEF
 
struct  DP_LIB_LIST
 

Macros

#define ODPPSVCIDLENGTH   10
 
#define ODPP_PROVIDER_ID_MAX_LENGTH   ODPPSVCIDLENGTH
 
#define RETVAL   int
 
#define ODPP_MBCS_CHAR_BYTES   6
 
#define ODPP_PROVIDER_NAME_LEN   50
 
#define ODPP_PROVIDER_DESCRIPTION_LEN   256
 
#define ODPP_MAX_ERR_MSG_SRC_LENGTH   (512) + 10
 
#define ODPP_MAX_ERR_MSG_TEXT_LENGTH   (512*2) + 50
 
#define ODPP_MAX_ERR_MSG_BODY_LENGTH   (512*3) + 50
 
#define ODPP_MAX_PATH_LEN   2048
 
#define ODPP_MAX_FILENAME_LEN   1024
 
#define DP_PARSER_ERRMSG_MAX_LEN   512
 
#define ENV_OPTDIS   'D'
 
#define ENV_UDF   'U'
 
#define ENV_LUA   'L'
 
#define RDB_ORACLE   'O'
 
#define RDB_SYBASE   'S'
 
#define RDB_ODBC   'M'
 
#define RDB_INFORMIX   'I'
 
#define RDB_RDB   'R'
 
#define RDB_DB2ZOS   RDB_DB2MVS
 
#define RDB_DB2LUW   RDB_DB2CS
 
#define RDB_SQLSERVER   'G'
 
#define RDB_ANY   '*'
 
#define RDB_NONE   'N'
 
#define RDB_TERADATA   'T'
 
#define ODPP_CODE_PAGE_NONE   0x80000000
 
#define PARAM_VAL_NONE   0
 
#define PARAM_VAL_NUM   1
 
#define PARAM_VAL_WC   2
 
#define PARAM_VAL_MC   3
 
#define INITIALIZE_ODPP_STRUCT(OBJ, TYPE)
 
#define INITIALIZE_ODPP_STRUCT_PTR(OBJ_PTR, TYPE)
 
#define DP_ECB_EC   "ECBD"
 
#define DP_FIELD_DATA_DEF_EC   "DATA"
 
#define DP_ROW_DEF_EC   "ROWD"
 
#define DP_ROWSET_DEF_EC   "RWST"
 
#define DP_FIELD_DEF_EC   "FLDX"
 
#define DP_INIT_OP_DEF_EC   "OPRX"
 
#define DP_FRMW_PARAMS_DEF_EC   "FRPX"
 
#define DP_SVC_DEF_EC   "SVCX"
 
#define DP_PRV_DEF_EC   "PRVX"
 
#define DP_ERR_MSG_EC   "EMSG"
 
#define DP_PARMGEN_DEF_EC   "PGDA"
 
#define DP_PARAMS_DEF_EC   "PRMA"
 
#define DP_KVPAIR_DEF_EC   "KVPA"
 
#define PARAM_VAL_NONE   0
 
#define PARAM_VAL_NUM   1
 
#define PARAM_VAL_WC   2
 
#define PARAM_VAL_MC   3
 

Functions

RETVAL Provider_PreLoad (char *pBinPath, int iBinPathBytes, DP_LIB_LIST *pLibList, int iArrCnt)
 
RETVAL Provider_FrmwInit (DP_FRMW_PARAMS_DEF *pInitParams)
 
RETVAL Provider_Init (int *pSvcToken, char *pSvcID, int iSvcIdLen, DP_SVC_DEF *pSvcdef, char bAllocInitBlock)
 
RETVAL Provider_Service (int iSvcToken, short sMethod, DP_SVC_DEF *pSvcDef, DP_ROWSET_DEF *pRowSet)
 
RETVAL Provider_Term (int iSvcToken)
 
RETVAL Provider_Enumerate (DP_PRV_DEF *pPrvDetails, short *pCount)
 
RETVAL Provider_GetErrorCount (int iSvcToken, short *pErrCount, int *pErrAreaLen)
 
RETVAL Provider_GetError (int iSvcToken, DP_ECB *pECB)
 
RETVAL Provider_GetFormattedErrorMsg (DP_ERR_MSG *pErrMsg)
 
RETVAL Provider_GetFmtErrMsgEarly (DP_ERR_MSG *pErrMsg)
 
RETVAL Provider_TermErrors (int iSvcToken)
 
RETVAL Provider_GetInfo (int iSvcToken, short sRequest, void *ptr, int *pBufLen)
 
RETVAL Provider_FrmwTerm (void)
 
RETVAL Parser_Init (void)
 
RETVAL Parser_Service (DP_PARAMS_DEF *pParamDef)
 
RETVAL Parser_GetErrorCount (short *pErrCount, int *pErrAreaLen)
 
RETVAL Parser_GetError (DP_ECB *pECB)
 
RETVAL Parser_GetFormattedErrorMsg (DP_ERR_MSG *pErrMsg)
 
RETVAL Parser_Term (void)
 
RETVAL ParmGen_Init (void)
 
RETVAL ParmGen_Service (DP_PARMGEN_DEF *pParmGen)
 
RETVAL ParmGen_Clean (DP_SVC_DEF *pSvcDef)
 
RETVAL ParmGen_GetErrorCount (short *pErrCount, int *pErrAreaLen)
 
RETVAL ParmGen_GetError (DP_ECB *pECB)
 
RETVAL ParmGen_GetFormattedErrorMsg (DP_ERR_MSG *pErrMsg)
 
RETVAL ParmGen_Term (void)
 

Detailed Description

-----------------------------------------------------------------------------
File Name:  ODPPCmnAPI.H

Purpose:    Provides the Interface declarations for ODPP, including the 
            function declarations and structure declarations. This file is 
            supposed to be used by the external applications using ODPP. 
            
            Only declarations that are part of the API should be declared 
            here.

Author:     IBM Optim
-----------------------------------------------------------------------------

Macro Definition Documentation

#define ODPPSVCIDLENGTH   10

ODPP Service Provider ID maximum length.

#define ODPP_PROVIDER_ID_MAX_LENGTH   ODPPSVCIDLENGTH

ODPP Service Provider ID maximum length.

#define RETVAL   int

ODPP API return value and is equivalent to integer data type.

#define ODPP_MBCS_CHAR_BYTES   6

MBCS/SBCS character bytes

#define ODPP_PROVIDER_NAME_LEN   50

Maximum size(in bytes) of the buffer to hold the provider name

#define ODPP_PROVIDER_DESCRIPTION_LEN   256

Maximum size(in bytes) of the buffer to hold the provider description

#define ODPP_MAX_ERR_MSG_SRC_LENGTH   (512) + 10

Maximum size(in bytes) of the buffer to hold the Error message source

#define ODPP_MAX_ERR_MSG_TEXT_LENGTH   (512*2) + 50

Maximum size of the buffer to hold the Error message text

#define ODPP_MAX_ERR_MSG_BODY_LENGTH   (512*3) + 50

Maximum size of the buffer to hold the Error message body

#define ODPP_MAX_PATH_LEN   2048

Maximum length of Directory path

#define ODPP_MAX_FILENAME_LEN   1024

Maximum length of File name

#define DP_PARSER_ERRMSG_MAX_LEN   512

Maximum length of Error message

#define ENV_OPTDIS   'D'

Environment code for Optim Distributed

#define ENV_UDF   'U'

Environment code for User Define Function (UDF)

#define ENV_LUA   'L'

Environment code for LUA expression

#define RDB_ORACLE   'O'

DBMS Type code for Oracle

#define RDB_SYBASE   'S'

DBMS Type code for Sybase

#define RDB_ODBC   'M'

DBMS Type code for ODBC(syncpoint)

#define RDB_INFORMIX   'I'

DBMS Type code for Informix

#define RDB_RDB   'R'

DBMS Type code for Internal purpose

#define RDB_DB2ZOS   RDB_DB2MVS

DBMS Type code for DB2 zOS

#define RDB_DB2LUW   RDB_DB2CS

DBMS Type code for DB2 LUW

#define RDB_SQLSERVER   'G'

DBMS Type code for DB2 MS SQL Server

#define RDB_ANY   '*'

DBMS Type code used when passing DBMS code to ICU functions to mean "no specific DBMS" or "first match"

#define RDB_NONE   'N'

DBMS Type code Used when passing DBMS code to ICU functions to mean "no DBMS", only use process-specific converters

#define RDB_TERADATA   'T'

DBMS Type code for DB2 Teradata

#define ODPP_CODE_PAGE_NONE   0x80000000

To specify that code page and DBMS type is supplied by the parent structure DP_SVC_DEF

#define PARAM_VAL_NONE   0

To specify that Initialization Parameter supplied to Provider_Init() does not hold any value.

#define PARAM_VAL_NUM   1

To specify that Initialization Parameter supplied to Provider_Init() will hold numeric value.

#define PARAM_VAL_WC   2

To specify that Initialization Parameter supplied to Provider_Init() will hold the value expressed in wide character (Unicode) format.

#define PARAM_VAL_MC   3

To specify that Initialization Parameter supplied to Provider_Init() will hold the value expressed in mixed character (SBCS/MBCS) format.

#define INITIALIZE_ODPP_STRUCT (   OBJ,
  TYPE 
)
Value:
{OBJ.sStructVer = ODPP_CUR_VERSION; \
memcpy(OBJ.cEyeCatcher,EYE_CATCHER(TYPE),sizeof(OBJ.cEyeCatcher));}

To initialize an ODPP structure instance, by passing the structure object. Sets the ODPP version number and EyeCatcher for the structure instance.

#define INITIALIZE_ODPP_STRUCT_PTR (   OBJ_PTR,
  TYPE 
)
Value:
{OBJ_PTR->sStructVer = ODPP_CUR_VERSION; \
memcpy(OBJ_PTR->cEyeCatcher,EYE_CATCHER(TYPE),sizeof(OBJ_PTR->cEyeCatcher));}

To initialize an ODPP structure pointer, by passing the structure object pointer. Sets the ODPP version number and EyeCatcher for the structure instance.

#define DP_ECB_EC   "ECBD"

Eye catcher for DP_ECB

#define DP_FIELD_DATA_DEF_EC   "DATA"

Eye catcher for DP_FIELD_DATA_DEF

#define DP_ROW_DEF_EC   "ROWD"

Eye catcher for DP_ROW_DEF

#define DP_ROWSET_DEF_EC   "RWST"

Eye catcher for DP_ROWSET_DEF

#define DP_FIELD_DEF_EC   "FLDX"

Eye catcher for DP_FIELD_DEF

#define DP_INIT_OP_DEF_EC   "OPRX"

Eye catcher for DP_INIT_OP_DEF

#define DP_FRMW_PARAMS_DEF_EC   "FRPX"

Eye catcher for DP_FRMW_PARAMS_DEF

#define DP_SVC_DEF_EC   "SVCX"

Eye catcher for DP_SVC_DEF

#define DP_PRV_DEF_EC   "PRVX"

Eye catcher for DP_PRV_DEF

#define DP_ERR_MSG_EC   "EMSG"

Eye catcher for DP_ERR_MSG

#define DP_PARMGEN_DEF_EC   "PGDA"

Eye catcher for DP_PARMGEN_DEF

#define DP_PARAMS_DEF_EC   "PRMA"

Eye catcher for DP_PARAMS_DEF

#define DP_KVPAIR_DEF_EC   "KVPA"

Eye catcher for DP_KVPAIR_DEF

#define PARAM_VAL_NONE   0

To specify that Initialization Parameter supplied to Provider_Init() does not hold any value.

#define PARAM_VAL_NUM   1

To specify that Initialization Parameter supplied to Provider_Init() will hold numeric value.

#define PARAM_VAL_WC   2

To specify that Initialization Parameter supplied to Provider_Init() will hold the value expressed in wide character (Unicode) format.

#define PARAM_VAL_MC   3

To specify that Initialization Parameter supplied to Provider_Init() will hold the value expressed in mixed character (SBCS/MBCS) format.

Function Documentation

RETVAL Provider_PreLoad ( char *  pBinPath,
int  iBinPathBytes,
DP_LIB_LIST pLibList,
int  iArrCnt 
)

Dynamically loads the ODPP libraries except the service provider libraries and their dependent libraries.

Parameters
pBinPathPointer to a fully-qualified directory path containing ODPP binaries.
iBinPathBytesSize of the buffer pointed to by pBinPath in bytes.
pLibListPointer to an optional array which contains additional libraries to load or NULL.
iArrCntCount of elements in array pLibList or 0.
Returns
ODPPSUCCESS : Success
ODPPFAILURE : Invalid arguments
ODPP_OS_LIB_LOAD_FAILED : Library load failed
Author
IBM Optim

Example

RETVAL Provider_FrmwInit ( DP_FRMW_PARAMS_DEF pInitParams)

This function initializes the ODPP common framework. It includes the initialization of ODPPCmnLst and Mutex.

Parameters
pInitParamsPointer to a list of Parameters, i.e., a list of DP_INIT_OP_DEF structures.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_Init ( int *  pSvcToken,
char *  pSvcID,
int  iSvcIdLen,
DP_SVC_DEF pSvcdef,
char  bAllocInitBlock 
)

For each Service type that the caller wants to initiate, an Initialization call is required, and a TOKEN is returned to establish a session. This TOKEN will then be required on all subsequent calls for this session.

Parameters
pSvcTokenInteger pointer that represents the TOKEN required on subsequent session calls. The value should be initialized to zero on entry.

Provider_Init() will work on the concept of Service Tokens as explained below:
  1. Every first call by a thread to Provider_Init() will create a new Init Control Block and a new Service Token. Init Control Block along with the thread ID will be mapped to this Service Token for use with the Provider_Service() call.
  2. Every other call to Provider_Init() by the same thread will return the same Service Token mapped to that thread ID.
  3. Setting #bAllocInitBlock to TRUE in the call to Provider_Init() will allocate a new Init Control Block, even if called from the same thread.
  4. Init Control Block will be directly linked to the Service Token returned from Provider_Init().

pSvcIDService Identifier that describes the type of data privacy service desired. This is a string value and can be of maximum size 10.
The values currently can be:
  • NID
  • CCN
  • EML
  • COL
  • AGE
  • HASH
  • LKP

iSvcIdLenLength of Service Identifier.

pSvcdefPointer to the service initialization control block (DP_SVC_DEF) for the service being requested. It contains all the attributes that a Service needs to perform the requested function. This will initialize the internal variables of the Service Provider required for validating the data and executing the service routine(s). All the Services will share this common Control Block for initialization. Service Provider specific flags and attributes will be provided by means of parameters in the parameter list.

bAllocInitBlockThis will allocate a new Control Block holding the initialization data variables. Setting this to TRUE will allocate a new Init Control Block, create a new Service Token, map the Service Token to the Control Block and return the Service Token.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_Service ( int  iSvcToken,
short  sMethod,
DP_SVC_DEF pSvcDef,
DP_ROWSET_DEF pRowSet 
)

This function executes the Service Provider based on the Service Token supplied.

Parameters
iSvcTokenInteger that contains the TOKEN value returned from Provider_Init() call and to be used in subsequent Provider_Service() calls.

sMethodMethod to execute to perform the desired Service.

"Default" is the only value supported so far. Value ODPP_METHOD_DEFAULT signifies that the Method parameter, i.e. ODPP_OPR_METHOD, supplied during the call to Provider_Init() defines the type of Service to provide.

This value overrides the "Method" parameter supplied during Provider_Init().

pSvcDefPointer to the Service initialization control block (DP_SVC_DEF) for the Service being requested. It contains all the attributes that a Service needs to perform the requested function. This would typically be used to change/add a parameter to control the working of the Service Provider.
[NOT IMPLEMENTED AS OF NOW]

pRowSetPointer to a row or a list of rows carrying the data in table format.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_Term ( int  iSvcToken)

When the user has finished with a Service they will be required to make a termination call. This call will close the Service Provider and free all the memory allocated during Provider_Init(). It will also call the Service Provider Terminate function to enable the Service Provider to free any memory allocated by it during Init().

Parameters
iSvcTokenInteger that contains the TOKEN value returned from the Provider_Init() call.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_Enumerate ( DP_PRV_DEF pPrvDetails,
short *  pCount 
)

This function is used to list all the available Service Providers along with their details. This would provide a means to the calling code to enumerate all the available Service Providers.

The following rules will apply while searching for the Service Providers:

  1. Search will be performed in the current directory and in the directory specified in the path.
  2. Search will only try to find and load inbuilt Service Providers.
Parameters
pPrvDetailsPointer to a list of DP_PRV_DEF structures either in form of an array or a chain to return the details of available Service Providers. The initial call to this function will have this argument as NULL to return the number of available Service Providers.
The typical usage would be as follows:
  1. The Client calls the function with #pPrvDetails as NULL and #pCount which is a short integer pointer. The call will return the number of Service Providers enumerated in #pCount.
  2. The Client uses the value returned to allocate memory for #pCount number of DP_PRV_DEF structures.
  3. The Client again calls Provider_Enumerate() and passes the pointer to the list of DP_PRV_DEF structures to get the details of the Service Providers.

pCountA short integer pointer that will hold the number of Service Providers enumerated.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_GetErrorCount ( int  iSvcToken,
short *  pErrCount,
int *  pErrAreaLen 
)

This function will return the number of errors that have not yet been retrieved by the caller and the required length of the Error Control Block (ECB) storage area. The caller is responsible for both allocating and freeing this area and furnishing its pointer to the Provider_GetError() function.

Attention
This function should be called after the Provider_FrmwInit() call.
Parameters
iSvcTokenInteger that contains the TOKEN value returned from the Provider_Init() call.

pErrCountPointer to a short integer which gets set to the number of un-retrieved errors.

pErrAreaLenPointer to an integer which gets set to the size of the ECB return area.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_GetError ( int  iSvcToken,
DP_ECB pECB 
)

This function will return the oldest available Error Control Block (ECB) and associated tokens in the supplied area. The user can interpret the ECB or supply it to the Formatted Message Processor to retrieve a message in an available language. Each invocation of Provider_GetError() will return the information from the oldest ECB not previously returned in the supplied ECB storage area (the same ECB area can be used for every call).

Attention
This function should be called after the Provider_GetErrorCount() call.
Parameters
iSvcTokenInteger that contains the TOKEN value returned from the Provider_Init() call.

pECBPointer to the ECB storage area which has been allocated by the user.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_GetFormattedErrorMsg ( DP_ERR_MSG pErrMsg)

This function will return the formatted message from the data in the supplied Error Control Block (ECB).

Parameters
pErrMsgPointer to the DP_ERR_MSG structure which contains Error Control Block. It holds the error code, the row number where the error occurred and optionally any number of tokens containing specific details.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_GetFmtErrMsgEarly ( DP_ERR_MSG pErrMsg)

This function will return the formatted message corresponding to the error code. This function may be used to report errors without the ODPP framework being initialized.

Parameters
pErrMsgPointer to the DP_ERR_MSG structure. The iErrNum member of the DP_ERR_MSG structure must be set with the error code.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_TermErrors ( int  iSvcToken)

This function will release all Error Control Block (ECB) storage areas from errors not retrieved. The caller is required to invoke Provider_TermErrors() when exiting the error reporting loop. If unreported errors exist they will be discarded.

If Provider_TermErrors() is not invoked,

  1. any errors that occur during a subsequent invocation of the Service Provider will be appended to the existing list and the unreported errors will be considered in checking the discard limit specified using parameter ODPP_OPR_DISCARD_LIMIT.
  2. It will be invoked implicitly during Provider_Term().
Parameters
iSvcTokenInteger that contains the TOKEN value returned from the Provider_Init() call.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Provider_GetInfo ( int  iSvcToken,
short  sRequest,
void *  ptr,
int *  pBufLen 
)

This function is used to get Provider-specific information from the Service Provider. An application would typically call this function passing an information request number (#define in terms of C) defined, understood and processed by an individual Service Provider to get the return value. The return value will be defined by the Service Provider. It can be a string, number or a structure.

Parameters
iSvcTokenInteger that contains the TOKEN value returned from the Provider_Init() call.

sRequestShort integer which is a Provider-specific information request that is defined, understood and processed by the Service Provider.

ptrThis points to a Service Provider specific return type.

To get the bytes required for a particular request:
  • in the first call set this argument to NULL and #pBufLen to a valid integer pointer. The bytes required will be returned in #pBufLen.
  • Allocate memory to #ptr equal to the number of bytes returned in #pBufLen and call Provider_GetInfo() again.

pBufLenInteger pointer that will hold the length of the supplied buffer in bytes.
Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim

Example

RETVAL Provider_FrmwTerm ( void  )

This function will de-initialize the ODPP framework and all its components like the link list, mutex etc.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim

Example

RETVAL Parser_Init ( void  )

Initializes the ODPP Parser component. This function must be called prior to calling any of the other Parser-type functions.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim
RETVAL Parser_Service ( DP_PARAMS_DEF pParamDef)

Invokes the ODPP Parser and uses the ODPP input/output structure of DP_PARAMS_DEF. This function is used to convert the ODPP parameter string to ODPP Key-Value pairs i.e. DP_KVPAIR_DEF) array. If #pKeyValueArr is NULL and #iKeyValueArrSize value is 0 and the Provider_Service() method is called the parser returns the number of Key-Value pairs required in pParamDef->iKeyCount, #iKeyMaxBytes and #iValueMaxBytes have the max key and value bytes required which can be used to allocate #pKey and #pValue.

Parameters
pParamDefa pointer to the DP_PARAMS_DEF used as input to and output from the ODPP parser. Typically the caller will make two calls to Parser_Service(). Before the first call, DP_PARAMS_DEF->pKeyValueArr must be set to NULL and DP_PARAMS_DEF->iKeyValueArrSize must be set to 0. Upon return from the first call, iKeyCount will contain the count of the total number of DP_KVPAIR_DEF entries that must be provided on the second call, iKeyMaxBytes will contain the size of the largest key encountered and iValueMaxBytes will contain the size of the largest value encountered.

Before the second call, the caller must allocate an array/linked list of DP_KVPAIR_DEF containing at least iKeyCount entries and update pKeyValueArr with a pointer to this allocated array/linked-list and further update iKeyValueArrSize with the iKeyCount value. The iKeyMaxBytes value should be used to determine the size of the buffer to be allocated and pointed to by DP_KVPAIR_DEF->pKey. The iValueMaxBytes value should be used to determine the size of the buffer to be allocated and pointed by by DP_KVPAIR_DEF->pValue.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL Parser_GetErrorCount ( short *  pErrCount,
int *  pErrAreaLen 
)

Returns the number of parser-type errors and the required length of the Error Control Block (ECB) storage area. The caller is responsible for furnishing the pointer to the Parser_GetError() function as well as allocating and freeing the ECB.

Attention
This function should not be called while a service call running for the specified service token otherwise behavior is undefined
Parameters
pErrCountpointer to a short integer which contains the number of errors.

pErrAreaLenpointer to an integer which contains the size of the required area to hold error.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL Parser_GetError ( DP_ECB pECB)

Returns the oldest available Error Control Block (ECB) and associated tokens in the ECB. The user can interpret the ECB or supply it to the Formatted Message Processor, via Parser_GetFormattedErrorMsg() to retrieve a message in an available language. Each invocation of Parser_GetError() will return the information from the oldest ECB not previously returned in the supplied ECB storage area (the same ECB area can be used for every call).

Attention
This function should not be called while a service call running for the specified service token otherwise behavior is undefined.
Parameters
pECBpointer to the ECB storage area which has been previously allocated by the caller.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL Parser_GetFormattedErrorMsg ( DP_ERR_MSG pErrMsg)

Returns the formatted message from the data in the associated Error Control Block (ECB).

Parameters
pErrMsgpointer to the formatted error message in the error message (DP_ERR_MSG) structure

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL Parser_Term ( void  )

Cleans-up any resources and terminates the ODPP Parser

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure.
Author
IBM Optim
RETVAL ParmGen_Init ( void  )

Initializes the ODPP Parameter Generator. This function must be called prior to calling any of the other Parameter Generator-type functions.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_Service ( DP_PARMGEN_DEF pParmGen)

Invokes the ODPP Parameter Generator, takes an ODPP input/output structure of DP_PARMGEN_DEF. Within this structure is a pointer to an DP_PARAMS_DEF structure which contains parameter string and array/chain of key-value pairs (DP_KVPAIR_DEF) that contain the primary values returned from the ODPP Parser. The primary output from the ODPP Parameter Generator is a DP_SVC_DEF structure that becomes input to the ODPP service provider initialization.

Parameters
pParmGena pointer to the DP_PARMGEN_DEF completed by the ODPP parser upon return from the Parser_Service() method.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_Clean ( DP_SVC_DEF pSvcDef)

Frees all of the memory allocated by the parameter generator for the service definition (DP_SVC_DEF) parameters and embedded field definition structures (DP_FIELD_DEF).

Parameters
pSvcDefa pointer to the DP_SVC_DEF.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_GetErrorCount ( short *  pErrCount,
int *  pErrAreaLen 
)

Returns the number of parameter generator-type errors and the required length of the Error Control Block (ECB) storage area. The caller is responsible for furnishing the pointer to the ParmGen_GetError() function as well as allocating and freeing the ECB.

Parameters
pErrCountpointer to a short integer which contains the number of errors.

pErrAreaLenpointer to an integer which contains the size of the required area to hold error.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_GetError ( DP_ECB pECB)

Returns the oldest available Error Control Block (ECB) and associated tokens in the ECB. The user can interpret the ECB or supply it to the Formatted Message Processor, via ParmGen_GetFormattedErrorMsg() to retrieve a message in an available language. Each invocation of ParmGen_GetError() will return the information from the oldest ECB not previously returned in the supplied ECB storage area (the same ECB area can be used for every call).

Parameters
pECBpointer to the ECB storage area which has been previously allocated by the caller.

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_GetFormattedErrorMsg ( DP_ERR_MSG pErrMsg)

Returns the formatted message from the data in the associated Error Control Block (ECB).

Parameters
pErrMsgpointer to the formatted error message in the error message (DP_ERR_MSG) structure

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim
RETVAL ParmGen_Term ( void  )

cleans-up any resources and terminates the ODPP Parser

Returns
Returns ODPPSUCCESS if successful or a valid error code on failure
Author
IBM Optim