LAPI_Qenv Subroutine

#include <lapif.h>
 
int LAPI_Qenv(hndl, query, ret_val)
lapi_handle_t  hndl;
lapi_query_t   query;
int           *ret_val; /* ret_val's type varies (see Additional query types) */

include 'lapif.h'
 
LAPI_QENV(hndl, query, ret_val, ierror)
INTEGER hndl
INTEGER query
INTEGER ret_val /* ret_val's type varies (see Additional query types) */
INTEGER ierror

For example, you can query the size of the table that LAPI uses for the LAPI_Addr_set subroutine using a query value of LOC_ADDRTBL_SZ:

LAPI_Qenv(hndl, LOC_ADDRTBL_SZ, &ret_val);

ret_val will contain the upper bound on the table index. A subsequent call to LAPI_Addr_set (hndl, addr, addr_hndl); could then ensure that the value of addr_hndl is between 0 and ret_val.

When used to show the size of a parameter, a comparison of values, or a range of values, valid values for the query parameter of the LAPI_Qenv subroutine appear in SMALL, BOLD capital letters. For example:

 
NUM_TASKS
 

is a shorthand notation for:

 
LAPI_Qenv(hndl, NUM_TASKS, ret_val)
 

In C, lapi_query_t defines the valid types of LAPI queries:

typedef enum {
        TASK_ID=0,      /* Query the task ID of the current task in the job        */
        NUM_TASKS,      /* Query the number of tasks in the job                    */
        MAX_UHDR_SZ,    /* Query the maximum user header size for active messaging */
        MAX_DATA_SZ,    /* Query the maximum data length that can be sent          */
        ERROR_CHK,      /* Query and set parameter checking on (1) or off (0)      */
        TIMEOUT,        /* Query and set the current communication timeout setting */ 
                        /* in seconds                                              */
        MIN_TIMEOUT, /* Query the minimum communication timeout setting in seconds */ 
        MAX_TIMEOUT, /* Query the maximum communication timeout setting in seconds */ 
        INTERRUPT_SET,  /* Query and set interrupt mode on (1) or off (0)          */
        MAX_PORTS,    /* Query the maximum number of available communication ports */
        MAX_PKT_SZ,     /* This is the payload size of 1 packet                    */
        NUM_REX_BUFS,   /* Number of retransmission buffers                        */
        REX_BUF_SZ,     /* Size of each retransmission buffer in bytes             */
        LOC_ADDRTBL_SZ, /* Size of address store table used by LAPI_Addr_set       */
        EPOCH_NUM,      /* No longer used by LAPI (supports legacy code)           */
        USE_THRESH,     /* No longer used by LAPI (supports legacy code)           */
        RCV_FIFO_SIZE,  /* No longer used by LAPI (supports legacy code)           */
        MAX_ATOM_SIZE,/* Query the maximum atom size for a DGSP accumulate transfer*/
        BUF_CP_SIZE, /* Query the size of the message buffer to save (default 128b)*/
        MAX_PKTS_OUT,   /* Query the maximum number of messages outstanding /      */ 
                        /* destination                                             */
        ACK_THRESHOLD,  /* Query and set the threshold of acknowledgments going    */ 
                        /* back to the source                                      */
        QUERY_SHM_ENABLED,    /* Query to see if shared memory is enabled          */
        QUERY_SHM_NUM_TASKS,  /* Query to get the number of tasks that use shared  */ 
                              /* memory                                            */
        QUERY_SHM_TASKS,  /* Query to get the list of task IDs that make up shared */
                          /* memory; pass in an array of size QUERY_SHM_NUM_TASKS  */
        QUERY_STATISTICS,    /* Query to get packet statistics from LAPI, as       */
                             /* defined by the lapi_statistics_t structure. For    */
                             /* this query, pass in 'lapi_statistics_t *' rather   */
                             /* than 'int *ret_val'; otherwise, the data will      */
                             /* overflow the buffer.                               */
        PRINT_STATISTICS,    /* Query debug print function to print out statistics */
        QUERY_SHM_STATISTICS,/* Similar query as QUERY_STATISTICS for shared       */
                             /* memory path.                                       */
        QUERY_LOCAL_SEND_STATISTICS ,/* Similar query as QUERY_STATISTICS          */
                                     /* for local copy path.                       */
        BULK_XFER, /* Query to see if bulk transfer is enabled (1) or disabled (0) */
        BULK_MIN_MSG_SIZE, /* Query the current bulk transfer minimum message size */  
        LAST_QUERY
} lapi_query_t;


