The CitectSCADA CTAPI supports both synchronous and asynchronous (or overlapped) operations. The ctCicode(), ctListRead(), and ctListWrite() functions can be performed either synchronously or asynchronously. The ctTagRead() and ctTagWrite() functions can be performed synchronously only.
When a function is executed synchronously, it does not return until the operation has been completed. This means that the execution of the calling thread can be blocked for an indefinite period while it waits for a time-consuming operation to finish. A function called for an overlapped operation can return immediately, even though the operation has not been completed. This enables a time-consuming I/O operation to be executed in the background while the calling thread is free to perform other tasks. For example, a single thread can perform simultaneous operations on different handles, or even simultaneous read and write operations on the same handle. To synchronize its execution with the completion of the overlapped operation, the calling thread uses the ctGetOverlappedResult() function or one of the wait functions to determine when the overlapped operation has been completed. You can also use the ctHasOverlappedIoCompleted() macro to poll for completion.
To call a function to perform an overlapped operation, the calling thread needs to specify a pointer to a CTOVERLAPPED structure. If this pointer is NULL, the function return value may incorrectly indicate that the operation completed. The CTOVERLAPPED structure needs to contain a handle to a manual-reset, not an auto-reset event object. The system sets the state of the event object to non-signaled when a call to the I/O function returns before the operation has been completed. The system sets the state of the event object to signaled when the operation has been completed.
When a function is called to perform an overlapped operation, it is possible that the operation will be completed before the function returns. When this happens, the results are handled as if the operation had been performed synchronously. If the operation was not completed, however, the function's return value is FALSE, and the GetLastError() function returns ERROR_IO_PENDING.
A thread can manage overlapped operations by either of two methods:
When performing multiple simultaneous overlapped operations, the calling thread needs to specify a CTOVERLAPPED structure with a different manual-reset event object for each operation. To wait for any one of the overlapped operations to be completed, the thread specifies the manual-reset event handles as wait criteria in one of the multiple-object wait functions. The return value of the multiple-object wait function indicates which manual-reset event object was signaled, so the thread can determine which overlapped operation caused the wait operation to be completed.
You can cancel a pending asynchronous operation using the ctCancelIO() function. Pending asynchronous operations are canceled when you call ctClose().
Reading Data Using the CTAPI Functions