Session Schedule : OnixS .NET Framework FIX Engine

Session Schedule

The Session Scheduler exposes the SessionSchedule class to define the interval of time during which a session must be logged on (active). It also provides the facility to automatically reset message sequence numbers, as it is commonly required by trading systems and venues.

Defining Session Connection Time-frames

The SessionSchedule constructor initializes the session schedule for all supported cases based on the given parameters.

The first two parameters (firstDay and lastDay) define an activity week. During these days, the session will always be connected at logon time and disconnected at logout time if specified session duration equals to a single day. If the session must continue for the entire week, then the scheduler will connect the session at logon time on the day, that is specified by the firstDay parameter and disconnected at logout time on the day specified by the lastDay parameter.

Note
All combinations of values for the firstDay and lastDay parameters are supported. It is possible for the firstDay parameter value to be greater than the value of the lastDay parameter. In such case, the schedule will cross the end of the week and continue till the lastDay. If the firstDay and lastDay parameters are of the same value, then the length (number of days) of an activity week depends on the values of the logonTime and the logoutTime parameters. In particular, if logonTime is less than logoutTime, then the activity week will equal to a single day. However, if logonTime is greater than logoutTime, then the activity week will equal to seven days (the first logon will be performed at logon time on the first day, the last logout will be performed at logout time a week later).

Note

All combinations of values for the firstDay and lastDay parameters are supported. It is possible for the firstDay parameter value to be greater than the value of the lastDay parameter. In such case, the schedule will cross the end of the week and continue till the lastDay.

If the firstDay and lastDay parameters are of the same value, then the length (number of days) of an activity week depends on the values of the logonTime and the logoutTime parameters. In particular, if logonTime is less than logoutTime, then the activity week will equal to a single day. However, if logonTime is greater than logoutTime, then the activity week will equal to seven days (the first logon will be performed at logon time on the first day, the last logout will be performed at logout time a week later).

The logonTime and logoutTime parameters respectively define the time of logon and logout for the session for each activity day if session duration is a single day. If the session must continue for the entire week, then the logonTime parameter value specifies the time for logon to be performed on the first day of the activity week, and the logoutTime parameter value defines the time of logout performed on the last day of the activity week.

Note
If a session duration, specified by the sessionDuration parameter, is equal to the Day value and the value of the logoutTime parameter is less than the logonTime parameter value, then it is assumed that the activity time crosses midnight. In such case, the session scheduler will connect a session at logon time on one day and disconnect it on the next calendar day.

The sessionDuration parameter defines whether the session must continue for the entire activity week (specified by the firstDay and lastDay parameters), or the activity time frame is limited to a single day (24 hours). In particular, if the parameter value equals to Day, then logon and logout occur on the same day (logout may occur the next day if the value of the logoutTime parameter is less than the value of the logonTime parameter).

The Final seqNumberResetPolicy parameter specifies whether the message sequence numbers must be reset and on which basis (daily or weekly).

Note
The value of the seqNumberResetPolicy parameter must conform to the value of the sessionDuration parameter. In particular, message sequence numbers cannot be reset on a daily basis if logon/logout frequency is one per week.

Note
By default, the Scheduler uses the local time to determine when a session should be connected/disconnected in accordance with the Schedule. In this case, for different time zones, there is a need to create/configure different schedules. However, you can use UtcTimeUsage property for switching local time to UTC time usage. In this case, the Scheduler will use the UTC time and you can create/configure the one schedule using the UTC time for all time zones. This can be useful when you deploy your application in different time zones and you need the same behavior of the Scheduler in all time zones by creating only one schedule.

Note

By default, the Scheduler uses the local time to determine when a session should be connected/disconnected in accordance with the Schedule. In this case, for different time zones, there is a need to create/configure different schedules. However, you can use UtcTimeUsage property for switching local time to UTC time usage. In this case, the Scheduler will use the UTC time and you can create/configure the one schedule using the UTC time for all time zones. This can be useful when you deploy your application in different time zones and you need the same behavior of the Scheduler in all time zones by creating only one schedule.

Example

Copy

