IBM Books

Command and Technical Reference, Volume 2


SP subroutines

getvhostname subroutine

Purpose

getvhostname - Gets the virtual host name of the local host.

Library

Availability Library (libavail.a)

Syntax

 #include <vhost.h>
int getvhostname (name, name_length);
char *name;
int name_length;

Parameters

name
Specifies the address of an array of bytes where the virtual host name is to be stored.

name_length
Specifies the length of the name array.

Description

Use this subroutine to retrieve the virtual host name of a host machine. This routine is similar to the gethostname system call with the exception that it retrieves the virtual host name from the /etc/vhostname file instead of using a kernel variable. The getvhostname subroutine is a library call and gethostname is a system call.

The name is retrieved from the /etc/vhostname file. If the file does not exist, the gethostname system call is used and the real host name is returned. If excess space is provided, the returned name parameter is null terminated. If insufficient space is provided, the returned name parameter is truncated to fit in the given space. Virtual host names are limited to MAX_VHOSTNAME_LEN bytes (255), not including the terminating null character. The MAX_VHOSTNAME_LEN macro is defined in the vhost.h header file. To guarantee sufficient buffer space to hold the virtual host name, the name_length parameter should be MAX_VHOSTNAME_LEN + 1 or 256.

To clear the virtual host name so that the virtual host name no longer exists, remove the /etc/vhostname file.

Note:
You must have root authority to remove the /etc/vhostname file.

The virtual host name is used in fail over situations when an application has associated the host name in the kernel of a particular machine to the service it is providing. When the application is restarted on the fail over node that has a different host name, the application may not work or work incorrectly. If the application needs to associate a host name with a particular service and it cannot handle having multiple host names, a virtual host name can be provided. The application can call getvhostname instead of gethostname and get the host name of the node it normally runs on. This eliminates the need to change the real host name in the kernel on the backup node. It should be noted that changing the real host name in the kernel can cause problems with other applications that rely on the real host name to identify the physical machine.

Note:
The High Availability Cluster Multiprocessing (HACMP) event scripts supplied with the High Availability Control Workstation (HACWS) option of the IBM Parallel System Support Programs for AIX (PSSP), set and clear the virtual host name in the supplied HACMP pre- and post-event scripts. The administrator should not normally have to set the virtual host name.

Return Values

Upon successful completion, the getvhostname subroutine returns a value of 0. Otherwise, a value of -1 is returned, the global variable errno is set to identify the error, and the contents of the buffer pointed to by the name parameter are indeterminate.

The getvhostname subroutine is unsuccessful if the following error occurs:

EFAULT
Indicates that either the name or name_length parameter gave an address that is not valid.

EINVAL
Indicates that the name_length parameter is less than 0.

If one of the system calls used to retrieve the virtual host name from the /etc/vhostname file encounters and error(for example, open or read), errno is set by the system call that encountered an error.

Related Information

PSSP commands: vhostname

PSSP subroutines: setvhostname

AIX commands: hostname

AIX subroutines: gethostname, sethostname

Header files: vhost.h

Examples

  1. To clear the virtual host name so that it no longer exists, enter:
    rm /etc/vhostname
    
    Note:
    You must have root authority to remove the /etc/vhostname file.
  2. To get the virtual host name from the /etc/vhostname file, enter:
    #include <vhost.h>
    main ( )
    {
    char name [MAX_VHOSTNAME_LEN + 1];
    getvhostname (name, (MAX_VHOSTNAME_LEN + 1));
    }
    

hacws_set subroutine

Purpose

hacws_set - Sets the HACWS state of the control workstation.

Library

Availability Library (libavail.a)

Location

/usr/lib/libavail.a

Syntax

 #include <hacws.h>
int hacws_set (state);
int state;

Parameters

state
Specifies the state of the control workstation. Valid values are: 0, 1, 2, 16, 32.

Description

Use this subroutine to set the current HACWS state of the control workstation. It is valid only when issued on the control workstation. When the subroutine is called and the calling process is not on a control workstation, an error occurs.

Note:
The High Availability Cluster Multiprocessing (HACMP) event scripts and installation scripts supplied with the High Availability Control Workstation (HACWS) option of the IBM Parallel System Support Programs for AIX (PSSP), set the control workstation state. The state is changed during fail over or reintegration in the HACWS supplied pre- and post-event scripts for HACMP. The administrator should not normally have to set the control workstation state.

Return Values

