Optim Data Privacy Providers  11.3.0
 All Data Structures Files Functions Variables Macros Groups Pages
ODPPCmnAPI.h
Go to the documentation of this file.
1 
16 /*-----------------------------------------------------------------------------
17 File Name: ODPPCmnAPI.H
18 
19 Purpose: Provides the Interface declarations for ODPP, including the
20  function declarations and structure declarations. This file is
21  supposed to be used by the external applications using ODPP.
22 
23  Only declarations that are part of the API should be declared
24  here.
25 
26 Author:
27  IBM Optim
28 ----------------------------------------------------------------------------*/
29 #ifndef __ODPPCMNAPIH__
30 #define __ODPPCMNAPIH__
31 
32 /*============================================================================
33  ODPP VERSION NUMBER,
34  THIS SHOULD BE USED FOR ALL STRUCTURES DECLARATIONS
35  ============================================================================*/
36 #define ODPP_CUR_VERSION 21
37 #ifndef ODPP_WCHAR
38  #define ODPP_WCHAR wchar_t
39 #endif
40 
44 #define ODPPSVCIDLENGTH 10
45 
48 #define ODPP_PROVIDER_ID_MAX_LENGTH ODPPSVCIDLENGTH
49 
52 #define RETVAL int
53 
56 #define ODPP_MBCS_CHAR_BYTES 6
57 
60 #define ODPP_PROVIDER_NAME_LEN 50
61 
64 #define ODPP_PROVIDER_DESCRIPTION_LEN 256
65 
68 #define ODPP_MAX_ERR_MSG_SRC_LENGTH (512) + 10
69 
72 #define ODPP_MAX_ERR_MSG_TEXT_LENGTH (512*2) + 50
73 
76 #define ODPP_MAX_ERR_MSG_BODY_LENGTH (512*3) + 50
77 
80 #define ODPP_MAX_PATH_LEN 2048
81 
84 #define ODPP_MAX_FILENAME_LEN 1024
85 
86 
87 //==========================================================================
88 // ODPP PARSER SPECIFIC DEFINES, STRUCTURES
89 //==========================================================================
90 
94 #define DP_PARSER_ERRMSG_MAX_LEN 512
95 
96 //List of Env codes
100 #define ENV_OPTDIS 'D'
101 
105 #define ENV_UDF 'U'
106 
110 #define ENV_LUA 'L'
111 
112 // List of DBMS Type codes for MBCS/SBCS environments
113 #define RDB_DB2MVS '2' // DB2 MVS
114 #define RDB_DB2CS 'C' // DB2 Common Server
115 
119 #define RDB_ORACLE 'O' // Oracle
120 
123 #define RDB_SYBASE 'S' // Sybase
124 
127 #define RDB_ODBC 'M' // ODBC (syncpoint)
128 
131 #define RDB_INFORMIX 'I' // Informix
132 
135 #define RDB_RDB 'R' // Internal
136 
139 #define RDB_DB2ZOS RDB_DB2MVS // DB2 zOS (used to be MVS)
140 
143 #define RDB_DB2LUW RDB_DB2CS // DB2 LUW (used to be CS (client server) then UDB (univ. data base) now LUW (Linux Unix Windows))
144 
147 #define RDB_SQLSERVER 'G' // MS SQL Server
148 
151 #define RDB_ANY '*' // Used when passing DBMS code to ICU functions to mean "no specific DBMS" or "first match"
152 
155 #define RDB_NONE 'N' // Used when passing DBMS code to ICU functions to mean "no DBMS", only use process-specific converters
156 
159 #define RDB_TERADATA 'T' // Teradata
160 
161 //===========================================================================
162 // IMPORTANT NOTE
163 //===========================================================================
164 // If specifying CodePage value at the parent structure level for structures
165 // DP_SVC_DEF/DP_FRMW_PARAMS_DEF set the code page member of child
166 // structures DPFD_MC_SS/DPPRM_VAL_MC_SS/DPPRM_NAME_MC_SS to
167 // ODPP_CODE_PAGE_NONE.
168 // ==========================================================================
169 // Codepage value set in the child structure(s) always take precedence over
170 // codepage value set in parent structure
171 // ==========================================================================
175 #define ODPP_CODE_PAGE_NONE 0x80000000
176 
180 #define PARAM_VAL_NONE 0 //This parameters has no value
181 
184 #define PARAM_VAL_NUM 1 //Parameter value is numeric
185 
188 #define PARAM_VAL_WC 2 //Parameter value is Wide Char string
189 
192 #define PARAM_VAL_MC 3 //Parameter value is SBCS/MBCS
193 
194 /*===========================================================================
195  IMPORTANT NOTE
196  ============================================================================
197  USE THE BELOW MACRO TO INITIALIZE ODPP STRUCTURES OBJECTS. IT IS IMPORTANT
198  AS THIS MACRO ADD THE VERSION INFO TO THE STRUCTURES
199 
200  ===========================================================================*/
201 #define EC1(T) T ## _EC
202 #define EYE_CATCHER(TYPE) EC1(TYPE)
203 
207 #define INITIALIZE_ODPP_STRUCT(OBJ, TYPE) \
208  {OBJ.sStructVer = ODPP_CUR_VERSION; \
209  memcpy(OBJ.cEyeCatcher,EYE_CATCHER(TYPE),sizeof(OBJ.cEyeCatcher));}
210 
214 #define INITIALIZE_ODPP_STRUCT_PTR(OBJ_PTR, TYPE) \
215  {OBJ_PTR->sStructVer = ODPP_CUR_VERSION; \
216  memcpy(OBJ_PTR->cEyeCatcher,EYE_CATCHER(TYPE),sizeof(OBJ_PTR->cEyeCatcher));}
217 
221 #define DP_ECB_EC "ECBD"
222 
225 #define DP_FIELD_DATA_DEF_EC "DATA"
226 
229 #define DP_ROW_DEF_EC "ROWD"
230 
233 #define DP_ROWSET_DEF_EC "RWST"
234 
237 #define DP_FIELD_DEF_EC "FLDX"
238 
241 #define DP_INIT_OP_DEF_EC "OPRX"
242 
245 #define DP_FRMW_PARAMS_DEF_EC "FRPX"
246 
249 #define DP_SVC_DEF_EC "SVCX"
250 
253 #define DP_PRV_DEF_EC "PRVX"
254 
257 #define DP_ERR_MSG_EC "EMSG"
258 /* Eye catcher for DP_PARMGEN_DEF */
262 #define DP_PARMGEN_DEF_EC "PGDA"
263 
264 /* Eye catcher for DP_PARAMS_DEF */
268 #define DP_PARAMS_DEF_EC "PRMA"
269 
270 /* Eye catcher for DP_KVPAIR_DEF */
274 #define DP_KVPAIR_DEF_EC "KVPA"
275 
276 /*============================================================================
277  Structure declarations to be used by the Optim Data Privacy Provider API's
278  ===========================================================================*/
289 typedef struct s_odbc_date
290 {
299  signed short Year;
300 
309  unsigned short Month;
310 
319  unsigned short Day;
321 
332 typedef struct s_odbc_time
333 {
342  unsigned short Hour;
343 
352  unsigned short Minute;
353 
362  unsigned short Second;
364 
375 typedef struct s_odbc_timestamp
376 {
385  signed short Year;
386 
395  unsigned short Month;
396 
405  unsigned short Day;
406 
415  unsigned short Hour;
416 
425  unsigned short Minute;
426 
435  unsigned short Second;
436 
445  unsigned int Fraction;
447 
448 
449 #define ODPPTOKID(s) ODPP_TOKID_ ## s ,
450 
451 /* Token Identifiers */
452 enum DP_ETOKENID {
453  ODPP_TOKEN_NODE_UNUSED,
454 #include "ODPPTokIdsH.h"
455  ODPP_NUM_TOKENS
456 };
457 #undef ODPPTOKID
458 
472 typedef struct s_DP_Token
473 {
485  enum DP_ETOKENID eId;
486 
498  ODPP_WCHAR *pValue;
499 } DP_TOKEN;
500 
501 
515 typedef struct DP_ECB
516 {
528  struct DP_ECB *pNext; // Pointer to next ECB
529 
541  char cEyeCatcher[4]; // Eye catcher
542 
554  short sStructVer; // Version of this structure
555 
567  short sStructLen; // Length of this structure
568 
580  short sNumTokens; // Number of tokens
581 
593  int iErrCode; // Error Code
594 
606  int iRowNum; // Input row
607 
619  DP_TOKEN aToken[1]; // Error tokens
620 } DP_ECB;
621 
635 typedef struct DP_FIELD_DATA_DEF
636 {
723  *pNext; // Next element in chain of DP_FIELD_DATA_DEF
724 
736  unsigned char cEyeCatcher[4]; // eye catcher
737 
749  short sStructVer; // version of this structure
750 
762  short sStructLen; // length of this structure
763 
778  char bSrcNull; // Source Null indicator
779 
792  char bDstNull; // Dest Null indicator
793 
816  int iSrcBufLen; // length, or max length of source buffer
817  // in bytes. On Return in case bCopyToDest of SvcDef
818  // is FALSE this variable will be updated to
819  // contain the size of the output data in bytes
820 
838  int iDstBufLen; // length, or max length of dest buffer
839  // in bytes. On Return in case bCopyToDest of SvcDef
840  // is TRUE this variable will be updated to
841  // contain the size of the output data in bytes
842 
855  int iOutBufLen; // bytes of the data returned in the pDstBuf. In case of
856  // ODPPSUCCESS, this is the bytes of return data. If
857  // RETURN CODE = ODPP_DATACNV_ERR_DATA_TRUNCATED, this
858  // is the max bytes required to hold the return data
859 
871  int iErrorCode; // Error code for this data
872 
892  unsigned char *pSrcBuf; // buffer to source buffer
893 
913  unsigned char *pDstBuf; // buffer to destination buffer
915 
916 
917 //---------------------------------------------------------------------
918 // Name: DP_ROW_DEF
919 // Description:
920 // The Row Definition encapsulates the DP_FIELD_DEFINE struct
921 // to provide a 2-dimensional array of DP_FIELD_DEFINE
922 //
923 //********************IMPORTANT****************************************
924 // bProcessed should be FALSE (i.e. 0) for each row
925 // in the first Service Call.
926 //********************IMPORTANT****************************************
927 //---------------------------------------------------------------------
928 
942 typedef struct DP_ROW_DEF
943 {
1018  struct DP_ROW_DEF
1019  *pNext; // Next element in chain of DP_ROW_DEF
1020 
1032  unsigned char cEyeCatcher[4]; // eye catcher
1033 
1045  short sStructVer; // version of this structure
1046 
1058  short sStructLen; // length of this structure
1059 
1071  char bProcessed; // TRUE if the ROW processed earlier
1072  // This should be FALSE (i.e. 0) for each
1073  // row in first Service Call.
1074 
1086  char bHasError; // TRUE if any column(s) has an error code
1087 
1099  short sCount; // Count of DP_FIELD_DATA_DEF(s) either
1100  // in form of an array or a chain of
1101  // elements
1102 
1115  *pFldDataDefine; // Pointer to an array of
1116  // DP_FIELD_DATA_DEF(s) OR pointer
1117  // to the first element of chain of
1118  // DP_FIELD_DATA_DEF.
1119 }DP_ROW_DEF;
1120 
1121 
1122 //---------------------------------------------------------------------
1123 // Name: DP_ROWSET_DEF
1124 // Description:
1125 // The Rowset Definition encapsulates a batch of DP_ROW_DEFs
1126 //---------------------------------------------------------------------
1140 typedef struct DP_ROWSET_DEF
1141 {
1153  unsigned char cEyeCatcher[4]; // Eye catcher
1154 
1166  short sStructVer; // version of this structure
1167 
1179  short sStructLen; // length of this structure
1180 
1192  int iCount; // Count of DP_ROW_DEF(s) either in form of
1193  // an array or a chain of elements
1194 
1206  int iLastPrcsRow; // Index of the last row processed. Needed for
1207  // restart after discard limit failure.
1208  // This should be 0 for first Service Call.
1209 
1221  DP_ROW_DEF *pRowDefine; // Pointer to an array of DP_ROW_DEF(s)
1222  // OR pointer to the first element of chain of
1223  // DP_ROW_DEF.
1224 }DP_ROWSET_DEF;
1225 
1226 //----------------------------------------------------------------------
1227 // Name: DPFD_WC_SS
1228 // Description:
1229 // The field definition for the wide-character (Unicode)
1230 // sub-structure for DP_FIELD_DEF
1231 //----------------------------------------------------------------------
1245 typedef struct DPFD_WC_SS
1246 {
1258  ODPP_WCHAR *pColName; // Pointer to column name
1259  // expressed in wide character (Unicode) format
1260 }DPFD_WC_SS;
1261 
1262 //----------------------------------------------------------------------
1263 // Name: DPFD_MC_SS
1264 // Description:
1265 // The field definition for the mixed-character (e.g. SBCS/MBCS)
1266 // sub-structure for DP_FIELD_DEF
1267 //----------------------------------------------------------------------
1281 typedef struct DPFD_MC_SS
1282 {
1294  char cColNameDBMSType; // DBMS type of the column name
1295 
1308  int iColNameCodePage; // Code page of the column name
1309  //Set iColNameCodePage to ODPP_CODE_PAGE_NONE to use code page and DBMSType
1310  //supplied by the parent structure DP_SVC_DEF
1311 
1323  char *pColName; // Pointer to column name
1324  // expressed in mixed (SBCS/MBCS) character format
1325 }DPFD_MC_SS;
1326 
1327 //----------------------------------------------------------------------
1328 // Name: DP_FIELD_DEF
1329 // Description:
1330 // The field definition describes all of the attributes of a field
1331 //----------------------------------------------------------------------
1345 typedef struct DP_FIELD_DEF
1346 {
1407  *pNext; // Pointer to next element in chain of DP_FIELD_DEF
1408 
1420  char cEyeCatcher[4]; // Eye catcher
1421 
1433  short sStructVer; // Version of this structure
1434 
1446  short sStructLen; // Length of this structure
1447 
1462  short sDatatype; // Data type of the input data
1463 
1477  int iLength; // Column length (for string types)
1478 
1490  int iPrecision; // Precision (for decimal types) and ORA_VARNUM
1491 
1503  short sScale; // Scale (for decimal data)
1504 
1516  int iDataCodePage; // Code page of the data
1517 
1529  char cDataDBMSType; // DBMS type of the data
1530 
1542  int iColNameBytes; // Size, in bytes, of the column name
1543 
1562  char cSubType; // Type of sub-structure
1563  // (W or blank or 0=wide-char, M=mixed (SBCS/MBCS) char
1564 
1565 
1566  union // Union of sub-structures
1567  {
1580  DPFD_WC_SS *pWC; // Pointer to wide character (Unicode) sub-structure
1581 
1594  DPFD_MC_SS *pMC; // Pointer to mixed character (SBCS/MBCS) sub-structure
1595  }COLNAME_SS CN;
1596 
1597 } DP_FIELD_DEF;
1598 
1599 //----------------------------------------------------------------------
1600 // Name: DPPRM_NAME_WC_SS
1601 // Description:
1602 // Wide-character (Unicode) parameter name sub-structure for DP_INIT_OP_DEF
1603 //----------------------------------------------------------------------
1604 
1605 /*
1606  - Name: #DPPRM_NAME_WC_SS
1607 
1608  - Use: <BR>
1609  This structure is used to pass on the wide character (Unicode) initialization parameter name to the Provider_Init() API as a child member of structure #DP_INIT_OP_DEF.
1610 
1611  - Description: <BR>
1612  The structure is used to supply wide character (Unicode) initialization parameter name required for the current Service Provider and is used by ODPP framework to initialize the data privacy Service Provider.
1613  This is used in scenario when there is no parameter ID. Set usOperand = 0 when a parameter name is passed instead of ParameterID
1614  <BR><BR>
1615  Before using this structure ensure that it is "memset" with 0.
1616 
1617  - \ref init_example "Example"
1618  */
1619 typedef struct DPPRM_NAME_WC_SS
1620 {
1621  /*
1622  - Use: <BR>
1623  This member is used to specify the name of the parameter in wide character (Unicode) format.
1624 
1625  - Description: <BR>
1626  This is a wide character (Unicode) format string which specifies the name of the initialization parameter required for the Service Provider.
1627  Set usOperand = 0 when a parameter name is passed instead of ParameterID
1628 
1629  - Optional: <BR>
1630  Yes, but is required in scenario when there is no parameter ID.
1631 
1632  */
1633  ODPP_WCHAR *pParmName; // Pointer to parm key
1634  // expressed in wide character (Unicode) format
1635 }DPPRM_NAME_WC_SS;
1636 
1637 //----------------------------------------------------------------------
1638 // Name: DPPRM_NAME_MC_SS
1639 // Description:
1640 // mixed-character (e.g. SBCS/MBCS) parameter name sub-structure for
1641 // DP_INIT_OP_DEF
1642 //----------------------------------------------------------------------
1643 
1644 /*
1645  - Name: #DPPRM_NAME_MC_SS
1646 
1647  - Use: <BR>
1648  This structure is used to pass on the mixed character (SBCS/MBCS) initialization parameter name to the Provider_Init() API as a child member of structure #DP_INIT_OP_DEF.
1649 
1650  - Description: <BR>
1651  The structure is used to supply mixed character (SBCS/MBCS) initialization parameter name required for the current Service Provider and is used by ODPP framework to initialize the data privacy Service Provider.
1652  This is used in scenario when there is no parameter ID. Set usOperand = 0 when a parameter name is passed instead of ParameterID
1653  <BR><BR>
1654  Before using this structure ensure that it is "memset" with 0.
1655 
1656  - \ref init_example "Example"
1657  */
1658 typedef struct DPPRM_NAME_MC_SS
1659 {
1660  /*
1661  - Use: <BR>
1662  This member is used to specify the DBMS type of the current mixed-character(SBCS/MBCS) format initialization parameter name.
1663 
1664  - Description: <BR>
1665  This is a mixed-character(SBCS/MBCS) format initialization parameter name DBMS type.
1666 
1667  - Optional: <BR>
1668  No
1669 
1670  */
1671  char cParamNameDBMSType; // DBMS type of the parameter name
1672 
1673  /*
1674  - Use: <BR>
1675  This member is used to specify the Code page of the current mixed-character(SBCS/MBCS) format initialization parameter name.
1676 
1677  - Description: <BR>
1678  This is a mixed-character(SBCS/MBCS) initialization parameter name code page type. To use code page and DBMS type supplied by the parent structure #DP_FRMW_PARAMS_DEF/#DP_SVC_DEF, set iParamaNameCodePage to ODPP_CODE_PAGE_NONE
1679 
1680  - Optional: <BR>
1681  No
1682 
1683  */
1684  int iParamNameCodePage; // Code page of the parameter name
1685  //Set iParamNameCodePage to ODPP_CODE_PAGE_NONE to use code page and DBMSType
1686  //supplied by the parent structure (DP_FRMW_PARAMS_DEF/DP_SVC_DEF)
1687 
1688  /*
1689  - Use: <BR>
1690  This member is used to specify the name of the parameter in mixed character (SBCS/MBCS) format.
1691 
1692  - Description: <BR>
1693  This is a mixed character (SBCS/MBCS) format string which specifies the name of the initialization parameter required for the Service Provider.
1694  Set usOperand = 0 when a parameter name is passed instead of ParameterID
1695 
1696  - Optional: <BR>
1697  Yes, but is required in scenario when there is no parameter ID.
1698 
1699  */
1700  // char *pParmName; // Pointer to parm key
1701  // expressed in mixed (SBCS/MBCS) character format
1702 }DPPRM_NAME_MC_SS;
1703 
1704 //----------------------------------------------------------------------
1705 // Name: DPPRM_VAL_WC_SS
1706 // Description:
1707 // Wide-character (Unicode) parameter value sub-structure for DP_INIT_OP_DEF
1708 //----------------------------------------------------------------------
1709 
1723 typedef struct DPPRM_VAL_WC_SS
1724 {
1736  ODPP_WCHAR *pParmVal; // Pointer to parm key
1737  // expressed in wide character (Unicode) format
1739 
1740 //----------------------------------------------------------------------
1741 // Name: DPPRM_VAL_MC_SS
1742 // Description:
1743 // mixed-character (e.g. SBCS/MBCS) parameter value sub-structure for
1744 // DP_INIT_OP_DEF
1745 //----------------------------------------------------------------------
1759 typedef struct DPPRM_VAL_MC_SS
1760 {
1772  char cParamValDBMSType; // DBMS type of the parameter value
1773 
1785  int iParamValCodePage; // Code page of the parameter value
1786  //Set iParamValCodePage to ODPP_CODE_PAGE_NONE to use code page and DBMSType
1787  //supplied by the parent structure (DP_FRMW_PARAMS_DEF/DP_SVC_DEF)
1788 
1800  char *pParmVal; // Pointer to parm key
1801  // expressed in mixed (SBCS/MBCS) character format
1803 
1804 //----------------------------------------------------------------------
1805 // Name: DP_INIT_OP_DEF
1806 // Description:
1807 // Init Operand Definition contains all the initialization
1808 // parameters required for the current service
1809 //----------------------------------------------------------------------
1810 
1824 typedef struct DP_INIT_OP_DEF
1825 {
1928  *pNext; //Pointer to next element in chain of operands
1929 
1941  char cEyeCatcher[4]; // Eye Catcher
1942 
1954  short sStructVer; // Version of this structure
1955 
1967  short sStructLen; // Length of this structure
1968 
1980  unsigned short usParameterID; // ODPP Parameter
1981 
1982  /*
1983  - Use: <BR>
1984  [FOR FUTURE USE]
1985 
1986  - Description: <BR>
1987  [FOR FUTURE USE]
1988 
1989  - Optional: <BR>
1990  [FOR FUTURE USE]
1991 
1992  */
1993  //char cParamNameSubType; // Type of parameter sub-structure
1994  // (W or blank=wide-char, M=mixed (SBCS/MBCS) char
1995 
1996  /*
1997  - Use: <BR>
1998  [FOR FUTURE USE]
1999 
2000  - Description: <BR>
2001  [FOR FUTURE USE]
2002 
2003  - Optional: <BR>
2004  [FOR FUTURE USE]
2005 
2006  */
2007  //int iParamNameBufBytes; // Size (in bytes) of param value buffer
2008 
2009  // =================
2010  // Parameter name
2011  // =================
2012  // Used in scenario when there is no parameter ID
2013  // Set usOperand = 0 when a parameter name is passed instead of ParameterID
2014  //union
2015  //{
2016  /*
2017  - Use: <BR>
2018  [FOR FUTURE USE]
2019 
2020  - Description: <BR>
2021  [FOR FUTURE USE]
2022 
2023  - Optional: <BR>
2024  [FOR FUTURE USE]
2025 
2026  */
2027  // DPPRM_NAME_WC_SS
2028  // *pWC; // Pointer to wide character (Unicode) sub-structure
2029 
2030  /*
2031  - Use: <BR>
2032  [FOR FUTURE USE]
2033 
2034  - Description: <BR>
2035  [FOR FUTURE USE]
2036 
2037  - Optional: <BR>
2038  [FOR FUTURE USE]
2039 
2040  */
2041  // DPPRM_NAME_WC_SS
2042  // *pMC; // Pointer to mixed character (SBCS/MBCS) sub-structure
2043  //}PARAM_NAME_SS PN;
2044 
2045  // =================
2046  // Parameter value
2047  // =================
2069  int iValueSubType; // Type of parameter value as defined below
2070  // any value except these are user defined values
2071  // and indicates the use of pUserVal.
2072  //================================================
2073  // Custom service providers can define their own
2074  // values for their usage
2075  //================================================
2076  #define PARAM_VAL_NONE 0 //This parameters has no value
2077  #define PARAM_VAL_NUM 1 //Parameter value is numeric
2078  #define PARAM_VAL_WC 2 //Parameter value is Wide Char string
2079  #define PARAM_VAL_MC 3 //Parameter value is SBCS/MBCS
2080 
2092  int iValueBufBytes; // Size (in bytes) of param value buffer
2093 
2094  union
2095  {
2108  unsigned int uiVal; // User-supplied numeric value
2109 
2122  DPPRM_VAL_WC_SS *pWC; // Pointer to wide character (Unicode) sub-structure
2123 
2136  DPPRM_VAL_MC_SS *pMC; // Pointer to mixed character (SBCS/MBCS) sub-structure
2137 
2149  void *pUserVal; // User defined parameter value
2150  }PARAM_VAL PV;
2151 
2153 
2154 
2155 //----------------------------------------------------------------------
2156 // Name: DP_FRMW_PARAMS_DEF
2157 // Description:
2158 // Encapsulates the parameters required for the
2159 // ODPP framework initialization
2160 //----------------------------------------------------------------------
2161 
2175 typedef struct DP_FRMW_PARAMS_DEF
2176 {
2188  char cEyeCatcher[4]; // Eye Catcher
2189 
2201  short sStructVer; // Version of this structure
2202 
2214  short sStructLen; // Length of this structure
2215 
2227  short sParamCount; // Count of parameters in pParams
2228 
2229  // Default Code Page and DBMS Type for Parameter names and values
2230  //
2231  // Note: Codepage/DBMSType values set for individual parameters take
2232  // precedence over these value
2244  char cDBMSType; // DBMSType of parameter Data
2245 
2257  int iParamDataCP; // Code page of parameter Data
2258 
2271  *pParams; // List of parameters
2272 
2274 
2275 //----------------------------------------------------------------------
2276 // Name: DP_SVC_DEF
2277 // Description:
2278 // The Service Definition contains the operands and field definition lists
2279 // and the other service definition type initialization parameters.
2280 //----------------------------------------------------------------------
2294 typedef struct DP_SVC_DEF
2295 {
2307  char cEyeCatcher[4]; // Eye Catcher
2308 
2320  short sStructVer; // Version of this structure
2321 
2333  short sStructLen; // Length of this structure
2334 
2346  char bRefreshSVCDef;/* TRUE to refresh the existing svc def
2347  with this one [Not used as of now] */
2348 
2360  char bCopyToDest; // Copy the masked data to destination buf
2361 
2373  short sParamCount; // No. of elements in pOperands
2374 
2386  short sFldCount; // no of elements in pFldDef
2387 
2388  // Default Code Page and DBMS Type for Parameter names and values
2389  //
2390  // Note: Codepage/DBMSType values set for individual parameters/fields
2391  // take precedence over these value
2403  char cCtrlDataDBMSType; // DBMSType of control Data
2404  // in DP_INIT_OP_DEF and DP_FIELD_DEF
2405 
2417  int iCtrlDataCP; // Code page of control data
2418  // in DP_INIT_OP_DEF and DP_FIELD_DEF
2419 
2432  *pParams; // Pointer to array or first element in
2433  // chain of DP_INIT_OP_DEF. Provides all
2434  // needed operands.
2435 
2447  DP_FIELD_DEF *pFldDef; // Pointer to array or first element in
2448  // chain of DP_FIELD_DEF.
2449 
2450 }DP_SVC_DEF;
2451 
2452 
2453 //----------------------------------------------------------------------
2454 // Name: DPPD_WC_SS
2455 // Description:
2456 // The provider definition for the wide-character (Unicode)
2457 // sub-structure for DP_PRV_DETAILS
2458 //----------------------------------------------------------------------
2472 typedef struct DPPD_WC_SS
2473 {
2485  ODPP_WCHAR *pProviderName; // Pointer to provider name
2486  // expressed in wide character (Unicode) format
2498  ODPP_WCHAR *pDescription; // Pointer to provider description
2499  // expressed in wide character (Unicode) format
2500 }DPPD_WC_SS;
2501 
2502 //----------------------------------------------------------------------
2503 // Name: DPPD_MC_SS
2504 // Description:
2505 // The provider definition for the mixed-character (e.g. SBCS/MBCS)
2506 // sub-structure for DP_PRV_DETAILS
2507 //----------------------------------------------------------------------
2521 typedef struct DPPD_MC_SS
2522 {
2534  char *pProviderName; // Pointer to provider name
2535  // expressed in mixed (SBCS/MBCS) character format
2547  char *pDescription; // Pointer to provider description
2548  // expressed in mixed (SBCS/MBCS) character format
2549 }DPPD_MC_SS;
2550 
2551 //----------------------------------------------------------------------
2552 // Name: DP_PRV_DETAILS
2553 // Description:
2554 // The Provider Details is an entry in the linked-list of
2555 // provider-type information that is returned
2556 // to the caller of Provider_Enumerate
2557 //----------------------------------------------------------------------
2558 
2572 typedef struct DP_PRV_DETAILS
2573 {
2586  *pNext; // Pointer to next element in chain
2598  char bUserDefine; // When TRUE, this is a user-supplied provider
2599 
2611  char bLicensed; // When TRUE, this is a licensed provider
2612 
2624  short sProviderID; // ODPP internally defined provider ID
2625 
2637  short sProviderVer; // Version of the provider
2638 
2650  int iPrvNameBufBytes; // Size, in bytes, of the provider name
2651 
2663  int iPrvDescBufBytes; // Size, in bytes, of the provider description
2664 
2665  union
2666  {
2678  DPPD_WC_SS *pWC; // Pointer to wide character (Unicode) sub-structure
2679 
2691  DPPD_MC_SS *pMC; // Pointer to mixed character (SBCS/MBCS) sub-structure
2692  }PD_SS PD;
2694 
2695 //----------------------------------------------------------------------
2696 // Name: DP_PRV_DEF
2697 // Description:
2698 // The Provider Definition contains provider details in a linked-list of
2699 // provider-type information that is returned to the caller of
2700 // Provider_Enumerate
2701 //----------------------------------------------------------------------
2702 
2716 typedef struct DP_PRV_DEF
2717 {
2729  char cEyeCatcher[4]; // Eye Catcher
2730 
2742  short sStructVer; // Version of this structure
2743 
2755  short sStructLen; // Length of this structure
2756 
2774  char cSubType; // Type of sub-structure
2775  // (W or blank=wide-char, M=mixed (SBCS/MBCS) char
2776 
2788  char cPDDBMSType; // DBMSType of the provider name and description
2789 
2801  int iPDCodePage; // Code page of the provider name and description
2802 
2815  *pPrvDetails; // Array or Link List of Providers with details
2816 }DP_PRV_DEF;
2817 
2818 
2819 //----------------------------------------------------------------------
2820 // Name: DPEM_WC_SS
2821 // Description:
2822 // The Formatted error message definition for the wide-character (Unicode)
2823 // sub-structure for DP_ERR_MSG
2824 //----------------------------------------------------------------------
2838 typedef struct DPEM_WC_SS
2839 {
2852 
2865 
2878 
2890  ODPP_WCHAR *pMsgSrc;
2891 
2903  ODPP_WCHAR *pMsg;
2904 
2916  ODPP_WCHAR *pMsgBody;
2917 
2918 }DPEM_WC_SS;
2919 
2920 //----------------------------------------------------------------------
2921 // Name: DPEM_MC_SS
2922 // Description:
2923 // The provider definition for the mixed-character (e.g. SBCS/MBCS)
2924 // sub-structure for DP_ERR_MSG
2925 //----------------------------------------------------------------------
2939 typedef struct DPEM_MC_SS
2940 {
2953 
2966 
2979 
2992 
3005 
3017  char *pMsgSrc;
3018 
3030  char *pMsg;
3031 
3043  char *pMsgBody;
3044 }DPEM_MC_SS;
3045 
3046 //----------------------------------------------------------------------
3047 // Name: DP_ERR_MSG
3048 // Description:
3049 // The Provider Definition is an entry in the linked-list of
3050 // provider-type information that is returned
3051 // to the caller of Provider_GetFormattedErrorMsg
3052 //----------------------------------------------------------------------
3053 
3067 typedef struct DP_ERR_MSG
3068 {
3080  char cEyeCatcher[4]; // Eye Catcher
3081 
3093  short sStructVer; // Version of this structure
3094 
3095 
3107  int iErrNum; // Error number/Return code. USED ONLY
3108  // WHEN pECB is NULL, IGNORED OTHERWISE
3109 
3121  int iLanguage; // Language to use for error messages
3122 
3134  DP_ECB *pECB; // Error Control Block
3135 
3136 
3155  char cSubType; // Type of sub-structure
3156  // (W or blank=wide-char, M=mixed (SBCS/MBCS) char
3157  union
3158  {
3170  DPEM_WC_SS // Pointer to wide character (Unicode) sub-structure
3171  *pWC;
3172 
3173 
3185  DPEM_MC_SS // Pointer to mixed character (SBCS/MBCS) sub-structure
3186  *pMC;
3187  }EM_SS EM;
3188 
3189 }DP_ERR_MSG;
3190 
3191 
3192 //----------------------------------------------------------------------
3193 // Name: DP_KVPAIR_DEF
3194 // Description:
3195 // Structure to hold key-value pairs returned from Parser_Service
3196 //----------------------------------------------------------------------
3197 
3210 typedef struct DP_KVPAIR_DEF
3211 {
3224  *pNext; // Pointer to next element in chain of parameters
3225 
3237  char cEyeCatcher[4]; // Eye catcher
3238 
3250  short sStructVer; // Version of this structure
3251 
3263  short sStructLen; // Length of this structure
3264 
3276  ODPP_WCHAR *pKey;
3277 
3289  unsigned int uiKeyID;
3290 
3302  int iKeyBytes; //size in bytes of the allocated pKey buffer
3303 
3315  int iKeyOutBytes; //bytes written to the pKey buffer include NULL terminator or bytes required if there's an error
3316 
3328  ODPP_WCHAR *pValue;
3329 
3341  unsigned int uiValueID;
3342 
3354  int iValueBytes; //size in bytes of the allocated pValue buffer
3355 
3367  int iValueOutBytes; //bytes written to the pValue buffer include NULL terminator or bytes required if there's an error
3368 
3380  int iErrorCode; //Error code if data was truncated
3381 }DP_KVPAIR_DEF;
3382 
3383 // Sub-structure contains the DP_PARAMS_DEF parameter string
3384 // in wide-character (UTF-16) format
3385 
3398 typedef struct DPPS_WC_SS
3399 {
3411  ODPP_WCHAR *pParamString;
3412 
3413 }DPPS_WC_SS;
3414 
3415 // Sub-structure contains the DP_PARAMS_DEF parameter string
3416 // in mixed-character (SBCS/MBCS) format
3417 
3430 typedef struct DPPS_MC_SS
3431 {
3444 
3457 
3470 }DPPS_MC_SS;
3471 
3484 // Structure contains the Provider_Parse input/output parameters
3485 typedef struct DP_PARAMS_DEF
3486 {
3498  char cEyeCatcher[4]; // Eye catcher
3499 
3511  short sStructVer; // Version of this structure
3512 
3524  short sStructLen; // Length of this structure
3525 
3542 
3558  int iKeyValueArrSize; //number of elements in pKeyValueArr
3559 
3575  int iKeyCount; //[out] number of key-value pairs set into pKeyValueArr after parsing
3576 
3589 
3602 
3614  char cEnv; //Env code
3615 
3627  char bHasError; //[out] set to TRUE is an error occurred
3628 
3640  unsigned short usEncoding; //future use
3641 
3653  unsigned short usConversion; //future use
3654 
3673  char cParamStringType; // (W or 0=wide-char, M=mixed (SBCS/MBCS) char
3674 
3686  int iParamStringBytes; //size in bytes of the data excluding NULL character
3687 
3688  union
3689  {
3703 
3717  } PARAM_STRING_SS PS;
3718 }DP_PARAMS_DEF;
3719 
3733 typedef struct DP_PARMGEN_DEF
3734 {
3746  char cEyeCatcher[4]; // Eye catcher
3747 
3759  short sStructVer; // Version of this structure
3760 
3772  short sStructLen; // Length of this structure
3773 
3786 
3799 
3811  char *pSvcId;
3812 
3825 
3839 
3840 
3841 // Structure containing the input the Instance Manager
3842 typedef struct DP_INSTANCE_DEF
3843 {
3844  char cEyeCatcher[4];
3845  short sStructVer;
3846  short sStructLen;
3847  int iSvcToken;
3848  char *pParmStr;
3849  int iParmStrBytes;
3850 }DP_INSTANCE_DEF;
3851 
3852 //----------------------------------------------------------------------
3853 // Name: DP_LIB_LIST
3854 // Description:
3855 // An element in an array of additional ODPP libraries to load.
3856 //----------------------------------------------------------------------
3872 typedef struct DP_LIB_LIST
3873 {
3885  int iBufBytes; // Size of the buffer pointed to by pLib in bytes
3897  char* pLib; // Pointer to the name of the shared library to load
3898 }DP_LIB_LIST;
3899 
3900 
3901 //============================================================================
3902 // API's to be used by applications to use ODPP Services
3903 //==========================================================================*/
3932  (
3933  char *pBinPath,
3934  int iBinPathBytes,
3935  DP_LIB_LIST *pLibList,
3936  int iArrCnt
3937  );
3938 // This will initialize the framework and all its components
3953  (
3954  DP_FRMW_PARAMS_DEF *pInitParams
3955  );
3956 
3957 // For each Service type that the caller wants to initiate, an Initialization
3958 // call is required, and a TOKEN is returned to establish a session. This
3959 // TOKEN will then be required on all subsequent calls for this session.
4022  (
4023  int *pSvcToken,
4024  char *pSvcID,
4025  int iSvcIdLen,
4026  DP_SVC_DEF *pSvcdef,
4027  char bAllocInitBlock
4028  );
4029 
4030 // The appropriate data privacy method would then be requested via a Provider
4031 // Service call to perform data privacy function using pre-determined standard
4032 // names as described in the Optim Data Privacy Development manual.
4033 // Data privacy method if specific here will overwrite the method specified
4034 // during Provider_Init using parameter ODPP_OPR_METHOD.
4035 //
4036 // Curently ONLY ODPP_METHOD_MASK OR ODPP_METHOD_DEFAULT IS SUPPORTED FOR sMethod
4037 //
4038 // 3rd Argument, i.e. pSvcDef, is for future use. It should be set to NULL.
4039 //
4075  (
4076  int iSvcToken,
4077  short sMethod,
4078  DP_SVC_DEF *pSvcDef, //FOR FUTURE USE
4079  DP_ROWSET_DEF *pRowSet
4080  );
4081 
4082 
4083 // When the user is finished with a Service they will be required to make a
4084 // termination call
4102  (
4103  int iSvcToken
4104  );
4105 
4106 // Used to list all the available providers along with their details
4138  (
4139  DP_PRV_DEF *pPrvDetails,
4140  short *pCount
4141  );
4142 
4143 
4144 // Returns the error count and max ECB size
4145 // This function should not be called while a service call running
4146 // for the specified service token otherwise behavior is undefined
4174  (
4175  int iSvcToken,
4176  short * pErrCount,
4177  int * pErrAreaLen
4178  );
4179 
4180 // Returns the list of ECBs starting with the oldest ECB first
4181 // This function should not be called while a service call running
4182 // for the specified service token otherwise behavior is undefined
4210  (
4211  int iSvcToken,
4212  DP_ECB * pECB
4213  );
4214 
4215 // Returns the formatted error message
4235  (
4236  DP_ERR_MSG *pErrMsg
4237  );
4238 
4239 // Returns the formatted error message. Can be used without the Framework being initialized.
4258 
4259 // Terminates ECB processing
4280  (
4281  int iSvcToken
4282  );
4283 
4284 // Returns the provider specific information requested by
4285 // sRequest in ptr
4322  (
4323  int iSvcToken,
4324  short sRequest,
4325  void *ptr,
4326  int *pBufLen
4327  );
4328 
4329 // This will terminate the framework and all of its components
4341  (
4342  void
4343  );
4344 
4345 
4346 
4347 //----------------------------------------------------------------------------
4348 //Parser related functions
4349 //----------------------------------------------------------------------------
4350 //Initialise the parser
4360 RETVAL Parser_Init ( void );
4361 
4362 // Call this to convert the ODPP parameter string to ODPP Key-Value pairs
4363 // (i.e. DP_KVPAIR_DEF) array. If pKeyValueArr is NULL and iKeyValueArrSize
4364 // value is 0 and the Provider_Parse() method is called the parser returns the
4365 // number of Key-Value pairs required in pParamDef->iKeyCount, iKeyMaxBytes and
4366 // iValueMaxBytes have the max key and value bytes required which can be used to
4367 // allocate pKey and pValue
4400  DP_PARAMS_DEF *pParamDef
4401  );
4402 
4403 // Returns the error count and max ECB size
4404 // This function should not be called while a service call running
4405 // for the specified service token otherwise behavior is undefined
4428  (
4429  short * pErrCount,
4430  int * pErrAreaLen
4431  );
4432 
4433 // Returns the list of ECBs starting with the oldest ECB first
4434 // This function should not be called while a service call running
4435 // for the specified service token otherwise behavior is undefined
4457  (
4458  DP_ECB * pECB
4459  );
4460 
4461 // Returns the formatted error message
4476  (
4477  DP_ERR_MSG *pErrMsg
4478  );
4479 
4480 //Terminate the parser
4490  ( void );
4491 
4492 
4493 //----------------------------------------------------------------------------
4494 //Parameter Generator related functions
4495 //----------------------------------------------------------------------------
4496 
4497 // Initialize ODPP Parameter generator (Adapter)
4510  (
4511  void
4512  );
4513 
4514 
4515 // Call this to convert the ODPP Key-Value pairs array into a DP_SVC_DEF structure
4534  (
4535  DP_PARMGEN_DEF *pParmGen
4536  );
4537 
4538 //Free's all the memory allocated for DP_FIELD_DEF structure(s) and
4539 //DP_INIT_OP_DEF structures
4555  (
4556  DP_SVC_DEF *pSvcDef
4557  );
4558 
4559 // Returns the error count and max ECB size for Parameter Generator
4560 // This function should not be called while a service call running
4561 // for the specified service token otherwise behavior is undefined
4582  (
4583  short * pErrCount,
4584  int * pErrAreaLen
4585  );
4586 
4587 // Returns the list of ECBs starting with the oldest ECB first
4588 // This function should not be called while a service call running
4589 // for the specified service token otherwise behavior is undefined
4608  (
4609  DP_ECB * pECB
4610  );
4611 
4612 // Returns the formatted error message
4627  (
4628  DP_ERR_MSG *pErrMsg
4629  );
4630 
4641  (
4642  void
4643  );
4644 
4645 
4646 //Initialize the Instance Manager
4647 RETVAL InstMgr_Init(void);
4648 
4649 //Lock the Instance Manager mutex
4650 RETVAL InstMgr_Lock(void);
4651 
4652 //Searches the list of instances and returns an error if the instance
4653 //corresponding to the parameter string is not found
4654 RETVAL InstMgr_Find(DP_INSTANCE_DEF *pInstanceDef);
4655 
4656 //Adds the instance to the internal list of active service provider instances
4657 RETVAL InstMgr_Add(DP_INSTANCE_DEF *pInstanceDef);
4658 
4659 //Deletes the instance from the internal list of active service provider instances
4660 RETVAL InstMgr_Delete(DP_INSTANCE_DEF *pInstanceDef);
4661 
4662 //Unlock the Instance Manager mutex
4663 RETVAL InstMgr_Unlock(void);
4664 
4665 //Terminate the Instance Manager
4666 RETVAL InstMgr_Term(void);
4667 
4668 #endif //__ODPPCMNAPIH__