8 Oracle Calendar SDK FAQ and Troubleshooting

This chapter contains frequently asked questions and troubleshooting information for the Oracle Calendar SDK.

Frequently Asked Questions

Will my applications written with the CAPI functions from older Oracle Calendar SDK work with Oracle Calendar server Release 2 (9.0.4) and up?

Yes, your older applications will continue to work and you can continue to write applications using the CAPI functions of Release 2 (9.0.4) of the Oracle Calendar SDK.

However, these older CAPI functions store and retrieve some iCalendar properties on the Oracle Calendar server in a format only understood by these CAPI functions. So clients like Oracle Connector for Outlook or applications written with CSDK functions of the Oracle Calendar SDK will not see these properties. Since Release 2 (9.0.4) of Oracle Collaboration Suite, the Oracle Calendar SDK has introduced the CSDK functions that completely respect the Oracle Calendar data representation to eliminate this incompatibility. Oracle encourages you to migrate your Oracle Calendar SDK applications to use the CSDK functions.

The following iCalendar properties are the ones that are incompatible:

COMMENT
CONTACT
RELATED-TO
SEQUENCE
UID
URL
Any X-ORACLE properties

Likewise, applications using the older CAPI functions will not obtain the values set for those properties by applications using CSDK functions of the Oracle Calendar SDK or clients like Oracle Connector for Outlook.

Can I write an Oracle Calendar SDK program using Visual Basic or other programming languages?

The Oracle Calendar SDK is a package of C/C++ function calls, so any language that can natively support C can be used to create a wrapper and access these functions.

Options include using Visual Basic, Perl, Java, and Python. There may be other independent efforts in existence; the Oracle Calendar SDK forum on Oracle OTN is a good place to look for such information.

What is the minimal information required to create a new event?

You need the following properties to create an event:

ATTENDEE
DTSTART
DTEND or DURATION

However, if you use the CSDK_StoreEvents function with the CSDK_FLAG_STORE_INVITE_SELF flag, you do not have to include an ATTENDEE property.

How do I uninvite someone from an event?

Replace the event by calling CSDK_StoreEvents and supplying an iCalendar without an ATTENDEE property for the user.

How do I invite someone to an event?

Provide an ATTENDEE property for the user when calling CSDK_StoreEvents.

Can I log in as the Oracle Calendar server administrator (Oracle Calendar SYSOP) using the Oracle Calendar SDK?

Yes. Oracle Calendar SYSOP login is supported as of release 9.0.4 of the Oracle Calendar SDK.

How do I delete an event completely?

Use the function CSDK_DeleteEvents, supplying the event UID.

What is the default access level of an event or task?

If you do not specify the CLASS property in an event or task, that event or task will have an access level of PUBLIC. This is the behavior as defined in RFC 2445.

Can I fetch ATTENDEE properties for all attendees (resources and users) of an event, even if some of those attendees do not have an email address?

Yes. Use one of the following flags with the functions CSDK_FetchEventsByRange, CSDK_FetchEventsByAlarmRange, or CSDK_FetchEventsByUID:

CSDK_FLAG_FETCH_RESOURCES_WITHOUT_ADDRESSES: The Oracle Calendar SDK will generate an ATTENDEE property for any resource without an email address. It will create a mailto URI of the form "mailto:<guid>@email.invalid" (see RTC 2606 for more information about reserved invalid domain names).
CSDK_FLAG_FETCH_USERS_WITHOUT_ADDRESSES: The Oracle Calendar SDK will generate an ATTENDEE property for any normal user without an email address. It will create a mailto URI of the form "mailto:<guid>@email.invalid".

How do I modify the start time (DTSTART) of an event?

To modify the start time of an event instance (it is irrelevant whether the event is the only instance or has multiple instances), set the RECURRENCE-ID property to the current start time of the instance as it exists on the Oracle Calendar server, and set DTSTART to the new start time. In this way, the Oracle Calendar SDK can determine precisely which instance to reschedule. If you set only the DTSTART to a time different than the current start time, the Oracle Calendar SDK will attempt to add a new instance to your event at the new start time.

