NI DAQMX Task Configuration And Control
- DAQmxAddGlobalChansToTask
- DAQmxClearTask
- DAQmxConfigureLogging
- DAQmxCreateTask
- DAQmxIsTaskDone
- DAQmxStartTask
- DAQmxStartNewFile
- DAQmxStopTask
- DAQmxWaitUntilTaskDone
- Events
- Advanced
int32 DAQmxAddGlobalChansToTask (TaskHandle taskHandle, const char channelNames[]);
Adds global virtual channels from MAX to the given task.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task to which to add the channels from MAX. |
| channelNames | const char [] | The channels to add to the task. You can specify a list or range of channels. These channels must be valid channels available from MAX. If you pass an invalid channel, NI-DAQmx returns an error. This value is ignored if it is empty. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxClearTask (TaskHandle taskHandle);
Clears the task. Before clearing, this function aborts the task, if necessary, and releases any resources reserved by the task. You cannot use a task once you clear the task without recreating or reloading the task.
If you use the DAQmxCreateTask function or any of the NI-DAQmx Create Channel functions within a loop, use this function within the loop after you finish with the task to avoid allocating unnecessary memory.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task to clear. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxConfigureLogging (TaskHandle taskHandle, const char filePath[], int32 loggingMode, const char groupName[], int32 operation);
Configures TDMS file logging for the task.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| filePath | const char [] | The path to the TDMS file to which you want to log data. |
| loggingMode | int32 | Specifies whether to enable logging and whether to allow reading data while logging. Log mode allows for the best performance. However, you cannot read data while logging if you specify this mode. If you want to read data while logging, specify Log and Read mode. |
| Value | Description | |
|---|---|---|
| DAQmx_Val_Off | Disable logging for the task. | |
| DAQmx_Val_Log | Enable logging for the task. You cannot read data using DAQmx Read when using this mode. If you require access to the data, read from the TDMS file. | |
| DAQmx_Val_LogAndRead | Enable both logging and reading data for the task. You must use DAQmx Read to read samples for NI-DAQmx to stream them to disk. |
| groupName | const char [] |
The name of the group to create within the TDMS file for data from this task. If you append data to an existing file and the specified group already exists, NI-DAQmx appends a number symbol and a number to the group name, incrementing that number until finding a group name that does not exist. For example, if you specify a group name of Voltage Task, and that group already exists, NI-DAQmx assigns the group name Voltage Task #1, then Voltage Task #2. If you do not specify a group name, NI-DAQmx uses the name of the task. For digital input tasks, NI-DAQmx creates a group for each virtual channel in the task. For each created group, NI-DAQmx appends a hyphen and the virtual channel name to the group name. |
| operation | int32 | Specifies how to open the TDMS file. |
| Value | Description | |
|---|---|---|
| DAQmx_Val_Open | Open an existing TDMS file, and append data to that file. If the file does not exist, NI-DAQmx returns an error. | |
| DAQmx_Val_OpenOrCreate | Open an existing TDMS file, and append data to that file. If the file does not exist, NI-DAQmx creates a new TDMS file. | |
| DAQmx_Val_CreateOrReplace | Create a new TDMS file, or replace an existing TDMS file. | |
| DAQmx_Val_Create | Create a new TDMS file. If the file already exists, NI-DAQmx returns an error. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxCreateTask (const char taskName[], TaskHandle *taskHandle);
Creates a task . If you use this function to create a task, you must use DAQmxClearTask to destroy it.
If you use this function within a loop, NI-DAQmx creates a new task in each iteration of the loop. Use the DAQmxClearTask function within the loop after you finish with the task to avoid allocating unnecessary memory.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskName | const char [] | Name assigned to the task. |
 |
