/*! \mainpage

This DLL supplies two modules that fill the CDR properties with values loaded from
 a database. The lookup in the database is performed using some keys values extracted
 from the CDR or Kernel global variables.

The two modules differ in the way they connect to the database and execute the queries:
- the old module CGeneralMap loads the database on the local machine and performs syncronous
  operations
- the new module CGeneralMapWithService connects to a remote database using MapService and
  performs asyncronous operations.

This manual focuses mainly on the new module CGeneralMapWithService.

The DLL allocates the old CGeneralMap when NewObject() is called with a name that differs from "UseMapService", 
 or the new CGeneralMapWithService when NewObject() contains a string equal to "UseMapService".
 


\page generalmap_howitworks How it works

In order to allow asyncronous requests, the following method is used:

- When CGeneralMapWithService::Process() is called, then CGeneralMapWithService replaces the CDR in the
   function parameter with a CDR for which the database query has already been performed.\n
  The CDR specified in the parameter is queued for further processing by MapService.\n
  If when CGeneralMapWithService::Process() is called there isn't any record already processed by
   MapService then the function consumes the CDR.\n
  CGeneralMapWithService::Process() blocks only when the list of CDRs waiting for MapService reaches
   its limit.
- When CGeneralMapWithService::Read() is called, then all the CDRs that haven't been returned by
   When CGeneralMapWithService::Process() are sent back to IceProcessor.\n
  The function blocks until MapService returns some processed CDRs or all the CDRs have been retrieved.



\page generalmap_installation Installation

The module is contained in the file GeneralMap.dll and requires the runtime C++ and MFC libraries.

The scripts and the parameters need to be upgraded to use the new features of GeneralMap (with the usage
 of the service MapService)

If the scripts are left unchanged then the old GeneralMap module will be used.
See \ref generalmap_script for further information.



\page generalmap_parameters Parameters

\section generalmap_parameters_private Private parameters

The following private parameters are loaded from the STEP node that declares the module.


\subsection generalmap_parameters_dbkeys "s:DB_KEYS"

Comma separated names of the fields in the SQL query (see \ref generalmap_parameters_sql) that are 
 used to build the key string.


\subsection generalmap_parameters_cdrkeys "s:CDR_KEYS"

Comma separated names of the CDR properties that are used to build the key string.
The resulting string is matched against the string generated by the parameters in \ref generalmap_parameters_dbkeys.


\subsection generalmap_parameters_cdrresults "s:CDR_RESULTS" 

Comma separated names of the CDR properties filled with the result from the SQL query (see generalmap_parameters_sql).
The database fields used to fill the CDR properties are the one specified in the SQL query after the fields
 specified in \ref generalmap_parameters_sql have been removed.

 
\subsection generalmap_parameters_cdrdefaults "s:CDR_DEFAULTS"

Comma separated values used to fill the CDR properties specified in \ref generalmap_parameters_cdrresults when
 a match cannot be found in the database.


\section generalmap_parameters_settings Parameters from the "Settings" xml file

The following parameters are loaded from the section CHARGING/DATABASE in the settings file, but can be overwritten
 in the private parameters section by adding the prefix "s:".

\subsection generalmap_parameters_sql "SQL"

The sql string that retrieves the data from the database. Must include the fields used to build the key and the
 fields that are returned in the CDR.

See \ref generalmap_parameters_dbkeys and generalmap_parameters_cdrresults.


\subsection generalmap_parameters_adoconnection "ADOConnection"

The ADO connection string that MapService must use to connect to the database.
May need the user name and password (see \ref generalmap_parameters_uid and \ref generalmap_parameters_pwd).


\subsection generalmap_parameters_uid "UID"

The username for the ADOConnection (see \ref generalmap_parameters_adoconnection).


\subsection generalmap_parameters_pwd "PWD"

The password for the ADOConnection (see \ref generalmap_parameters_adoconnection).


\subsection generalmap_parameters_serviceip "ServiceIP"

The IP of the machine on which MapService is running.


\subsection generalmap_parameters_matchmode "MatchMode"

When set to "Prefix" then MapService looks for the largest fit, otherwise looks for the exact fit.

When the largest fit is used then MapService retrieves the record with the longest key that is contained
 in the key built fromthe CDR.



\page generalmap_script Script

The DLL can return the old GeneralMap object or the new one described in this manual.
In order to retrieve the new object specify the name "UseMapService" in the STEP node that
 declares the filter.

Example:
\code

<STEP Name="UseMapService" Dll="GeneralMap.dll">
		<s:DB_KEYS>field3</s:DB_KEYS>
		<s:CDR_KEYS>@ANUM</s:CDR_KEYS>
		<s:CDR_RESULTS>@BNUM</s:CDR_RESULTS>
		<s:SQL>select field3, field1 from table1</s:SQL>
		<s:ADOConnection>Driver={Microsoft Access Driver (*.mdb)}; DBQ=c:\testMapService.mdb</s:ADOConnection>
		<s:ServiceIP>127.0.0.1</s:ServiceIP>
</STEP>

\endcode

*/