Dynamic Configuration#

Warning

The dynamic configuration methods could potentially make the system unstable if used after starting up. Modification to system configuration can be safely done by loading a new configuration file with xiaLoadSystem(), then calling xiaStartSystem().

For advanced or dynamic system configuration, all of the information associated with these structures is modified through a uniform set of routines:

  • xiaNew{NAME},

  • xiaAdd{NAME}Item,

  • xiaModify{NAME}Item,

  • xiaGet{NAME}Item and

  • xiaRemove{NAME},

where {NAME} is one of “Detector”, “Firmware”, or “Module”.

int xiaNewDetector(char *alias)#

Creates a new detector with the name alias that can be referenced by other routines such as xiaAddDetectorItem(), xiaGetDetectorItem(), xiaModifyDetectorItem() and xiaRemoveDetector().

Param[in] alias:

Name of new detector to be added to system.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_ALIAS_SIZE – Length of alias exceeds the maximum allowed length

  • XIA_ALIAS_EXISTS – A detector with the specified alias already exists

  • XIA_NOMEM – Ran out of memory trying to create new detector

Example Usage

int status;
status = xiaNewDetector("detector1");
if (status != XIA_SUCCESS) {
    /* ERROR Creating new detector */
}
int xiaAddDetectorItem(char *alias, char *name, void *value)#

Adds information about the detector using name-value pairs. Reference the [Detector Items] list for valid names and required value types.

An error is returned if the specified alias has not been created with a previous call to xiaNewDetector().

Param[in] alias:

A valid detector alias.

Param[in] name:

Name from table above corresponding to the information the user wishes to set.

Param[out] value:

Value to set the corresponding detector information to, cast to a void *. See Usage for examples of using void pointers in this context.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_BAD_VALUE – value could not be converted to the required type.

  • XIA_NO_ALIAS – Specified alias does not exist.

  • XIA_BAD_NAME – name is not a valid detector item.

Example Usage

int status;
unsigned int number_of_channels = 1;
double gain = 5.6;

/* Assume that detector already created with alias = detector1 */
status = xiaAddDetectorItem("detector1", "number_of_channels",
                            (void *)&number_of_channels);
if (status != XIA_SUCCESS) {
    /* ERROR Adding number_of_channels */
}

status = xiaAddDetectorItem("detector1", "channel0_gain", (void *)&gain);
if (status != XIA_SUCCESS) {
    /* ERROR adding gain */
}

status = xiaAddDetectorItem("detector1", "channel0_polarity", (void *)"pos");
if (status != XIA_SUCCESS) {
    /* ERROR adding polarity */
}
int xiaModifyDetectorItem(char *alias, char *name, void *value)#

Modifies the value of a detector item. See [Detector Items] for the table of allowed names and value types.

Warning

You must call xiaStartSystem() in order for the changed values to be reflected in the hardware.

Param[in] alias:

A valid detector alias

Param[in] name:

Name of value to modify. See description for allowed names.

Param[out] value:

Value to change current setting to, cast into a void pointer. See the Usage section for an example of using a void pointer in this context.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_BAD_VALUE – Value is NULL or there is an error with it

  • XIA_BAD_NAME – Specified name is not allowed to be modified or is invalid

  • XIA_NO_ALIAS – Specified alias does not exist

Example Usage

int status;
double new_gain = 5.7;

/* Assume a detector with alias "detector1" has already been created.
 */
status = xiaModifyDetectorItem("detector1", "channel0_gain", (void *)&new_gain);
if (status != XIA_SUCCESS) {
    /* ERROR Modifying channel 0 gain */
}

status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    /* ERROR starting system */
}
int xiaRemoveDetector(char *alias)#

Removes a detector from the system.

Param[in] alias:

A valid detector alias

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_NO_ALIAS – Specified alias does not exist

Example Usage

int status;

/* Remove detector w/ alias detector1 */
status = xiaRemoveDetector("detector1");
if (status != XIA_SUCCESS) {
    /* ERROR removing detector */
}
int xiaNewFirmware(char *alias)#

Creates a new firmware with the name alias that can be referenced by other routines such as xiaAddFirmwareItem(), xiaGetFirmwareItem(), xiaModifyFirmwareItem() and xiaRemoveFirmware().