Note This name may be changed internally. If you are using the C API, call DAQmxGetTaskName to verify whether the name was changed during creation. If you are using the CVI API, call DAQmxGetTaskAttribute with attribute ID DAQmx_Task_Name to verify the name change. |
|---|
| Output | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle * | A reference to the task created in this function. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxIsTaskDone (TaskHandle taskHandle, bool32 *isTaskDone);
Queries the status of the task and indicates if it completed execution. Use this function to ensure that the specified operation is complete before you stop the task.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| Output | ||
| Name | Type | Description |
| isTaskDone | bool32 * | Indicates whether the measurement or generation completed. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxStartTask (TaskHandle taskHandle);
Transitions the task from the committed state to the running state, which begins measurement or generation. Using this function is required for some applications and optional for others.
If you do not use this function, a measurement task starts automatically when a read operation begins. The autoStart parameter of the NI-DAQmx Write functions determines if a generation task starts automatically when you use an NI-DAQmx Write function.
If you do not call DAQmxStartTask and DAQmxStopTask when you call NI-DAQmx Read functions or NI-DAQmx Write functions multiple times, such as in a loop, the task starts and stops repeatedly. Starting and stopping a task repeatedly reduces the performance of the application.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task to start. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
DAQmxStartNewFile(TaskHandle taskHandle, const char filePath[]);
Starts a new TDMS file the next time data is written to disk.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| filePath | const char [] | The path to the TDMS file to which you want to log data. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxStopTask (TaskHandle taskHandle);
Stops the task and returns it to the state it was in before you called DAQmxStartTask or called an NI-DAQmx Write function with autoStart set to TRUE.
If you do not call DAQmxStartTask and DAQmxStopTask when you call NI-DAQmx Read functions or NI-DAQmx Write functions multiple times, such as in a loop, the task starts and stops repeatedly. Starting and stopping a task repeatedly reduces the performance of the application.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task to stop. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxWaitUntilTaskDone (TaskHandle taskHandle, float64 timeToWait);
Waits for the measurement or generation to complete. Use this function to ensure that the specified operation is complete before you stop the task.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| timeToWait | float64 | The maximum amount of time, in seconds, to wait for the measurement or generation to complete. The function returns an error if the time elapses before the measurement or generation is complete. A value of -1 (DAQmx_Val_WaitInfinitely) means to wait indefinitely. If you set timeToWait to 0, the function checks once and returns an error if the measurement or generation is not done. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
Note: see Using Callback Functions for an example of how to use this through gRPC.
int32 DAQmxRegisterDoneEvent (TaskHandle taskHandle, uInt32 options, DAQmxDoneEventCallbackPtr callbackFunction, void *callbackData);
Registers a callback function to receive an event when a task stops due to an error or when a finite acquisition task or finite generation task completes execution. A Done event does not occur when a task is stopped explicitly, such as by calling DAQmxStopTask.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| options | uInt32 | Use this parameter to set certain options. You can combine flags with the bitwise-OR operator (' |
| Value | Description | |
|---|---|---|
| 0 | The callback function is called in a DAQmx thread. This is the default value. | |
| DAQmx_Val_SynchronousEventCallbacks |
The callback function is called in the thread which registered the event. In order for the callback to occur, you must be processing messages. Windows This option is supported only on Windows. |
|
Note If you are receiving synchronous events faster than you are processing them, then the user interface of your application might become unresponsive. |
|---|
| callbackFunction | DAQmxDoneEventCallbackPtr | The function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype: int32 CVICALLBACK Callback (TaskHandle taskHandle, int32 status, void *callbackData); Upon entry to the callback, the taskHandle parameter contains the handle to the task on which the event occurred. The status parameter contains the status of the task when the event occurred. If the status value is negative, it indicates an error. If the status value is zero, it indicates no error. If the status value is positive, it indicates a warning. The callbackData parameter contains the value you passed in the callbackData parameter of this function. Passing NULL for this parameter unregisters the event callback function. |
| callbackData | void * | A value that you want DAQmx to pass to the callback function as the function data parameter. Callback functions may be called even after a task is cleared. Do not pass the address of a local variable, a variable associated with a cleared task, or any other variable that might not be valid when the function is executed. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
Note: see Using Callback Functions for an example of how to use this through gRPC.
int32 DAQmxRegisterEveryNSamplesEvent (TaskHandle taskHandle, int32 everyNsamplesEventType, uInt32 nSamples, uInt32 options, DAQmxEveryNSamplesEventCallbackPtr callbackFunction, void *callbackData);
Registers a callback function to receive an event when the specified number of samples is written from the device to the buffer or from the buffer to the device. This function only works with devices that support buffered tasks. When you stop a task explicitly any pending events are discarded. For example, if you call DAQmxStopTask then you do not receive any pending events.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| everyNsamplesEventType | int32 | The type of event you want to receive. |
| Value | Description | |
|---|---|---|
| DAQmx_Val_Acquired_Into_Buffer | This event type is only supported for input tasks. Events occur when the specified number of samples are acquired into the buffer from the device. | |
| DAQmx_Val_Transferred_From_Buffer | This event type is only supported for output tasks. Events occur when the specified number of samples are transferred from the buffer to the device. |
| nSamples | uInt32 | The number of samples after which each event should occur. |
| options | uInt32 | Use this parameter to set certain options. You can combine flags with the bitwise-OR operator (' |
| Value | Description | |
|---|---|---|
| 0 | The callback function is called in a DAQmx thread. This is the default value. | |
| DAQmx_Val_SynchronousEventCallbacks |
The callback function is called in the thread which registered the event. In order for the callback to occur, you must be processing messages. Windows This option is supported only on Windows. |
|
Note If you are receiving synchronous events faster than you are processing them, then the user interface of your application might become unresponsive. |
|---|
| callbackFunction | DAQmxEveryNSamplesEventCallbackPtr | The function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype: int32 CVICALLBACK Callback (TaskHandle taskHandle, int32 everyNsamplesEventType, uInt32 nSamples, void *callbackData); Upon entry to the callback, the taskHandle parameter contains the handle to the task on which the event occurred. The everyNSamplesEventType parameter contains the value you passed in the everyNSamplesEventType parameter of this function. The nSamples parameter contains the value you passed in the nSamples parameter of this function. The callbackData parameter contains the value you passed in the callbackData parameter of this function. Passing NULL for this parameter unregisters the event callback function. |
| callbackData | void * | A value that you want DAQmx to pass to the callback function as the function data parameter. Callback functions may be called even after a task is cleared. Do not pass the address of a local variable, a variable associated with a cleared task, or any other variable that might not be valid when the function is executed. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
Note: see Using Callback Functions for an example of how to use this through gRPC.
int32 DAQmxRegisterSignalEvent (TaskHandle taskHandle, int32 signalID, uInt32 options, DAQmxSignalEventCallbackPtr callbackFunction, void *callbackData);
Registers a callback function to receive an event when the specified hardware event occurs. When you stop a task explicitly any pending events are discarded. For example, if you call DAQmxStopTask then you do not receive any pending events.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| signalID | int32 | The signal for which you want to receive results. |
| Value | Description | |
|---|---|---|
| DAQmx_Val_SampleClock | Sample clock | |
| DAQmx_Val_SampleCompleteEvent | Sample complete event | |
| DAQmx_Val_ChangeDetectionEvent | Change detection event | |
| DAQmx_Val_CounterOutputEvent | Counter output event |
| options | uInt32 | Use this parameter to set certain options. You can combine flags with the bitwise-OR operator (' |
| Value | Description | |
|---|---|---|
| 0 | The callback function is called in a DAQmx thread. This is the default value. | |
| DAQmx_Val_SynchronousEventCallbacks |
The callback function is called in the thread which registered the event. In order for the callback to occur, you must be processing messages. Windows This option is supported only on Windows. |
|
Note If you are receiving synchronous events faster than you are processing them, then the user interface of your application might become unresponsive. |
|---|
| callbackFunction | DAQmxSignalEventCallbackPtr | The function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype: int32 CVICALLBACK Callback (TaskHandle taskHandle, int32 signalID, void *callbackData); Upon entry to the callback, the taskHandle parameter contains the handle to the task on which the event occurred. The signalID parameter contains the value you passed in the signalID parameter of this function. The callbackData parameter contains the value you passed in the callbackData parameter of this function. Passing NULL for this parameter unregisters the event callback function. |
| callbackData | void * | A value that you want DAQmx to pass to the callback function as the function data parameter. Callback functions may be called even after a task is cleared. Do not pass the address of a local variable, a variable associated with a cleared task, or any other variable that might not be valid when the function is executed. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |
int32 DAQmxGetNthTaskChannel (TaskHandle taskHandle, uInt32 index, char buffer[], int32 bufferSize);
Returns the Nth channel. This function takes the taskHandle, index, and bufferSize you specify and returns the Nth channel.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| index | uInt32 | The Nth channel to return. The index starts at 1. |
| bufferSize | int32 | The size, in bytes, of buffer. If you pass 0, this function returns the number of bytes needed to allocate. |
| Output | ||
| buffer | char [] | The Nth channel in the index. If you pass NULL, this function returns the number of bytes needed to allocate. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A negative value indicates an error. For this function, if you pass NULL for the buffer or 0 for the buffer size, this function returns the number of bytes needed to allocate. |
int32 DAQmxGetNthTaskDevice (TaskHandle taskHandle, uInt32 index, char buffer[], int32 bufferSize);
Returns the Nth device. This function takes the taskHandle, index, and bufferSize you specify and returns the Nth device.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| index | uInt32 | The Nth device you want to return. The index starts at 1. |
| bufferSize | int32 | The size, in bytes, of buffer. If you pass 0, this function returns the number of bytes needed to allocate. |
| Output | ||
| buffer | char [] | The Nth device in the index. If you pass NULL, this function returns the number of bytes needed to allocate. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A negative value indicates an error. For this function, if you pass NULL for the buffer or 0 for the buffer size, this function returns the number of bytes needed to allocate. |
int32 DAQmxTaskControl (TaskHandle taskHandle, int32 action);
Alters the state of a task according to the action you specify. To minimize the time required to start a task, for example, DAQmxTaskControl can commit the task prior to starting.
| Input | ||
|---|---|---|
| Name | Type | Description |
| taskHandle | TaskHandle | The task used in this function. |
| action | int32 | Specifies how to alter the task state. |
| Value | Description | |
|---|---|---|
| DAQmx_Val_Task_Start | Starts execution of the task. | |
| DAQmx_Val_Task_Stop | Stops execution of the task. | |
| DAQmx_Val_Task_Verify | Verifies that all task parameters are valid for the hardware. | |
| DAQmx_Val_Task_Commit | Programs the hardware as much as possible according to the task configuration. | |
| DAQmx_Val_Task_Reserve | Reserves the hardware resources needed for the task. No other tasks can reserve these same resources. | |
| DAQmx_Val_Task_Unreserve | Releases all previously reserved resources. | |
| DAQmx_Val_Task_Abort | Abort is used to stop an operation, such as Read or Write, that is currently active. Abort puts the task into an unstable but recoverable state. To recover the task, call Start to restart the task or call Stop to reset the task without starting it. |
| Name | Type | Description |
|---|---|---|
| status | int32 | The error code returned by the function in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. |