static void SchedulesVariations()
{
    // Session continues since 8:00 till 17:00 each day of business week.
    SessionSchedule regularSingleDay = new SessionSchedule(
        DayOfWeek.Monday, DayOfWeek.Friday,
        new TimeSpan(8, 0, 0), new TimeSpan(17, 0, 0),
        SessionDuration.Day,
        SequenceNumberResetPolicy.Never);

    // Session starts on Monday, at 8:00 and continues till 17:00 of Friday.
    SessionSchedule regularWeek = new SessionSchedule(
        DayOfWeek.Monday, DayOfWeek.Friday,
        new TimeSpan(8, 0, 0), new TimeSpan(17, 0, 0),
        SessionDuration.Week,
        SequenceNumberResetPolicy.Never);

    // Session starts on Monday at 23:00, crosses midnight and is disconnected
    // at 05:00 on Tuesday. Next connection is established on Tuesday, at 23:00
    // and interrupted at 05:00 on Wednesday. And so on. Last logon will be performed
    // on Friday, at 23:00 and final logout will occur at 5:00 on Saturday morning.
    // Next Monday, before the logon, message sequence numbers will be reset.
    SessionSchedule crossMidnightSingleDay = new SessionSchedule(
        DayOfWeek.Monday, DayOfWeek.Saturday,
        new TimeSpan(23, 0, 0), new TimeSpan(5, 0, 0),
        SessionDuration.Day,
        SequenceNumberResetPolicy.Weekly);

    // Session starts on Friday at 16:00, continues four
    // calendar days and is disconnected on Monday, at 02:00.
    SessionSchedule crossMidnightWeek = new SessionSchedule(
        DayOfWeek.Friday, DayOfWeek.Monday,
        new TimeSpan(16, 0, 0), new TimeSpan(2, 0, 0),
        SessionDuration.Week,
        SequenceNumberResetPolicy.Never);
}

Copy

Private Shared Sub SchedulesVariations()
    ' Session continues since 8:00 till 17:00 each day of business week.
    Dim regularSingleDay As New SessionSchedule(DayOfWeek.Monday, DayOfWeek.Friday, New TimeSpan(8, 0, 0), New TimeSpan(17, 0, 0), SessionDuration.Day, SequenceNumberResetPolicy.Never)

    ' Session starts on Monday, at 8:00 and continues till 17:00 of Friday.
    Dim regularWeek As New SessionSchedule(DayOfWeek.Monday, DayOfWeek.Friday, New TimeSpan(8, 0, 0), New TimeSpan(17, 0, 0), SessionDuration.Week, SequenceNumberResetPolicy.Never)

    ' Session starts on Monday at 23:00, crosses midnight and is disconnected
    ' at 05:00 on Tuesday. Next connection is established on Tuesday, at 23:00
    ' and interrupted at 05:00 on Wednesday. And so on. Last logon will be performed
    ' on Friday, at 23:00 and final logout will occur at 5:00 on Saturday morning.
    ' Next Monday, before the logon, message sequence numbers will be reset.
    Dim crossMidnightSingleDay As New SessionSchedule(DayOfWeek.Monday, DayOfWeek.Saturday, New TimeSpan(23, 0, 0), New TimeSpan(5, 0, 0), SessionDuration.Day, SequenceNumberResetPolicy.Weekly)

    ' Session starts on Friday at 16:00, continues four
    ' calendar days and is disconnected on Monday, at 02:00.
    Dim crossMidnightWeek As New SessionSchedule(DayOfWeek.Friday, DayOfWeek.Monday, New TimeSpan(16, 0, 0), New TimeSpan(2, 0, 0), SessionDuration.Week, SequenceNumberResetPolicy.Never)

End Sub

Advanced Cases

The schedule construction is simplified with the parameters to satisfy the most common use cases. In particular, it exposes only the ability to define logon and logout time equal for all activity days. However, sometimes it is necessary to define different logon and logout times for different days. SessionSchedule provides this ability through LogonTimes and LogoutTimes properties.

Both the LogonTimes and LogoutTimes properties return a collection of TimeSpan values which identifies the time of the event (logon or logout) for each day in the week starting from Sunday till Saturday. Modifying entries of these collections gives the more advanced capability to define different logon/logout time for different days.

Example

The following example demonstrates how a schedule can be updated to make a session be disconnected earlier on Friday compared to other days.

Copy