Upon successful completion, the hacws_set subroutine returns a value of 0. Otherwise, a value of -1 is returned and the global variable errno is set to identify the error.

The hacws_set subroutine is unsuccessful if any of the following errors occur:

EINVAL
Indicates that the value of the state parameter is not one of the valid values contained in hacws.h.

ENODEV
Indicates that the calling process is not on a control workstation.

ENOENT
Indicates that the hacws_set subroutine could not determine whether the calling process is on a control workstation.

EPERM
Indicates that the calling process did not have root's effective user ID.

If one of the system calls used to store the HACWS state value into the /etc/hacws.state file encounters an error (for example, open, write, rename), errno is set by the system call that encountered the error.

Macros

The /usr/include/hacws.h header file defines the following macros as valid input values for the hacws_set subroutine:

0  or  HACWS_NOT_AN_HACWS
Indicates that this control workstation is not in an HACWS configuration.

1  or  HACWS_PRIM_INACT_CWS
Indicates that this control workstation is the primary control workstation, but not the currently active control workstation.

2  or  HACWS_PRIM_ACT_CWS
Indicates that this control workstation is the primary control workstation and is the currently active control workstation.

16  or  HACWS_BACK_INACT_CWS
Indicates that this control workstation is the backup control workstation, but not the currently active control workstation.

32  or  HACWS_BACK_ACT_CWS
Indicates that this control workstation is the backup control workstation and is the currently active control workstation.

Prerequisite Information

Refer to PSSP: Administration Guide for information on the HACWS option.

Related Information

Commands: lshacws, sethacws

Subroutines: hacws_stat

Header files: hacws.h

hacws_stat subroutine

Purpose

hacws_stat - Gets the state of the control workstation.

Library

Availability Library (libavail.a)

Location

/usr/lib/libavail.a

Syntax

 #include <hacws.h>
int hacws_stat (void);

Description

Use this subroutine to return the current state of the control workstation. It returns an integer that indicates the state of the primary or backup control workstation and specifies whether the control workstation is a high availability configuration. This subroutine is valid only when issued on the control workstation. When the subroutine is called and the calling process is not on a control workstation, an error occurs.

Note:
The High Availability Cluster Multiprocessing (HACMP) event scripts and installation scripts supplied with the High Availability Control Workstation (HACWS) option of the IBM Parallel System Support Programs for AIX (PSSP), set the control workstation state. The state is changed during fail over or reintegration in the HACWS supplied pre- and post-event scripts for HACMP. The administrator should not normally have to set the control workstation state.

Return Values

Upon successful completion, the hacws_stat subroutine returns a nonnegative value. If the hacws_stat subroutine is unsuccessful, a value of -1 is returned and the global variable errno is set to identify the error.

The hacws_stat subroutine is unsuccessful if any of the following errors occur:

ENODEV
Indicates that the calling process is not on a control workstation.

ENOENT
Indicates that the hacws_stat subroutine could not determine whether the calling process is on a control workstation.

ERANGE
Indicates that the /etc/hacws.state file does not contain a valid HACWS state.

If one of the system calls used to retrieve the HACWS state value from the /etc/hacws.state file encounters an error (for example, open or read), errno is set by the system call that encountered an error.

Macros

The /usr/include/hacws.h header file defines the following macros for the nonnegative return values for the hacws_stat subroutine:

0  or  HACWS_NOT_AN_HACWS
Indicates that this control workstation is not in an HACWS configuration.

1  or  HACWS_PRIM_INACT_CWS
Indicates that this control workstation is the primary control workstation, but not the currently active control workstation.

2  or  HACWS_PRIM_ACT_CWS
Indicates that this control workstation is the primary control workstation and is the currently active control workstation.

16  or  HACWS_BACK_INACT_CWS
Indicates that this control workstation is the backup control workstation, but not the currently active control workstation.

32  or  HACWS_BACK_ACT_CWS
Indicates that this control workstation is the backup control workstation and is the currently active control workstation.

Prerequisite Information

Refer to PSSP: Administration Guide for information on the HACWS option.

Related Information

Commands: lshacws, sethacws

Subroutines: hacws_set

Header files: hacws.h

LAPI_Addr_get subroutine

Purpose

LAPI_Addr_get - Enquires a LAPI instance regarding the address of a user function.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Addr_get (hndl, addr, addr_hndl)
lapi_handle_t hndl;
void **addr;
int *addr_hndl;
 

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_ADDR_GET (hndl, addr, addr_hndl, ierror)
|INTEGER hndl
|INTEGER (KIND=LAPI_ADDR_TYPE) :: addr
|INTEGER addr_hndl(*), ierror
| 

