Using ziCore Modules in the LabOne C API#

group modules

This sections describes ziAPI’s interface for working with ziCore Modules. Modules provide a high-level interface for performing common measurement tasks such as sweeping data (Sweeper Module) or recording bursts of when certain trigger criteria have been fulfilled (Software Trigger Module). For an introduction to working with Modules please see the “ziCore Modules” section in the LabOne Programming Manual: https://www.zhinst.com/manuals/programming .

Typedefs

typedef struct ZIChunkHeader ZIChunkHeader#
typedef struct ZIModuleEvent ZIModuleEvent#
typedef ZIModuleEvent *ZIModuleEventPtr#

The pointer to a Module’s data chunk to read out, updated via ziAPIModGetChunk.

Enums

enum ZIChunkHeaderFlags_enum

Defines the flags returned in the chunk header for all modules.

Values:

enumerator ZI_CHUNK_HEADER_FLAG_FINISHED = 0x00000001

Indicates that the chunk data is complete. This flag will be set if data is read out from the module before the measurement (e.g. sweep) has finished.

enumerator ZI_CHUNK_HEADER_FLAG_ROLLMODE = 0x00000002

Unused.

enumerator ZI_CHUNK_HEADER_FLAG_DATALOSS = 0x00000004

Indicates that dataloss has occurred.

enumerator ZI_CHUNK_HEADER_FLAG_VALID = 0x00000008

Indcates that the data is valid.

enumerator ZI_CHUNK_HEADER_FLAG_DATA = 0x00000010

Indicates whether then chunk contains data (opposite to setting).

enumerator ZI_CHUNK_HEADER_FLAG_DISPLAY = 0x00000020

Internal use only.

enumerator ZI_CHUNK_HEADER_FLAG_FREQDOMAIN = 0x00000040

chunk contains frequency domain data, opposite to time domain.

enumerator ZI_CHUNK_HEADER_FLAG_SPECTRUM = 0x00000080

chunk recorded in spectrum mode.

enumerator ZI_CHUNK_HEADER_FLAG_OVERLAPPED = 0x00000100

chunk results overlap with neighboring chunks, see spectrum.

enumerator ZI_CHUNK_HEADER_FLAG_ROWFINISHED = 0x00000200

indicates that the current row is finished - useful for row first averaging.

enumerator ZI_CHUNK_HEADER_FLAG_ONGRIDSAMPLING = 0x00000400

exact sampling was used.

enumerator ZI_CHUNK_HEADER_FLAG_ROWREPETITION = 0x00000800

row first averaging is enabled.

enumerator ZI_CHUNK_HEADER_FLAG_PREVIEW = 0x00001000

chunk contains preview (fft with less points).

enum ZIChunkHeaderModuleFlags_enum

Defines flags returned in the chunk header that only apply for certain modules.

Values:

enumerator ZI_CHUNK_HEADER_MODULE_FLAGS_WINDOW = 0x00000003

FFT Window used in the Data Acquisition Module: 0 - Rectangular, 1 - Hann, 2 - Hamming, 3 - Blackmanharris, 4 - Exponential, 5 - Cosine, 6 - CosineSquare.

Functions

ZIResult_enum ziAPIModCreate(ZIConnection conn, ZIModuleHandle *handle, const char *moduleId)

Create a ZIModuleHandle that can be used for asynchronous measurement tasks.

This function initializes a ziCore module and provides a pointer (handle) with which to access and work with it. Note that this function does not start the module’s thread. Before the thread can be started (with ziAPIModExecute):

  • the device serial (e.g., “dev100”) to be used with module must be specified via ziAPIModSetByteArray.

  • the desired data (node paths) to record during the measurement must be specified via ziAPIModSubscribe. The module’s thread is stopped with ziAPIModClear.

