History Requests

The Totalflow EIE provides various ways to request history, depending on the Totalflow device model, the specified protocol, and the device's firmware version. DB1 and DB2 protocol devices issue history requests by contract day relative to the current day. The Totalflow G4 DB2 Enhanced option enables three ways to request history: by date/time range; by sequence number; and by contract day relative to the current day. The three data groups that define history requests are "History - Daily", "History - Event", and "History - Log Period".

For more information, see the following subsections below:

• DB1 and DB2 History Requests
• DB1/DB2 and Get Latest
• Polling History on a DB1 or DB2 Remote Device
• DB2 Enhanced History Requests
• DB2 Enhanced and Get Latest From
• Polling History on a DB2 Enhanced Remote Device

DB1 and DB2 History Requests

Totalflow devices using the DB1 or DB2 protocol retrieve history by contract day relative to the current day. You have two basic options for retrieving history:

• Retrieve Data for Last n Contract Days: Retrieves history from a specified number of past contract days up to the current contract day. A value of "1" returns data for the current contract day. Partial contract days are collected.
• Get Latest: Retrieves history from the most recently cached history timestamp, which displays in the Get Latest field. For this to work, you must poll the field device for the first time using the Retrieve Data for Last n Contract Days option; this establishes a cached timestamp. For information, see DB1/DB2 and Get Latest.

DB1/DB2 and Get Latest

The Get Latest feature retrieves history from the most recently cached history timestamp. After you use the Retrieve Data for Last n Contract Days option to poll history for the first time, a timestamp is cached in the remote device. The cached timestamp marks when the most recent poll occurred and when to begin the next Get Latest poll. After the initial poll, every time you poll using the Get Latest option a new most recent history timestamp is cached in the remote device. The only way you can establish a cached history timestamp after the initial history poll is by enabling the Get Latest option.

After the initial poll, when you use the Retrieve Data for Last n Contract Days option in conjunction with the Get Latest option, whichever date is most recent overrides the other date. For instance, if you enter a value of 6 for Retrieve Data for Last n Contract Days but your most recent timestamp only goes back 3 days, the poll returns only the most recent 3 days of history.

Polling History on a DB1 or DB2 Remote Device

You have two basic options for retrieving DB1 and DB2 history: poll a single data group once and/or create a UIS command component.

To Poll a Single History Data Group Once

1. In the remote device editor in the DDS, select the remote device for which you want to retrieve history.
2. Click the Data Group page.
3. Double-click a history data group.
4. Click Get from RTU.
5. In the History Collection Retrieval dialog box, specify the date from which you want to collect history. The History Collection Retrieval dialog box looks similar to the two following examples, depending on whether this is an initial poll or not:

6. When you are finished, click OK.

History Collection Retrieval Properties

The following table lists and describes the properties found on the History Collection Retrieval dialog box.

To Poll Using a UIS Command Component

1. In the remote device editor in the DDS, select the remote device for which you want to retrieve history.
2. Click the UIS Commands page.
3. Add a DG_F_DEV command type component for a history data group type to a new or existing command. For instructions, see Configuring a UIS Command.
4. In the Edit Command Component dialog box, double-click the Parameters row corresponding to the command component parameter Day or SDateLast.

5. In the Modify parms dialog box, specify the appropriate New Value(s) and click OK. For Day, the Low Range and High Range fields set the lowest to highest possible number of contract days for which you could collect history. The default is 1 for Low Range and 40 for High Range, which means you could retrieve history from 40 contract days in the past up to the present contract day. If you do not specify parameters, data is retrieved for the current contract day.
6. When you are finished entering command component parameter values, click OK.
7. Continue configuring your UIS command to suit your needs.
8. When you are finished configuring your UIS command(s), set up command scheduling in the Master Scheduling Service (MSS), if required. For more information, see UIS Command Task.

For information about defining UIS commands in a device template file, see UIS Commands and Device Template Files.

DB2 Enhanced History Requests

