Run Configuration#

Routines for setting and getting acquisition values, or run parameters.

int xiaSetAcquisitionValues(int detChan, char *name, void *value)#

Translates a high-level acquisition value into the appropriate DSP parameter(s) in the hardware. Product-specific Handel manuals list the acquisition values for each product.

This is the preferred method for modifying the DSP settings of a module since Handel and the PSL are responsible for making all of the necessary calculations and setting all of the necessary parameters.

In some cases, the actual acquisition value will be slightly different then the value passed in. This routine returns the actual value in the value parameter so that the host software may keep its data synchronized with the data in Handel.

This routine will also accept names that are in all capital letters and interpret them as DSP parameters. Calling this routine with a DSP parameter as the name will cause the parameter to be written to the channel specified by detChan and will also add it to the list of acquisition values to be saved.

Setting acquisition values is the mechanism that Handel provides for persistence of DSP and acquisition value settings. Handel will save this information in the .ini file generated by a call to xiaSaveSystem(). Calling xiaLoadSystem() with the generated .ini file will cause the saved parameter and acquisition values to be loaded into the DSP. This allows for a system to be started up in a state very close to the one it was saved in. See also: [Initializing Handel].

Param[in] detChan:

detChan to apply the acquisition value to. May be a single detChan or a detChan set.

Param[in] name:

The name of the acquisition value supported by the product or a DSP parameter.

Param[out] value:

Value to set the corresponding acquisition value to. double * cast to void *.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_DET_UNKNOWN – Internal Handel error. Contact XIA.

  • XIA_PEAKINGTIME_OOR – (For Saturn/Mercury) New peaking time is out of range for specified product.

  • XIA_FILEERR – (For Saturn/Mercury) Error getting firmware from FDD file.

  • XIA_OPEN_FILE – (For Saturn/Mercury) Error opening temporary file.

  • XIA_NOSUPPORT_FIRM – (For Saturn/Mercury) The specified type of firmware to download is not supported for this board type.

  • XIA_UNKNOWN_FIRM – (For Saturn/Mercury) The specified type of firmware to download is unknown.

  • XIA_BINS_OOR – (For Saturn/Mercury) The specified number of bins is out of range for this board type.

  • XIA_GAIN_OOR – (For Saturn/Mercury) The computed gain value is out of range for this board type.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
double new_threshold = 1000.0;

/* Set up a valid system here */
status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    /* ERROR starting system */
}

/* Change trigger threshold to 1000 eV */
status = xiaSetAcquisitionValue(0, "trigger_threshold", (void *)&new_threshold);
if (status != XIA_SUCCESS) {
    /* ERROR setting trigger threshold */
}

printf("Trigger threshold now set to: %lf\n", new_threshold);
int xiaGetAcquisitionValues(int detChan, char *name, void *value)#

Retrieves the current setting of an acquisition value. This routine returns the same value as xiaSetAcquisitionValues() in the value parameters.

Param[in] detChan:

detChan to retrieve the acquisition value from. Must be a single detChan.

Param[in] name:

The name of the acquisition value to retrieve. Reference the product-specific Handel manuals for the complete list by product.

Param[out] value:

Variable to return the value. double * cast in void *.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_BAD_TYPE – Specified detChan must be a single detChan and not a detChan set.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_UNKNOWN_VALUE – Specified name isn’t supported by this board type.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
double peaking_time;

/* Setup valid system here */
status = xiaGetAcquisitionValues(0, "peaking_time", (void *)&peaking_time);
if (status != XIA_SUCCESS) {
    /* ERROR getting peaking time */
}

printf("Peaking time = %lf\n", peaking_time);
int xiaRemoveAcquisitionValues(int detChan, char *name)#

Removes an acquisition value for the specified channel.

This routine is not generally needed in user programs, which work with built in acquisition values and do not add and remove their own. Handel protects against the removal of any acquisition values that are required for a specific board type.

Note

The implementation of this routine reapplies the values of other acquisition values to the device. Therefore, as is documented practice with other acquisition values routines, it must only be called during the setup phase of the program, i.e. before the first run or in between runs.

Param[in] detChan:

detChan or detChan set to remove the acquisition value from.

Param[in] name:

The name of the acquisition value to remove

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned short slowgap = 3;