Parameters:
  • conn[in] The ZIConnection which should be used to initialize the module.

  • handle[out] Pointer to the initialized ZIModuleHandle, which from then on can be used to reference the module.

  • moduleId[in] The name specifying the type the module to create (only the following ziCore Modules are currently supported in ziAPI):

    • ”sweep” to initialize an instance of the Sweeper Module.

    • ”record” to initialize an instance of the Software Trigger (Recorder) Module.

    • ”zoomFFT” to initialize an instance of the Spectrum Module.

    • ”deviceSettings” to initialize an instance to save/load device settings.

    • ”pidAdvisor” to initialize an instance of the PID Advisor Module.

    • ”awgModule” to initialize an instance of the AWG Compiler Module.

    • ”impedanceModule” to initialize an instance of the Impedance Compensation Module.

    • ”scopeModule” to initialize an instance of the Scope Module to assembly scope shots.

    • ”multiDeviceSyncModule” to initialize an instance of the Device Synchronization Module.

    • ”dataAcquisitionModule” to initialize an instance of the Data Acquisition Module.

    • ”precompensationAdvisor” to initialize an instance of the Precompensation Advisor Module.

    • ”quantumAnalyzerModule” to initialize an instance of the Quantum Analyzer Module.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred.

  • ZI_WARNING_NOTFOUND if the provided moduleId was invalid.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetDoubleData(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIDoubleData value)

Sets a module parameter to the specified double type.

This function is used to configure (set) module parameters which have double types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • value[in] The double data to write to the path.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetIntegerData(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIIntegerData value)

Sets a module parameter to the specified integer type.

This function is used to configure (set) module parameters which have integer types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • value[in] The integer data to write to the path.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetByteArray(ZIConnection conn, ZIModuleHandle handle, const char *path, uint8_t *buffer, uint32_t length)

Sets a module parameter to the specified byte array.

This function is used to configure (set) module parameters which have byte array types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • buffer[in] Pointer to the byte array with the data.

  • length[in] Length of the data in the buffer.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetString(ZIConnection conn, ZIModuleHandle handle, const char *path, const char *str)

Sets a module parameter to the specified null-terminated string.

This function is used to configure (set) module parameters which have string types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • str[in] Pointer to a null-terminated string (max 64k characters).

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char *path, const wchar_t *wstr)

Sets a module parameter to the specified null-terminated unicode string.

This function is used to configure (set) module parameters which have string types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • wstr[in] Pointer to a null-terminated unicode string (max 64k characters).

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSetVector(ZIConnection conn, ZIModuleHandle handle, const char *path, const void *vectorData, ZIVectorElementType_enum elementType, unsigned int numElements)

Sets a module parameter to the specified vector.

This function is used to configure (set) module parameters which have vector types.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to set data on.

  • path[in] Path of the module parameter to set.

  • vectorData[in] Pointer to the vector data.

  • elementType[in] Type of elements stored in the vector.

  • numElements[in] Number of elements of the vector.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetInteger(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIIntegerData *value)

Gets the integer-type value of the specified module parameter path.

This function is used to retrieve module parameter values of type integer.

See also

ziAPIModGetDouble, ziApiModGetString

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved.

  • handle[in] The ZIModuleHandle specifying the module to get the value from.

  • path[in] The path of the module parameter to get data from.

  • value[out] Pointer to an 64bit integer in which the value should be written

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN

  • ZI_ERROR_COMMAND on an incorrect answer of the server

  • ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server

  • ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path

  • ZI_ERROR_TIMEOUT when communication timed out

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetDouble(ZIConnection conn, ZIModuleHandle handle, const char *path, ZIDoubleData *value)

Gets the double-type value of the specified module parameter path.

This function is used to retrieve module parameter values of type floating point double.

See also

ziAPIModGetInteger, ziApiModGetString

Parameters:
  • conn[in] Pointer to ZIConnection with which the value should be retrieved

  • handle[in] The ZIModuleHandle specifying the module to get the value from.

  • path[in] The path of the module parameter to get data from.

  • value[out] Pointer to an floating point double in which the value should be written

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN

  • ZI_ERROR_COMMAND on an incorrect answer of the server

  • ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server

  • ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path

  • ZI_ERROR_TIMEOUT when communication timed out

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetString(ZIConnection conn, ZIModuleHandle handle, const char *path, char *buffer, unsigned int *length, unsigned int bufferSize)

