Read Trace VI

LabVIEW 2017 Datalogging and Supervisory Control Module Help

Edition Date: March 2017

Part Number: 371618K-01

»View Product Info
Download Help (Windows Only)

Owning Palette: Historical VIs

Requires: DSC Module

Reads the historical data for a given variable using the specified time interval, up to the max points per trace specified.

You must manually select the polymorphic instance to use.

Details  Example

Use the pull-down menu to select an instance of this VI.

Read Trace (Numeric)

timeout specifies the maximum time, in seconds, that this VI waits for reading data from the Citadel database. The default is 30. A timeout value of less than or equal to 0 specifies no timeout, which means this VI waits indefinitely until this VI receives data from the Citadel database.
max points per trace specifies the maximum number of points to read from the database.

This VI returns all available points of this trace between start timestamp and stop timestamp in the following cases:
  • max points per trace is less than zero.
  • The number of the data points between start timestamp and stop timestamp is less than the max points per trace.
If max points per trace is zero, this VI returns no point for the trace. The default is –1.
database URL specifies the computer name and the database name where the Citadel database resides. Enter the database URL in the format \\computer\database.

For example, if you have a copy of the LabVIEW Datalogging and Supervisory Control (DSC) Module and Citadel service installed on a computer named datalogger and the name of the database on that computer is data, you can access the data on datalogger from another computer by using the path \\datalogger\data. If you provide a database name only, this VI searches for the database on the local computer. If you do not wire database URL, this VI resolves the database URL from the Shared Variable Engine (SVE). If the SVE resolution fails, this VI reads data from the database associated with the default DSC Module process.
trace name specifies the trace that this VI uses for the data operation. You can specify either a Shared Variable reference or an existing trace for this parameter. If the trace is not logged in the historical database, this VI returns an empty trace.
time interval is the span of time between the start timestamp and stop timestamp. If you do not wire this input, this VI reads all data logged up to now.
start timestamp specifies the start date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the first data point in the database.
stop timestamp specifies the end date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the last data point in the database.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
options specifies the format settings for the data as this VI reads the trace.
interpolate data? determines whether this VI estimates data values within an interpolation interval. The default is FALSE.

If you set interpolate data? to TRUE, this VI estimates data values based on the data values that the DSC Module logs at the interpolation interval.
extrapolate to now determines whether this VI extrapolates the last data point in the database to the current system time. The default is FALSE.

If you turn off logging for a shared variable, the DSC Module logs the last data point of this shared variable as a break. This VI does not extrapolate for traces that end with breaks unless you set remove data breaks? to TRUE.
remove data breaks determines whether to remove the value of a data break from the trace. The default is FALSE.

The DSC Module marks gaps in the logged data as data breaks. If you set remove data breaks to TRUE, this VI removes the break markers from the trace. Then you cannot identify the gaps in the data.
maintain trending info determines whether to include the last data point before start timestamp and the first data point after stop timestamp with the returned trace. The default is TRUE.

If this input is FALSE, the returned trace includes only points strictly between start timestamp and stop timestamp.
interpolation interval specifies the interval, in seconds, at which this VI interpolates the data. The default is 1.
database URL out returns the computer name and the database name that specify where the Citadel database resides. The format is \\computer\database.
historical trace is the historical trace for the input trace name that this VI reads from the Citadel database. The data in the trace starts at the date and time specified by start timestamp and ends at the date and time specified by stop timestamp. If you do not wire the start timestamp and stop timestamp values, this VI returns all the logged data for the trace, up to max points in trace. If a value is a data break, this output returns a data point whose data is NaN and whose timestamp you can ignore.
timestamps returns the timestamp of each value in the trace name array.
data returns the data values of the data points.
quality is the data quality of the trace(s) read. A value of zero indicates good quality. The following table lists some of the possible quality values.

Bit NumberDescription
1The value from this shared variable might not be the most current value from the data source.
2Sensor failure.
3General device error response.
4Server failure.
5General communications failure.
6Unable to locate variable in the SVE. Deployment of this variable may have failed.
7The shared variable has no known value.
8The shared variable is inactive.
10Low Limited.
11High Limited.
12Constant.
13Sensor inaccurate.
14Engineering unit limits exceeded.
15Generic OPC Error.
16Math error.
17Communications link failure.
18NI Publish-Subscribe Protocol (NI-PSP) has not connected to the server yet.
19DNS lookup failed for the server.
20The server is not reachable.
21Service lookup failed for the server.
22The connection to the server was disconnected.
23The process was not found or is not responding.
24Failed to resolve URL for this shared variable.
25Read access is denied to the shared variable.
26Invalid URL for this shared variable.
30Point has an active alarm.
31Subscription failed.
32Quality bit greater than 32 is set, or there is an error/status reported.
33The shared variable client-side read buffer is full.
34The shared variable client-side read buffer overflowed.
35The shared variable server-side write buffer is full.
36The shared variable server-side write buffer has overflowed.
error out contains error information. This output provides standard error out functionality.