typedef struct {
      	lapi_long_t Tot_dup_pkt_cnt;     /* Total duplicate packet count  */
      	lapi_long_t Tot_retrans_pkt_cnt; /* Total retransmit packet count */
      	lapi_long_t Tot_gho_pkt_cnt;     /* Total Ghost packet count      */
      	lapi_long_t Tot_pkt_sent_cnt;    /* Total packet sent count       */
      	lapi_long_t Tot_pkt_recv_cnt;    /* Total packet receive count    */
      	lapi_long_t Tot_data_sent;       /* Total data sent               */
      	lapi_long_t Tot_data_recv;       /* Total data receive            */
      } lapi_statistics_t;

In FORTRAN, the valid types of LAPI queries are defined in lapif.h as follows:

      integer TASK_ID,NUM_TASKS,MAX_UHDR_SZ,MAX_DATA_SZ,ERROR_CHK
      integer TIMEOUT,MIN_TIMEOUT,MAX_TIMEOUT
      integer INTERRUPT_SET,MAX_PORTS,MAX_PKT_SZ,NUM_REX_BUFS
      integer REX_BUF_SZ,LOC_ADDRTBL_SZ,EPOCH_NUM,USE_THRESH
      integer RCV_FIFO_SIZE,MAX_ATOM_SIZE,BUF_CP_SIZE
      integer MAX_PKTS_OUT,ACK_THRESHOLD,QUERY_SHM_ENABLED
      integer QUERY_SHM_NUM_TASKS,QUERY_SHM_TASKS
      integer QUERY_STATISTICS,PRINT_STATISTICS
      integer QUERY_SHM_STATISTICS,QUERY_LOCAL_SEND_STATISTICS
      integer BULK_XFER,BULK_MIN_MSG_SIZE,
      integer LAST_QUERY
      parameter (TASK_ID=0,NUM_TASKS=1,MAX_UHDR_SZ=2,MAX_DATA_SZ=3)
      parameter (ERROR_CHK=4,TIMEOUT=5,MIN_TIMEOUT=6)
      parameter (MAX_TIMEOUT=7,INTERRUPT_SET=8,MAX_PORTS=9)
      parameter (MAX_PKT_SZ=10,NUM_REX_BUFS=11,REX_BUF_SZ=12)
      parameter (LOC_ADDRTBL_SZ=13,EPOCH_NUM=14,USE_THRESH=15)
      parameter (RCV_FIFO_SIZE=16,MAX_ATOM_SIZE=17,BUF_CP_SIZE=18)
      parameter (MAX_PKTS_OUT=19,ACK_THRESHOLD=20)
      parameter (QUERY_SHM_ENABLED=21,QUERY_SHM_NUM_TASKS=22)
      parameter (QUERY_SHM_TASKS=23,QUERY_STATISTICS=24)
      parameter (PRINT_STATISTICS=25)
      parameter (QUERY_SHM_STATISTICS=26,QUERY_LOCAL_SEND_STATISTICS=27)
      parameter (BULK_XFER=28,BULK_MIN_MSG_SIZE=29)
      parameter (LAST_QUERY=30)

LAPI provides additional query types for which the behavior of LAPI_Qenv is slightly different:

PRINT_STATISTICS

When passed this query type, LAPI sends data transfer statistics to standard output. In this case, ret_val is unaffected. However, LAPI's error checking requires that the value of ret_val is not NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) for all LAPI_Qenv types (including PRINT_STATISTICS).

QUERY_LOCAL_SEND_STATISTICS

When passed this query type, LAPI_Qenv interprets ret_val as a pointer to type lapi_statistics_t. Upon function return, the fields of the structure contain LAPI's data transfer statistics for data transferred through intra-task local copy. The packet count will be 0.

QUERY_SHM_STATISTICS

When passed this query type, LAPI_Qenv interprets ret_val as a pointer to type lapi_statistics_t. Upon function return, the fields of the structure contain LAPI's data transfer statistics for data transferred through shared memory.

QUERY_SHM_TASKS

When passed this query type, LAPI_Qenv returns a list of task IDs with which this task can communicate using shared memory. ret_val must be an int * with enough space to hold NUM_TASKS integers. For each task i, if it is possible to use shared memory, ret_val[i] will contain the shared memory task ID. If it is not possible to use shared memory, ret_val[i] will contain -1.

QUERY_STATISTICS

When passed this query type, LAPI_Qenv interprets ret_val as a pointer to type lapi_statistics_t. Upon function return, the fields of the structure contain LAPI's data transfer statistics for data transferred using the user space (US) protocol or UDP/IP.

To query runtime values from LAPI:

{
    int               task_id;
    lapi_statistics_t stats;
    .    
    .
    .
    LAPI_Qenv(hndl, TASK_ID, &task_id);
    /* task_id now contains the task ID */ 	
    .
    .
    .    
    LAPI_Qenv(hndl, QUERY_STATISTICS, (int *)&stats);
    /* the fields of the stats structure are now 
       filled in with runtime values */ 	
    .    
    .
    .
}