6.2.  LM_PARM: Learn Mode Parameters

The LM_PARM structure is declared as follows:

typedef struct {

   unsigned short int lm_cadflag;    /* cadence/continuous tone flag    */

   unsigned short int lm_cnt_min;    /* min on-time for continuous tone */

   unsigned short int lm_frames;     /* number of tone on/off samples   */

   unsigned short int lm_qualid;     /* qualification ID used           */

   unsigned short int lm_method;     /* method for freq/dur tolerances  */

   float              lm_frq_tol;    /* frequency parm for tolerance    */

   float              lm_dur_tol;    /* duration parm for tolerance     */

} LM_PARM;

The learn mode parameters structure (LM_PARM) specifies the parameters and options for learning a tone and is used for input to the lm_LearnTone( ) function. These options include the continuous tone minimum on-time, the number of learning samples, the qualification ID (which controls the immunity to noise), and the methods and values for calculating the frequency and cadence range for the final tone description.

NOTE:

Set any field to 0 to use the default value.

Use the lm_clrparm( ) function to clear the fields of an LM_PARM structure.

Table 1.  LM_PARM Structure

Field	Description
lm_cadflag	Length: 2 (unsigned short int) Default: 0 Continuous or cadence mode. Specifies whether the tone to be learned is continuous or has a cadence. If you set the tn_rangep parameter of lm_LearnTone( ) function to restrict learning to a specified range, you must set the lm_cadflag field to indicate a cadence or continuous tone.
	0	To learn a tone when you don't know whether the tone is continuous or cadence.
	1	To learn a tone having a cadence.
	2	To learn a continuous tone.
lm_cnt_min	Length: 2 (unsigned short int) Units: 10 ms. Range: 1 -- 1000 Default: 400 (4 seconds) Continuous tone minimum on-time. Specifies in 10 ms units the tone-on duration for the tone to qualify as a continuous tone. After the tone qualifies, sampling is performed for the number of frames (samples) specified in lm_frames.
	Set this field to 0 to use the default value (400).
lm_frames	Length: 2 (unsigned short int) Default: 10 Range: 5 -- 127 Number of learning samples. For a cadence tone, this specifies the number of tone-on/tone-off transitions for learning the cadence. For a continuous tone, this specifies the number of samples taken after the tone qualifies as a continuous tone (see lm_cnt_min) and on which the final frequency range is based. It is recommended that you set lm_frames to a minimum of 30 if you are using lm_method LM_STATISTICAL.
	Set this field to 0 to use the default value (10).
lm_qualid	Length: 2 (unsigned short int) Default: QT_LMDEF (sets to QT_LMMID) Qualification ID. Specifies the qualification template ID used for learning. The qualification ID specified here is also output in the tn_qualid field of the final tone description in the TN_DESC structure. Increase the qualification ID for more immunity to noise and less sensitivity to the tone.
	QT_LMDEF		Sets the qualification ID to the default (middle).
	QT_LMLOW		Low qualification (poor line quality).
	QT_LMMID		Middle qualification (medium line quality).
	QT_LMHIGH		High qualification (high line quality).
lm_method	Length: 2 (unsigned short int) Default: DEF_METHOD (sets to LM_RATIO) User-selectable tolerance method. Indicates the method used to calculate the frequency range and cadence range needed to detect the tone.
	DEF_METHOD		Sets to the default method, LM_RATIO.
	LM_ABSOLUTE		Absolute Tolerance (constant value) takes the samples with the highest and lowest values and then adds and subtracts the constant value specified in lm_frq_tol or lm_dur_tol. Absolute tolerance specifies a value independent of the sample value.
	LM_RATIO		Ratio Tolerance (percentage) takes the samples with the highest and lowest values and then adds and subtracts the percentage specified in lm_frq_tol or lm_dur_tol. Ratio tolerance specifies a percentage of the sample value.
	LM_STATISTICAL		Statistical Tolerance method based on calculating the mean and variance of the samples; lm_frq_tol and lm_dur_tol specify the percentage of extreme samples to exclude; places less weight on a "bad" sample (aberration or extreme deviation); preferable method when the tone data is poor. For good results with this method, we recommend that you set lm_frames to a minimum of 30.
lm_frq_tol	Length: 4 (float) Frequency Tolerance. Specifies a value used in calculating the frequency tolerance. The default, range, and units depend upon the tolerance lm_method selected.
	LM_ABSOLUTE		Units: Hz Range: 0 -- 300 Default: 30 Hz Specifies in Hz a constant value to add to and subtract from the samples with the highest and lowest values to obtain the frequency detection range.
	LM_RATIO		Units: Percentage Range: 0 -- 1 Default: 0.06 Specifies a percentage to add to and subtract from the samples with the highest and lowest values to obtain the frequency detection range.
	LM_STATISTICAL		Units: Percentage Range: 0 -- 0.2 Default: 0.03 Specifies the percentage of extreme samples to exclude from the normal distribution.
lm_dur_tol	Length: 4 (float) Duration Tolerance. Specifies a value used in calculating the tolerance for the tone cadence (tone-on/tone-off durations). The default, range, and units depend upon the tolerance lm_method selected.
	LM_ABSOLUTE		Units: 10 ms Range: 0 -- 100 Default: 3.0 Specifies in units of 10 ms a constant value to add to and subtract from the samples with the highest and lowest values to obtain the cadence detection range.
	LM_RATIO		Units: Percentage Range: 0 -- 1 Default: 0.08 Specifies a percentage to add to and subtract from the samples with the highest and lowest values to obtain the cadence detection range.
	LM_STATISTICAL		Units: Percentage Range: 0 -- 0.2 Default: 0.03 Specifies the percentage of extreme samples to exclude from the normal distribution.

Click here to contact Telecom Support Resources