Parameters

hndl
IN Specifies the LAPI context.

addr
OUT Returns a function address the user registered with LAPI.

addr_hndl
IN A user function address used in LAPI messages for the header handler. This parameter has to be in the range [0..MAX_FTBL_SZ-1].

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

This function is used to obtain the pointer previously registered with LAPI associated with the handle addr_hndl. The value of addr_hndl has to lie in the range [0..MAX_FTBL_SZ-1]. The value of MAX_FTBL_SZ can be obtained from LAPI_Qenv using LOC_ADDRTBL_SZ as the query value.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid. This can mean that either the addr_hndl parameter being passed is not in the range of [0..MAX_FTBL_SZ-1], or that a LAPI hndl which is not valid is being used.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Addr_set, LAPI_Qenv

LAPI_Addr_set subroutine

Purpose

LAPI_Addr_set - Maps indices to addresses of functions in the user's address space.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Addr_set (hndl, addr, addr_hndl)
lapi_handle_t hndl;
void *addr;
int addr_hndl;
 
 

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_ADDR_SET (hndl, addr, addr_hndl, ierror)
|INTEGER hndl
|INTEGER (KIND=LAPI_ADDR_TYPE) :: addr
|INTEGER addr_hndl, ierror
| 

Parameters

hndl
IN Specifies the LAPI context.

addr
IN Specifies an address of the function handler, that the user wants to register with LAPI.

addr_hndl
IN A user function address used in LAPI messages for the header handler. This parameter has to be in the range [0..MAX_FTBL_SZ-1].

Description

This function is used to obtain the pointer previously registered user function with LAPI associated with the handle addr_hndl. The value of addr_hndl has to lie in the range [0..MAX_FTBL_SZ-1]. The value of MAX_FTBL_SZ can be obtained from LAPI_Qenv using LOC_ADDRTBL_SZ as the query value.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid. This can mean that either the addr_hndl parameter being passed is not in the range of [0..MAX_FTBL_SZ-1], or that a LAPI hndl which is not valid is being used.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Addr_get, LAPI_Qenv

LAPI_Address subroutine

Purpose

LAPI_Address - Gets an unsigned integer value for a specified user address.

Library

Availability Library (liblapi_r.a)

C Syntax

| #include <lapi.h>
| 
|int LAPI_Address(my_addr, ret_addr)
|void *my_addr;
|ulong *ret_addr;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_ADDRESS(my_addr, ret_addr, ierror)
|INTEGER (KIND=LAPI_ADDR_TYPE) my_addr
|INTEGER ret_addr
|INTEGER ierror

Parameters

my_addr
IN Specifies the address to save. This parameter cannot be NULL.

ret_addr
OUT Stores the my_addr address for later use. This is especially useful in FORTRAN programs. This parameter cannot be NULL.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine in FORTRAN programs when specified addresses need to be stored in an array. In FORTRAN, the concept of address ('&') does not exist as it does in C. This function provides that ability to FORTRAN programmers.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

LAPI_Address_init subroutine

Purpose

LAPI_Address_init - Exchanges virtual addresses to be used for target addresses in message passing calls for non-SPMD programs and dynamically allocated data.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Address_init(hndl, my_addr, add_tab)
lapi_handle_t hndl;
void *my_addr;
void *add_tab[];

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_ADDRESS_INIT(hndl, my_addr, add_tab, ierror)
|INTEGER hndl
|INTEGER (KIND=LAPI_ADDR_TYPE) my_addr
|INTEGER (KIND=LAPI_ADDR_TYPE) :: add_tab(*)
|INTEGER ierror

Parameters

hndl
IN The handle specifying the LAPI context.

my_addr
IN The entry supplied by each process/(task). This parameter can be NULL.

add_tab
IN/OUT The address table containing the addresses supplied by all process/(tasks). This parameter cannot be NULL.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

This function is used to exchange virtual addresses among tasks of a parallel application. add_tab is an array of pointers of size greater than or equal to LAPI_Qenv (NUM_TASKS). This function is a collective call over the LAPI context hndl which fills the table add_tab with the virtual address entries supplied by each task. Upon completion of this call, add_tab[i] will contain the virtual address entry provided by task i.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

LAPI_Amsend subroutine

Purpose

LAPI_Amsend - Invokes a user-provided Active Message (AM) handler to run on a remote (target) process along with transferring a user message.

