Defines the characteristics of a playback session. This command is the first step in creating a playback session.
hs_create_playback_session start_time, end_time, summarization_interval, allow_estimation, missing_data_option, target, directory_name, protection_level, script_type, delete_option, session_id[ , session_id... ]
specifies the date and time of the beginning of the recorded data to be played back. The default is to start playback from the beginning of the first session specified by session_id. Use the value NULL to accept the default.
The format for start_time is:
“year/month/day hour:minute[:second] [time zone]”
Depending on the summarization_interval and missing_data_option parameters, and depending on whether there is any data available at the time specified, playback might use data from a time later than that specified; however, playback does not use data from a time earlier than start_time.
The start_time, if specified, must be earlier than the end time of at least one of the sessions specified in session_id. The following time zone options are available:
Parameter value |
Explanation |
|---|---|
EST |
U.S. Eastern Time zone, standard time. |
EDT |
U.S. Eastern Time zone, daylight saving time. |
CST |
U.S. Central Time zone, standard time. |
CDT |
U.S. Central Time zone, daylight saving time. |
MST |
U.S. Mountain Time zone, standard time. |
MDT |
U.S. Mountain Time zone, daylight saving time. |
PST |
U.S. Pacific Time zone, standard time |
PDT |
U.S. Pacific Time zone, daylight saving time |
MET |
Middle European Time zone, standard time |
MET DST |
Middle European Time zone, daylight saving time |
WET DST |
Western European (Greenwich) Time zone, daylight saving time |
GMT |
Greenwich Mean Time. This is equivalent to Western European (Greenwich) Time zone without regard to daylight saving time. All of the preceding time zone specifications, such as EST or EDT, can be supplied only in combination with dates and times when Standard Time or Daylight Savings Time is in effect. GMT can be paired with any date and time specification. |
GMT{+-}hours_offset |
To specify any other time zone, where hours_offset is the number of hours that must be added to Greenwich Mean Time to derive the local time. The acceptable range of offset values is between +24 and -24 hours, inclusive. Fractional offsets such as +5.5 are valid. |
The default time_zone is the local time zone of Historical Server.
specifies the date and time for the end of the recorded data to be played back. The default is to end playback at the end of the last session specified. Use the value NULL to accept the default.
The format of this parameter is the same as the start_time format. The end_time, if specified, must be later than the start_time of at least one input session.
a required parameter (no default exists) that specifies the level of detail of the playback. Valid values are:
raw – plays back data as it was collected, using the same sample intervals. Choose this option to view raw data as it was recorded. Also, this is the only option available for playing back snapshot data, such as current SQL statement data and status information on locks or processes. See Table C-2 for a definitive list of the snapshot data items. (They are the ones with “no” in the “Allowed for Non-raw” column.)
This option is valid only when target is client.
actual – plays back data using the same sample intervals as the input recording sessions.
This option allows you to specify some data item changes in the playback view. Also, Historical Server makes appropriate adjustments to the first and last samples when the recording session times do not align with the requested playback session times.
Choose this option to add or change certain data items when summarization is not required. Also, when target is set to file, this option provides a way to concatenate the non-snapshot data in multiple recording sessions.
This option is valid only when target is client.
entire – plays back data for each input recording session summarized as a single sample. The sample interval is the timespan between the requested playback start_time and end_time.
This option allows you to specify some data item changes in the playback view. Also, Historical Server makes appropriate adjustments to the data values to accurately reflect the requested playback session start and end times.
Choose this option to consolidate recorded data, rolling up details into overviews of activity over longer time periods.
plays back data summarized into sample intervals of the specified length. The parameter value is the sample interval length, specified as:
"S" "M:S" "H:M:S" "D H:M:S"
where:
S – is seconds
M – is minutes
H – is hours
D – is days
All components are numeric and can be one or two digits. Some examples are:
"30" (specifies sample intervals of 30 seconds)
"10:0" (specifies sample intervals of 10 minutes)
"8:30:0" (specifies sample intervals of 8 1/2 hours)
"5 0:0:0" (specifies sample intervals of 5 days)
The first sample interval starts at start_time, and every sample, except possibly the last one, has the specified length.This option allows you to specify some data item changes in the playback view. Also, Historical Server makes appropriate adjustments to the data values to accurately reflect the requested playback session length and playback sample intervals.
Choose this option to summarize data into any desired granularity. This type of summary can mediate deviations in activity and is useful for observing trends over time.
The actual, entire, and user-defined interval options have the following features in common:
Data item changes in playback views – for all three options, the playback view can use statistic types different from those in the input view, and it can include some estimated and calculated data items not in the input view. It cannot include snapshot data, such as current SQL statement data. See Table C-2 for a definitive list of data items and statistic types that can be included in playback views when these options are chosen.
Data adjustments – for all three options, Historical Server performs appropriate mathematical computations to compensate for differences in:
the input recording session(s) sample interval and the requested playback sample interval
the input recording sessions(s) session lengths and the requested playback start and end times
To handle these differences, accumulated counts are prorated. Percentages and rates are weight-averaged, weighted by the number of seconds that each input sample contributes.
See Appendix C, “Specifications for Defining Playback Views” for more information.
specifies whether or not you want playback to estimate values for data items that cannot be calculated exactly. Valid values are:
disallow (the default) – causes the hs_create_playback_view command to return an error if it encounters data items that require estimation.
allow – causes playback to estimate values, if necessary, for certain data items. Some data items cannot be included in a playback view unless you allow estimation in the playback session.
This parameter is ignored if summarization_interval is raw.
See Table C-2 to determine which data items require estimation.
when target is client, this parameter specifies how the hs_playback_sample command treats periods of time when no data is available in the input session(s). Valid values are:
skip (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. During client playback, the column headers are returned with zero rows.
When target is file, gaps are not allowed.
specifies the target results of the playback session. Valid values are:
client (default) – enables playback to the client.
file – enables creation of a new session containing all the data specified by this hs_create_playback_session command and by subsequent hs_create_playback_view commands. Use the hs_initiate_playback command to create the new session. Setting target to file is not allowed if the summarization_interval parameter is raw or actual.
when target is file, this parameter specifies the directory where the new files are created. This parameter is ignored when target is client. The default is the Historical Server home directory.
The operating system account that started Historical Server must have execute (search) and write permission on the specified directory.
when target is file, this parameter specifies the permission level that the hs_initiate_playback command assigns to the data files for the newly created session. The protection level controls viewing the metadata in the control file (using the hs_list command) and creating playback sessions with the data (using the hs_create_playback_session command). Valid values are:
private (default) – specifies that the new files will be password-protected. The files will be accessible only to the same account that created them or to the Historical Server superuser.
public – gives unrestricted access to the data in the new session’s files.
null – implements the default value, private.
When target is client, this parameter is ignored.
when target is file, this parameter specifies whether you want the hs_initiate_playback command to create a script file for the newly created session. The script file contains SQL commands that create an Adaptive Server table for each playback view defined for the new session. Valid values are:
no_script (default) – does not create a script file for the new session.
sybase_script – creates a script file. The file is located in the Historical Server home directory. Its name is sSessionId, where:
s is a constant
SessionId is assigned by Historical Server
null – implements the default value, no_script.
When target is client, this parameter is ignored.
when target is file, this parameter specifies whether you want the hs_initiate_playback command to delete the input session files after successfully creating the new session. Valid values are:
retain (default) – does not delete the files containing the data for the input sessions.
delete – deletes all input session files, if creation of the new session is successful. The user must be either the Historical Server superuser or the owner of all the input sessions.
null – implements the default value, retain.
When target is client, this parameter is ignored.
specifies the unique identifier(s) for the input session(s) to be played back. At least one session_id is required. When more than one are used, they must be specified in the correct order according to their start times, with the earliest start time first. Playback skips over the sessions that are out of order. If summarization_interval is raw, then only one session_id is valid.
Historical Server assigns a session ID to a recording session when the recording session is defined. Use the hs_list command to find the session IDs that you want to play back.
If target is file, no gaps can exist between an input session’s end time and the next input session’s start time. Also, each session specified must have completed its recording.
If target is client, then each session must have started recording, but can be continuing to record when you submit the hs_create_playback_session command.
This example creates a playback session based on a single input session (session 7). The session is played back in its entirety, with no summarization or normalization, and without creating a new session.
hs_create_playback_session null, null, raw, null, null, client, null, null, null, null, 7
This example creates a playback session based on three input sessions (sessions 4, 6, and 9). Only data collected between the time period from 9:00 to 5:00 is played back. The played back data is summarized at half-hour intervals. The playback is stored as a new session.
hs_create_playback_session "1996/5/3 9:00", "1996/5/3 17:00", "0 00:30:00", disallow, skip, file, null, public, no_script, retain, 4, 6, 9
A connection to Historical Server can either be defining a recording session or defining and executing a playback session, but not both. After the successful execution of the hs_create_playback_session command, you must successfully execute a hs_terminate_playback command before starting to define a recording session or starting to define another playback session.
The behavior of the playback session is different depending on the value of the target parameter:
If target is client, the client retrieves the data using the hs_playback_sample command. Playback can occur from recording sessions that are still in the process of recording.
If target is file, the client does not retrieve any data for this playback session; instead, Historical Server creates a new session and fills the data file(s) for that new session with the data from this playback session. The accessibility of the new session is determined by the protection_level parameter. The user who invokes this command is the owner of the new session. The hs_initiate_playback command creates the new session.
Playback is restricted to sessions that are finished recording as of when you submit the hs_create_playback_session command.
If target is file and multiple playback sessions are used as input, no time gaps are allowed. For example, if you collected data from 9 a.m. to 5 p.m. every day from Monday through Friday, you could not play back those five recording sessions to create a new, summarized, weekly session. However, if you eliminate the time gaps by collecting data from 9 a.m. to 9 a.m. every day from Monday through Friday, you could use the playback feature to create a new, summarized weekly session. Another way to eliminate the time gaps is to keep the 9 a.m. to 5 p.m. recording session, but add another set of recording sessions scheduled from 5 p.m. to 9 a.m. Use a longer sample interval for the off hours to reduce the volume of data collected.
The value of the summarization_interval parameter used in the hs_create_playback_session command affects the rules that the hs_create_playback_view command uses to define views.
