LAPI_Init Subroutine

#include <lapi.h>
 
int LAPI_Init(hndl,lapi_info)
lapi_handle_t *hndl;
lapi_info_t *lapi_info;

include 'lapif.h'
 
LAPI_INIT(hndl,lapi_info,ierror)
INTEGER hndl
TYPE (LAPI_INFO_T) :: lapi_info
INTEGER ierror

The lapi_info_t structure is defined as follows:

typedef struct {                     
    lapi_dev_t     protocol;      /* Protocol device returned                    */
    lapi_lib_t     lib_vers;      /* LAPI library version -- user-supplied       */
    uint           epoch_num;     /* No longer used                              */
    int            num_compl_hndlr_thr; /* Number of completion handler threads  */
    uint           instance_no;   /* Instance of LAPI to initialize [1-16]       */ 
    int            info6;         /* Future support                              */
    LAPI_err_hndlr *err_hndlr;    /* User-registered error handler               */
    com_thread_info_t *lapi_thread_attr; /* Support thread att and init function */
    void           *adapter_name; /* What adapter to initialize, i.e. css0, ml0  */
    lapi_extend_t  *add_info;     /* Additional structure extension              */
} lapi_info_t;

The fields are used as follows:

protocol

LAPI sets this field to the protocol that has been initialized.

lib_vers

Is used to indicate a library version to LAPI for compatibility purposes. Valid values for this field are:

L1_LIB

Provides basic functionality (this is the default).

L2_LIB

Provides the ability to use counters as structures.

LAST_LIB

Provides the most current level of functionality. For new users of LAPI, lib_vers should be set to LAST_LIB.

This field must be set to L2_LIB or LAST_LIB to use LAPI_Nopoll_wait and LAPI_Setcntr_wstatus.

epoch_num

This field is no longer used.

num_compl_hndlr_thr

Indicates to LAPI the number of completion handler threads to initialize.

instance_no

Specifies the instance of LAPI to initialize (1 to 16).

info6

This field is for future use.

err_hndlr

Use this field to optionally pass a callback pointer to an error-handler routine.

lapi_thread_attr

Supports thread attributes and initialization function.

adapter_name

Is used in persistent subsystem (PSS) mode to pass an adapter name.

add_info

Is used for additional information in standalone UDP mode.

The following environment variable must be set before LAPI is initialized:

MP_MSG_API=[ lapi | [ lapi,mpi | mpi,lapi ] | mpi_lapi ]

The following environment variables are also commonly used:

MP_EUILIB=[ ip | us ] (ip is the default)

MP_PROCS=number_of_tasks_in_job

LAPI_USE_SHM=[ yes | no | only ] (no is the default)

To initialize LAPI, follow these steps:

1. Set environment variables (as described in RSCT for AIX 5L: LAPI Programming Guide) before the user application is invoked. The remaining steps are done in the user application.
2. Clear lapi_info_t, then set any fields.
3. Call LAPI_Init.

To initialize a LAPI handle:

{
    lapi_handle_t hndl;
    lapi_info_t info;
 
    bzero(&info, sizeof(lapi_info_t));  /* clear lapi_info */
 
    LAPI_Init(&hndl, &info);
}

To initialize a LAPI handle and register an error handler:

void my_err_hndlr(lapi_handle_t *hndl, int *error_code, lapi_err_t *err_type,
                  int *task_id, int *src )
{
   /* examine passed parameters and delete desired information */
   
   if ( user wants to terminate ) {
       LAPI_Term(*hndl);                /* will terminate LAPI */
       exit(some_return_code);  
   }
 
   /* any additional processing */
   
   return; /* signals to LAPI that error is non-fatal; execution should continue */
}
 
{
    lapi_handle_t hndl;
    lapi_info_t info;
 
 
    bzero(&info, sizeof(lapi_info_t));  /* clear lapi_info */
 
    /* set error handler pointer */
    info.err_hndlr = (LAPI_err_hndlr) my_err_hndlr;
 
    LAPI_Init(&hndl, &info);
}

To initialize a LAPI handle for UDP/IP communication using a user handler:

