Optim Data Privacy Providers  11.7.0
 All Data Structures Files Functions Variables Macros Groups Pages
ODPPCmnApiX.h
Go to the documentation of this file.
1 
22 /*----------------------------------------------------------------------------
23 File Name: ODPPCmnApiX.H
24 
25 Purpose: Provides the declarations for user written ODPP service providers,
26  including the function and structure declarations. This file will
27  be used by developers writing their own ODPP service providers
28 
29 Functions:
30 
31  Name Purpose
32 
33 Structures:
34 
35  Name Purpose
36 
37 Author:
38  IBM Optim
39 ----------------------------------------------------------------------------*/
40 #include "ODPPCmnAPI.h"
41 
42 #ifndef __ODPPCMNAPI21_XH__
43 #define __ODPPCMNAPI21_XH__
44 
45 
46 /* Eye catcher for DP_FIELD_DEF_X */
50 #define DP_FIELD_DEF_X_EC "FLDX"
51 
52 /* Eye catcher for DP_INIT_OP_DEF_X */
56 #define DP_INIT_OP_DEF_X_EC "OPRX"
57 
58 /* Eye catcher for DP_SVC_DEF_X */
62 #define DP_SVC_DEF_X_EC "SVCX"
63 
64 /* Eye catcher for DP_PRV_DEF_X */
68 #define DP_PRV_DEF_X_EC "PRVX"
69 
70 /* Eye catcher for DP_BLK_DEF_X */
74 #define DP_BLK_DEF_X_EC "BLKX"
75 
76 /* Eye catcher for DP_LDS_FLD_DEF_X */
80 #define DP_LDS_FLD_DEF_X_EC "LFLX"
81 
82 /* Eye catcher for DP_LDS_ROW_DEF_X */
86 #define DP_LDS_ROW_DEF_X_EC "LDRX"
87 
88 
89 //---------------------------------------------------------------
90 // Name: DP_FIELD_DEF_X
91 //
92 // Description:
93 //
94 // A Field Definition should describe all of the attributes of
95 // a field. A field descriptor used for input will describe
96 // all of the attributes of that input as well as setting a
97 // pointer to that field. A field descriptor used for output
98 // will set a pointer to where the data should be placed, and
99 // attributes should be set as to what form the data is in
100 // that the caller expects. Masked data can be returned either
101 // by modifying the Source or by the Target
102 // --------------------------------------------------------------
116 typedef struct DP_FIELD_DEF_X
117 {
133  *pNext; // Next element in chain of DP_FIELD_DEFINE
134 
146  char cEyeCatcher[4]; // Eye catcher
147 
159  short sStructVer; // version of this structure
160 
172  short sStructLen; // length of this structure
173 
188  short sDatatype; // data type of the input data
189 
203  int iLength; // column length in case of string data types
204 
216  int iPrecision; // precision of the input decimal data,
217  // and precesion of ORA_VARNUM
218 
230  short sScale; // scale of the input decimal data
231 
243  int iCodePage; // CodePage of data to be passed
244 
256  char cDBMSType; // DBMSType of data to be passed
257 
269  ODPP_WCHAR *pColNameW; // WideChar Column Name.
270 
282  char *pColNameA; // SBCS/MBCS Column Name.
283 
295  int iColNameWBytes; //Size of Wide Char Column Name buffer in bytes
296 
308  int iColNameABytes; //Size of SBCS/MBCS Column Name buffer in bytes
310 
311 /*-------------------------------------------------------------*
312  * Name: DP_INIT_OP_DEF_X *
313  *
314  * Description: *
315  *
316  * Init Operand Definition contains all the initialization *
317  * operands required for the current service *
318  *------------------------------------------------------------*/
332 typedef struct DP_INIT_OP_DEF_X
333 {
346  *pNext; //Pointer to next element in chain of operands
347 
359  char cEyeCatcher[4]; // Eyecatcher
360 
372  short sStructVer; // version of this structure
373 
385  short sStructLen; // length of this structure
386 
387  // Parameter ID
388 
400  unsigned short usParameterID; // ODPP Parameter
401 
402  // Parameter names. Used in situations when there is no parameter ID
403  // usParameterID = 0 when a parameter name is passed
404 
416  ODPP_WCHAR *pParamNameW; // Wide Char Parameter Name
417 
429  char *pParamNameA; // SBCS/MBCS Parameter Name
430 
442  char cPrmNameDBMSType; // DBMS type of parameter name
443 
455  int iPrmNameCodePage; // Code page of parameter name
456 
468  int iPrmNameBufBytes; // Size of parameter name buffer in bytes.
469  //Parameter values
470 
482  int iValueSubType; // Type of parameter value as defined below
483  // any value except these are user defined values
484  // and indicates the use of pUserVal.
485  //================================================
486  // Custom service providers can define their own
487  // values for their usage
488  //================================================
489 
490 
491 
503  char cValDBMSType; // DBMS type of the parameter value
504 
516  int iValCodePage; // Code page of the parameter value
517 
529  int iValABytes; // Size of pValA buffer in bytes.
530 
542  int iValWBytes; // Size of pVal buffer in bytes.
543 
555  unsigned int uiVal; // numeric parameter value
556 
568  ODPP_WCHAR *pVal; // wide-string param value
569 
581  char *pValA; // SBCS/MBCS string param value
582 
594  void *pUserVal; // User defined parameter value
596 
597 //----------------------------------------------------------------------
598 // Name: DP_SVC_DEF_X
599 // Description:
600 // The Service Definition contains the operands and field definition lists
601 // and the other service definition type initialization parameters.
602 //----------------------------------------------------------------------
603 
604 
617 typedef struct DP_SVC_DEF_X
618 {
630  char cEyeCatcher[4]; // Eye Catcher
631 
643  short sStructVer; // version of this structure
644 
656  short sStructLen; // length of this structure
657 
669  char bRefreshSVCDef; // [For Future Use] When TRUE, this
670  // causes the existing the existing
671  // service definition to be updated
683  char bCopyToDest; // Copy the masked data to destination buf
684 
696  short sParamCount; // Count of elements in pOperands
697 
709  short sFldCount; // Count of elements in pFldDef
710 
711  // Default Code Page and DBMS Type for Parameter names and values
712  //
713  // Note: Codepage/DBMSType values set for individual parameters/fields
714  // take precedence over these value
715 
727  char cCtrlDataDBMSType; // DBMSType of control Data
728  // in DP_INIT_OP_DEF_X and DP_FIELD_DEF_X
729 
741  int iCtrlDataCP; // Code page of control data
742  // in DP_INIT_OP_DEF_X and DP_FIELD_DEF_X
755  *pParams; // Pointer to array or first element in
756  // chain of DP_INIT_OP_DEF_X. Provides all
757  // needed operands.
758 
771  *pFldDef; // Pointer to array or first element in
772  // chain of DP_FIELD_DEF_X.
773 
774 }DP_SVC_DEF_X;
775 
776 //----------------------------------------------------------------------
777 // Name: DP_SRCCOL_DEF_X
778 // Description:
779 // Source column information. Will contain either the col index or name.
780 // If both or neither is provided, it will be an error
781 //----------------------------------------------------------------------
794 typedef struct DP_SRCCOL_DEF_X
795 {
808  *pNext; // Pointer to next element in chain of DP_SRCCOL_DEF_I
809 
821  short sColIndex; // Index of the column containing source data.
822 
835  *pSrcFldDef; // Pointer to User supplied Source Field Definition
837 
838 //----------------------------------------------------------------------
839 // Name: DP_BLK_DEF_X
840 // Description:
841 // Control block for an individual provider initialization.
842 // Supplies all of the information a provider needs to function.
843 //----------------------------------------------------------------------
856 typedef struct DP_BLK_DEF_X
857 {
869  char cEyeCatcher[4]; // Eye Catcher
870 
882  short sStructVer; // version of this structure
883 
895  short sStructLen; // length of this structure
896 
908  char bCopyToDest; // When TRUE, output is copied to dest buffer.
909  // else output is copied to the source buffer
910  char bUserPrv; // When TRUE, this control block
911  // is being initialized for a
912  // user-created service provider
913 
914 
915  short bRefCount; // Number of threads using this control block
916 
928  short sFlags; // Flags controlling the behaviour of providers
929  // specified for parameter ODPP_OPR_FLAGS
930  // For a list of flags see ODPPCmnOprH.h
931 
944  short sMethod; //ODPP_METHOD_MASK/ODPP_METHOD_RANDOM/ODPP_METHOD_HASH
945 
957  short sTraceLevel;
958 
970  short sSrcColCount; // Source column count
971 
983  short sDiscardLimit; // Total number of errors after which ODPP
984  // error subsystem should fail the
985  // Provider_Service call
986 
998  char cSysDBMSType; // System specific DBMSType
999 
1011  int iSysCodePage; // System specific CodePage. By default
1012  // this is the OS default code page
1013 
1025  int iSvcToken; // Service Provider Service Token as
1026  // assigned by the ODPP Service Manager
1039  *pFldDef; // Pointer to an array first element in
1040  // the chain of DP_FIELD_DEF_X(s)
1041 
1042 
1054  void *pExt; // Placeholder to hold service provider
1055  // specific control data.
1056  // Allocated and Managed by the service provider. Service providers can use
1057  // the above pointer pExt to preserve their instance specific data. This
1058  // pointer lives till service provider is terminated. Cleaning this area
1059  // will be responsibility of the individual Service Provider
1060 
1072  void *pSrvMgrBlk; // [Future Use] Service Manager specific block.
1073  // This will be used to provide any ODPP specific
1074  // functionality to service providers for e.g.
1075  // Data Conversion, Error Recording etc.
1076 
1089  SrcCol; // Source column link list
1090 
1091 }DP_BLK_DEF_X;
1092 
1093 
1094 //----------------------------------------------------------------------
1095 // Name: DP_LDS_FLD_DEF_X
1096 // Description:
1097 // Field definition representing an ODPPLDS field.
1098 // This would be used in an ODPPLDSGetData API call
1099 // to provide search and field(s) to the provider
1100 //----------------------------------------------------------------------
1111 typedef struct DP_LDS_FLD_DEF_X
1112 {
1125  *pNext; // Pointer to next element in
1126  // chain of DP_LDS_FLD_DEF_I
1138  char cEyeCatcher[4]; // Eye catcher
1139 
1151  short sStructVer; // version of this structure
1152 
1164  short sStructLen; // length of this structure
1165 
1177  char bNull; // Null indicator
1178 
1190  int iBufLen; // Max length of pBuf in Bytes
1191 
1203  int iErrorCode; // Error code for this data
1204 
1216  int iSrcBufBytes; // This tells the number of C buffer bytes
1217  // required to hold the source data.
1218 
1230  int iLdsBufBytes; // This tells the number of C buffer bytes
1231  // required to hold the LDS data.
1232 
1244  int iColPos; // Ordinal position of Column in lookup table
1245 
1257  int iColPreserveOpt; // Preserve Options for replacement columnns
1258 
1271  *pFldDefSrc; // Field definition sent by the caller
1272 
1285  *pFldDefLDS; // Field definition retrieved from the
1286  // LDS library
1298  unsigned char *pBuf; // buffer for field data
1300 
1301 
1302 //----------------------------------------------------------------------
1303 // Name: DP_LDS_ROW_DEF_X
1304 // Description:
1305 // LDS Row definition representing a list of ODPPLDS fields.
1306 // Used in the ODPPLDSGetDataMultiple API call to fetch multiple
1307 // rows similar to ...GetData
1308 //----------------------------------------------------------------------
1319 typedef struct DP_LDS_ROW_DEF_X
1320 {
1333  *pNext; // Pointer to next element in chain of DP_LDS_ROW_DEF_I
1345  char cEyeCatcher[4]; // Eye Catcher
1346 
1358  short sStructVer; // version of this structure
1359 
1371  short sStructLen; // length of this structure
1372 
1384  short sCount; // Count of DP_LDS_FLD_DEF_X(s)
1385  // in form of a chain of elements
1386 
1398  RETVAL iErrCode; // Error code for this row
1399 
1412  *pLdsFld; // Pointer to the first element in the
1413  // chain of DP_LDS_FLD_DEF_X(s).
1415 
1416 #ifdef _WIN32
1417  /* These are individual service provider interface APIs declares */
1418  typedef RETVAL (__stdcall *PINITX) (
1419  DP_BLK_DEF_X *pCtrlBlk,
1420  DP_SVC_DEF_X *pSvcDef
1421  );
1422 
1423  typedef RETVAL (__stdcall *PSERVICEX) (
1424  short sMethod,
1425  DP_BLK_DEF_X *pCtrlBlk,
1426  DP_ROWSET_DEF *pRowSet
1427  );
1428 
1429  typedef RETVAL (__stdcall *PTERMINATEX)(
1430  DP_BLK_DEF_X *pCtrlBlk
1431  );
1432 
1433  typedef RETVAL (__stdcall *PGETERRORMSGX)(
1434  RETVAL ErrorCode,
1435  int iLanguage,
1436  ODPP_WCHAR *pErrMsg
1437  );
1438 
1439  typedef RETVAL (__stdcall *PGETINFOX) (
1440  DP_BLK_DEF_X *pCtrlBlk,
1441  short sRequest,
1442  void *ptr,
1443  int *pBufLen
1444  );
1445 
1446  /*These are LDS interface APIs declares */
1447  typedef RETVAL (__stdcall *PENVINITX) (void);
1448 
1449  typedef RETVAL (__stdcall *PCONNECTX) (
1450  DP_BLK_DEF_X *pCtrlBlk,
1451  int *pLdsToken,
1452  DP_INIT_OP_DEF_X *pOperands,
1453  short sOprCount
1454  );
1455 
1456  typedef RETVAL (__stdcall *PDISCONNECTX)(
1457  int iLdsToken
1458  );
1459 
1460  typedef RETVAL (__stdcall *PGETCOLINFOX)(
1461  int iLdsToken,
1462  DP_LDS_FLD_DEF_X *pLdsColDefs,
1463  short sFldCount,
1464  DP_INIT_OP_DEF_X *pOperands,
1465  short sOprCount
1466  );
1467 
1468  typedef RETVAL (__stdcall *PGETDATAX) (
1469  int iLdsToken,
1470  DP_LDS_FLD_DEF_X *pSearchCols,
1471  DP_LDS_ROW_DEF_X *pDstRows,
1472  DP_INIT_OP_DEF_X *pOperands,
1473  short sOprCount,
1474  int iMaxRows,
1475  char bFetchMultiple,
1476  int *pRowsFetched
1477  );
1478 
1479  typedef RETVAL (__stdcall *PCLOSEFETCHX)(
1480  int iLdsToken
1481  );
1482 
1483  typedef RETVAL (__stdcall *PGETLDSINFOX)(
1484  int iLdsToken,
1485  DP_INIT_OP_DEF_X *pLkpOperands,
1486  short sOprCount,
1487  void *ptr
1488  );
1489 
1490  typedef RETVAL (__stdcall *PENVTERMX) (void);
1491 
1492 #else
1493  /* These are individual service provider interface APIs declares */
1494  typedef RETVAL ( *PINITX) (
1495  DP_BLK_DEF_X *pCtrlBlk,
1496  DP_SVC_DEF_X *pSvcDef
1497  );
1498 
1499  typedef RETVAL ( *PSERVICEX) (
1500  short sMethod,
1501  DP_BLK_DEF_X *pCtrlBlk,
1502  DP_ROWSET_DEF *pRowSet
1503  );
1504 
1505  typedef RETVAL ( *PTERMINATEX) (
1506  DP_BLK_DEF_X *pCtrlBlk
1507  );
1508 
1509  typedef RETVAL ( *PGETERRORMSGX) (
1510  RETVAL ErrorCode,
1511  int iLanguage,
1512  ODPP_WCHAR *pErrMsg
1513  );
1514 
1515  typedef RETVAL ( *PGETINFOX) (
1516  DP_BLK_DEF_X *pCtrlBlk,
1517  short sRequest,
1518  void *ptr,
1519  int *pBufLen
1520  );
1521 
1522  /* These are LDS interface APIs declares */
1523  typedef RETVAL ( *PENVINITX) (void);
1524 
1525  typedef RETVAL ( *PCONNECTX) (
1526  DP_BLK_DEF_X *pCtrlBlk,
1527  int *pLdsToken,
1528  DP_INIT_OP_DEF_X *pOperands,
1529  short sOprCount
1530  );
1531 
1532  typedef RETVAL ( *PDISCONNECTX) (
1533  int iLdsToken
1534  );
1535 
1536  typedef RETVAL ( *PGETCOLINFOX) (
1537  int iLdsToken,
1538  DP_LDS_FLD_DEF_X *pLdsColDefs,
1539  short sFldCount,
1540  DP_INIT_OP_DEF_X *pOperands,
1541  short sOprCount
1542  );
1543 
1544  typedef RETVAL ( *PGETDATAX) (
1545  int iLdsToken,
1546  DP_LDS_FLD_DEF_X *pSearchCols,
1547  DP_LDS_ROW_DEF_X *pDstRows,
1548  DP_INIT_OP_DEF_X *pOperands,
1549  short sOprCount,
1550  int iMaxRows,
1551  char bFetchMultiple,
1552  int *pRowsFetched
1553  );
1554 
1555  typedef RETVAL ( *PCLOSEFETCHX) (
1556  int iLdsToken
1557  );
1558 
1559  typedef RETVAL ( *PGETLDSINFOX) (
1560  int iLdsToken,
1561  DP_INIT_OP_DEF_X *pLkpOperands,
1562  short sOprCount,
1563  void *ptr
1564  );
1565 
1566  typedef RETVAL ( *PENVTERMX) (void);
1567 
1568 #endif //#ifdef _WIN32
1569 
1570 //----------------------------------------------------------------------
1571 // Name: DP_PRVAPI_DEF_X
1572 // Description: Holds the service providers api pointers
1573 //----------------------------------------------------------------------
1574 typedef struct DP_PRVAPI_DEF_X
1575 {
1576  PINITX pInit; // Init API pointer
1577  PSERVICEX pService; // Service API pointer
1578  PTERMINATEX pTerm; // Terminate API pointer
1579  PGETERRORMSGX pGetErrMsg; // GetErrorMessage API pointer
1580  PGETINFOX pGetInfo; // GetInfo API pointer
1581 }DP_PRVAPI_DEF_X;
1582 
1583 //#ifdef _DECLARE_SRVPRV_INTERFACE
1584 
1608 RETVAL Init
1609  (
1610  DP_BLK_DEF_X *pCtrlBlk,
1611  DP_SVC_DEF_X *pSvcDef
1612  );
1613 
1639 RETVAL Service
1640  (
1641  short sMethod,
1642  DP_BLK_DEF_X *pCtrlBlk,
1643  DP_ROWSET_DEF *pRowSet
1644  );
1645 
1658  (
1659  DP_BLK_DEF_X *pCtrlBlk
1660  );
1661 
1662 RETVAL GetErrorMsg
1663  (
1664  RETVAL ErrorCode,
1665  int iLanguage,
1666  ODPP_WCHAR *pErrMsg
1667  );
1668 
1669 
1695 RETVAL GetInfo
1696  (
1697  DP_BLK_DEF_X *pCtrlBlk,
1698  short sRequest,
1699  void *ptr,
1700  int *pBufLen
1701  );
1702 //#endif //_DECLARE_SRVPRV_INTERFACE
1703 
1704 /* These are LDS interface APIs declares */
1705 //#ifdef _DECLARE_LDS_INTERFACE
1706 
1714  RETVAL ODPPLDSEnvInit(void);
1715 
1716 
1740  DP_BLK_DEF_X *pCtrlBlk,
1741  int *pLdsToken,
1742  DP_INIT_OP_DEF_X *pOperands,
1743  short sOprCount
1744  );
1745 
1746 
1759  int iLdsToken
1760  );
1761 
1797  int iLdsToken,
1798  DP_LDS_FLD_DEF_X *pSearchCols,
1799  DP_LDS_ROW_DEF_X *pDstRows,
1800  DP_INIT_OP_DEF_X *pOperands,
1801  short sOprCount,
1802  int iMaxRows,
1803  char bFetchMultiple,
1804  int *pRowsFetched
1805  );
1806 
1820  int iLdsToken
1821  );
1822 
1823 
1852  int iLdsToken,
1853  DP_LDS_FLD_DEF_X *pLdsColDefs,
1854  short sFldCount,
1855  DP_INIT_OP_DEF_X *pOperands,
1856  short sOprCount
1857  );
1858 
1859  /*
1860  This will be used to retrieve information from LDS for e.g. max Hash Value (maximum sequence value in
1861  case of Hash) during Hash Lookup or anything else. This function will be passed predefined operands for
1862  which data is required LDS is expected to fill in the necessary information for those operands. There could
1863  also be other operands passed along with which are needed to get the required information. Operands will
1864  be defined by the Lookup Provider.
1865 
1866 
1867  @param iLdsToken
1868  LDS TOKEN for the current session.
1869  <BR><BR>
1870 
1871  @param pLkpOperands
1872  Pointer to the #DP_INIT_OP_DEF_X block which contains all the initialization parameter for the Lookup service provider.
1873 
1874  @param sOprCount
1875  Count of total number of initialization parameter
1876 
1877 
1878  @return Returns ODPPSUCCESS if successful or a valid error code on failure.
1879 
1880 
1881  */
1882  RETVAL ODPPLDSGetInfo(
1883  int iLdsToken,
1884  DP_INIT_OP_DEF_X *pLkpOperands,
1885  short sOprCount,
1886  void *ptr
1887  );
1888 
1889  /*
1890  Deinitializes the LDS library.
1891 
1892  @return Returns ODPPSUCCESS if successful or a valid error code on failure.
1893 
1894  */
1895  RETVAL ODPPLDSEnvTerm(void);
1896 //#endif //_DECLARE_LDS_INTERFACE
1897 
1898 #endif //__ODPPCMNAPI21_XH__