/* Assume valid system already setup */
/* Add optional "slowgap" acquisition value */
status = xiaSetAcquisitionValues(0, "slowgap", (void *)&slowgap);
if (status != XIA_SUCCESS) {
    /* ERROR adding slowgap acquisition value */
}

/* Now, remove it from the acquisition list */
status = xiaRemoveAcquisitionValues(0, "slowgap");
if (status != XIA_SUCCESS) {
    /* ERROR removing slowgap acquisition value */
}
int xiaUpdateUserParam(int detChan)#

Downloads the user parameters from the list of current acquisition values for the specified channel. In this context, a user parameter is a DSP parameter that has been added to the acquisition values list by a call to xiaSetAcquisitionValues(). This routine checks the acquisition values list for all DSP parameters and then downloads them to the board.

Param[in] detChan:

detChan or detChan set to download parameters to.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Assume valid system already setup */

/* Set DSP parameters via xiaSetAcquisitionValues uppercase name
 * notation. */

status = xiaUpdateUserParams(0);
if (status != XIA_SUCCESS) {
    /* ERROR updating user parameters */
}
int xiaGainOperation(int detChan, char *name, void *value)#

Performs product-specific special gain operations. This routine supersedes the deprecated xiaGainCalibrate() and xiaGainChange(). We provide below a list of operation names regognized by the function. The operations are valid for all systems unless otherwise specified.

  • calibrate:

    Calibrates the gain using the specified delta. This gain operation supersedes the deprecated routine xiaGainCalibrate().

    Adjusts the specified channel’s settings in order to scale the energy value by the specified amount. Typically the preamplifier gain is adjusted by the inverse of the delta.

    It may take several iterations of measuring and shifting the energy value in order to achieve the correct energy value due to small variations in gain control sensitivity.

    For Saturn, unlike the gain operation adjust_percent_rule (formerly the routine xiaGainChange()), the result of this routine is that the energy value is shifted by deltaGain. adjust_percent_rule modifies the absolute step size at the ADC but does not change the energy value.

  • adjust_percent_rule: (Saturn)

    Adjusts the acquisition value adc_percent_rule by the delta. This gain operation replaces the removed xiaGainChange() routine.

  • calibrate_gain_trim: (microDXP)

    Applies the delta to the acquisition value gain_trim.

  • scale_digital_gain: (MPX-32D)

    Calibrates the digital gain using the specified delta. Adjusts the digital gain by the inverse of the specified delta but doesn’t change the associated analog gain. Calling this gain operation is equivalent to calling the special run scale_digital_gain().

Param[in] detChan:

detChan or detChan set to perform the gain operation on

Param[in] name:

Name of the gain operation to perform.

Param[in/out] value:

Value required for the gain operation cast into a void pointer. The underlying value is a double for all gain operations defined to date.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_MISSING_TYPE – Internal Handel error. Contact XIA.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist in Handel.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_MISSING_TYPE – Internal Handel error. Contact XIA.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Set up a valid system here */

/* Scale gain by a factor of 2 */
double gainDelta = 2.0;
status = xiaGainOperation(0, "calibrate_gain_trim",  &gainDelta);
if (status != XIA_SUCCESS) {
    /* ERROR Changing gain */
}
int xiaGainCalibrate(int detChan, double deltaGain)#

..error:

Deprecated. See :c:func:`xiaGainOperation`.

Adjusts the specified channel’s settings in order to scale the energy value by the specified amount. Typically the preamplifier gain is adjusted by the inverse of the delta.

It may take several iterations of measuring and shifting the energy value in order to achieve the correct energy value due to small variations in gain control sensitivity.

Warning

For Saturn, unlike the gain operation adjust_percent_rule (formerly the routine xiaGainChange), the result of this routine is that the energy value is shifted by deltaGain. adjust_percent_rule modifies the absolute step size at the ADC but does not change the energy value.

Param[in] detChan:

detChan or detChan set to apply the calibration to.

Param[in] deltaGain:

Factor by which to scale the gain.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel

  • XIA_MISSING_TYPE – Internal Handel error. Contact XIA.

  • XIA_GAIN_OOR – (For Saturn/Mercury) The calculated gain value (in dB) is out of range.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
double calibEV = 5900.0;
double peakEV = 0.0;
double scaleFactor = 0.0;

/* Set up a valid system here */

/* To calibrate a spectrum peak, get the current
 * peak position and divide the calibration energy
 * by it to get the scale factor. Adjust the gain by
 * the scale factor.
 */

/* Get actual peak position here using whatever method
 * is appropriate. We will assume that peakEV is set
 * somehow.
 */

scaleFactor = calibEV / peakEV;
status = xiaGainCalibrate(0, scaleFactor);
if (status != XIA_SUCCESS) {
    /* ERROR calibrating gain */
}
int xiaGetParameter(int detChan, const char *name, unsigned short *value)#

Gets the current value of a DSP parameter for the specified channel.

Warning

Both this routine and xiaSetParameter() work directly with the parameters in the DSP. User programs should generally use xiaGetAcquisitionValues() instead.

Param[in] detChan:

detChan to get the value from. Must be a single detChan.

Param[in] name:

Name of DSP parameter to retrieve

Param[out] value:

Pointer to unsigned short variable in which to return the value of the DSP parameter.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel

  • XIA_BAD_TYPE – detChan is a set, not a single detChan.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

unsigned short value;

/* Set up a valid system here */

status = xiaGetParameter(0, "DECIMATION", &value);
if (status != XIA_SUCCESS) {
    /* ERROR getting DECIMATION */
}

printf("Decimation = %u\n", value);
int xiaSetParameter(int detChan, const char *name, unsigned short value)#

Sets a DSP parameter for the specified channel. If the parameter is marked as read-only by the DSP it will not be modified.

Warning

CAUTION: Both this routine and xiaGetParameter() work directly with the parameters in the DSP. User programs should generally use xiaSetAcquisitionValues() instead.

Param[in] detChan:

detChan or detChan set to set the DSP parameter on.

Param[in] name:

Name of DSP parameter to set.

Param[out] value:

Pointer in which to return the DSP parameter.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned short newThresh = 0x1000;

/* Set up a valid system */

status = xiaSetParameter(0, "THRESHOLD", newThresh);
if (status != XIA_SUCCESS) {
    /* ERROR setting THRESHOLD */
}
int xiaGetNumParams(int detChan, unsigned short *numParams)#

Returns the number of DSP parameters in the DSP code currently loaded on the specified detChan. This routine is typically used in conjunction with xiaGetParams() to allocate the proper amount of memory.

Param[in] detChan:

detChan to get number of parameters from. Must be a single detChan.

Param[out] numParams:

Pointer in which to return the number of parameters.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_BAD_TYPE – detChan is a set, not a single detChan

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned short numParams = 0;

/* Assumes that a system has been loaded and
 * that xiaStartSystem() has already been
 * called.

status = xiaGetNumParams(0, &numParams);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of DSP parameters */
}

printf("detChan 0 has %u DSP parameters.\n", numParams);
int xiaGetParamData(int detChan, char *name, void *value)#

Gets the parameter information specified by the name-value pair.

Name

Type

Description

names

char**

The names of all of the DSP parameters for the specified detChan. The proper amount of memory must be allocated for the string array passed in. The standard size is the number of parameters (retrieved using xiaGetNumParams() by MAXSYMBOL_LEN, which is defined in handel_generic.h.

values

unsigned short*

The values of all of the DSP parameters for the specified detChan. The proper amount of memory must be allocated for the array passed in. Typically, the number of parameters is retrieved from xiaGetNumParams() and then used to allocate an array of the proper length.

access

unsigned short*

The access information for all of the DSP parameters for the specified detChan. The proper amount of memory must be allocated for the array passed in. Typically, the number of parameters is retrieved from xiaGetNumParams() and then used to allocate an array of the proper length. The access values are interpreted as follows: 0 = Read/Write, 1 = Read Only and 2 = WriteOnly.

lower_bounds

unsigned short*

The lower bounds information for all of the DSP parameters for the specified detChan. The proper amount of memory must be allocated for the array passed in. Typically, the number of parameters is retrieved from xiaGetNumParams() and then used to allocate an array of the proper length. If both the lower bounds and upper bounds information for a DSP parameter are equal to 0, then that DSP parameter doesn’t have any defined bounds.

upper_bounds

unsigned short*

The upper bounds information for all of the DSP parameters for the specified detChan. The proper amount of memory must be allocated for the array passed in. Typically, the number of parameters is retrieved from xiaGetNumParams() and then used to allocate an array of the proper length. If both the lower bounds and upper bounds information for a DSP parameter are equal to 0, then that DSP parameter doesn’t have any defined bounds.
Param[in] detChan:

detChan to get the DSP parameter names and values from. Must be a single detChan.

Param[in] name:

Name from table above corresponding to the desired type of DSP parameter information.

Param[out] value:

Value to set the DSP parameter information to, cast to void *. See the table above require data types and memory allocation information for each name.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel

  • XIA_BAD_TYPE – detChan is set, not a single detChan

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned short numParams = 0;
unsigned short i;
unsigned short *values = NULL;
unsigned short *access = NULL;
unsigned short *lowBounds = NULL;
unsigned short *highBounds = NULL;
char **names = NULL;

/* Assume that a system has been loaded and
 * that xiaStartSystem() has been called.
 */

status = xiaGetNumParams(0, &numParams);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of DSP parameters */
}