int my_udp_hndlr(lapi_handle_t *hndl, lapi_udp_t *local_addr, lapi_udp_t *addr_list, 
                 lapi_udpinfo_t *info)

{
    /* LAPI will allocate and free addr_list pointer when using */
    /* a user handler                                           */

    /* use the AIX(r) inet_addr call to convert an IP address      */
    /* from a dotted quad to a long                             */
    task_0_ip_as_long = inet_addr(task_0_ip_as_string);
    addr_list[0].ip_addr = task_0_ip_as_long;
    addr_list[0].port_no = task_0_port_as_unsigned;

    task_1_ip_as_long = inet_addr(task_1_ip_as_string);
    addr_list[1].ip_addr = task_1_ip_as_long;
    addr_list[1].port_no = task_1_port_as_unsigned;
    .	
    .
    .
    task_num_tasks-1_ip_as_long = inet_addr(task_num_tasks-1_ip_as_string);
    addr_list[num_tasks-1].ip_addr = task_num_tasks-1_ip_as_long;
    addr_list[num_tasks-1].port_no = task_num_tasks-1_port_as_unsigned;

}


{
    lapi_handle_t hndl;
    lapi_info_t info;
    lapi_extend_t extend_info;

    bzero(&info, sizeof(lapi_info_t));           /* clear lapi_info        */
    bzero(&extend_info, sizeof(lapi_extend_t));  /* clear lapi_extend_info */

    extend_info.udp_hndlr = (udp_init_hndlr *) my_udp_hndlr;
    info.add_info = &extend_info;
    
 
    LAPI_Init(&hndl, &info);
}

To initialize a LAPI handle for UDP/IP communication using a user list:

{
    lapi_handle_t hndl;
    lapi_info_t info;
    lapi_extend_t extend_info;
    lapi_udp_t *addr_list;

    bzero(&info, sizeof(lapi_info_t));           /* clear lapi_info        */
    bzero(&extend_info, sizeof(lapi_extend_t));  /* clear lapi_extend_info */

    /* when using a user list, the user is responsible for allocating          */
    /* and freeing the list pointer                                            */
    addr_list = malloc(num_tasks);
    
    /* Note, since we need to know the number of tasks before LAPI is          */
    /* initialized, we can't use LAPI_Qenv.  getenv("MP_PROCS") will           */
    /* do the trick.                                                           */


    /* populate addr_list                                                      */
    /* use the AIX(r) inet_addr call to convert an IP address                     */
    /* from a dotted quad to a long                                            */
    task_0_ip_as_long = inet_addr(task_0_ip_as_string);
    addr_list[0].ip_addr = task_0_ip_as_long;
    addr_list[0].port_no = task_0_port_as_unsigned;

    task_1_ip_as_long = inet_addr(task_1_ip_as_string);
    addr_list[1].ip_addr = task_1_ip_as_long;
    addr_list[1].port_no = task_1_port_as_unsigned;
    .
    .
    .
    task_num_tasks-1_ip_as_long = inet_addr(task_num_tasks-1_ip_as_string);
    addr_list[num_tasks-1].ip_addr = task_num_tasks-1_ip_as_long;
    addr_list[num_tasks-1].port_no = task_num_tasks-1_port_as_unsigned;


    /* then assign to extend pointer */
    extend_info.add_udp_addrs = addr_list;

    info.add_info = &extend_info;
    
 
    LAPI_Init(&hndl, &info);
    .
    .
    .

    /* user's responsibility only in the case of user list */
    free(addr_list);

}

To initialize a LAPI handle for user space (US) communication in standalone mode:

export MP_MSG_API=lapi
export MP_EUILIB=us
export MP_PROCS=                    /* number of tasks in job   */
export MP_PARTITION=                /* unique job key           */
export MP_CHILD=                    /* unique task ID           */
export MP_LAPI_NETWORK=@1:164,sn0   /* LAPI network information */

run LAPI jobs as normal  

See the README.LAPI.STANDALONE.US file in the standalone/us directory of the LAPI sample files for complete details.