Modules#

Routines for querying information about modules. A module is an XIA card consisting of one or more channels.

int xiaGetNumModules(unsigned int *numModules)#

Returns the number of modules currently defined in the system.

Param[out] numModules:: Pointer to a variable to store the returned number of detectors in
Returns:: A status code indicating the result of the operation.

Example Usage

int status;
unsigned int numModules = 0;

/* Assume that a system has already been
 * created or loaded.
 */
status = xiaGetNumModules(&numModules);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of modules */
}

printf("There are currently %u modules defined.\n", numModules);

int xiaGetModuleItem(char *alias, char *name, void *value)#

Retrieve information from a module’s configuration. All names listed below may be retrieved using this routine except for _firmware_set_all_. Consult the list for the data types to use for value.

Param[in] alias:

A valid module alias

Param[in] name:

Name of value to retrieve

Param[out] value:

Void pointer to variable in which the returned data will be stored. It is very important that the type of this variable is appropriate for the data to be retrieved. See the lists above for more information. Consult the Usage section below for more information on how to use void pointers in this context.

Returns:

A status code indicating the result of the operation.

Return values:

XIA_NO_ALIAS – Specified alias does not exist
XIA_BAD_NAME – Specified name is invalid
XIA_WRONG_INTERFACE – Specified name does not apply to the current interface
XIA_BAD_CHANNEL – Internal Handel error. Contact XIA.

Module Items

Name	Interface	Type	Description
module_type	any	null-terminated string	The name corresponding to the type of module. Supported types are saturn (and dxpx10p and x10p for backward compatibility), udxp, udxps, xmap, mercury, and stj. Note that a build of Handel may support only one product line; the other products are compiled out of the code. This must be specified first.
interface	any	null-terminated string	The physical interface type for this module. Supported interfaces are “genericEPP”, “epp”, “usb”, “usb2”, “serial”, “pxi”. It is not strictly necessary to specify the interface, as Handel can recognize the interface based on the first interface item that is added to the system.
number_of_channels	any	unsigned int	Number of channels associated with a module of this type. Not the number of channels in use. That information will be specified elsewhere. If you have a 4-channel XMAP module and only plan to use 2 of the channels, this value must still be set to 4. This value must be added before any of values listed below are added.
channel{n}_alias	any	int	The “detChan” value for channel n. Each physical channel in the system has a unique “detChan” value associated with it. This value is important because it is how an individual channel is operated on by other Handel routines. To disable a channel, set its detChan value to -1.
channel{n}_detector	any	null-terminated string	The alias of the detector that channel n is attached to. The format of this string is “detector_alias:m” where is m is the channel number of the actual detector channel (preamplifier) that this module channel is attached to. The alias must be a valid detector alias defined in the [detector section](#ini_detector) of the .ini file.
channel{n}_gain	any	double	Gain, in this context, describes any modifications made to the input gain stage of a channel. Most users should set this to 1.00. This value is not the same as the preamplifier gain, as described in the [Detectors] section, nor is it the same as the gain set by the DSP parameter GAINDAC.
firmware_set_all	any	null-terminated string	Same as firmware_set_chan{n} except that the same alias will be used for all channels in the module.
epp_address	GenericEPP/EPP	unsigned int	The address of the EPP port on the host computer. Typically the address is 0x378 or, ocassionally, 0x278.
daisy_chain_id	GenericEPP/EPP	unsigned int	(Optional) The daisy chain ID for this module. Should only be specified if the module specifically implements the daisy chain protocol.
device_number	USB/USB 2	unsigned int	The USB device number associated with this module. Typically this is 0 for a single module system, and increments by one for each additional module.
com_port	Serial	unsigned int	The one-based serial port number to which the module is attached. Port number N corresponds to COMx where x = N-1.
device_file	Serial	char*	On Linux, a device file to open for terminal IO. This replaces com_port on that platform.
baud_rate	Serial	unsigned int	The baud rate of the serial port. Typically 115200 but may be firmware-dependent.
pci_slot	PXI	byte_t
pci_bus	PXI	byte_t

Example Usage

int status;
int detChan;

/* Create a module with alias module1 here and then add all of the
 * information associated with a DXP-X10P to it. We will only
 * retrieve the detChan value of channel 0 here but the other
 * names follow the same pattern.
 */

status = xiaGetModuleItem("module1", "channel0_alias", (void *)&detChan);
if (status != XIA_SUCCESS) {
    /* ERROR Getting channel0_alias */
}

printf("Channel 0 detChan = %d\n", detChan);

int xiaGetModules(char *modules[])#

Returns a list of the aliases of the modules defined in the system.

The caller must allocate memory for modules. Typically this is done by calling xiaGetNumModules() and using the number to initialize a string array. Allocate a char * of length MAXALIAS_LEN for each module.

Param[out] modules:: A string array of the proper length: numModules by MAXALIAS_LEN (defined in handel_generic.h)
Returns:: A status code indicating the result of the operation.

Example Usage

int status;
unsigned int numModules = 0;
unsigned int i;
char **modules = NULL;

/* Assume that a system has already been loaded. */
status = xiaGetNumModules(&numModules);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of modules */
}

/* Allocate the memory we need for the string array */
modules = (char **)malloc(numModules * sizeof(char *));
if (modules == NULL) {
    /* ERROR allocating memory for modules */
}

for (i = 0; i < numModules; i++) {
    modules[i] = (char *)malloc(MAXALIAS_LEN * sizeof(char));
    if (modules[i] == NULL) {
        /* ERROR allocating memory for modules[i] */
    }
}

