Plays back a sample when the playback target is client. The target is defined in the hs_create_playback_session command.
hs_playback_sample [step [, retry_count]]
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.
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.
This example plays back the next sample:
hs_playback_sample
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
This section discusses the following topics:
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:
Views with server level data items always return a row, even when there is no activity to report.
Views that contain the key data items Process ID, Object ID, or Procedure ID omit the row when there is no activity to report. See “Views with Process ID” for more explanation about when a Process ID is returned.
Views that contain keys other than those listed in the previous item return rows even when there is no activity.
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.
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:
Recording session views (and hence, raw playback views) return a row only for Process IDs representing processes that exist at the end of a sample interval. If a server process terminates in the middle of a sample interval, a row is not returned for its Process ID.
Summary playback views do not require the server process to exist for the duration of the playback sample. Summary views return rows for all server processes included in any of the input views. However, since Process ID is not guaranteed to be unique, the Kernel Process ID must be included in any summary view that includes Process ID to ensure uniqueness of the key. Otherwise, the summary could erroneously combine data from two different processes.
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).
When 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:
The input sessions specified for the playback session are not contiguous. For example, if a series of input sessions covered the time period between 9 a.m. and 5 a.m., Monday through Friday, data gaps would exist between 5 p.m. each evening and 9 a.m. the next morning. Larger gaps would exist between Friday evening and Monday morning.
The playback session does summarization and has a start or end time beyond when data is available from the input session(s).
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:
skip (the default) – when a time period contains no data, the hs_playback_sample command goes directly to the next time period containing data, rather than returning a sample having no data.
show – the hs_playback_sample command returns a sample even for a time period where no data is available. No data is returned (the length of each data table returned is zero).
For the client to receive a timestamp in this case, there must be a playback view containing only the data item Timestamp or Timestamp Datim. A view containing any other data item(s) will return zero rows.
The playback session’s summarization level affects the number of empty samples returned during playback:
if summarization_level is raw or actual, the entire gap is represented with one sample. For example, a gap in data between the hours of 5 p.m. and 9 a.m. would be represented by one sample.
if summarization_level is
a time interval, such as 1/2 hour (specified as "0 00:30:00"),
the gap is represented with a sample for each time interval. For
example, if the time interval is specified as 1/2 hour,
a gap in data between the hours of 5 p.m. and 9 a.m. would be represented
by 32 empty samples.
if summarization_level is entire, gaps are ignored.
