AIDA_boSetStackParam

The AIDA_boSetStackParam function changes a parameter of an AIDA stack component.

bool AIDA_boSetStackParam(
  handle hStack,
  byte bLevel,
  const xchar *xsName,
  ...
);

Parameters

hStack: Handle to a stack previously created by AIDA_hCreateStack
bLevel: Stacklevel of a component previously added to the stack by AIDA_bAddToStack. To set broadcast parameters (these are parameters with their enParamAttrib set to AIDA_nenBroadcastWhenOffline or AIDA_nenBroadcastWhenOnline) you may pass either a valid stacklevel where such a parameter exists or AIDA_nBroadcast. In either case the stacklevel is ignored and all broadcast parameters of the given name are set.
xsName: Name of the parameter to be changed
...: Value of the parameter. Attention: Parameter unions must not be passed as values here since this is nonportable and will lead to malfunctions on some platforms (e. g. PPC).

Return Values

AIDA_boSetStackParam returns True on success.

If the requested parameter could not be changed or if the AIDA component does not accept the new value the function returns False. The application can retrieve the error code using AIDA_iGetError.

Remarks

The requested component may check the parameter for validity and may alter its value as needed. This does lead to an error. Please note that the behaviour of the AIDA library has changed between releases 1.0.3 and 1.0.4. In older versions when a component didn't accept a value AIDA_boSetStackParam returned true.

AIDA_boSetStackParam takes exactly one parameter in the variable part of the parameter list. This may be a string (... is const xchar *xsValue), a DWord (... is dword dwValue), a Long (... is int32 i32Value) or a Real (... is double dValue).

The parameter value is stored internally before AIDA_boSetStackParam returns. This is important when the parameter is a string. The string may be altered by the caller immediately after the function returns.

Before a parameter is changed by AIDA_boSetStackParam its type should be checked by reading the parameter with AIDA_pstGetStackParam.

Example

/* SETPARAM.C: This program sets a DWord parameter named "Port" of an AIDA component to zero.
 */

#include <stdio.h>
#include <errno.h>
#include "bsk_aida.h";

bool boResetValue( handle hStack,  bLevel )
{
  /* Reset a dword value of a component */
  if( !AIDA_boSetStackParam( hStack, bLevel, "Port", (int32)0 )
  {
    printf( "Error resetting parameter \"Port\": %d.\n", AIDA_iGetEror() );
    return False;
  }
  else
  {
    AIDA_tstParam *pstParam;
    
    /* Try to read back the parameter */
    pstParam = AIDA_pstGetStackParam( hStack, bLevel, "Port" );
    if( pstParam != NULL )
      printf( "Parameter \"Port\" is now %lu.\n", pstParam->unParamVal.dwValue );
    else
      printf( "Error reading back parameter \"Port\": %d!\n", AIDA_iGetError() );
  }
  return True;
}

Output

Parameter "Port" is now 0.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Linux: Requires a kernel supporting ELF binaries.
  Header: Declared in bsk_aida.h, also requires portab.h.
  Import Library (Windows): Use BSK_AIDA.lib.