This document covers the following topics:
Return a list of time ranges in which all or most of the specified attendees and/or cabinets are available.
This subprogram is the same as Z-STIME with the exception that it uses time slices consisting of 5 minutes (not full quarters of an hour) and that the Work-parameter has a different format.
This subprogram can be used, for example, in the following situations:
Situation: Basic meeting information and addressees have not been
specified.
Before calling Z-ADD06 (add
the basic information of a meeting) and Z-ADDATT (add attendees and resources to a
meeting), run this subprogram with parameter Attendee-ISN. Specifying the
parameter Calendar-ISN only makes sense when basic meeting information and
addressees have already been added (see below).
Situation: Basic meeting information and addressees have been
added, but the invitations have not been sent (meeting is pending). You want to
search the cabinets of either current attendees or newly added attendees for
free time.
To search the cabinets of the current attendees for free time, specify
parameter Calendar-ISN without Attendee-ISN. The first 50 attendees are checked
for free time and the ISNs of all checked attendees are returned.
To search the cabinets of newly added attendees for free time, specify parameter Attendee-ISNs without Calendar-ISN.
Situation: Invitations for a meeting (version
n) have been sent. You need to modify the basic
meeting information or add new attendees (the version number for the meeting
will be increased by one).
To search the cabinets of the current attendees for free time after
modifying the basic meeting information, specify parameter Calendar-ISN without
parameter Attendee-ISN. The cabinets of the first 50 previously invited
attendees are searched for free time. The time range occupied by the previous
version is viewed as free time. The ISNs of the checked attendees are returned.
To search the cabinets of the newly added attendees for free time, specify parameter Attendee-ISNs without Calendar-ISN.
Up to 24 hours can be specified in the parameters Search-for-hours and Search-for-minutes.
The search period is always set to time slices consisting of 5 minutes. Example: when you specify the time range 1:14 to 2:37, this is automatically set to 1:15 to 2:35.
The values specified in the parameters Search-for-hours and Search-for-minutes are also set to time slices consisting of 5 minutes. Example: when you specify 38 minutes, this is automatically set to 40 minutes.
If Start-time and End-time are not specified, the time range from 0:00 to 23:59 is automatically provided.
The date range must be less than or equal to 90 days.
If the parameter Separate-daily-entries is specified, the meeting occupies only the specified time range for each day. If the parameter Separate-daily-entries is not specified, the whole time range starting with the Start-time of the first day and ending with the End-time of the last day is reserved.
All time parameters are interpreted as GMT (0). Therefore, when changing the suggested time ranges into a user time format, it is possible that a continuous time range is split into two days.
Using the parameter Number-of attendees, the array of Attendee-ISNs can be limited.
Each Attendee-ISN is checked and returned in the parameter Return-status.
Found free time is returned in the Free-time-array. This may include up to 20 time ranges. The parameter Found-attendees indicates the number of attendees for which free time was found. If no free time was found for some of the attendees, the Free-time-array provides the 20 best suggestions (in this case, no iterative calls are required).
This subprogram may be invoked iteratively until the return code is 77.
| Parameter | Format | In | Out | Remarks |
|---|---|---|---|---|
| Return-code | N2 | O | X | Input -1: no ET. |
| Cabinet | A8 | R | The cabinet which contains the meeting to be added or modified. | |
| Password | A8 | R | The password of the above cabinet. | |
| Calendar-ISN | P10 | R/O | Required, if Attendee-ISN is not specified. The ISN of the meeting for which the time range is to be changed. If Attendee-ISN is not specified, the first 50 attendees are checked for free time. The time occupied by the previous version of this meeting is viewed as free time. | |
| Start-date | A8 | R | The starting date of the meeting. Format yyyymmdd. | |
| Start-time | A4 | O | The starting time of the meeting. Format hhmm. | |
| End-date | A8 | O | The ending date of the meeting. Format yyyymmdd. | |
| End-time | A4 | O | The ending time of the meeting. Format hhmm. | |
| Separate-daily-entries | A1 | O | If marked, the meeting occupies only the specified time range for each day. If not marked, the whole time range starting with the Start-time of the first day and ending with the End-time of the last day is reserved. | |
| Search-for-hours | N2 | R | Search for free time: the number of hours. | |
| Search-for-minutes | N2 | R | Search for free time: the number of minutes. | |
| Number-of-attendees | I1 | R | The number of attendees in whose calendar you want to search for free time. Default and maximum: 50. | |
| Attendee-ISN | P10/1:50 | R/O | X | Required, if Calendar-ISN is not specified. The ISN of each attendee's cabinet that is to be searched for free time. For an attendee (object number 1), use the ISN that you have previously returned by one of the Z-GET01 subprograms. For a cabinet (object number 5), use the ISN that you have previously returned by Z-DIS05. Output: If Calendar-ISN is specified without Attendee-ISN, the ISNs of checked attendees are returned. |
| Return-status | I1/1:50 | X | Return status about free time corresponding to the Attendee-ISNs returned. 00=address accepted, 01= address rejected, 04=Attendee-ISN not found, 33=Attendee not unique. | |
| Free-time-array (20) | ||||
| Found-start-date | A8 | X | Start date of found free time. | |
| Found-start-time | A4 | X | Start time of found free time. | |
| Found-end-time | A4 | X | End time of found free time. | |
| Found-attendees | I1 | X | The number of attendees for which free time was found. | |
| Work-parameter | B1/1:1214 | For internal use. See The Work Parameter. | ||
| 00 | Success |
| 02 | Invalid cabinet name or - in batch mode only - locked cabinet |
| 03 | Password incorrect |
| 04 | ISN was not found |
| 18 | API context buffer not available |
| 24 | Security violation |
| 33 | Attendee not unique. |
| 39 | Time range too small for search |
| 40 | Date range is negative or more than 90 days |
| 41 | Invalid start-date |
| 42 | Invalid start-time |
| 43 | Invalid end-date |
| 44 | Invalid end-time |
| 49 | Invalid value for Search-for-hours/Search-for-minutes |
| 50 | Value for Search-for-hours/Search-for-minutes is greater than specified time range |
| 77 | End of list |
| 96 | No free time found |
Z-061625
Z-061635
Z-120
Z-122
Z-123
Z-165
Z-175
Z-120&0
DEFINE DATA LOCAL * 1 RETURN-CODE (N2) 1 CABINET (A8) 1 PASSWORD (A8) 1 CALENDAR-ISN (P10) 1 START-DATE (A8) 1 START-TIME (A4) 1 END-DATE (A8) 1 END-TIME (A4) 1 SEPARATE-DAILY-ENTRIES (A1) 1 SEARCH-FOR-HOURS (N2) 1 SEARCH-FOR-MINUTES (N2) 1 NUMBER-OF-ATTENDEES (I1) 1 ATTENDEE-ISN (P10/1:50) 1 RETURN-STATUS (I1/1:50) 1 FREE-TIME-ARRAY (20) 2 FOUND-START-DATE (A8) 2 FOUND-START-TIME (A4) 2 FOUND-END-TIME (A4) 2 FOUND-ATTENDEES (I1) 1 WORK-PARAMETER (B1/1:1214) END-DEFINE * MOVE 'Cabinet' TO CABINET MOVE 'Password' TO PASSWORD * MOVE 117412 TO CALENDAR-ISN /* do not consider previous version! MOVE '20010505' TO START-DATE MOVE '1900' TO START-TIME MOVE '20010508' TO END-DATE MOVE '2100' TO END-TIME MOVE 'X' TO SEPARATE-DAILY-ENTRIES MOVE 2 TO SEARCH-FOR-HOURS MOVE 00 TO SEARCH-FOR-MINUTES MOVE 2 TO NUMBER-OF-ATTENDEES MOVE 29300 TO ATTENDEE-ISN (1) MOVE 2191 TO ATTENDEE-ISN (2) * CALLNAT 'Z-STIME5' RETURN-CODE CABINET PASSWORD CALENDAR-ISN START-DATE START-TIME END-DATE END-TIME SEPARATE-DAILY-ENTRIES SEARCH-FOR-HOURS SEARCH-FOR-MINUTES NUMBER-OF-ATTENDEES ATTENDEE-ISN(*) RETURN-STATUS(*) FREE-TIME-ARRAY (*) WORK-PARAMETER (*) * WRITE '=' CABINET / '=' PASSWORD / '=' CALENDAR-ISN / '=' START-DATE '=' START-TIME / '=' END-DATE '=' END-TIME / '=' SEPARATE-DAILY-ENTRIES / '=' RETURN-STATUS(1:3) / ' Found Periods: Date From To Attendee' / ' ' FOUND-START-DATE(1) ' ' FOUND-START-TIME(1) ' ' FOUND-END-TIME (1) ' ' FOUND-ATTENDEES (1) / ' ' FOUND-START-DATE(2) ' ' FOUND-START-TIME(2) ' ' FOUND-END-TIME (2) ' ' FOUND-ATTENDEES (2) / ' ' FOUND-START-DATE(3) ' ' FOUND-START-TIME(3) ' ' FOUND-END-TIME (3) ' ' FOUND-ATTENDEES (3) / ' ' FOUND-START-DATE(4) ' ' FOUND-START-TIME(4) ' ' FOUND-END-TIME (4) ' ' FOUND-ATTENDEES (4) / ' ' FOUND-START-DATE(5) ' ' FOUND-START-TIME(5) ' ' FOUND-END-TIME (5) ' ' FOUND-ATTENDEES (5) / * IF RETURN-CODE NE 0 WRITE / 'Return code' RETURN-CODE ELSE WRITE / 'Return status OK' END-IF * END