gets the null-terminated string value of the specified module parameter path

This function is used to retrieve module parameter values of type string.

See also

ziAPIModGetInteger, ziApiModGetDouble

Parameters:
  • conn[in] Pointer to the ziConnection with which the value should be retrieved

  • handle[in] The ZIModuleHandle specifying the module to get the value from.

  • path[in] The path of the module parameter to get data from.

  • buffer[out] Pointer to a buffer to store the retrieved null-terminated string

  • length[out] Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.

  • bufferSize[in] The length of the passed buffer

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN

  • ZI_ERROR_COMMAND on an incorrect answer of the server

  • ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server

  • ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path

  • ZI_ERROR_TIMEOUT when communication timed out

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetStringUnicode(ZIConnection conn, ZIModuleHandle handle, const char *path, wchar_t *wbuffer, unsigned int *length, unsigned int bufferSize)

Gets the null-terminated string value of the specified module parameter path.

This function is used to retrieve module parameter values of type string.

See also

ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString

Parameters:
  • conn[in] Pointer to the ziConnection with which the value should be retrieved

  • handle[in] The ZIModuleHandle specifying the module to get the value from.

  • path[in] The path of the module parameter to get data from.

  • wbuffer[out] Pointer to a buffer to store the retrieved null-terminated string

  • length[out] Pointer to an unsigned int which after the call, contains the length of the retrieved data (including the null terminator). If the length of the passed buffer is insufficient, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.

  • bufferSize[in] The length of the passed buffer

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • ZI_ERROR_LENGTH if the path’s length exceeds MAX_PATH_LEN

  • ZI_ERROR_COMMAND on an incorrect answer of the server

  • ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server

  • ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path

  • ZI_ERROR_TIMEOUT when communication timed out

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetVector(ZIConnection conn, ZIModuleHandle handle, const char *path, void *buffer, unsigned int *bufferSize, ZIVectorElementType_enum *elementType, unsigned int *numElements)

Gets the vector stored at the specified module parameter path.

This function is used to retrieve module parameter values of type vector.

See also

ziAPIModGetInteger, ziApiModGetDouble, ziAPIModGetString

Parameters:
  • conn[in] Pointer to the ziConnection with which the value should be retrieved.

  • handle[in] The ZIModuleHandle specifying the module to get the value from.

  • path[in] The path of the module parameter to get data from.

  • buffer[out] Pointer to a buffer to store the retrieved vector buffer.

  • bufferSize[inout] Pointer to an unsigned int indicating the length of the buffer. If the length of the passed buffer is insufficient to store the vector, the value is modified to indicate the required minimum buffer size and ZI_ERROR_LENGTH is returned.

  • elementType[out] Pointer to store the type of vector elements.

  • numElements[out] Pointer to an unsigned int to store the number of elements of the vector. If the length of the passed buffer is insufficient, a zero will be returned.

Returns:

  • ZI_INFO_SUCCESS on success

  • ZI_ERROR_CONNECTION when the connection is invalid (not connected) or when a communication error occurred

  • ZI_ERROR_LENGTH if the vector’s length exceeds the buffer size

  • ZI_ERROR_COMMAND on an incorrect answer of the server

  • ZI_ERROR_SERVER_INTERNAL if an internal error occurred in Data Server

  • ZI_WARNING_NOTFOUND if the given path could not be resolved or no value is attached to the path

  • ZI_ERROR_TIMEOUT when communication timed out

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModListNodes(ZIConnection conn, ZIModuleHandle handle, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)

Returns all child parameter node paths found under the specified parent module parameter path.

This function returns a list of parameter names found at the specified path. The path may contain wildcards. The list is returned in a null-terminated char-buffer, each element delimited by a newline. If the maximum length of the buffer (bufferSize) is not sufficient for all elements, nothing will be returned and the return value will be ZI_ERROR_LENGTH.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle from which the parameter names should be retrieved.

  • path[in] Path for which all children will be returned. The path may contain wildcard characters.

  • nodes[out] Upon call filled with newline-delimited list of the names of all the children found. The string is zero-terminated.

  • bufferSize[in] The length of the buffer specified as the nodes output parameter.

  • flags[in] A combination of flags (applied bitwise) as defined in ZIListNodes_enum.

Returns:

  • ZI_INFO_SUCCESS On success

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_LENGTH If the path’s length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by bufferSize is too small for all elements.

  • ZI_ERROR_COMMAND On an incorrect answer of the server.

  • ZI_ERROR_SERVER_INTERNAL If an internal error occurred in Data Server.

  • ZI_WARNING_NOTFOUND If the given path could not be resolved.

  • ZI_ERROR_TIMEOUT When communication timed out.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModListNodesJSON(ZIConnection conn, ZIModuleHandle handle, const char *path, char *nodes, uint32_t bufferSize, uint32_t flags)

Returns all child parameter node paths found under the specified parent module parameter path.

This function returns a list of node names found at the specified path, formatted as JSON. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents. The list is returned in a null-terminated char-buffer. If the maximum length of the buffer (bufferSize) is not sufficient for all elements, nothing will be returned and the return value will be ZI_ERROR_LENGTH.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle from which the parameter names should be retrieved.

  • path[in] Path for which all children will be returned. The path may contain wildcard characters.

  • nodes[out] Upon call filled with JSON-formatted list of the names of all the children found. The string is zero-terminated.

  • bufferSize[in] The length of the buffer used for the nodes output parameter.

  • flags[in] A combination of flags (applied bitwise) as defined in ZIListNodes_enum.

Returns:

  • ZI_INFO_SUCCESS On success

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_LENGTH If the path’s length exceeds MAX_PATH_LEN or the length of the char-buffer for the nodes given by bufferSize is too small for all elements.

  • ZI_ERROR_COMMAND On an incorrect answer of the server.

  • ZI_ERROR_SERVER_INTERNAL If an internal error occurred in Data Server.

  • ZI_WARNING_NOTFOUND If the given path could not be resolved.

  • ZI_ERROR_TIMEOUT When communication timed out.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSubscribe(ZIConnection conn, ZIModuleHandle handle, const char *path)

Subscribes to the nodes specified by path, these nodes will be recorded during module execution.

This function subscribes to nodes so that whenever the value of the node changes while the module is executing the new value will be accumulated and then read using ziAPIModRead. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one leaf can be subscribed to with one function call.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module in which the nodes should be subscribed to.

  • path[in] Path specifying the nodes to subscribe to, may contain wildcards.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or a general error occurred, enable ziAPI’s log for detailed information, see ziAPISetDebugLevel.

  • ZI_ERROR_LENGTH If the Path’s Length exceeds MAX_PATH_LEN.

  • ZI_ERROR_COMMAND On an incorrect answer of the server.

  • ZI_ERROR_SERVER_INTERNAL If an internal error occurred in the Data Server.

  • ZI_WARNING_NOTFOUND If the given path could not be resolved or no node given by path is able to hold values.

  • ZI_ERROR_TIMEOUT When communication timed out.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModUnSubscribe(ZIConnection conn, ZIModuleHandle handle, const char *path)

Unsubscribes to the nodes specified by path.

This function is the complement to ziAPIModSubscribe. By using wildcards or by using a path that is not a leaf node but contains sub nodes, more than one node can be unsubscribed with one function call.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifyin the module in which the nodes should be unsubscribed from.

  • path[in] Path specifying the nodes to unsubscribe from, may contain wildcards.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_LENGTH If the Path’s Length exceeds MAX_PATH_LEN.

  • ZI_ERROR_COMMAND On an incorrect answer of the server.

  • ZI_ERROR_SERVER_INTERNAL If an internal error occurred in the Data Server.

  • ZI_WARNING_NOTFOUND If the given path could not be resolved or no node given by path is able to hold values.

  • ZI_ERROR_TIMEOUT When communication timed out.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModExecute(ZIConnection conn, ZIModuleHandle handle)