Library

Availability Library (liblapi_r.a)

C Syntax

| #include <lapi.h>
| 
|typedef void (compl_hndlr_t)(hndl, user_info);
|lapi_handle_t   *hndl;       /* pointer to LAPI context passed in from
|                                LAPI_Amsend. */
|void            *user_info;  /* Buffer (user_info) pointer passed in from
|                                header handler (void * (hnd_hndlr_t)). */
| 
|typedef void    *(hdr_hndlr_t)(hndl, uhdr, uhdr_len,
|msg_len, comp_h, user_info);
| 
|lapi_handle_t   *hndl;       /* pointer to LAPI context passedin from
|                                LAPI_Amsend. */
|void             *uhdr;      /* uhdr passed in from LPI_Amsend. */
|uint             *uhdr_len;  /* uhdr_len passed in from LPI_Amsend. */
|ulong            *msg_len;   /* udata_len passed in fom LAPI_Amsend. */
|compl_hndlr_t   **comp_h;    /* Function address of completion handler
|                                (void (compl_hndlr_t)) that nee to be filled
|                                out by this header handler function. */
|void          **user_info;   /* Buffer pointer (user_info that is
|                                provided by this header handler function
|                                to pass to the completion handler. */
| 
|int LAPI_Amsend(hndl, tgt, hdr_hdl, uhdr, uhdr_len, udata, udata_len,
|tgt_cntr, org_cntr, cmpl_cntr)
| 
|lapi_handle_t  hndl;
|uint           *tgt;
|void           *hdr_hdl;
|void           *uhdr;
|uint           *uhdr_len;
|void           *udata;
|ulong          *udata_len;
|lapi_cntr_t    *tgt_cntr;
|lapi_cntr_t    *org_cntr;
|lapi_cntr_t    *cmpl_cntr;

FORTRAN Syntax

| include 'lapif.h'
| 
|INTEGER FUNCTION COMPL_H(hndl, user_info)
|INTEGER hndl
|INTEGER user_info
| 
|INTEGER FUNCTION HDR_HDL(hndl, uhdr, uhdr_len, msg_len, comp_h, user_info)
|INTEGER hndl
|INTEGER uhdr
|INTEGER uhdr_len
|INTEGER (KIND=LAPI_INT_TYPE) msg_len
|INTEGER comp_h
|INTEGER user_info
| 
|LAPI_AMSEND(hndl, tgt, hdr_hdl, uhdr, uhdr_len, udata, udata_len,
|tgt_cntr, org_cntr, cmpl_cntr, ierror)
|INTEGER hndl
|INTEGER tgt
|EXTERNAL INTEGER FUNCTION hdr_hdl
|INTEGER uhdr
|INTEGER uhdr_len
|INTEGER udata
|INTEGER (KIND=LAPI_INT_TYPE) udata_len
|TYPE (LAPI_CNTR_T) :: tgt_cntr, org_cntr, cmpl_cntr
|INTEGER ierror

Parameters

hndl
IN A handle that specifies a particular Low-Level Application Programming Interface (LAPI) context.

tgt
IN Specifies the target task number. This parameter is valid from 0 <= tgt < LAPI_Qenv(,NUM_TASKS,).

hdr_hdl
IN Specifies the pointer to the remote header handler function to be invoked at the target. This parameter cannot be NULL.

uhdr
IN Specifies the pointer to the local header (parameter list) that is passed to the handler function when invoked at the target side. This parameter can be NULL if uhdr_len is equivalent to 0.

uhdr_len
IN This parameter is valid from 0 <= uhdr_len <= LAPI_Qenv(,MAX_UHDR_SZ,).

udata
IN Specifies the pointer to the user data. This parameter can be NULL if udata_len is equivalent to 0.

udata_len
IN Specifies the length of the user data in bytes. This parameter is valid from 0 <= udata_len <= LAPI_Qenv(,MAX_DATA_SZ,).

tgt_cntr
IN Specifies the target counter address. The target counter is incremented after data arrives at the target and after the completion handler completes. If the parameter is NULL, this counter will not be updated.

org_cntr
IN/OUT Specifies the origin counter address. The origin counter is incremented after data is copied out of the origin address. If the parameter is NULL, this counter will not be updated.

cmpl_cntr
IN/OUT Specifies the counter at the origin that signifies completion of the completion handler. It is updated once the completion handler completes. If the parameter is NULL, the counter will not be updated.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to transfer the hdr_hdl function pointer along with the contents of uhdr and udata from the origin to the tgt target process. When the message arrives at the target process, the hdr_hdl header handler is invoked at the tgt task with the pointer to uhdr as one of the parameters.

