Run Control#

Routines to start and stop runs and read data from the device.

int xiaStartRun(int detChan, unsigned short resume)#

Starts a run on the specified detChan or detChan set. For some products, e.g. XMAP, even if a single channel is specified, all channels for that module will have a run started. This is an intrinsic property of the hardware and there is no way to circumvent it in the software.

The resume parameter controls whether the MCA memory will be cleared prior to starting the run.

Param[in] detChan:

detChan or detChan set on which to start a run.

Param[in] resume:

0 to clear the MCA. 1 to resume without clearing the MCA.

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;

/* Set up a valid system here */

status = xiaStartRun(0, 0);
if (status != XIA_SUCCESS) {
    /* ERROR starting a run */
}

int xiaStopRun(int detChan)#

Stops a run on the specified channel(s). For some products, this will stop a run on all of the channels in detChan’s module.

Param[in] detChan:

detChan or detChan set on which to stop the run.

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_TIMEOUT – (For Saturn/Mercury) Timeout waiting for run to end. (BUSY not equal to 0)
XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Set up a valid system here */

status = xiaStartRun(0, 0);

if (status != XIA_SUCCESS) {
    /* ERROR starting run */

}

/* Wait for data to be collected */

status = xiaStopRun(0);

if (status != XIA_SUCCESS) {
    /* ERROR stopping run */
}

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

Returns run data for the channel. This is the primary routine to read out spectra or any other data pertaining to a run.

Param[in] detChan:

detChan to get data from. Must be a single detChan.

Param[in] name:

Type of data to get. Reference the product-specific Handel manuals for complete lists by product.

Param[out] value:

Variable to return the data in, cast into a void *. See the product-specific Handel manuals for the required data type 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 a set, not a single detChan.
XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned long mcaSize = 0;
unsigned long *mca = NULL;

/* Set up a valid system here. */

status = xiaStartRun(0, 0);
if (status != XIA_SUCCESS) {
    /* ERROR starting run */
}

/* Wait for data to collect */

status = xiaStopRun(0);
if (status != XIA_SUCCESS) {
    /* ERROR stopping run */
}

/* Now we can read out the data */
status = xiaGetRunData(0, "mca_length", (void *)&mcaSize);
if (status != XIA_SUCCESS) {
    /* ERROR reading out mca_length */
}

mca = (unsigned long *)malloc(mcaSize * sizeof(unsigned long));
if (mca == NULL) {
    /* Ran out of memory */
}

status = xiaGetRunData(0, "mca", (void *)mca);
if (status != XIA_SUCCESS) {
    /* ERROR reading our mca data */
}

/* Process spectrum data here */

int xiaDoSpecialRun(int detChan, char *name, void *info)#

Starts and stops a special run on the specified channel. Special runs include various diagnostic, setup, and calibration routines, as opposed to MCA and mapping, and list mode runs started with xiaStartRun().

This routine will block program execution until the special run is complete or an internal timeout occurs. (Internal timeouts vary between XIA processors and special run types.)

The types of special runs available for the various products are listed in the Special Run Data tables in the product-specific Handel manuals along with the composition of the info array for each type of run. The info array is used to provide additional parameters for some special run types.

Note

Some special runs require a call to xiaGetSpecialRunData() in order to properly stop the run. Reference the product-specific Handel manuals for a designation of this behavior by special run type.

Param[in] detChan:

detChan or detChan set to start the special run on.

Param[in] name:

Type of special run to perform. See Appendix E for a complete list.

Param[out] info:

An array containing additional information (if required) for the special run cast to void *. See the run specifications for the values this may contain.

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_TRACE_OOR – (For Saturn/Mercury) The specified TRACEWAIT time is out of range.
XIA_TIMEOUT – (For Saturn/Mercury) Timeout waiting for the special run to finish. (BUSY not equal to 0).
XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* tracewait of 5 microseconds (in nanoseconds) */
double info[2] = { 0.0, 5000.0 };

/* Set up a valid system here */

/* Acquire an ADC trace */
status = xiaDoSpecialRun(0, "adc_trace", (void *)info);
if (status != XIA_SUCCESS) {
    /* ERROR doing ADC trace run */
}

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

Returns data associated with a special run. For most special runs this also stops the special run that was started by xiaDoSpecialRun(). This routine must be called after xiaDoSpecialRun for some types of special runs.

See the Special Run tables in the product-specific Handel manuals for information on which special runs require the data to be read out and for the names and data types of the special run data to read out.

Param[in] detChan:

detChan to get data from. Must be a single detChan.

Param[in] name:

The name of the data to get.

Param[out] value:

Variable to return the data in, cast into a 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_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;
unsigned long adcLen = 0;;
unsigned long *adc = NULL;

/* tracewait of 5 microseconds (in nanoseconds) */
double info[2] = { 0.0, 5000.0 };

/* Set up a valid system here */

/* Want to acquire an ADC trace */
status = xiaDoSpecialRun(0, "adc_trace", (void *)info);
if (status != XIA_SUCCESS) {
    /* ERROR doing ADC trace run */
}

status = xiaGetSpecialRunData(0, "adc_trace_length", (void *)&adcLen);
if (status != XIA_SUCCESS) {
    /* ERROR getting length of ADC trace */
}

adc = (unsigned long *)malloc(adcLen * sizeof(unsigned long));
if (adc == NULL) {
    /* ERROR allocating memory for adc trace */
}

/* Stops run and gets data */
status = xiaGetSpecialRunData(0, "adc_trace", (void *)adc);
if (status != XIA_SUCCESS) {
    /* ERROR getting ADC trace */
}

/* Post-process ADC trace data */