hs_create_playback_session

Description

Defines the characteristics of a playback session. This command is the first step in creating a playback session.

Syntax

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... ]

Parameters

start_time

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.

end_time

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.

summarization_interval

a required parameter (no default exists) that specifies the level of detail of the playback. Valid values are:

sample_interval

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:

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:

allow_estimation

specifies whether or not you want playback to estimate values for data items that cannot be calculated exactly. Valid values are:

This parameter is ignored if summarization_interval is raw.

See Table C-2 to determine which data items require estimation.

missing_data_option

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:

When target is file, gaps are not allowed.

target

specifies the target results of the playback session. Valid values are:

directory_name

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.

protection_level

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:

When target is client, this parameter is ignored.

script_type

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:

When target is client, this parameter is ignored.

delete_option

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:

When target is client, this parameter is ignored.

session_id[ ,session_id. . .]

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.

Examples

Example 1

  1. 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
    
  2. 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
    

Usage