The user-supplied header handler is expected to return a buffer pointer as the return value in which udata is to be copied. The header handler is also expected to save any information that will be required later by the completion handler. The header handler returns (through reference parameters) the completion handler and a pointer to the saved information (user_info).

Note:
The header handler should be nonblocking because no progress on the messages associated with hndl can be made until control is returned to the communications library from the header handler.

After the header handler returns, the udata (if any) is copied into the user-specified buffer. When all of the udata is copied into the user buffer, the completion handler specified through the header handler is enqueued for execution.

After the parameters (including the contents of uhdr and udata) are copied out of the memory at the origin, the org_cntr is incremented. After the completion handler finishes running at the tgt, the tgt_cntr is incremented. If the completion handler specified is NULL, the tgt_cntr is incremented after all of the udata is copied into the user-specified buffers. If the user-specified buffer is NULL and the completion handler is also NULL, the tgt_cntr will be incremented in some implementation-specific manner. Either counter addresses may be NULL.

This is a nonblocking call. The calling process cannot change the uhdr (origin header) and udata data until completion at the origin is signaled by the org_cntr being incremented. Similarly, it can be assumed that the specified AM completion handler has run at the tgt only after the tgt_cntr target counter is incremented. The cmpl_cntr and tgt_cntr counters are incremented after the AM completion handler has completed execution at the target. When the AM handler has both a hdr_hdl header handler and a comp_h completion handler, the cmpl_cntr and tgt_cntr counters are incremented after the completion handler has completed execution. If the AM handler has only a hdr_hdl header handler, the cmpl_cntr and tgt_cntr counters will be incremented after the entire message has reached the target buffer specified by the header handler. This call can be made synchronous if the origin waits for the cmpl_cntr update to complete.

The length (uhdr_len) of the user-specified header is constrained by an implementation specified maximum value (LAPI_Qenv(,MAX_UHDR_SZ,)). In the current implementation, the amount of udata sent per packet is LAPI_Qenv(,MAX_UHDR_SZ,) - uhdr_len. To get the best bandwidth, uhdr_len should be as small as possible.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask() being called.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Fence, LAPI_Getcntr, LAPI_Nopoll_wait, LAPI_Qenv, LAPI_Waitcntr

LAPI_Amsendv subroutine

Purpose

LAPI_Amsendv - Invokes a user provided Active Message (AM) handler to run on a remote (target) process while transferring vectors of data.

C Syntax

| #include <lapi.h>
| 
|typedef void  (compl_hndlr_t)(hndl, user_info);
|lapi_handle_t  *hndl;        /* LAPI context passed in from LAPI_Amsendv. */
|void           *user_info;   /* Buffer (user_info) pointer passed in from
|                                header_handler (void *(vhdr_hndlr_t)). */
| 
|typedef lapi_vec_t *(vhdr_hndlr_t)(hndl, uhdr, uhdr_len, len_vec, comp_h, uinfo);
| 
|lapi_handle_t  *hndl;        /* pointer to LAPI context passed in from
|                                LAPI_Amsendv.*/
|void           *uhdr;        /* uhdr passed in from LAPI_Amsendv. */
|uint           uhdr_len;     /* uhdr_len passed in from LAPI_Amsendv. */
|ulong          *len_vec [ ]; /* vector of lengths passed in LAPI_Amsendv.  */
|compl_hndlr_t **comp_h;      /* Function address of completion handler
|                                (void (compl_hndlr_t)) that needs to be filled
|                                out by this header handler funtion. */
|void           **user_info;  /* Buffer pointer (user_info) that is provided
|                                by this header handler function to pass to the
|                                completion handler.*/
| 
|int LAPI_Amsendv(hndl, tgt, hdr_hdl, uhdr, uhdr_len, org_vec, tcntr, ocntr, ccntr);
| 
|lapi_handle_t   *hndl;
|uint            tgt;
|void            *hdr_hdl;
|void            *uhdr;
|uint            uhdr_len;
|lapi_vec_t      *org _vec;
|lapi_cntr_t     *tcntr;
|lapi_cntr_t     *ocntr;
|lapi_cntr_t     *ccntr; 

FORTRAN Syntax