Read Trace (Logical)

timeout specifies the maximum time, in seconds, that this VI waits for reading data from the Citadel database. The default is 30. A timeout value of less than or equal to 0 specifies no timeout, which means this VI waits indefinitely until this VI receives data from the Citadel database.
max points per trace specifies the maximum number of points to read from the database.

This VI returns all available points of this trace between start timestamp and stop timestamp in the following cases:
  • max points per trace is less than zero.
  • The number of the data points between start timestamp and stop timestamp is less than the max points per trace.
If max points per trace is zero, this VI returns no point for the trace. The default is –1.
database URL specifies the computer name and the database name where the Citadel database resides. Enter the database URL in the format \\computer\database.

For example, if you have a copy of the LabVIEW Datalogging and Supervisory Control (DSC) Module and Citadel service installed on a computer named datalogger and the name of the database on that computer is data, you can access the data on datalogger from another computer by using the path \\datalogger\data. If you provide a database name only, this VI searches for the database on the local computer. If you do not wire database URL, this VI resolves the database URL from the Shared Variable Engine (SVE). If the SVE resolution fails, this VI reads data from the database associated with the default DSC Module process.
trace name specifies the trace that this VI uses for the data operation. You can specify either a Shared Variable reference or an existing trace for this parameter. If the trace is not logged in the historical database, this VI returns an empty trace.
time interval is the span of time between the start timestamp and stop timestamp. If you do not wire this input, this VI reads all data logged up to now.
start timestamp specifies the start date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the first data point in the database.
stop timestamp specifies the end date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the last data point in the database.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
options specifies the format settings for the data as this VI reads the trace.
interpolate data? determines whether this VI estimates data values within an interpolation interval. The default is FALSE.

If you set interpolate data? to TRUE, this VI estimates data values based on the data values that the DSC Module logs at the interpolation interval.
extrapolate to now determines whether this VI extrapolates the last data point in the database to the current system time. The default is FALSE.

If you turn off logging for a shared variable, the DSC Module logs the last data point of this shared variable as a break. This VI does not extrapolate for traces that end with breaks unless you set remove data breaks? to TRUE.
remove data breaks determines whether to remove the value of a data break from the trace. The default is FALSE.

The DSC Module marks gaps in the logged data as data breaks. If you set remove data breaks to TRUE, this VI removes the break markers from the trace. Then you cannot identify the gaps in the data.
maintain trending info determines whether to include the last data point before start timestamp and the first data point after stop timestamp with the returned trace. The default is TRUE.

If this input is FALSE, the returned trace includes only points strictly between start timestamp and stop timestamp.
interpolation interval specifies the interval, in seconds, at which this VI interpolates the data. The default is 1.
database URL out returns the computer name and the database name that specify where the Citadel database resides. The format is \\computer\database.
historical trace is the historical trace for the input trace name that is read from the historical database. The data in the trace starts at the date and time specified by start timestamp and ends at the date and time specified by stop timestamp. If you do not wire the start timestamp and stop timestamp values, this VI returns all the logged data for the trace, up to max points in trace. If a value is a data break, this output returns a data point whose data is NaN and whose timestamp you can ignore.
timestamps returns the timestamp of each value in the trace name array.
data returns the data values of the data points.
quality is the data quality of the trace(s) read. A value of zero indicates good quality.
error out contains error information. This output provides standard error out functionality.

Read Trace (Bit Array)

timeout specifies the maximum time, in seconds, that this VI waits for reading data from the Citadel database. The default is 30. A timeout value of less than or equal to 0 specifies no timeout, which means this VI waits indefinitely until this VI receives data from the Citadel database.
max points per trace specifies the maximum number of points to read from the database.

This VI returns all available points of this trace between start timestamp and stop timestamp in the following cases:
  • max points per trace is less than zero.
  • The number of the data points between start timestamp and stop timestamp is less than the max points per trace.
If max points per trace is zero, this VI returns no point for the trace. The default is –1.
database URL specifies the computer name and the database name where the Citadel database resides. Enter the database URL in the format \\computer\database.