The Totalflow G4 DB2 Enhanced option enables three ways to request history: by time range; by sequence number; and by contract day relative to the current day. You have three basic options for retrieving history:

• Time Range: Retrieves history for a user-specified time range. Start Time may be a user-defined value or the Get Latest From value. The Get Latest From value retrieves history from the most recently cached history timestamp and displays the latest timestamp in the Get Latest From field. When you use the Start Time option in conjunction with the Get Latest From option, whichever time is most recent overrides the other time. You must always specify an End Date, regardless of how the start time is set. For more information, see DB2 Enhanced and Get Latest From.
• Sequence Number Range n to n: Retrieves history based on a Totalflow sequence number range. This feature is useful for troubleshooting. To display sequence numbers for a given history poll, click to check the Show All option on the respective history data group's data dialog box. For more information about Totalflow sequence numbers, see Totalflow documentation or contact a Totalflow representative.
• Last n Contract Days: Retrieves history from a specified number of past contract days up to the current contract day. A value of "1" returns data for the current contract day. Partial contract days are collected. A value of "0" does not make sense to the EIE.

DB2 Enhanced and Get Latest From

The Get Latest From feature is part of the Time Range option. The Get Latest From feature retrieves history from the most recently cached history timestamp. After you use one of the three options above to poll history for the first time, a timestamp is cached in the remote device. The cached timestamp marks when the most recent poll occurred and when to begin the next Get Latest From poll. After the initial poll, every time you poll using the Get Latest From option a new most recent history timestamp is cached in the remote device.

The only way you can establish a cached history timestamp after the initial history poll is by enabling the Get Latest From option. For instance, if you disable Get Latest From and enter a Start Time value and retrieve data, the data corresponds to the Start Time entered but the timestamp as indicated in the field beside Get Latest From does not change.

Polling History on a DB2 Enhanced Remote Device

As with the DB1 and DB2 protocols, you have two basic options for retrieving DB2 Enhanced history: poll a single data group once and/or create a UIS command component. However, the DB2 Enhanced option provides several methods of defining parameters within these two basic options.

To Poll a Single History Data Group Once

1. In the remote device editor in the DDS, select the remote device for which you want to retrieve history.
2. Click the Data Group page.
3. Double-click a history data group.
4. Click Get from RTU.
5. In the History Collection Retrieval dialog box, select the history retrieval option you require.

6. When you are finished, click OK.

History Retrieval Collection Properties

The following table lists and describes the properties found on the History Collection Retrieval dialog box.

To Poll Using a UIS Command Component

1. In the remote device editor in the DDS, select the remote device for which you want to retrieve history.
2. Click the UIS Commands page.
3. Add a DG_F_DEV command type component for a history data group type to a new or existing command. For instructions, see Configuring a UIS Command.
4. In the Edit Command Component dialog box, double-click the appropriate Parameters row corresponding to the history retrieval method you want to use. Available UIS parameters for DB2 Enhanced are as follows:

• Day: Corresponds to Last n Contract Days on the History Collection Retrieval dialog box.
• SDate: Corresponds to Start Time on the History Collection Retrieval dialog box.
• EDate: Corresponds to End Time on the History Collection Retrieval dialog box.
• SITEM: Corresponds to Sequence Number Range n to n on the History Collection Retrieval dialog box.
• EITEM: Corresponds to Sequence Number Range n to n on the History Collection Retrieval dialog box.
• SDateLast: Corresponds to Get Latest From on the History Collection Retrieval dialog box.

5. In the Modify parms dialog box, specify the appropriate New Value and click OK. If you are defining a history retrieval method that requires two parameters, repeat steps 4 - 5 for the other parameter. If you do not specify parameters, data is retrieved for the current contract day.
6. Continue configuring your UIS command to suit your needs.
7. When you are finished configuring your UIS command(s), set up command scheduling in the Master Scheduling Service (MSS), if required. For more information, see UIS Command Task.

For information about defining UIS commands in a device template file, see UIS Commands and Device Template Files.