|include 'lapif.h'
| 
|INTEGER FUNCTION COMPL_H(hndl, user_info)
|INTEGER hndl
|INTEGER user_info(*)
|INTEGER FUNCTION VHDR_HDL(hndl, uhdr, uhdr_len, len_vec, comp_h, user_info)
|INTEGER hndl
|INTEGER uhdr
|INTEGER uhdr_len
|INTEGER (KIND=LAPI_INT_TYPE) len_vec
|INTEGER comp_h
|INTEGER user_info
|LAPI_AMSENDV(hndl, tgt, hdr_hdl, uhdr, uhdr_len, org_vec, tcntr, ocntr, ccntr, ierror)
|INTEGER hndl
|INTEGER tgt
|EXTERNAL INTEGER FUNCTION hdr_hdl
|INTEGER uhdr
|INTEGER uhdr_len
|TYPE (LAPI_VEC_T) :: org_vec
|TYPE (LAPI_CNTR_T) :: tcntr, ocntr, ccntr
|INTEGER ierror
| 

Parameters

hndl
IN Specifies the LAPI context.

tgt
IN Specifies the target task number. This parameter is valid from 0 < tgt < LAPI Qenv(,NUM TASKS,).

hdr_hdl
IN Points to the remote header handler function to be invoked at the target. This parameter cannot be NULL.

uhdr
IN Points to the local header (parameter list) which is passed to the handler function. This parameter can be NULL if uhdr_len = 0.

uhdr_len
IN This parameter is valid from 0 < uhdr_len < LAPI_Qenv(,MAX_UHDR_SZ,).

org_vec
IN Points to the origin i/o vector.

tcntr
IN Specifies the address of the target counter.

ocntr
IN/OUT Specifies the address of the origin counter.

ccntr
IN/OUT Specifies the address of the completion counter.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

This function transfers hdr_hdl function pointer along with the contents of uhdr and data described in org_vec from the origin to the target process tgt. When the message arrives at the target process, the header-handler hdr_hdl is invoked at the tgt with the pointer to uhdr as one of the parameters.

The user-supplied header-handler must return a pointer to a structure of type lapi_vec_t specifying the fields depending on the vec_type . For example, if the vec_type specified is LAPI_GEN_IOVECTOR, then it must contain:

  1. the number of vectors (num_vec)
  2. a vector of the length num_vec containing buffer pointers
  3. num_vec vector of lengths as the return value.

This description provides the information of where the message data is to be copied by LAPI. The header-handler is also expected to save any information that will be required later by the completion-handler. The header-handler returns (through reference parameters) a pointer to the completion-handler and a pointer to a structure to be passed to the completion-handler (referred to by the variable user_info).

Note:
The header-handler should be non-blocking because no progress on the messages associated with the context hndl can be made until control is returned to the communications library from the header-handler.

After the header-handler returns, data described by org_vec (if any) is copied into the user-returned buffers in the structure returned by the header handler. When all of the data described by org_vec has been copied into the user buffers, the completion-handler specified by the user through the header-handler is enqueued for execution.

After the parameters (including contents of uhdr and data described by org_vec) are copied out of the memory at the origin, the ocntr is incremented. After the completion-handler has completed execution at the tgt, the tcntr is incremented. If the completion handler specified is a NULL, then tcntr is incremented after all data described by org_vec has been copied into the user specified buffers. If the user returned buffer is NULL and the completion handler is also NULL, the results of the data transfer are undefined and the counters will be incremented in some implementation specific manner. Any of the counter addresses may be NULL.

This is a non-blocking call. The calling process cannot change the uhdr (origin header) and org_vec data until completion at the origin is signaled by the ocntr being incremented. Further, the calling process cannot assume that the org_vec structure can be changed before the origin counter is incremented. Also, the structure (of type lapi_vec_t ) returned by the header-handler cannot be modified before the target and completion counters have been incremented. Similarly, it can be assumed that the specified completion handler has run at tgt only after the target counter tcntr has been incremented. When the hdr_hdl header handler specifies a comp_h completion handler, the ccntr at the origin and tcntr counter at the target will be incremented after the completion handler has completed execution.

The length (uhdr_len) of the user specified header is constrained by an implementation specified maximum value (LAPI_Qenv(,MAX_UHDR_SZ,)). To get the best bandwidth uhdr_len should be as small as possible.

If a strided vector is being transferred, the size of each block must not be greater than the stride size in bytes. The number of vectors to be transferred must be greater than zero. The vector lengths specified in org_vec-> len, or org_vec->info in the strided transfer case, must be multiples of the machine word size in bytes. If any of these requirements are not satisfied, an error condition occurs.

