7.9 Parameter Management

 (Page 10 of 11 in this chapter)
This section describes the functions that modify parameter structure values used when invoking telephony functions. The parameter functions are listed below:

Function

 Description

adiGetParms

 Gets the default values of the specified parameter structure.

adiGetParmByName

 Gets the value of a parameter by its name.

adiConfigParm

 Changes the default value of a parameter.

adiGetParmInfo

 Gets the size, type, and units of a parameter.

Parameters are variables that affect the behavior of asynchronous functions. Multiple parameters are grouped together in 'C' language structures called parameter structures. For the purposes of this manual, the term parameters is used to refer to all parameters in a parameter structure unless otherwise noted.

The application program may modify the behavior of an AG Access function by reassigning the function's parameter values. The following are examples of how parameters affect functions:

When initiating asynchronous functions, the application can specify the address of a parameter structure. Parameters contained in that structure are used for the duration of the function. Once initiated, the function parameters cannot be modified.

Application programmers have two options for specifying parameters:

These options are discussed in the following two sections.

7.9.1 Individual Parameter Assignment

To modify individual parameters, applications typically assign values in a two- step process:

  1. Retrieve the default parameters from AG Access via the adiGetParms function.

  2. Modify the individual parameters as desired.

Applications retrieve the default parameter values for a parameter structure by invoking adiGetParms. The application specifies a parameter structure by passing a parameter ID to adiGetParms, as illustrated in the following example: 

		ADICOLLECT_PARMS  collectparms ;
		
		adiGetParms( ADICOLLECT_PARMID,
			     &collectparms,
			     sizeof(collectparms) );
The following example illustrates parameter modification for the adiCollectDigits function such that only the '#' key terminates the collection. Error checking is ignored for clarity. 

		#define NDIGITS 15
		char  buffer[ NDIGITS+1 ];  /* +1 for null-terminator */

		ADICOLLECT_PARMS  collectparms ;

		adiGetParms( ADICOLLECT_PARMID,
			     &collectparms,
			     sizeof(collectparms) );
	
		collectparms.terminators = ADI_DIGIT_POUND;

		adiCollectDigits(porthd, buffer, sizeof(buffer), &collectparms);

7.9.2 Default Parameters

To simplify programming, AG Access allows the application to specify NULL as the parameter structure address. The NULL parameter instructs AG Access to use the default parameters for that function.

AG Access provides three sources of default parameters:

  1. Using the AG Access compile-time defaults as shipped.

  2. Modifying the compile-time defaults in the local process only using adiConfigParm.

  3. Modifying the host defaults using addaemon.

Default parameter values are compiled into the AG Access library. The compile- time defaults are documented in the AG Access Function Reference Manual.

An application may override default parameters with new values in the local process using adiConfigParm. The function adiConfigParm accepts a fully- qualified parameter name (e.g., structure.fieldname), and a new default value. The new value overwrites the compile-time value and is then used whenever the application specifies the NULL parameter address. The adiConfigParm function affects parameters in the executing process only (unless addaemon is running).

Alternatively, the application programmer can define a set of host default parameters. This is accomplished with the AG Access daemon, addaemon. This is a utility program that modifies default parameters for all processes in the host computer. Assigning host defaults is a two-step process:

  1. Edit the configuration file containing the defaults.

  2. Launch the addaemon process and specify the file name containing the defaults.

The addaemon process parses the configuration file and writes the binary equivalent for the parameters into shared memory. Any process launched after the addaemon will use the defaults defined in the configuration file, as depicted in Figure 36.



: The addaemon Process

The configuration file syntax is described in the sample configuration file sample.par which is shipped with the AG Access software. The values contained in the sample configuration file are the compile-time defaults.

The application can view the default parameters by executing the adiparm program. If the addaemon is running, the adiparm program reads the default values from shared memory and writes them to standard out. If the addaemon is not running, adiparm displays the compile-time defaults.

7.9.3 System Restrictions

The following system restrictions should be noted regarding parameter management:

The adiConfigParm function modifies default parameters regardless of whether or not they are in shared memory. The parameters in shared memory are not protected from concurrent access. If using shared memory, only the AG Access daemon (addaemon) should modify the parameter values.

In addition, the adiConfigParm function does not modify a complete structure. This function is used to modify single fields in a parameter structure.

(Page 10 of 11 in this chapter)

Copyright 1996 Natural MicroSystems, Inc. All Rights Reserved.