Param[in] alias:

Name of new firmware to be added to system

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_ALIAS_SIZE – Length of alias exceeds the maximum allowed length

  • XIA_ALIAS_EXISTS – Firmware with the specified alias already exists

  • XIA_NOMEM – Ran out of memory trying to create new firmware

Example Usage

int status;
status = xiaNewFirmware("firmware1");
if (status != XIA_SUCCESS) {
    /* ERROR Creating new firmware */
}
int xiaAddFirmwareItem(char *alias, char *name, void *value)#

Adds information about the firmware using name-value pairs. Firmware can be divided into two categories: those that use the FDD and those that don’t. Each category has its own set of name-value pairs. Reference the Firmware Items lists for details.

The standard procedure is to use an XIA supplied FDD file. If one is defining custom firmware there are some key points to remember:

  1. The PTRRs may not overlap

  2. Once a call to xiaAddFirmwareItem() has been made with the name “ptrr”, all calls to xiaAddFirmwareItem() using names listed below “ptrr” in the table above will be added to the most recently added “ptrr”. The implication of this is that you must add all of the PTRR information before switching to the next PTRR. However, any information that is omitted may be added using xiaModifyDetectorItem().

Param[in] alias:

A valid firmware alias

Param[in] name:

Name from table above corresponding to the information the user wishes to set

Param[in] value:

Value to set the corresponding firmware information to, cast into a void *. See Usage section for examples of using void pointers in this context.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_NO_ALIAS – Specified alias does not exist

  • XIA_BAD_VALUE – Error with value passed in

  • XIA_BAD_NAME – Specified name is invalid

  • XIA_BAD_PTRR – The PTRR to be added already exists

Example Usage

int status;
unsigned short ptrr = 0;
double min_ptime = 0.25;
double max_ptime = 1.25;

/* Only illustrate how to create firmware using PTRRs since using the
 * FDD files is trivial. Assume firmware "firmware1" already
 * created.
 */

status = xiaAddFirmwareItem("firmware1", "ptrr", (void *)&ptrr);
if (status != XIA_SUCCESS) {
    /* ERROR Adding PTRR */
}

status = xiaAddFirmwareItem("firmware1", "min_peaking_time", (void *)&min_ptime);
if (status != XIA_SUCCESS) {
    /* Error Adding minimum peaking time to PTRR 0 */
}

status = xiaAddFirmwareItem("firmware1", "max_peaking_time", (void *)&max_ptime);
if (status != XIA_SUCCESS) {
    /* ERROR Adding maximum peaking time to PTRR 0 */
}

status = xiaAddFirmwareItem("firmware1", "fippi", (void *)"fxpd0g.fip");
if (status != XIA_SUCCESS) {
    /* ERROR Adding FiPPI file to PTRR 0 */
}

status = xiaAddFirmwareItem("firmware1", "dsp", (void *)"x10p.hex");
if (status != XIA_SUCCESS) {
    /* ERROR Adding DSP file to PTRR 0 */
}

ptrr = 1;
min_ptime = 1.25;
max_ptime = 5.0;
status = xiaAddFirmwareItem("firmware1", "ptrr", (void *)&ptrr);

if (status != XIA_SUCCESS) {
    /* ERROR Adding new PTRR */
}

status = xiaAddFirmwareItem("firmware1", "min_peaking_time", (void *)&min_ptime);
if (status != XIA_SUCCESS) {
    /* ERROR Adding minimum peaking time to PTRR 1 */
}
int xiaModifyFirmwareItem(char *alias, unsigned short ptrr, char *name, void *value)#

Modifies a firmware set item. See Firmware Items for a table of names. The overall disposition of the firmware may not be modified, i.e., if a firmware is already using the FDD, it may not use PTRRs; a new firmware alias should be created for the PTRRs.

Warning

You must call xiaDownloadFirmware() or xiaStartSystem() if you wish to update the firmware that is currently downloaded to the processor.

Param[in] alias:

A valid firmware alias

Param[in] ptrr:

The PTRR that corresponds to the information to be modified. Not all names to be modified require a PTRR, in which case it may be set to NULL.

Param[in] name:

Name of value to modify, which must come from the tables in Firmware Items.

Param[in] value:

Value to change current setting to, cast to void *. Reference the tables for the data type to use for the actual variable.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_BAD_VALUE – Value is NULL or there is an error with it

  • XIA_NO_ALIAS – Specified alias does not exist

  • XIA_BAD_NAME – Specified name is invalid

Example Usage

int status;

/* Add firmware called "firmware1" here that uses PTRRs. Assume that
 * there is a single PTRR with the value of 0.
 */

status = xiaModifyFirmwareItem("firmware1", 0, "dsp", (void *)"d2xr0105.hex");
if (status != XIA_SUCCESS) {
    /* ERROR Modifying PTRR 0 DSP file name */
}
int xiaRemoveFirmware(char *alias)#

Removes a firmware set from the system.

Param[in] alias:

A valid firmware alias

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_NO_ALIAS – Specified alias does not exist

Example Usage

int status;

/* Assume firmware w/ alias "firmware1" already exists */
status = xiaRemoveFirmware("firmware1");
if (status != XIA_SUCCESS) {
    /* ERROR Removing firmware */
}
int xiaNewModule(char *alias)#

Creates a new module with the name alias that can be referenced by other routines such as xiaAddModuleItem(), xiaGetModuleItem(), xiaModifyModuleItem() and xiaRemoveModule().

Param[in] alias:

Name of new module to be added to system

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_ALIAS_SIZE – Length of alias exceeds the maximum allowed length

  • XIA_ALIAS_EXISTS – A module with the specified alias already exists

  • XIA_NOMEM – Ran out of memory trying to create a new module

Example Usage

int status;
status = xiaNewModule("module1");
if (status != XIA_SUCCESS) {
    /* ERROR Creating new module */
}
int xiaAddModuleItem(char *alias, char *name, void *value)#

Adds information about the module using name-value pairs. Reference the Module Items list for valid names and required value types.

When setting up a new module, always add the module_type first, then add the other details. Certain items in this table apply only to certain module types. An error is returned if you attempt to add an item that does not apply.

Param[in] alias:

A valid module alias

Param[in] name:

Name from the tables above corresponding to the information that the user wants to set

Param[in] value:

Value to set the corresponding module information to, cast into a void pointer. See Usage section for an example of using void pointers in this context.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_BAD_VALUE – Error with value passed in

  • XIA_NO_ALIAS – Specified alias does not exist. May refer to module, detector or firmware alias depending on the context of the error message.

  • XIA_BAD_INTERFACE – Specified interface is invalid

  • XIA_WRONG_INTERFACE – Specified name is not a valid element of the current interface

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is invalid

  • XIA_BAD_TYPE – Internal error. Contact XIA

  • XIA_BAD_CHANNEL – Specified physical detector channel (see channel_detector{n}) is invalid

Example Usage

int status;
int chan0alias = 0;
unsigned int epp_address = 0x378;
unsigned int num_channels = 1;
double chan0gain = 1.0;

/* Assume that module already created with alias "module1". This
 * example will show how to add a DXP-X10P box to the system.
 */

status = xiaAddModuleItem("module1", "module_type", (void *)"dxpx10p");

if (status != XIA_SUCCESS) {
    /* ERROR Adding module_type */
}

status = xiaAddModuleItem("module1", "interface", (void *)"epp");
if (status != XIA_SUCCESS) {
    /* ERROR Adding interface */
}

status = xiaAddModuleItem("module1", "epp_address", (void *)&epp_address);
if (status != XIA_SUCCESS) {
    /* ERROR Adding epp_address */
}

status = xiaAddModuleItem("module1", "number_of_channels", (void *)&num_channels);
if (status != XIA_SUCCESS) {
    /* ERROR Adding number_of_channels */
}

/* Here, assume that we have the following aliases defined:
 * detector1, firmware1.
 */
status = xiaAddModuleItem("module1", "channel0_alias", (void *)&chan0alias);
if (status != XIA_SUCCESS) {
    /* ERROR Adding channel0_alias */
}

status = xiaAddModuleItem("module1", "channel0_detector", (void *)"detector1:0");
if (status != XIA_SUCCESS) {
    /* ERROR Adding channel0_detector */
}

status = xiaAddModuleItem("module1", "channel0_gain", (void *)&chan0gain);
if (status != XIA_SUCCESS) {
    /* ERROR Adding channel0_gain */
}