Starts the module’s thread and its associated measurement task.

Once the module’s parameters has been configured as required via, e.g. ziAPIModSetDoubleData, this function starts the module’s thread. This starts the module’s main measurement task which will run asynchronously. The thread will run until either the module has completed its task or until ziAPIModFinish is called. Subscription or unsubscription is not possible while the module is executing. The status of the module can be obtained with either ziAPIModFinished or ziAPIModProgress.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModTrigger(ZIConnection conn, ZIModuleHandle handle)

Manually issue a trigger forcing data recording (SW Trigger Module only).

This function is used with the Software Trigger Module in order to manually issue a trigger in order to force recording of data. A burst of subscribed data will be recorded as configured via the SW Trigger’s parameters as would a regular trigger event.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModProgress(ZIConnection conn, ZIModuleHandle handle, ZIDoubleData *progress)

Queries the current state of progress of the module’s measurement task.

This function can be used to query the module’s progress in performing its current measurement task, the progress is returned as a double in [0, 1], where 1 indicates task completion.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • progress[out] A pointer to ZIDoubleData indicating the current progress of the module.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModFinished(ZIConnection conn, ZIModuleHandle handle, ZIIntegerData *finished)

Queries whether the module has finished its measurement task.

This function can be used to query whether the module has finished its task or not.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • finished[out] A pointer to ZIIntegerData, upon return this will be 0 if the module is still executing or 1 if it has finished executing.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModFinish(ZIConnection conn, ZIModuleHandle handle)

Stops the module performing its measurement task.

This functions stops the module performing its associated measurement task and stops recording any data. The task and data recording may be restarted by calling ziAPIModExecute’ again.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModSave(ZIConnection conn, ZIModuleHandle handle, const char *fileName)

Saves the currently accumulated data to file.

This function saves the currently accumulated data to a file. The path of the file to save data to is specified via the module’s directory parameter.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • fileName[in] The basename of the file to save the data in.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModRead(ZIConnection conn, ZIModuleHandle handle, const char *path)

Make the currently accumulated data available for use in the C program.

This function can be used to either read (get) module parameters, in this case a path that addresses the module must be specified, or it can be used to read out the currently accumulated data from subscribed nodes in the module. In either case the actual data must then be accessed by the user using ziAPIModNextNode and ziAPIModGetChunk.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • path[in] The path specifying the module parameter(s) to get, specify NULL to obtain all subscribed data.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModNextNode(ZIConnection conn, ZIModuleHandle handle, char *path, uint32_t bufferSize, ZIValueType_enum *valueType, uint64_t *chunks)

Make the data for the next node available for reading with ziAPIModGetChunk.

After callin ziAPIModRead, subscribed data (or module parameters) may now be read out on a node-by-node and chunk-by-chunk basis. All nodes with data available in the module can be iterated over by using ziAPIModNextNode, then for each node the chunks of data available are read out using ziAPIModGetChunk. Calling this function makes the data from the next node available for read.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • path[out] A string specifying the node’s path whose data chunk points to.

  • bufferSize[in] The length of the buffer specified as the path output parameter.

  • valueType[out] The ZIValueType_enum of the node’s data.

  • chunks[out] The number of chunks of data available for the node.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModGetChunk(ZIConnection conn, ZIModuleHandle handle, uint64_t chunkIndex, ZIModuleEventPtr *ev)

Get the specified data chunk from the current node.

Data is read out node-by-node and then chunk-by-chunk. This function can be used to obtain specific data chunks from the current node that data is being read from. More precisely, it ppreallocates space for an event structure big enough to hold the node’s data at the specified chunk index, updates ZIModuleEventPtr to point to this space and then copies the chunk data to this space.

Note, before the very first call to ziAPIModGetChunk, the ZIModuleEventPtr should be initialized to NULL and then left untouched for all subsequent calls (even after calling ziAPIModNextNode to get data from the next node). This is because ziAPIModGetChunk internally manages the required space allocation for the event and then in subsequent calls only reallocates space when it is required. It is optimized to reduce the number of required space reallocations for the event.

