Technical Reference > CtAPI Functions > Function Reference > ctListData

ctListData

Gets the value of a tag on the list. Call this function after ctListRead() has completed for the added tag. You may call ctListData() while subsequent ctListRead() functions are pending, and the last data read will be returned. If you wish to get the value of a specific quality part of a tag element item data use ctListItem which includes the same parameters with the addition of the dwItem parameter.

Syntax

ctListData(hTag, pBuffer, dwLength, dwMode)

hTag

Type: HANDLE
Input/output: Input
Description: The handle to the tag, as returned from ctListAdd().

pBuffer

Type: VOID*
Input/output: Input
Description: Pointer to a buffer to return the data. The data is returned scaled and as a formatted string.

dwLength

Type: Dword
Input/output: Input
Description: Length (in bytes) of the raw data buffer.

dwMode

Type: DWORD
Input/output: Input
Description: Mode of the data. The following modes are supported:

0 (zero) - The value is scaled using the scale specified in the CitectSCADA project, and formatted using the format specified in the CitectSCADA project.

FMT_NO_FORMAT - The value is not formatted to the format specified in the CitectSCADA project. A default format is used. If there is a scale specified in the CitectSCADA project, it will be used to scale the value.

The dwMode argument no longer supports option FMT_NO_SCALE which allowed you to dynamically get the raw value or the engineering value of a tag in the list. If you wish to get the raw value of a tag, add it to the list with this mode by calling ctListAddEx and specifying bRaw = TRUE..

Return Value

If the function succeeds, the return value is TRUE. If the function does not succeed, the return value is FALSE. To get extended error information, call GetLastError().

If an error occurred when reading the data from the I/O Device, the return value will be FALSE and GetLastError() will return the associated CitectSCADA error code.

Related Functions

ctListItem, ctOpen, ctListNew, ctListFree, ctListAdd, ctListRead, ctListWrite,

 

Example

See ctListNew