LAPI does not check for any overlapping regions among vectors either at the origin or the target. If such overlapping regions exist on the origin side, there may be a degradation in performance. If the overlapping regions exist on the target side, the contents of target buffer are undefined.

|Starting with PSSP 3.4, a generic version of the |LAPI_Amsendv function is available. The number of vectors and |the length of vectors on the origin and target do not need to match. |The effect of this function is to simply transfer a given number of bytes in |noncontiguous buffers specified by the vector structure to another number of |bytes in noncontiguous buffers specified by the vector structure returned by |the header handler. If the total length of the noncontiguous buffers in |the target, for example N, is less than the total length of the |noncontiguous buffers in the origin, for example M, only the first |N bytes from the origin buffers will be transferred and the remaining |bytes will be discarded. |If M is greater than N, all M bytes will |be transferred.

|This function transfers the hdr_hdl function pointer along |with the contents of uhdr and data described in org_vec from |the origin to the target process tgt. When the message arrives |at the target process, the header handler hdr_hdl is invoked at the |tgt with the pointer to uhdr as one of the |parameters. The origin vector structure org_vec must specify, |from the vec_type field, a type of LAPI_GEN_GENERIC. |The user-supplied header handler must return a pointer to a structure of type |lapi_vec_t with a value of LAPI_GEN_GENERIC. This |structure must contain:

  1. |The number of vectors (num_vec)
  2. |A vector of the length num_vec containing buffer pointers
  3. |The num_vec vector of lengths as the return value

|This description provides the information of where the message data |is to be copied by LAPI. The header handler is also expected to save |any information that will be required later by the completion handler. |The header handler returns (through reference parameters) a pointer to the |completion handler and a pointer to a structure to be passed to the completion |handler (which we will refer to as the variable user_info).

|Note:
The header handler should be nonblocking because no progress on the messages |associated with the context hndl can be made until control is |returned to the communications library from the header handler. |

|After the header handler returns, data in org_vec (if any) |is copied into the user-returned buffers in the structure returned by the |header handler. When all of the data in org_vec has been |received at the target, the completion handler specified by the user through |the header handler is enqueued for execution.