For example, if you have a copy of the LabVIEW Datalogging and Supervisory Control (DSC) Module and Citadel service installed on a computer named datalogger and the name of the database on that computer is data, you can access the data on datalogger from another computer by using the path \\datalogger\data. If you provide a database name only, this VI searches for the database on the local computer. If you do not wire database URL, this VI resolves the database URL from the Shared Variable Engine (SVE). If the SVE resolution fails, this VI reads data from the database associated with the default DSC Module process.
trace name specifies the trace that this VI uses for the data operation. You can specify either a Shared Variable reference or an existing trace for this parameter. If the trace is not logged in the historical database, this VI returns an empty trace.
time interval is the span of time between the start timestamp and stop timestamp. If you do not wire this input, this VI reads all data logged up to now.
start timestamp specifies the start date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the first data point in the database.
stop timestamp specifies the end date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the last data point in the database.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
options specifies the format settings for the data as this VI reads the trace.
interpolate data? determines whether this VI estimates data values within an interpolation interval. The default is FALSE.

If you set interpolate data? to TRUE, this VI estimates data values based on the data values that the DSC Module logs at the interpolation interval.
extrapolate to now determines whether this VI extrapolates the last data point in the database to the current system time. The default is FALSE.

If you turn off logging for a shared variable, the DSC Module logs the last data point of this shared variable as a break. This VI does not extrapolate for traces that end with breaks unless you set remove data breaks? to TRUE.
remove data breaks determines whether to remove the value of a data break from the trace. The default is FALSE.

The DSC Module marks gaps in the logged data as data breaks. If you set remove data breaks to TRUE, this VI removes the break markers from the trace. Then you cannot identify the gaps in the data.
maintain trending info determines whether to include the last data point before start timestamp and the first data point after stop timestamp with the returned trace. The default is TRUE.

If this input is FALSE, the returned trace includes only points strictly between start timestamp and stop timestamp.
interpolation interval specifies the interval, in seconds, at which this VI interpolates the data. The default is 1.
database URL out returns the computer name and the database name that specify where the Citadel database resides. The format is \\computer\database.
historical trace is the historical trace for the input trace name that is read from the historical database. The data in the trace starts at the date and time specified by start timestamp and ends at the date and time specified by stop timestamp. If you do not wire the start timestamp and stop timestamp values, this VI returns all the logged data for the trace, up to max points in trace. If a value is a data break, this output returns a data point whose data is NaN and whose timestamp you can ignore.
timestamps returns the timestamp of each value in the trace name array.
data returns the data values of the data points.
quality is the data quality of the trace(s) read. A value of zero indicates good quality.
error out contains error information. This output provides standard error out functionality.

Read Trace (String)

timeout specifies the maximum time, in seconds, that this VI waits for reading data from the Citadel database. The default is 30. A timeout value of less than or equal to 0 specifies no timeout, which means this VI waits indefinitely until this VI receives data from the Citadel database.
max points per trace specifies the maximum number of points to read from the database.

This VI returns all available points of this trace between start timestamp and stop timestamp in the following cases:
  • max points per trace is less than zero.
  • The number of the data points between start timestamp and stop timestamp is less than the max points per trace.
If max points per trace is zero, this VI returns no point for the trace. The default is –1.
database URL specifies the computer name and the database name where the Citadel database resides. Enter the database URL in the format \\computer\database.

For example, if you have a copy of the LabVIEW Datalogging and Supervisory Control (DSC) Module and Citadel service installed on a computer named datalogger and the name of the database on that computer is data, you can access the data on datalogger from another computer by using the path \\datalogger\data. If you provide a database name only, this VI searches for the database on the local computer. If you do not wire database URL, this VI resolves the database URL from the Shared Variable Engine (SVE). If the SVE resolution fails, this VI reads data from the database associated with the default DSC Module process.
trace name specifies the trace that this VI uses for the data operation. You can specify either a Shared Variable reference or an existing trace for this parameter. If the trace is not logged in the historical database, this VI returns an empty trace.
time interval is the span of time between the start timestamp and stop timestamp. If you do not wire this input, this VI reads all data logged up to now.
start timestamp specifies the start date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the first data point in the database.
stop timestamp specifies the end date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the last data point in the database.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
options specifies the format settings for the data as this VI reads the trace.
interpolate data? determines whether this VI estimates data values within an interpolation interval. The default is FALSE.

If you set interpolate data? to TRUE, this VI estimates data values based on the data values that the DSC Module logs at the interpolation interval.
extrapolate to now determines whether this VI extrapolates the last data point in the database to the current system time. The default is FALSE.

If you turn off logging for a shared variable, the DSC Module logs the last data point of this shared variable as a break. This VI does not extrapolate for traces that end with breaks unless you set remove data breaks? to TRUE.
remove data breaks determines whether to remove the value of a data break from the trace. The default is FALSE.

The DSC Module marks gaps in the logged data as data breaks. If you set remove data breaks to TRUE, this VI removes the break markers from the trace. Then you cannot identify the gaps in the data.
maintain trending info determines whether to include the last data point before start timestamp and the first data point after stop timestamp with the returned trace. The default is TRUE.