names = (char **)malloc(numParams * sizeof(char *));
if (names == NULL) {
    /* Out of memory trying to create names */
}

for (i = 0; i < numParams, i++) {
    names[i] = (char *)malloc(MAXSYMBOL_LEN * sizeof(char));
    if (names[i] == NULL) {
        /* Out of memory trying to create names[i] */
    }
}

values = (unsigned short *)malloc(numParams * sizeof(unsigned short));
if (values == NULL) {
    /* Out of memory trying to create values */
}

access = (unsigned short *)malloc(numParams * sizeof(unsigned short));
if (access == NULL) {
    /* Out of memory trying to create access */
}

lowBounds = (unsigned short *)malloc(numParams * sizeof(unsigned short));
if (lowBounds == NULL) {
    /* Out of memory trying to create lowBounds */
}

highBounds = (unsigned short *)malloc(numParams * sizeof(unsigned short));
if (highBounds == NULL) {
    /* Out of memory trying to create high bounds */
}

status = xiaGetParamData(0, "names", (void *)names);
if (status != XIA_SUCCESS) {
    /* ERROR getting DSP parameter names */
}

status = xiaGetParamData(0, "values", (void *)values);
if (status != XIA_SUCCESS) {
    /* ERROR getting DSP parameter values */
}

status = xiaGetParamData(0, "access", (void *)access);
if (status != XIA_SUCCESS) {
    /* ERROR getting DSP parameter access information */
}

status = xiaGetParamData(0, "lower_bounds", (void *)lowBounds);
if (status != XIA_SUCCESS) {
    /* ERROR getting DSP parameter lower bounds information */
}

status = xiaGetParamData(0, "upper_bounds", (void *)highBounds);
if (status != XIA_SUCCESS) {
    /* ERROR getting DSP parameter upper bounds information */
}

for (i = 0; i < numParams; i++) {
    printf("%s = %u: %u %u %u\n", names[i], values[i], access[i],
        lowBounds[i], highBounds[i]);
}

for (i = 0; i < numParams; i++) {
    free((void *)names[i]);
}

free((void *)names);
names = NULL;

free((void *)values);
values = NULL;

free((void *)access);
access = NULL;

free((void *)lowBounds);
lowBounds = NULL;

free((void *)highBounds);
highBounds = NULL;
int xiaGetParamName(int detChan, unsigned short index, char *name)#

Returns the DSP parameter name located at the specified index. This routine should be used in place of xiaGetParams() when interfacing to Handel with a language that doesn’t support the passing of string arrays to DLLs, like Visual Basic.

Typical use is to get the number of DSP parameters for the detChan with a call to xiaGetNumParams(). Then loop for 0 to numParams –1 to read in all of the DSP parameter names.

Param[in] detChan:

detChan to get the DSP parameter name from. Must be a single detChan.

Param[in] index:

Index of the desired DSP parameter name in the complete DSP parameter name list.

Param[in] name:

A string of the proper length, MAXSYMBOL_LEN (defined in handel_generic.h)

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel

  • XIA_BAD_TYPE – detChan is set, not a single detChan

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned short numParams = 0;
unsigned short i;
char name[MAXSYMBOL_LEN];

/* Assume that a valid system has been setup here */

status = xiaGetNumParams(0, &numParams);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of DSP params */
}

for (i = 0; i < numParams; i++) {
    status = xiaGetParamName(0, i, name);
    if (status != XIA_SUCCESS) {
        /* ERROR getting DSP parameter name at index i */
    }

    printf("DSP Parameter Name at index = %u: %s\n", i, name);
}