NCM_GetVariables( )

---

Description | Cautions | Example | Error Codes | See Also

Name:	NCMRetCode NCM_GetVariables( pncmFamily, pncmDevice, pncmProperty, ppncmVariables )
Inputs:	NCMFamily *pncmFamily	pointer to a structure containing a family of boards
	NCMDevice *pncmDevice	pointer to a structure containing a device name
	NCMProperty *pncmProperty	pointer to a structure containing a property section
	NCMVariable **ppncmVariables	address of pointer where configuration parameters will be output
Returns:	NCM_SUCCESS if success NCM error code if failure
Includes:	NCMApi.h
Mode:	synchronous

Description

The NCM_GetVariables( ) function gets the parameters for a property section. It fills a pointer to a pointer with the beginning address of a list of configuration parameters for a particular property section.

The function parameters are defined as follows:

Parameter	Description
pncmFamily	pointer to the structure containing the family name; the value of the structure must be an installable family (see Cautions below)
pncmDevice	pointer to the structure containing a device name; the device name can be either a device model name or a unique device name (the unique device name must be the same name you used to add the device to the system configuration with the NCM_AddDevice( ) function)
pncmProperty	pointer to the structure containing the property name; the value of the structure must be an installable property (see Cautions below)
ppncmVariables	address of the pointer to the list to be filled with configuration parameter structures

Cautions

This function provides the configuration parameters that can be set for a device as defined in the DCM Catalog. To determine the value of a configuration parameter instantiated in your system configuration, use NCM_GetValue( ). For more information about the distinction between the system configuration and the DCM Catalog, see Section 2.1, The DCM API Architecture.

The NCM_GetVariables ( ) function can be used to retrieve a list of all global configuration parameters from the DCM Catalog by setting both the NCMFamily and NCMDevice structures to NULL.

The DCM API allocates memory for the data returned by this function. To avoid memory leaks, the client application must deallocate this memory by calling the NCM_Dealloc( ) or NCM_DeallocValue( ) function.

Example

#include "NCMApi.h" 
...
//
// Prepare inputs
// 
NCMFamily family;
family.name = "D/x1D";
family.next = NULL; 
NCMDevice device;
device.name = "D/41D-1";
device.next = NULL; 
NCMProperty property;
property.name = "System";
property.next = NULL; 
NCMVariable * pVariables = NULL; 
//
// Execute
// 
NCMRetCode     ncmRc = NCM_GetVariables( &family, &device, &property,
                                                  &pVariables );
if ( ncmRc == NCM_SUCCESS )
{
     NCMVariable * pCurrVariables = pVariables;
     while ( pCurrVariables != NULL )
     {     // Process list
          ...
          pCurrVariables = pCurrVariables ->next;
     }
}
else
{     // Process error
     ...     
} 
// Deallocate memory
NCM_Dealloc( pVariables );
... 

Error Codes

Equate	Returned When
NCME_NO_INF	the DCM Catalog could not be found
NCME_MEM_ALLOC	memory could not be allocated to perform the function
NCME_GENERAL	a problem occurred retrieving the data
NCME_INVALID_INPUTS	the values of the parameters supplied are invalid

See Also

• NCM_GetAllDevices( ),
• NCM_GetAllFamilies( )
• NCM_GetProperties( )
• NCM_GetValueRange( )
• NCM_GetValueRangeEx( )
• NCM_Dealloc( )
• NCM_DeallocValue( )

Click here to contact Telecom Support Resources