If this input is FALSE, the returned trace includes only points strictly between start timestamp and stop timestamp.
interpolation interval specifies the interval, in seconds, at which this VI interpolates the data. The default is 1.
database URL out returns the computer name and the database name that specify where the Citadel database resides. The format is \\computer\database.
historical trace is the historical trace for the input trace name that is read from the historical database. The data in the trace starts at the date and time specified by start timestamp and ends at the date and time specified by stop timestamp. If you do not wire the start timestamp and stop timestamp values, this VI returns all the logged data for the trace, up to max points in trace. If a value is a data break, this output returns a data point whose data is NaN and whose timestamp you can ignore.
timestamps returns the timestamp of each value in the trace name array.
data returns the data values of the data points.
quality is the data quality of the trace(s) read. A value of zero indicates good quality.
error out contains error information. This output provides standard error out functionality.

Read Trace (Variant)

timeout specifies the maximum time, in seconds, that this VI waits for reading data from the Citadel database. The default is 30. A timeout value of less than or equal to 0 specifies no timeout, which means this VI waits indefinitely until this VI receives data from the Citadel database.
max points per trace specifies the maximum number of points to read from the database.

This VI returns all available points of this trace between start timestamp and stop timestamp in the following cases:
  • max points per trace is less than zero.
  • The number of the data points between start timestamp and stop timestamp is less than the max points per trace.
If max points per trace is zero, this VI returns no point for the trace. The default is –1.
database URL specifies the computer name and the database name where the Citadel database resides. Enter the database URL in the format \\computer\database.

For example, if you have a copy of the LabVIEW Datalogging and Supervisory Control (DSC) Module and Citadel service installed on a computer named datalogger and the name of the database on that computer is data, you can access the data on datalogger from another computer by using the path \\datalogger\data. If you provide a database name only, this VI searches for the database on the local computer. If you do not wire database URL, this VI resolves the database URL from the Shared Variable Engine (SVE). If the SVE resolution fails, this VI reads data from the database associated with the default DSC Module process.
trace name specifies the trace that this VI uses for the data operation. You can specify either a Shared Variable reference or an existing trace for this parameter. If the trace is not logged in the historical database, this VI returns an empty trace.
time interval is the span of time between the start timestamp and stop timestamp. If you do not wire this input, this VI reads all data logged up to now.
start timestamp specifies the start date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the first data point in the database.
stop timestamp specifies the end date and time of data you want to retrieve from the Citadel database. If you do not wire this input, this VI uses the timestamp of the last data point in the database.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
options specifies the format settings for the data as this VI reads the trace.
interpolate data? determines whether this VI estimates data values within an interpolation interval. The default is FALSE.

If you set interpolate data? to TRUE, this VI estimates data values based on the data values that the DSC Module logs at the interpolation interval.
extrapolate to now determines whether this VI extrapolates the last data point in the database to the current system time. The default is FALSE.

If you turn off logging for a shared variable, the DSC Module logs the last data point of this shared variable as a break. This VI does not extrapolate for traces that end with breaks unless you set remove data breaks? to TRUE.
remove data breaks determines whether to remove the value of a data break from the trace. The default is FALSE.

The DSC Module marks gaps in the logged data as data breaks. If you set remove data breaks to TRUE, this VI removes the break markers from the trace. Then you cannot identify the gaps in the data.
maintain trending info determines whether to include the last data point before start timestamp and the first data point after stop timestamp with the returned trace. The default is TRUE.

If this input is FALSE, the returned trace includes only points strictly between start timestamp and stop timestamp.
interpolation interval specifies the interval, in seconds, at which this VI interpolates the data. The default is 1.
database URL out returns the computer name and the database name that specify where the Citadel database resides. The format is \\computer\database.
historical trace is the historical trace for the input trace name that is read from the historical database. The data in the trace starts at the date and time specified by start timestamp and ends at the date and time specified by stop timestamp. If you do not wire the start timestamp and stop timestamp values, this VI returns all the logged data for the trace, up to max points in trace. If a value is a data break, this output returns a data point whose data is NaN and whose timestamp you can ignore.
timestamps is an array of the timestamps of the data points.
data returns the data values of the data points.
quality is the data quality of the trace(s) read. A value of zero indicates good quality.
error out contains error information. This output provides standard error out functionality.

Read Trace Details

If database URL is unwired, this VI reads the trace name from the database associated with the default DSC Module process.

If you do not wire time interval, this VI returns all historical data for the trace, up to max points in trace specified. If you do not wire max points in trace, this VI returns all points between the start and stop timestamps set in time interval.

Example

Refer to the NIHyperTrend Graph XML Configuration.lvproj in the labview\examples\lvdsc\HMI Design\NIHyperTrend Graph XML Configuration directory for an example of using the Read Trace VI.

WAS THIS ARTICLE HELPFUL?

Not Helpful