hs_playback_sample

Description

Plays back a sample when the playback target is client. The target is defined in the hs_create_playback_session command.

Syntax

hs_playback_sample [step [, retry_count]]

Parameters

step

specifies the sample to send to the client, relative to the sample sent in the most recent hs_playback_sample command for the current playback session. Valid values are 0 or positive numbers.

The default is +1, which sends the next later sample. At the beginning, a step of +1 returns the first sample. Zero resends the most recently sent sample. A step of +2 sends the next later sample after the one that a step of +1 would have sent, and so on. An attempt to display a sample later than the last sample returns an error message.

The hs_initiate_playback command initializes playback so that the default (+1) sends the first sample in the playback session.

The definition of what constitutes a sample is affected by the summarization_interval and missing_data_option parameters to the hs_create_playback_session command. See the “Comments” section for more information.

If the playback session was created with a summarization_interval parameter of actual, entire, or a user-specified interval, and if any view in the playback session contains a data item with a statistic type of “Value for Session” or “Rate for Session”, then the only permissible value for step is +1, the default.

retry_count

specifies the number of times that the Historical Server will retry, at one-second intervals, to read data from a historical data file of a recording session that is still recording at the time of playback.

The default is zero, that is, no retries are attempted and an error is returned when playback reaches an end-of-file condition while reading a historical data file.

Examples

Example 1

  1. This example plays back the next sample:

    hs_playback_sample
    
  2. This example skips over one sample and plays the next sample. If recording is ongoing, Historical Server retrys up to 30 times to retrieve another sample if the end-of-file is reached.

    hs_playback_sample 2, 30
    

Usage

This section discusses the following topics:


Format of returned data

The hs_playback_sample command returns data in the form of tables. It returns one table for each playback view. The tables are arranged in the same order in which you submitted the hs_create_playback_view commands that created the views.

The columns in each table correspond to the data items in the corresponding playback view. The columns are arranged in the order in which the data items were listed when you defined the playback view. See Table B-3 to determine the datatype of each column.

Each row represents a different combination of key data items in the view. If the view contains no key data items, then the table returns a single row reflecting server-level data.

When there is no activity to report, some views return a row with zero values and other views omit the row. The rules controlling whether or not a row with zero values appears in a view are:

If playback is summarizing data, a row is returned for a combination of keys if any sample in any of the input session(s) contains the same combination of keys.

If an integer data item overflows, Historical Server returns the largest valid number in the data item, and returns an information message to the client.


Views with Process ID

When a server process terminates, Adaptive Server can reuse its Process ID for a new process. Therefore, the Process ID data item is not guaranteed to uniquely identify a process. The Kernel Process ID data item, however, uniquely identifies a process.

Views that include Process ID return rows as follows:


Gaps in data within the playback session

The start_time and end_time parameters to the hs_create_playback_session command define the period of time that the playback session covers. When the target parameter to the hs_create_playback_session command is client, there might be intervals of time between the playback session’s start and end times for which no data is available in any of the input session(s).

NoteWhen target is file, no gaps are allowed in the specified input sessions, so there will not be gaps in the playback session.

Gaps in available data might occur when:

When the target of playback is a client, Historical Server handles gaps according to the value of the missing_data_option parameter to the hs_create_playback_session command: