16.1.1 Calendar Name List Acquisition API

This section explains the calendar name list acquisition API (Mp_ListCalendar).

Synopsis

int Mp_ListCalendar (char *APL_name,
              CAL_LIST *calendar_list) ;

Description

The Mp_ListCalendar function acquires a list of the calendar names registered on the server.

Parameters

APL_name

Specify the storage area address for the requested source application name (64 bytes or less).

Specify NULL at the end of the requested source application name. Do not use names that begin with "Mp_" or "_CAL_."

calendar_list

Specify the address for the calendar name acquisition information structure (CAL_LIST).

Return Values

Return Value	Meaning	Action
0	Normal termination.	-
-7	Calendar list area insufficient.	Review the size of the calendar list area using the procedure shown in "Remarks".
-10	Calendar service/daemon is not running.	Start the calendar service.
-11	There is not enough memory.	Use one of the following methods to increase the amount of available memory: Close other applications. Add more physical memory.

Remarks

You must first obtain the calendar name storage field structure as an array. Set the address and number of arrays (number of possible storage locations for calendar names) in the calendar name acquisition information structure, then call up this function.

If the number of calendars exceeds the number of locations where calendar names can be stored, since the actual number of calendars is set in cal_num in the calendar name acquisition information structure, the extra number of calendar name storage area structures are re-acquired. The calendar name storage area structure address (pcal_name) and the number of possible storage locations for calendar names (cal_area_num) are updated, and this function is called up again.

Format of Calendar Name Acquisition Information Structure (CAL_LIST)


typedef struct CAL_LIST_TAG {
   short      cal_area_num ;   // number of possible storage locations for calendar names
   short      cal_num ;        // actual number of calendars
   CAL_NAME_AREA *pcal_name ;  // calendar name storage area structure address
} CAL_LIST ;

cal_area_num

Specify the number of calendar name storage locations (specified by the number of calendars).

cal_num

The actual number of calendars (also set when insufficient) stored on the server is set.

pcal_name

Specify the address of calendar name storage area structure (CAL_NAME_AREA).

Format of Calendar Name Storage Area Structure (CAL_NAME_AREA)

typedef struct CAL_NAME_AREA_TAG {
      char   cal_name[25] ;            // calendar name storage area
} CAL_NAME_AREA ;

cal_name

The calendar name is set.

Program Example

Below is an example program of the calendar name list acquisition API:

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>
#include <string.h>

#include <f3crhcap.h>

#define CAL_NUM 20

extern void put_calendar_list( CAL_LIST * ) ;

void main() {

          int ret ;
          CAL_LIST calendar_list ;

         /* initialization */
         memset( &calendar_list, 0x00, sizeof( CAL_LIST) ) ;

         /* calendar name area acquisition */
        calendar_list.pcal_name = (CAL_NAME_AREA *) malloc (sizeof (CAL_NAME_AREA) *CAL_NUM);
         if ( calendar_list.pcal_name == NULL ) {
                    printf( "Lack of memory !!\n") ;
                    exit ( 1 ) ;

         }
         /* calendar name area setting */
         calendar_list.cal_area_num = CAL_NUM ;

         /* calendar list acquisition */
       ret = Mp_ListCalendar( "Test Pro", &calendar_list) ;

       printf( "ret= %d  calendar num = %d\n", ret, calendar_list.cal_num ) ;

         /* calendar list post-acquisition processing */
       if ( ret == 0 )
               put_calendar_list( &calendar_list ) ;

         /* calendar name area return */
         free( calendar_list.pcal_name ) ;

     exit ( 0 ) ;
}