For example, suppose the following event is stored on the Oracle Calender server:

BEGIN:VCALENDAR
VERSION:2.0
PRODID://Oracle//CSDK//EN
BEGIN:VEVENT
UID:event_we_want_to_modify-oracle
DTSTART:20050101T120000Z
DTEND: 20050101T130000Z
END:VEVENT
END:VCALENDAR

To modify this event's DTSTART from January 1 to February 1, store the following event with the CSDK_StoreEvent function and the flag CSDK_FLAG_STORE_MODIFY:

BEGIN:VCALENDAR
VERSION:2.0
PRODID://Oracle//CSDK//EN
BEGIN:VEVENT
RECURRENCE-ID:20050101T120000Z
UID:event_we_want_to_modify-oracle
DTSTART:20050201T120000Z
DTEND:20050201T130000Z
END:VEVENT
END:VCALENDAR

How do I accept a meeting?

In order to accept a meeting, or set the reply status of an event not owned by the logged-in user, use the CSDK_FLAG_STORE_REPLY with the CSDK_StoreEvent function.

Do not use the CSDK_FLAT_STORE_MODIFY flag. For example, Abe (as the logged in user) creates an event with UID:abe@example.com. Abe invites Bea through the ATTENDEE property. If Bea (as the logged in user) tries to update her status on that event (with UID:abe@example.com) with the CSDK_FLAG_STORE_MODIFY flag, she will receive a CAPI_STAT_SECUR_WRITE error.

My calendar users are spread across different time zones. How can I accurately retrieve one day's events for a particular user?

Day events and daily notes have start times which are dependent on the time zone in which they were created. Because of this, to correctly retrieve all of them for a particular day, the time range needs to be extended up to twelve hours at both ends of the time range. This can be done separately from fetching regular meetings (using the exclusion flags), or you can fetch them all at once and manually filter out regular meetings that fall outside the desired time range.

How can I add an attendee to all instances of an event?

To add an attendee to all instances of an event, use the MODIFY flag to store an iCalendar object containing a VEVENT with only the UID of the event and the ATTENDEE property you wish to add.

If the event has any exceptions (as represented by separate VEVENTs that contain the RECURRENCE-ID property when fetched from the Oracle Calendar server), these need to be handled individually by also providing a VEVENT with the UID and corresponding RECURRENCE-ID of the instance, along with the ATTENDEE property to be added. Modifications to the series and the exceptions can be done in the same event store operation by including all the relevant VEVENTs in the same VCALENDAR object.

Troubleshooting

When I run the Oracle Calendar SDK demos, I get the error "libcapi.so not found, no such file or directory", or "Cannot load library libcapi". How do I fix this?

See the latest Oracle Calendar SDK Readme file for this information.

I'm getting error 2148073984 from calling an Oracle Calendar SDK function. What does that mean? Where can I find more information on Oracle Calendar SDK errors?

Chapter 6, "Oracle Calendar SDK Status Codes" contains a list of Oracle Calendar SDK status codes. Each code can be divided into five fields, each describing a different level of the problem.

The two helper functions, CSDK_GetStatusLevels() and CSDK_GetStatusString(), can help decode the error easily. You can also look at the demo applications that ship with the Oracle Calendar SDK for an example of how to decode error codes.

Why do my accented "é" characters appear as =C3=A9 in events I retrieve using the Oracle Calendar SDK?

The Oracle Calendar SDK encodes its output in UTF-8, in which the character is represented as 2 bytes: 0xC3 and 0xA9. When returning MIME-encapsulated data, the Oracle Calendar SDK further encodes those bytes in quoted-printable strings, which results in =C3=A9.

There seem to be a lot of extra =3D characters in the ATTENDEE property. Did I just discover a bug?