The ZIModuleEventPtr should be deallocated using ziAPIModEventDeallocate, otherwise the lifetime of the ZIModuleEventPtr is the same as the lifetime of the module. Indeed, the same ZIModuleEventPtr can be used, even for subsequent reads. It is also possible to work with multiple ZIModuleEventPtr so that some pointers can be kept for later processing.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

  • chunkIndex[out] The index of the data chunk to update the pointer to.

  • ev[out] The module’s ZIModuleEventPtr that points to the currently available data chunk.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModEventDeallocate(ZIConnection conn, ZIModuleHandle handle, ZIModuleEventPtr ev)

Deallocate the ZIModuleEventPtr being used by the module.

This function deallocates the ZIModuleEventPtr. Since a module event’s allocated space is managed internally by ziAPIModGetChunk, when the user no longer requires the event (all data has been read out) it must be deallocated by the user with this function.

Parameters:
Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

ZIResult_enum ziAPIModClear(ZIConnection conn, ZIModuleHandle handle)

Terminates the module’s thread and destroys the module.

This function terminates the module’s thread, releases memory and resources. After calling ziAPIModClear the module’s handle may not be used any more. A new instance of the module must be initialized if required. This command is especially important if modules are created repetitively inside a while or for loop, in order to prevent excessive memory and resource consumption.

Parameters:
  • conn[in] The ZIConnection from which the module was created.

  • handle[in] The ZIModuleHandle specifying the module to execute.

Returns:

  • ZI_INFO_SUCCESS On success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred.

  • ZI_ERROR_GENERAL If a general error occurred, use ziAPIGetLastError for a detailed error message.

  • Other return codes may also be returned, for a detailed error message use ziAPIGetLastError.

struct ZIChunkHeader
#include <ziAPI.h>

Structure to hold generic chunk data header information.

Public Members

ZITimeStamp systemTime#

System timestamp.

ZITimeStamp createdTimeStamp#

Creation timestamp.

ZITimeStamp changedTimeStamp#

Last changed timestamp.

uint32_t flags#

Flags (bitmask of values from ZIChunkHeaderFlags_enum)

uint32_t moduleFlags#

moduleFlags (bitmask of values from ZIChunkHeaderModuleFlags_enum, module-specific)

uint32_t status#

Status Flag: [0] : selected [1] : group assigned [2] : color edited [4] : name edited.

uint32_t reserved0#
uint64_t chunkSizeBytes#

Size in bytes used for memory usage calculation.

uint64_t triggerNumber#

SW Trigger counter since execution start.

char name[32]#

Name in history list.

uint32_t groupIndex#

Group index in history list.

uint32_t color#

Color in history list.

uint32_t activeRow#

Active row in history list.

uint32_t gridRows#

Number of grid rows.

uint32_t gridCols#

Number of grid columns.

uint32_t gridMode#

Grid mode interpolation mode (0 = off, 1 = nearest, 2 = linear, 3 = Lanczos)

uint32_t gridOperation#

Grid mode operation (0 = replace, 1 = average)

uint32_t gridDirection#

Grid mode direction (0 = forward, 1 = revers, 2 = bidirectional)

uint32_t gridRepetitions#

Number of repetitions in grid mode.

double gridColDelta#

Delta between grid points in SI unit.

double gridColOffset#

Offset of first grid point relative to trigger.

double gridRowDelta#

Delta between grid rows in SI unit.

double gridRowOffset#

Delay of first grid row relative to trigger.

double bandwidth#

For FFT the bandwidth of the signal.

double center#

The FFT center frequency.

double nenbw#

For FFT the normalized effective noise bandwidth.

struct ZIModuleEvent
#include <ziAPI.h>

This struct holds data of a single chunk from module lookup.

Public Members

uint64_t allocatedSize#

For internal use - never modify!

ZIChunkHeader *header#

Chunk header.

ZIEvent value[0]#

Defines location of stored ZIEvent.