status = xiaAddModuleItem("module1", "firmware_set_chan0", (void *)"firmware1");
if (status != XIA_SUCCESS) {
    /* ERROR Adding firmware_set_chan0 */
}
int xiaModifyModuleItem(char *alias, char *name, void *value)#

Modifies a module item. Allowed names are channel{n}_alias, channel{n}_detector, channel{n}_gain, firmware_set_all and firmware_set_chan{n}. See Module Items for the data types to use for value.

Warning

You must call xiaStartSystem() xiaDownloadFirmware() in order for the changed values to be reflected in the hardware.

Param[in] alias:

A valid module alias

Param[in] name:

Name of value to modify

Param[in] value:

Value to change current setting to, cast into a void pointer.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_NO_MODIFY – Specified name can not be modified

  • XIA_BAD_VALUE – Error with value passed in

  • XIA_NO_ALIAS – Specified alias does not exist. May refer to module, detector or firmware alias depending on the context of the error message.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is invalid

  • XIA_BAD_TYPE – Internal error. Contact XIA

  • XIA_BAD_CHANNEL – Specified physical detector channel (see channel_detector{n}) is invalid

Example Usage

int status;

/* Add a module called "module1" here. See xiaAddModuleItem() for an
 * example of the information in "module1".
 */
status = xiaModifyModuleItem("module1", "firmware_set_all", (void *)"new_firmware");
if (status != XIA_SUCCESS) {
    /* ERROR Modifying firmware_set_all */
}
int xiaRemoveModule(char *alias)#

Removes a module from the system.

Param[in]:

alias: A valid module alias

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_NO_ALIAS – Specified alias does not exist

Example Usage

int status;

/* Remove the module with alias module1 */
status = xiaRemoveModule("module1");
if (status != XIA_SUCCESS) {
    /* ERROR Removing module */
}
int xiaAddChannelSetElem(unsigned int detChan, unsigned int newChan)#

Adds a detChan to a detector channel set. If the detector channel set doesn’t already exist, it will be created. If it already exists, newChan will be added to it.

Param[in] detChan:

Detector channel set to, if necessary, create and add newChan to

Param[in] newChan:

Existing detector channel (or detector channel set) to add to detChan. CAUTION: This must be a previously created detector channel set or detector channel.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – newChan doesn’t exist yet

  • XIA_BAD_VALUE – Internal Handel error. Contact XIA.

  • XIA_BAD_TYPE – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Assume that a module with channel 0 set to detChan = 0 exists.
 * Now, we want to create a detector channel set with detChan = 1
 * that contains detChan = 0. (If this is confusing, consult the
 * Handel Users Manual for a detailed explanation of how detector
 * channels works.
 */
status = xiaAddChannelSetElem(1, 0);
if (status != XIA_SUCCESS) {
    /* ERROR Adding detChan 0 to detector channel set 1 */
}
int xiaRemoveChannelSetElem(unsigned int detChan, unsigned int chan)#

Remove a channel from a detector channel set.

Param[in] detChan:

Detector channel number of the set that contains chan

Param[in] chan:

Detector channel to remove from detChan

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_INVALID_DETCHAN – Specified detChan(s) are invalid

Example Usage

int status;

/* Assume that a detector channel set (detChan = 0) has been created
 * with detChans 1 & 2 as elements.
 */

/* Remove detChan = 1 from detChan = 0 */
status = xiaRemoveChannelSetElem(0, 1);
if (status != XIA_SUCCESS) {
    /* ERROR Removing detChan */
}
int xiaRemoveChannelSet(unsigned int detChan)#

Removes a detector channel set. Detector channels contained in the set are not removed; they are only dereferenced them from the specified set.

Param[in] detChan:

A valid detector channel set to be removed.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_WRONG_TYPE – Specified detChan is not a detector channel set

  • XIA_INVALID_DETCHAN – Specified detChan is invalid

  • XIA_BAD_TYPE – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Assume that a detector channel set (detChan = 0) has been created
 * with detChans 1 & 2.
 */

status = xiaRemoveChannelSet(0);
if (status != XIA_SUCCESS) {
    /* ERROR Removing detector channel set (detChan = 0) */
}