vcl-151033-expressscheduler-concepts-persisting-data-handling-raw-data.md
This topic describes how to persist a user event‘s data in the underlying data store manually (bypassing the scheduler storage – TcxSchedulerStorage or TcxSchedulerDBStorage).
The cxSchedulerTable.db table that is described in this topic was created in Paradox® format using the BDE toolset.
The following pieces of information on the scheduled user event are stored in the database:
The end date of a chain of occurrences if the user event is recurring (see the TcxSchedulerEvent.ActualFinish and TcxSchedulerDBStorageFieldNames.ActualFinish properties).
The start date of a chain of occurrences if the user event is recurring (see the TcxSchedulerEvent.ActualStart and TcxSchedulerDBStorageFieldNames.ActualStart properties).
The subject of the user event (see the TcxSchedulerEvent.Caption and TcxSchedulerDBStorageFieldNames.Caption properties).
The status of the current occurrence (see the TcxSchedulerEvent.EventType and TcxSchedulerDBStorageFieldNames.EventType properties).
The end time of the current occurrence (see the TcxSchedulerEvent.Finish and TcxSchedulerDBStorageFieldNames.Finish properties).
The unique identifier of the user event recorded in the dataset (see the TcxSchedulerEvent.ID property).
The color label of the user event (see the TcxSchedulerEvent.LabelColor and TcxSchedulerDBStorageFieldNames.LabelColor properties).
The location of the user event (see the TcxSchedulerEvent.Location and TcxSchedulerDBStorageFieldNames.Location properties).
The description of the user event (see the TcxSchedulerEvent.Message and TcxSchedulerDBStorageFieldNames.Message properties).
Whether the user event is an all-day event or task group, whether the time of the scheduled user event is later than the host environment’s time, whether a reminder is set on for the corresponding user event, and whether the predecessor task is expanded (see the TcxSchedulerEvent.AllDayEvent, TcxSchedulerEvent.IsGroup, TcxSchedulerEvent.Enabled, TcxSchedulerEvent.Reminder and TcxSchedulerEventLinks.Expanded properties). These five states are stored in a single dataset field (see the TcxSchedulerDBStorageFieldNames.Options property).
The unique identifier of the current occurrence’s parent if the parent user event is recurring (see the TcxSchedulerEvent.ParentID and TcxSchedulerDBStorageFieldNames.ParentID properties).
The unique identifier of the task group (see the TcxSchedulerEvent.GroupID and TcxSchedulerDBStorageFieldNames.GroupID properties).
The position (as a number) of the user event’s occurrence in the chain of reoccurrences (see the TcxSchedulerEvent.RecurrenceIndex and TcxSchedulerDBStorageFieldNames.RecurrenceIndex properties).
The user event’s recurrence details (see the TcxSchedulerEvent.RecurrenceInfo and TcxSchedulerDBStorageFieldNames.RecurrenceInfo properties).
The date and time of the reminder that is switched on for the corresponding user event (see the TcxSchedulerEvent.ReminderDate and TcxSchedulerDBStorageFieldNames.ReminderDate properties).
The reminder’s time interval (see the TcxSchedulerEvent.ReminderMinutesBeforeStart and TcxSchedulerDBStorageFieldNames.ReminderMinutesBeforeStart properties).
Information on reminders currently active in the scheduler (see the TcxSchedulerDBStorageFieldNames.ReminderResourcesData property).
The unique identifier of the resource the user event belongs to (see the TcxSchedulerEvent.ResourceID and TcxSchedulerDBStorageFieldNames.ResourceID properties). If the resource is shareable then the ResourceID field’s type should be defined as of BLOB.
The start time of the current occurrence (see the TcxSchedulerEvent.Start and TcxSchedulerDBStorageFieldNames.Start properties).
The availability of an end-user to others (see the TcxSchedulerEvent.State and TcxSchedulerDBStorageFieldNames.State properties).
The task completion (see the TcxSchedulerEvent.TaskComplete and TcxSchedulerDBStorageFieldNames.TaskCompleteField properties).
The task’s vertical position relative to other tasks (see the TcxSchedulerEvent.TaskIndex and TcxSchedulerDBStorageFieldNames.TaskIndexField properties).
Task links (see the TcxSchedulerEvent.TaskLinks and TcxSchedulerDBStorageFieldNames.TaskLinksField properties).
The task status (see the TcxSchedulerEvent.TaskStatus and TcxSchedulerDBStorageFieldNames.TaskStatusField properties).
The following table shows the structure of the cxSchedulerTable.db table that stores the detailed information on the scheduled user event:
| |
Field Name
|
Type
|
Size
|
Value Restriction Rule
| | --- | --- | --- | --- | --- | |
1
|
|
| | | |
2
|
|
| | | |
3
|
|
|
255
|
NULL must be allowed
| |
4
|
|
| | | |
5
|
|
| | | |
6
|
|
or GUID
| | | |
7
|
|
(Autoincrement)
or GUID
| | | |
8
|
|
| |
NULL must be allowed
| |
9
|
|
|
255
|
NULL must be allowed
| |
10
|
|
|
255
|
NULL must be allowed
| |
11
|
|
| |
NULL must be allowed
| |
12
|
|
or GUID
| | | |
13
|
|
| | | |
14
|
|
| | | |
15
|
|
| |
NULL must be allowed
| |
16
|
|
| |
NULL must be allowed
| |
17
|
|
| |
NULL must be allowed
| |
18
|
|
or TBlobField
| | | |
19
|
|
| | | |
20
|
|
| |
NULL must be allowed
| |
21
|
|
| | | |
22
|
|
| | | |
23
|
|
| | | |
24
|
|
| | |
You can also add custom fields to the table to store the custom data (to learn how to use custom fields in an application, refer to the Customizing Event and Event recurrence dialogs help topic).
The Options field’s value is a compound value and it’s made up of the omAllDayEvent, omCollapsed, omEnabled, omGroup, and omReminder values. If these flags are set at the same time, use the OR bitwise operator to build up the Options field’s value (see the example below).
The RecurrenceInfo field of the BLOB type stores the TcxSchedulerCustomRecurrenceInfoData record’s data that provides details on the user event recurrence. To transfer the TcxSchedulerCustomRecurrenceInfoData record’s data into a sequence of bytes, use the cxRecurrenceInfoDataToString routine; an example on this is provided later on in this topic.
The RecurrenceInfo field structure corresponds to the TcxSchedulerCustomRecurrenceInfoData record’s structure, as illustrated in the following table:
|
Record Field
|
Type
|
BLOB
Offset
|
Storage Requirement
(bytes)
|
Description
| | --- | --- | --- | --- | --- | |
Count
|
Integer
|
0
|
4
|
Specifies the number of occurrences of the recurring user event.
| |
DayNumber
|
Integer
|
4
|
4
|
Specifies the day number in a month, working week, Saturdays/Sundays in a month, or weekend that the user event will reoccur on (for details refer to the Applying The Recurrence Pattern topic).
| |
DayType
|
|
8
|
1
|
Specifies the day type used to calculate the user event’s reoccurrence in the Recurrence pattern.
| |
Finish
|
TDateTime
|
9
|
8
|
Specifies the end date and time of the user event’s reoccurrences.
| |
OccurDays
|
|
17
|
1
|
Specifies the days in a week that the user event reoccurs on.
| |
Periodicity
|
Integer
|
18
|
4
|
Specifies the frequency with which the user event reoccurs with respect to the time base specified by the Recurrence field.
| |
Recurrence
|
|
22
|
1
|
Specifies the time base for the frequency of the user event’s reoccurrences.
| |
Start
|
TDateTime
|
23
|
8
|
Specifies the start date and time for the user event’s reoccurrences.
| |
YearPeriodicity
|
Integer
|
31
|
4
|
Specifies the frequency with which the user event reoccurs on a yearly basis.
| |
Version
|
Byte
|
35
|
1
|
Reserved for internal use.
| |
DismissDate
|
Integer
|
36
|
4
|
Specifies the date when the reminder is switched off for the corresponding occurrence.
|
The following example shows how to store a new user event in the data store:
// ...
var
S: string;
ARecurrenceInfo: TcxSchedulerCustomRecurrenceInfoData;
begin
FillChar(ARecurrenceInfo, SizeOf(ARecurrenceInfo), 0);
// the all-day event repeats two days (Thursday and Friday)
with ARecurrenceInfo do
begin
Count := 2;
DayNumber := 1;
DayType := cxdtEveryDay;
Finish := -1;
OccurDays := [dThursday];
Periodicity := 1;
Recurrence := cxreDaily;
Start := 0;
YearPeriodicity := 1;
end;
// convert the TcxSchedulerCustomRecurrenceInfoData record's data into the binary data contained in the string that serves as a buffer between the record and the RecurrenceInfo dataset field
S := cxRecurrenceInfoDataToString(ARecurrenceInfo);
// post it to the dataset
with SchedulerTable do
begin
Append;
FieldValues['Type'] := Integer(etPattern);
FieldValues['Start'] := StrToDateTime('10/21/04 00:00');
FieldValues['Finish'] := StrToDateTime('10/22/04 00:00');
FieldValues['Options'] := omAllDayEvent or omEnabled;
FieldValues['Caption'] := 'Birthday';
FieldValues['RecurrenceIndex'] := -1;
FieldValues['RecurrenceInfo'] := S;
FieldValues['ResourceID'] := 1; // if the resource is set up in the scheduler
FieldValues['Location'] := 'Sea Food Restaurant';
FieldValues['Message'] := 'Party';
FieldValues['State'] := tlsOutOfOffice;
FieldValues['LabelColor'] := EventLabels.Items[1].Color; // the label is 'important'. To use the EventLabels collection (see description on the TcxSchedulerEventLabels class in the documentation), specify the cxSchedulerUtils unit in the uses clause
Post;
end;
end;
To learn how to use resources, refer to the Grouping User Events and Bound Mode help topics.
Note : the example shown above assumes that the ID field in the data store is automatically incremented. If the type of the ID field is defined as GUID (for example, in MS SQL Server) and if it is not generated by the database engine for some reason, then you can use the TGUID type and the CreateGUID function to generate a value for the ID field. It’s best to implement the TDataSet.BeforePost event handler and generate a new GUID in it before the data is posted to the data store, as shown below:
// ...
procedure TCustomDialogsForm.SchedulerTableBeforePost(DataSet: TDataSet);
var
ASchedulerTableID: TField;
G: TGuid;
begin
ASchedulerTableID := DataSet.FieldByName('ID');
if ASchedulerTableID.IsNull then
begin
// generate a new GUID
CreateGUID(G);
// assign the newly created GUID to the ID field
ASchedulerTableID.Value := GUIDToString(G);
end;
end;
Note
The type of the ID field and the ParentID field’s type must be the same.
See Also