status = xiaGetModules(modules);
if (status != XIA_SUCCESS) {
    /* ERROR getting module list */
}

for (i = 0; i < numModules; i++) {
    printf("modules[%u] = %sn", i, modules[i]);
}

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

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

int xiaGetModules_VB(unsigned int index, char *alias)#

Gets a module alias by index. This routine serves as a replacement of the routine xiaGetModules() for use with Visual Basic or other languages that will not allow an array of strings to be passed into the Handel DLL. This returns a single module alias, where index ranges from 0 to numModules – 1. The standard idiom is to get the number of modules in the system with a call to xiaGetNumModules() and then loop from 0 to numModule –1 in order to get all of the module aliases in the system.

The caller must allocate memory for alias.

Param[in] index:: Position of module alias in system where index ranges from 0 to numModule – 1. For instance, if you have a system where 3 modules are defined, the valid values for index are 0, 1 and 2.
Param[out] alias:: Alias of the module located at the specified index. The caller must allocate a string of length MAXALIAS_LEN (defined in handel_generic.h).
Returns:: A status code indicating the result of the operation.
Retval:: XIA_BAD_INDEX: The specified index is out-of-range

Example Usage

int status;
unsigned int numModules = 0;
unsigned int i;
char **aliases = NULL;

/* Assume that a valid system has been setup */
status = xiaGetNumModules(&numModules);
if (status != XIA_SUCCESS) {
    /* ERROR getting # of modules in system */
}

/* Must allocate proper amount of memory */
aliases = (char **)malloc(numModules * sizeof(char *));
if (aliases == NULL) {
    /* ERROR allocating memory for aliases array */
}

for (i = 0; i < numModules; i++) {
    aliases[i] = (char *)malloc(MAXALIAS_LEN * sizeof(char));
    if (aliases[i] == NULL) {
        /* ERROR allocating memory for aliases[i] */
    }
}

for (i = 0; i < numModules; i++) {
    status = xiaGetModules_VB(i, aliases[i]);
    if (status != XIA_SUCCESS) {
        /* ERROR getting module alias at index i */
    }
}

for (i = 0; i < numModules; i++) {
    printf("Module alias at index = %u: %s", i, aliases[i]);
}

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

free(aliases);

Enumerating Modules and Channels#

While XIA systems are defined hierarchically as a collection of modules each containing a number of channels, acquisition APIs require a unique channel alias, also known as a detChan, as the primary identifying argument. Thus some means of querying the system is needed to obtain the detChans to use in calling acquisition APIs.

While detChans by definition are only constrained to be unique for each channel, XIA tools do generate .ini files with zero-based whole number channel aliases. Therefore if you know the number of channels in the system, you can treat the detChan as a zero-based index. This may be easy in a single module system, but for robustness we recommend looping through the modules to get the aliases.

The following example shows the easiest way to loop through all modules and channels and perform an API call on each detChan. The same loop structure could be used at the beginning of your application to cache the detChans in a module structure for later use.

Note

The examples in this section use the routine xiaGetModules_VB() for convenience to avoid allocating memory for all the module aliases. You may also get all the aliases in one call using the techniques demonstrated in xiaGetModules().

int status;
unsigned int numModules = 0;
unsigned int mod;

/* Assume that a valid system has been setup */
status = xiaGetNumModules(&numModules);
if (status != XIA_SUCCESS) {
    /* ERROR getting # of modules in system */
}

/* For each module in the system */
for (mod = 0; mod < numModules; mod++) {
    char module[MAXALIAS_LEN];
    int numChannels;
    int chan;

    status = xiaGetModules_VB(mod, module);
    if (status != XIA_SUCCESS) {
        /* ERROR getting module alias at index mod */
    }

    status = xiaGetModuleItem(module, "number_of_channels", &numChannels);
    if (status != XIA_SUCCESS) {
        /* ERROR getting number of channels for module */
    }

    /* For each channel in the module */
    for (chan = 0; chan < numChannels; chan++) {
        char item[20];
        int detChan;

        sprintf(item, "channel%d_alias", chan);
        status = xiaGetModuleItem(module, item, &detChan);
        if (status != XIA_SUCCESS) {
            /* ERROR getting channel alias */
        }

        /* Performing an acquisition task with detChan here will do it
         * for each channel in the system.
         */
    }
}

To perform a task on the first channel in each module, simply operate on “channel0_alias” instead of all channels, as shown in the following example. The same loop structure could be used with module item “number_of_channels” to count the total number of channels in the system.

int status;
unsigned int numModules = 0;
unsigned int mod;

/* Assume that a valid system has been setup */
status = xiaGetNumModules(&numModules);
if (status != XIA_SUCCESS) {
    /* ERROR getting # of modules in system */
}

/* For each module in the system */
for (mod = 0; mod < numModules; mod++) {
    char module[MAXALIAS_LEN];
    int numChannels;
    int chan;

    /* Get the module alias */
    status = xiaGetModules_VB(mod, module);
    if (status != XIA_SUCCESS) {
        /* ERROR getting module alias at index mod */
    }

    /* Get the detChan of the first channel in the module */
    status = xiaGetModuleItem(module, "channel0_alias", &detChan);
    if (status != XIA_SUCCESS) {
        /* ERROR getting channel alias */
    }

    /* Performing an acquisition task with detChan here will do it
     * for the first channel in each module, e.g. get
     * run data module_statistics_2.
     */
}