No, this is not a bug. =3D is really an equal sign (=) encoded in quoted-printable. So, where you might expect to see partstat=confirmed, you would actually see partstat=3Dconfirmed.

Why do I get a LNK1106 error when compiling the Oracle Calendar SDK with Microsoft Visual C++?

The Oracle Calendar SDK was compiled with Visual C++ 6; older versions need a patch to work. Search the Microsoft Web site for available patches.

Ensuring that you are using Visual C++ will mitigate linking errors you may encounter with other C compilers. Refer to the demo applications project for recommended compiler and linker settings.

Why is my program aborting whenever I use CSDK_CreateFileStream()? I tried the other type of streams and they worked fine.

You need to link your application using Microsoft's C runtime library (the /MD switch if you're using the command line) as opposed to the static C libraries. This is required because the FILE pointer used by the file stream has different definitions depending on which version of the C library is being used.

CSDK_CreateFileStreamFromFilenames can be used, in which case the FILE pointer will not need to be passed between the SDK and your application.

Why does CSDK_GetHandle() tell me it can't find my resource?

There are a couple of possible answers:

Your resource name may contain accented or special characters such as "‡". The Oracle Calendar SDK expects user and resource identification strings to be in UTF-8. Be sure to use the proper UTF-8 values to describe accented or special characters.
Your resource name contains a forward-slash (/) character, such as "Training / Meeting Room". The use of this character inside resource names conflicts with the forward-slash used by default as the field delimiter. To fix this, simply use another character as your delimiter. For example, RS=Work/.

When I create a meeting, the STATUS says "CONFIRMED". Why does it say "Will confirm later" when I look at the meeting with the native client?

"Will confirm later" is the participation status of the attendee, while "CONFIRMED" is the STATUS property of the VEVENT. The Oracle Calendar SDK sets the STATUS property to "CONFIRMED" by default. You may set the STATUS property to other values including "TENTATIVE" and "CANCELLED".

The user's attendance status is stored in the PARTSTAT parameter of the ATTENDEE property corresponding to that user.

Why am I getting CAPI_STAT_DATA_MIME_HEADER errors?

By default, iCalendar objects passed to the Oracle Calendar SDK must have a MIME header. Otherwise, the Oracle Calendar SDK would return the error CAPI_STAT_DATA_MIME_HEADER otherwise.

Alternately, you can specify the CSDK_FLAG_STREAM_NOMIME flag, which is much simpler.

For example, the Oracle Calendar SDK considers the following MIME encapsulated iCalendar as valid:

String my_ical = "MIME-Version: 1.0\n" +
  "Content-Type: text/calendar\n" +
  "Content-Transfer-Encoding: quoted-printable\n\n" +
  "BEGIN:VCALENDAR\n" +
  "VERSION:2.0\n" +
  "PRODID:-//ORACLE//NONSGML CSDK 9.0.4.1 - Java SDK Demo 9.0.4.1//EN\n" +
  "BEGIN:VEVENT\n" +
  "DTSTART:20040210T183000Z\n" +
  "DTEND:  20040210T193000Z\n" +
  "SUMMARY:Asker Demo\n" +
  "LOCATION:office\n" +
  "ATTENDEE:MAILTO:john@example.com\n" +
  "ATTENDEE:MAILTO:jane@example.com\n" +
  "END:VEVENT\n" +
  "END:VCALENDAR\n";

Why am I getting CAPI_STAT_DATA_ICAL_NOATTENDEES errors?

In order to add an event to a user's agenda, that event must have an ATTENDEE property. Otherwise, the Oracle Calendar SDK would return the error CAPI_STAT_DATA_ICAL_NOATTENDEES.

Alternatively, the caller of the function (such as CSDK_StoreEvents) can specify the CSDK_FLAG_STORE_INVITE_SELF flag, which implicitly adds the caller as an attendee.