static SessionSchedule ConstructScheduleWithShortTradingForFriday()
{
    // Initially, constructs schedule with the same logon/logout time for all days.
    SessionSchedule scheduleWithShortFriday = new SessionSchedule(
        DayOfWeek.Monday, DayOfWeek.Friday,
        new TimeSpan(8, 0, 0), new TimeSpan(17, 0, 0),
        SessionDuration.Day,
        SequenceNumberResetPolicy.Never);

    // Then, updates value of logout event for Friday day.
    scheduleWithShortFriday.LogoutTimes[(int)DayOfWeek.Friday] = new TimeSpan(16, 30, 0);

    // And that's all.
    return scheduleWithShortFriday;
}

Copy

    Private Shared Function ConstructScheduleWithShortTradingForFriday() As SessionSchedule
    ' Initially, constructs schedule with the same logon/logout time for all days.
    Dim scheduleWithShortFriday As New SessionSchedule(DayOfWeek.Monday, DayOfWeek.Friday, New TimeSpan(8, 0, 0), New TimeSpan(17, 0, 0), SessionDuration.Day, SequenceNumberResetPolicy.Never)

    ' Then, updates value of logout event for Friday day.
    scheduleWithShortFriday.LogoutTimes(CInt(DayOfWeek.Friday)) = New TimeSpan(16, 30, 0)

    ' And that's all.
    Return scheduleWithShortFriday
End Function

Another example demonstrates how schedule can be updated to define one day off in the middle of the trading week.

Copy

static SessionSchedule ConstructScheduleWithWednesdayAsOffDay()
{
    // Initially, constructs schedule with the same logon/logout time for all days.
    SessionSchedule scheduleWithWednesdayOff = new SessionSchedule(
        DayOfWeek.Monday, DayOfWeek.Friday,
        new TimeSpan(8, 0, 0), new TimeSpan(17, 0, 0),
        SessionDuration.Day,
        SequenceNumberResetPolicy.Never);

    // Then, disables logon and logout on Wednesday.
    scheduleWithWednesdayOff.LogonTimes[(int)DayOfWeek.Wednesday] =
      scheduleWithWednesdayOff.LogoutTimes[(int)DayOfWeek.Wednesday] =
      TimeSpan.MinValue;

    // And that's all.
    return scheduleWithWednesdayOff;
}

Copy

Private Shared Function ConstructScheduleWithWednesdayAsOffDay() As SessionSchedule
    ' Initially, constructs schedule with the same logon/logout time for all days.
    Dim scheduleWithWednesdayOff As New SessionSchedule(DayOfWeek.Monday, DayOfWeek.Friday, New TimeSpan(8, 0, 0), New TimeSpan(17, 0, 0), SessionDuration.Day, SequenceNumberResetPolicy.Never)

    ' Then, disables logon and logout on Wednesday.
    scheduleWithWednesdayOff.LogonTimes(CInt(DayOfWeek.Wednesday)) = TimeSpan.MinValue
    scheduleWithWednesdayOff.LogoutTimes(CInt(DayOfWeek.Wednesday)) = TimeSpan.MinValue

    ' And that's all.
    Return scheduleWithWednesdayOff
End Function

Also, sometimes, it is necessary to do a pause during a working day and continue the work after some time. For such cases, the scheduler has an ability to register multiple schedules for a session, please see the example below.

Example

The example demonstrates how to use multiple schedules to achieve the following behavior on each working day:

Logon at 8:00 (sequence numbers reset) - Logout at 12:00
Logon at 13:00 (no sequence numbers reset) - Logout at 17:00

Copy

const int ScheduleNumber = 2;
SessionSchedule[] workingDaySchedules = new SessionSchedule[ScheduleNumber];

// Schedule for the first part of the working day.
workingDaySchedules[0] = new SessionSchedule(
    DayOfWeek.Monday, DayOfWeek.Friday,
    new TimeSpan(8, 0, 0), new TimeSpan(12, 0, 0),
    SessionDuration.Day,
    SequenceNumberResetPolicy.Daily);

// Schedule for the second part of the working day.
workingDaySchedules[1] = new SessionSchedule(
    DayOfWeek.Monday, DayOfWeek.Friday,
    new TimeSpan(13, 0, 0), new TimeSpan(17, 0, 0),
    SessionDuration.Day,
    SequenceNumberResetPolicy.Never);

// Register two schedules for the session.
scheduler.Register(
    initiator,
    workingDaySchedules,
    new InitiatorConnectionSettings("localhost", 4500));

Note
If multiple schedules are used, then you should set the sessionDuration parameter to the Day value and the logonTime should be less than the logoutTime, otherwise the behavior can be unexpected one.