|After the parameters (including the contents of uhdr and |org_vec are copied out of memory at the origin, the ocntr is |incremented. After the completion handler completes execution at the |tgt, the tnctr is incremented. If the completion |handler specified is NULL, the tnctr is incremented after all of |org_vec is copied into the user-specified buffers. If the user |returned buffer is NULL and the completion handler is also NULL, the results |of the data transfer are undefined and the contents will be incremented in |some implementation-specific manner. Any of the counter addresses can |be NULL. This is a nonblocking call. The calling process cannot |change the uhdr (origin header) and org_vec data until |completion at the origin is signaled by the ocntr being |incremented. In addition, the calling process cannot assume that the |org_vec structure can be changed before the origin counter is |incremented. Also, the structure (of the type lapi_vec_t) |returned by the header handler cannot be assumed to be modifiable before the |target and completion counters have been incremented. Similarly, it can |be assumed that the specified completion handler has run at tgt only |after the target counter tcntr is incremented. When the |hdr_hdl header handler specifies a comp_h completion |handler, the ccntr at the origin and tcntr counter at the |target will be incremented after the completion handler completes |execution. The length (uhdr_len) of the user-specified header |is constrained by an implementation-specified maximum value |(LAPI_Qenv(,MAX_UHDR_SZ,)). To get the best bandwidth, |uhdr_len should be as small as possible.

|The vector lengths specified in the origin vector structure in the |org_vec->len parameters must be multiples of the machine word size |in bytes.

|LAPI does not check for any overlapping regions among vectors either |at the origin or the target. If such overlapping regions exist on the |origin side, you may experience performance degradation. If the |overlapping regions exist on the target side, the contents of the target |buffer are undefined.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask() being called.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapters in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Fence, LAPI_Getv, LAPI_Nopoll_wait, LAPI_Putv, LAPI_Qenv, LAPI_Waitcntr

LAPI_Fence subroutine

Purpose

LAPI_Fence - Enforces order on Low-Level Application Programming Interface (LAPI) calls.

C Syntax

 #include <lapi.h>
 
int LAPI_Fence(hndl)
lapi_handle_t hndl;

FORTRAN Syntax

 include 'lapif.h'
 
LAPI_FENCE (hndl, ierror)
INTEGER hndl
INTEGER ierror
 

Parameters

hndl
IN Contains a handle that specifies a particular LAPI context.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

Use this subroutine to enforce order on LAPI calls. If a process calls LAPI_Fence, all the LAPI operations that were initiated by that process, before the fence using the LAPI context hndl, are guaranteed to complete at the target processes. This occurs before any of its communication operations using hndl, initiated after the LAPI_Fence, start transmission of data. This is a data fence which means that the data movement is complete. This is not an operation fence which would need to include Active Message completion handlers completing on the target.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Amsend, LAPI_Amsendv, LAPI_Get, LAPI_Getv, LAPI_Put, LAPI_Putv

LAPI_Get subroutine

Purpose

LAPI_Get - Copies data from a remote process to the local address on a local process.

Library

Availability Library (liblapi_r.a)

C Syntax

| #include <lapi.h>
| 
|int LAPI_Get(hndl, tgt, len, tgt_addr, org_addr, tgt_cntr, org_cntr)
|lapi_handle_t hndl;
|uint tgt;
|ulong len;
|void *tgt_addr;
|void *org_addr;
|lapi_cntr_t *tgt_cntr;
|lapi_cntr_t *org_cntr;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_GET(hndl, tgt, len, tgt_addr, org_addr, tgt_cntr, org_cntr, ierror)
|INTEGER hndl
|INTEGER tgt
|INTEGER (KIND=LAPI_INT_TYPE) len
|INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_addr
|INTEGER org_addr
|TYPE (LAPI_CNTR_T) :: tgt_cntr
|TYPE (LAPI_CNTR_T) :: org_cntr
|INTEGER ierror

Parameters

hndl
IN Contains a handle that specifies a particular Low-level Applications Programming Interface (LAPI) context.

tgt
IN Specifies the target task that is the source of the data. This parameter is valid from 0 <= tgt < LAPI_Qenv(,NUM_TASKS,).

len
IN Specifies the number of bytes of data to be copied. This parameter is valid from 0 <= len <= LAPI_Qenv(,MAX_DATA_SZ,).

tgt_addr
IN Specifies the target buffer address of the data source. This parameter can be NULL only if len is equivalent to 0.

org_addr
IN/OUT Specifies the local buffer address that the received data is copied into. This parameter can be NULL only if len is equivalent to 0.

tgt_cntr
IN Specifies the target counter address. The target counter is incremented after data arrives at the target. If the parameter is NULL, this counter will not be updated.

org_cntr
IN/OUT Specifies the origin counter address. The origin counter is incremented after data arrives at the origin. If the parameter is NULL, the counter will not be updated.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to transfer the len number of bytes from the tgt_addr address at the target process to the org_addr virtual address at the origin process over the context identified by hndl. After the data is copied out of the memory at the tgt_addr, the tgt_cntr is incremented. After the data arrives at the origin, the org_cntr is incremented. If either counter address is NULL, the data transfer occurs, but the corresponding counter increment does not take place.

This is a nonblocking call in that the calling program cannot assume that the target buffer can be changed, nor that the contents of the memory pointed to by the org_addr on the origin is ready for use. However, after the origin waits for the org_cntr update to complete, the origin can use the org_addr data. Similarly, the target can reuse the target buffer tgt_addr only after it has waited for the tgt_cntr update to complete at the target.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask() being called.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Fence, LAPI_Getcntr, LAPI_Getv, LAPI_Nopoll_wait, LAPI_Put, LAPI_Qenv, LAPI_Waitcntr

LAPI_Getcntr subroutine

Purpose

LAPI_Getcntr - Gets the integer value of counter.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Getcntr(hndl, cntr, val)
lapi handle t hndl;
lapi cntr t *cntr;
int *val;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_GETCNTR (hndl, cntr, val, ierror)
|INTEGER hndl
|TYPE (LAPI_CNTR_T) :: cntr
|INTEGER val
|INTEGER ierror
| 

Parameters

hndl
IN Specifies the LAPI context.

cntr
IN Specifies the address of the counter. This parameter cannot be NULL.

val
OUT Returns the integer value of counter. This parameter cannot be NULL. |

|ierror
|OUT Specifies a FORTRAN return code. It is always the last |argument.

Description

Gets the integer value of cntr. This can be used to see how much progress is being made in LAPI context hndl.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Amsend, LAPI_Amsendv, LAPI_Get, LAPI_Getv, LAPI_Put, LAPI_Putv, LAPI_Rmw, LAPI_Setcntr, LAPI_Waitcntr


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]