Sun Java System Calendar Server 6 2005Q4 Developer's Guide

Command: createcalendar

Purpose

Create a new calendar.

Parameters

Table 7–2 createcalendar Parameter


Parameter	Types	Purposes	Required	Default
`allowdoublebook`	integer (`0`,`1`)	Allows a user to determine whether or not to allow double booking on user’s calendars. `0` = Disallow double booking`1` = Allow double booking	N	`1`
`calid`	string	The user’s `calid,` used to generate the new calendar’s `calid`.	Y	N/A
`id`	unique identifier string	The session identifier.	Y	N/A
`fmt-out`	string	The format for the returned data. The three format types: `text/calendar` `text/xml`	Y	`text/calendar`
`set_calprops`	integer (`0`,`1`)	A boolean indicating whether to set the properties of the new calendar. `1` = Set properties.`0` = Do not set properties.	N	`0`
`subscribe`	integer (`0` or `1`)	Allows a user to specify if the newly created calendar should be added to the user’s subscribed calendar list. `1` = Subscribe to the calendar `0` = Do not subscribe to the calendar	N	`0`
`subscribe`	integer (`0`,`1`)	Allows a user to determine if a newly created calendar should be added to the user’s subscribed calendar list. `0` = Do not subscribe `1` = Subscribe	N	`1`

Description

Use this command to create a new calendar for the current user. To enable users who do not have administrative privileges to use this command, the service.wcap.allowcreatecalendars parameter in the ics.conf file must be set to “yes”, which is the default.

Creating a Valid Calid

The new calid of the created calendar is a combination of the user’s userid and the calid parameter passed in. The system retrieves the userid by doing a lookup on the session specified with the id parameter. The format for the new calendar’s calid is userid:calid. For example, if the user is jdoe, and the calid parameter is tv, the new calendar’s calid is jdoe:tv.

The server attempts to truncate calid parameters that are too long or contain any illegal characters. If the server is unable to truncate the calid parameter, the error returned is FAILED: ILLEGAL_CALID_NAME.

Valid characters for the calid parameter are:

Alphabet characters (A-Z, a-z)
Numeric characters (0-9)
Three special characters
- Dash (-)
- Underscore (_)
- Period (.)
  
  For example, these are legal values for the calid parameter: calendar1, calendar-1, calendar_1, calendar.1

Setting Calendar Properties

You can set the calendar properties during creation. Pass in the set_calprops parameter with a value of 1. You can then pass in any additional parameters as defined for the set_calprops command for setting calendar properties.

For more information on calendar properties you can set, see the Command: set_calprops command.

Note that at calendar creation, if you do not specify calendar properties, the defaults set in the ics.conf file are used.

Returns

The returned output shows the calendar properties (retrieved with a call to the fetchcomponents_by_range command) formatted according to the fmt-out value.

Error Codes

If the operation is successful, the error number of 0 is appended to the error string. If the newly created calid already exists in the database, an error code returns: FAILED: CREATECALENDAR_ALREADY_EXISTS_FAILED.

Example

The following example URL creates a calendar with the ID jdoe:newcal for the user jdoe, sets the name to New-Calendar, and the categories to business and work:

http:/calendarserver/createcalendar.wcap
                    ?id=b5q2o8ve2rk02nv9t6
                    &calid=newcal
                    &set_calprops=1
                    &name=New-Calendar
                    &categories=business;work