== Logic and Rationale ==

This page is a collection of different logic snippets used in the ezFIT design and implementation.  The description, use and rationale for each logic snippet is documented here as way of permanently recording ideas and decisions made on the different solutions to various problems.

The list of topics are not necessarily related (at least, not directly), so each topic should be treated atomically and independently of the others.






== Discovery of Drivers, Manufacturers, Circuits and Instruments ==
In order for the fitting module to discover the available drivers, manufacturers, circuits and instruments available to the application, we need to perform the following tasks:
  * Obtain list of available Instrument Driver Libraries.
  * Obtain list of supported manufacturers from list of Instrument Driver Libraries.
  * Obtain list of circuits supported by a specified library.
  * Obtain list of instruments supported by a specified circuit.

Methodology:
 * Fitting Module reads a list of files (each one formatted as ''InstrDrv//ManufacturerName//.bpl'') to discover available driver libraries. Eg: ''InstrDrvIntricon.bpl, InstrDrvSoundTech.bpl, InstrDrvSonic.bpl''.
 * Library reads an XML file (name formatted as ''proddef//ManufacturerName//.xml'') with Circuit and Instrument data.  Eg: ''proddefIntricon.xml'': <code xml>
<?xml version="1.0" encoding="UTF-8"?>
<ProdDef version="1.0" manuf="Intricon">
	<product code="prod_Intuition4" name="Intuition 4" id="0" circuit="DigitalOneNR4" visible="1" discontinued="0" active="1">
		<localization>
			<lang code="en">
				<shortname>Intuition 4</shortname>
				<longname>Intuition 4 (4 channels)</longname>
			</lang>
			<lang code="es">
				<shortname>Intuition 4</shortname>
				<longname>Intuition 4 (4 canales)</longname>
			</lang>
		</localization>
		<styles>
			<style name="CIC">
				<localization>
					<lang code="en"><name>CIC</name></lang>
					<lang code="es"><name>CIC</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Mini Canal">
				<localization>
					<lang code="en"><name>Mini Canal</name></lang>
					<lang code="es"><name>Mini Canal</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Canal">
				<localization>
					<lang code="en"><name>Canal</name></lang>
					<lang code="es"><name>Canal</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Half Shell">
				<localization>
					<lang code="en"><name>Half Shell</name></lang>
					<lang code="es"><name>Media Concha</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Full Shell">
				<localization>
					<lang code="en"><name>Full Shell</name></lang>
					<lang code="es"><name>Concha Entera</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Super60">
				<localization>
					<lang code="en"><name>Super60</name></lang>
					<lang code="es"><name>Super60</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="BTE">
				<localization>
					<lang code="en"><name>BTE</name></lang>
					<lang code="es"><name>Retro</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="OTE">
				<localization>
					<lang code="en"><name>OTE</name></lang>
					<lang code="es"><name>OTE</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
			<style name="Stock">
				<localization>
					<lang code="en"><name>Stock Pre-Fab</name></lang>
					<lang code="es"><name>Prefabricado</name></lang>
				</localization>
				<ranges>
					<range freq="250" minresp="30" maxresp="50"/>
					<range freq="1000" minresp="30" maxresp="70"/>
					<range freq="3000" minresp="30" maxresp="80"/>
				</ranges>
			</style>
		</styles>
	</product>
</ProdDef>
 </code>







== Guaranteeing Unique Circuit & Instrument References ==
To ensure that a reference to a product and/or circuit is unique, and also not stored in the application, we need to have a mechanism that will provide this simply by using libraries (DLLs or BPLs).

Requirements:

  * Get CircuitManufName.
  * Get CircuitID.
  * Get ProductID.
  * Get StyleID.
  * None of the above values should be defined by the main application, but rather internally in each instrument driver library.

Purposes:
  * To determine library to load.
  * To determine circuit to read.
  * To determine form to display.
  * To determine parameters to use.
  * Other.

Abstract Interface:
  * Lib.GetCircuitManufName([out] CircuitManufName)
  * Lib.GetProdAndStyleID([out] ProductID)
  * Lib.GetProductCode([in] CircuitID, [in] ProdAndStyleID, [out] ProductCode)
  * Lib.GetCircuitCode([in] CircuitID, [out] CircuitCode)
  * Lib.GetCircuitID([out] CircuitID)
  * Lib.GetStyleID([in] CircuitID, [in] ProdAndStyleID, [out] StyleID)

Pre-conditions:
  * StyleID is a unique set of values related to the product only. Eg: Product ''prod_Intuition4'' can have styles ''style_CIC, style_MiniCanal, style_Canal, style_HalfShell, style_FullShell, style_BTE, style_Stock, style_Security''.
  * ProductID is a unique set of values related to the circuit only. Eg: Circuit ''cir_DigitalOne4NRPlus'' can have products ''prod_Intuition4=1, prod_Sparo=2, prod_TransEar=3''.
  * CircuitID is a unique set of values related to the library only. Eg: Library ''InstrDrvIntricon.bpl'' can have circuits ''cir_DigitalOne2CT, cir_DigitalOne4AFC, cir_DigitalOne4NRPlus, cir_Intune, cir_Spin, cir_Ethos''.
  * CircuitManuf is a unique set of values related to the entire application calling the libraries. Eg: The main application would have unique values for ''manf_SoundDesignTech'', ''manf_Intricon'', ''manf_Sonic''.

Logistics:
  * To obtain a unique circuit, combine ''CircuitManuf + CircuitID''.
  * To obtain a unique product (i.e. name and style), combine ''CircuitManuf + CircuitID + ProductID + StyleID''.
  * To obtain supported styles in a product, combine ''CircuitManuf + CircuitID + ProductID''.

Hierarchy:
{{ezfit:manufcircuitproducthierarchy.png|}}







== Examples ==
Assumming the following ProdAndStyleID values:
<code delphi>
  // Product and Style IDs to be stored on Word2 (manuf reserved words) and ProdAndStyleID
  BTE_I4            = 1;    // Intuition 4
  BTE_I4D           = 2;    // Intuition D (Directional)
  BTE_I2            = 3;    // Intuition 2 (2 ch)
  FSS_I2            = 4;    // Intuition 2 (2 ch)
  ITE_I2            = 5;    // Intuition 2 (2 ch)
  FSS_I4            = 6;    // Intuition 4
  ITC_I4            = 7;    // Intuition 4
  CIC_I4            = 8;    // Intuition 4
  HS_I4             = 9;    // Intuition 4
  MiniCanal_I4      = 10;   // Intuition 4
  Canal_I4          = 11;   // Intuition 4
  Super60_I4        = 12;   // Intuition 4
  ezHear_I4         = 13;   // Intuition 4
  FSS_ClariD        = 14;   // Clari-D
  CIC_ClariD        = 15;   // Clari-D
  HS_ClariD         = 16;   // Clari-D
  MiniCanal_ClariD  = 17;   // Clari-D
  Canal_ClariD      = 18;   // Clari-D
  Super60_ClariD    = 19;   // Clari-D
  ...
  CIC_I8            = 1;    // Intuition 8
  CIC_I8Power       = 2;    // Intuition 8
  MiniCanal_I8      = 3;    // Intuition 8
  MiniCanal_I8Power = 4;    // Intuition 8
  Canal_I8          = 5;    // Intuition 8
  Canal_I8Power     = 6;    // Intuition 8
  HS_I8             = 7;    // Intuition 8
  HS_I8Power        = 8;    // Intuition 8
  FSS_I8            = 9;    // Intuition 8
  FSS_I8Power       = 10;   // Intuition 8
  Super60_I8        = 11;   // Intuition 8
  ezHear_I8         = 12;   // Intuition 8
  OTE_Flx           = 13;   // Flx, an OTE based on Ethos circuit
</code>

  * To obtain a circuit: <code delphi>
  ACircuitCode  := GetCircuitCodeFromInstrument();  // eg. cir_DigitalOne4NRPlus
  MyCircuitCode := GetCircuitCode(manf_Intricon, ACircuitCode);
</code>

  * To obtain a product: <code delphi>
  ACircuitCode  := GetCircuitCodeFromInstrument();  // eg. cir_DigitalOne4NRPlus
  MyProductCode := GetProductCode(manuf_Intricon, ACircuitCode, AProdAndStyleID {eg. 11});  // eg. 11 = Intuition4 + Canal
  // use product in some statement
  if MyProductCode in [prod_Intuition4, prod_TransEar] then begin
    // do some work
    ...
  end;
</code>

  * To obtain a style: <code delphi>
  ACircuitCode := GetCircuitCodeFromInstrument();  // eg. cir_DigitalOne4NRPlus
  MyStyleCode  := GetStyleCode(manuf_Intricon, ACircuitCode, AProdAndStyleID {eg. 11});    // eg. 11 = Intuition4 + Canal
  // use style in some statement
  if MyStyleCode in [style_CIC, style_MiniCanal, style_Canal] then begin
    // do some work
    ...
  end;
</code>