Purpose
LAPI_Setcntr - Sets a counter to a specified value.
Library
Availability Library (liblapi_r.a)
C Syntax
#include <lapi.h> int LAPI_Setcntr(hndl, cntr, val) lapi_handle_t hndl; lapi_cntr_t *cntr; int val;
FORTRAN Syntax
| include 'lapif.h' | |LAPI_SETCNTR(hndl, cntr, val, ierror) |INTEGER hndl |TYPE (LAPI_CNTR_T) :: cntr |INTEGER val |INTEGER ierror
Parameters
Description
Use this subroutine to set the cntr to the appropriate value. The LAPI context associated with hndl may or may not be polled for incoming messages.
Return Values
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_Getcntr, LAPI_Waitcntr
Purpose
LAPI_Setcntr_wstatus - Sets a counter to a specified value and sets the associate destination list array and destination status array to the counter.
Library
Availability Library (liblapi_r.a)
C Syntax
#include <lapi.h> int LAPI_Setcntr_wstatus(hndl, cntr, val, dest_list, dest_status) lapi_handle_t hndl; lapi_cntr_t*cntr; int val; uint *dest_list; int *dest_status;
FORTRAN Syntax
| include 'lapif.h' | |LAPI_SETCNTR_WSTATUS(hndl, cntr, val, dest_list, dest_status, ierror) |INTEGER hndl |TYPE (LAPI_CNTR_T) :: cntr |INTEGER val |INTEGER dest_list |INTEGER dest_status |INTEGER ierror
Parameters
Description
This function sets the cntr to the appropriate value. It returns with LAPI_ERR_BAD_PARAMETER if dest_list is not NULL and *dest_status is. dest_list and *dest_status record the status of a task from where the thread calling LAPI_Nopoll_wait() is waiting for a response. Status has the following format:
Return Values
Location
/usr/lib/liblapi_r.a
Related Information
Subroutines: LAPI_Getcntr, LAPI_Nopoll_wait, LAPI_Purge_totask, LAPI_Setcntr
Purpose
LAPI_Term - Terminates and cleans up the Low-Level Application Programming Interface (LAPI) subsystem.
Library
Availability Library (liblapi_r.a)
C Syntax
#include <lapi.h> int LAPI_Term(hndl) lapi_handle_t hndl;
FORTRAN Syntax
include 'lapif.h' LAPI_TERM(hndl, ierror) INTEGER hndl INTEGER ierror
Parameters
Description
Use this subroutine to terminate the LAPI context specified by hndl. Any LAPI notification threads associated with this context are terminated. An error occurs when any LAPI calls are made using hndl after LAPI_Term is called.
Return Values
Location
/usr/lib/liblapi_r.a
Related Information
Subroutines: LAPI_Init
Purpose
LAPI_Waitcntr - Waits until a specified counter reaches the value specified.
Library
Availability Library (liblapi_r.a)
C Syntax
#include <lapi.h> int LAPI_Waitcntr(hndl, cntr, val, cur_cntr_val) lapi_handle_t hndl; lapi_cntr_t *cntr; int val; int *cur_cntr_val;
FORTRAN Syntax
| include 'lapif.h' | |LAPI_WAITCNTR(hndl, cntr, val, cur_cntr_val, ierror) |INTEGER hndl |TYPE (LAPI_CNTR_T) :: cntr |INTEGER val |INTEGER cur_cntr_val |INTEGER ierror
Parameters
Description
Use this subroutine to wait until the cntr reaches or exceeds the specified val. Once the cntr reaches the val, the cntr is decremented by that value. (We say decremented rather than set to zero since the cntr could have had a value greater than the specified val when the call was made.) This call may or may not check for message arrivals over the LAPI context hndl. The cur_cntr_val variable is set to the current counter value.
Return Values
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_Amsend, LAPI_Get, LAPI_Getcntr, LAPI_Put, LAPI_Rmw, LAPI_Setcntr
Purpose
setvhostname - Sets the virtual host name of the local host.
Library
Availability Library (libavail.a)
Syntax
#include <vhost.h> int setvhostname (name, name_length); char *name; int name_length;
Parameters
Description
Use this subroutine to set the virtual host name of a host machine. Only programs with a root user ID can use this subroutine. This routine is similar to the sethostname system call with the exception that it stores the virtual host name in the /etc/vhostname file instead of using a kernel variable. The setvhostname subroutine is a library call and sethostname is a system call.
The name is stored in the /etc/vhostname file. If the file does not exist, it will be created. If it does exist, the file contents will be overwritten by the new virtual host name. 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. The name_length parameter does not have to allow for the terminating null character, therefore, the largest allowable value for name_length is MAX_VHOSTNAME_LEN.
To clear the virtual host name so that the virtual host name no longer exists, 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.
Return Values
Upon successful completion, the setvhostname 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 setvhostname subroutine is unsuccessful if the following error occurs:
If one of the system calls used to store the virtual host name into the /etc/vhostname file encounters an error (for example, open, write, rename), errno is set by the system call that encountered an error.
Related Information
PSSP commands: vhostname
PSSP subroutines: getvhostname
AIX commands: hostname
AIX subroutines: gethostname, sethostname
Examples
rm /etc/vhostname
#include <string.h>
#include <vhost.h>
main ( )
{
char name[]='spcw_prim';
setvhostname(name, strlen(name));
}
Purpose
swclockGetIncrement - Returns the hertz frequency at which the switch clock operates.
Library
Switch Clock Library (libswclock.a)
Location
/usr/lib/libswclock.a
Syntax
#include <swclock.h> int swclockGetIncrement(swclock_handle_t swclock_handle);
Parameters
Description
Use this thread-safe subroutine to obtain the hertz frequency at which the switch clock operates. Switch clock frequency can be used to convert the switch clock value returned by the swclockRead subroutine.
Return Values
Upon successful completion, the swclockGetIncrement subroutine returns the hertz frequency at which the switch clock operates. Otherwise, a value of -1 is returned and the global variable errno is set to identify the error.
Error Values
Related Information
Subroutines: swclockInit, swclockRead, swclockReadSec, swclockTerm
Header file: swclock.h
Purpose
swclockInit - Initializes the switch clock read interface for a thread.
Library
Switch Clock Library (libswclock.a)
Location
/usr/lib/libswclock.a
Syntax
#include <swclock.h> swclock_handle_t swclockInit(void);
Description
Use this thread-safe subroutine to initialize the switch clock read interface for the current thread. It returns a handle which must be passed as an input parameter to all other switch clock library subroutines.
Usage Notes:
Return Values
Upon successful completion, the swclockInit subroutine returns a handle that must be passed as input to all other switch clock library subroutines. Otherwise, a value of 0 is returned and the global variable errno is set to identify the error.
Error Values
Related Information
PSSP: Administration Guide
Subroutines: swclockGetIncrement, swclockRead, swclockReadSec, swclockTerm
Header file: swclock.h
Purpose
swclockRead - Returns the current switch clock value.
Library
Switch Clock Library (libswclock.a)
Location
/usr/lib/libswclock.a
Syntax
#include <swclock.h> long64_t swclockRead(swclock_handle_t swclock_handle);
Parameters
Description
Use this thread-safe subroutine to read the switch clock. The switch clock value can be converted using the frequency returned by the swclockGetIncrement subroutine. The swclockRead subroutine can be called as many times as needed once the switch clock read interface is initialized for the current thread.
The switch clock is synchronous across all nodes active on a switch. Its value is set to zero when the primary node powers on, and can be reset during switch operation and management.
Usage Notes:
Return Values
Upon successful completion, the swclockRead subroutine returns the current value of the switch clock. Otherwise, a value of -1 is returned and the global variable errno is set to identify the error.
Error Values
Related Information
PSSP: Diagnosis Guide
PSSP: Administration Guide
Subroutines: swclockGetIncrement, swclockInit, swclockReadSec, swclockTerm
Header file: swclock.h
Purpose
swclockReadSec - Returns the current switch clock value in seconds.
Library
Switch Clock Library (libswclock.a)
Location
/usr/lib/libswclock.a
Syntax
#include <swclock.h> double swclockReadSec(swclock_handle_t swclock_handle);
Parameters
Description
Use this thread-safe subroutine to read the switch clock. The swclockReadSec subroutine returns switch clock value converted to seconds. It can be called as many times as needed to read the switch clock once the switch clock read interface is initialized for the current thread.
The switch clock is synchronous across all nodes active on a switch. Its value is set to zero when the primary node powers on, and can be reset during switch operation and management.
Usage Notes:
Return Values
Upon successful completion, the swclockReadSec subroutine returns the current value of the switch clock converted to seconds. Otherwise, a value of -1 is returned and the global variable errno is set to identify the error.
Error Values
Related Information
PSSP: Diagnosis Guide
PSSP: Administration Guide
Subroutines: swclockGetIncrement, swclockInit, swclockRead, swclockTerm
Header file: swclock.h
Purpose
swclockTerm - Terminates the switch clock read interface for a thread.
Library
Switch Clock Library (libswclock.a)
Location
/usr/lib/libswclock.a
Syntax
#include <swclock.h> int swclockTerm(swclock_handle_t swclock_handle);
Parameters
Description
Use this thread-safe subroutine to terminate the switch clock read interface for the current thread. Switch clock library subroutines called subsequent to the swclockTerm subroutine will encounter an error unless the thread reinitializes the interface. If the swclockTerm subroutine is not called, the switch clock read interface will be terminated when the thread itself terminates.
Return Values
Upon successful completion, the swclockTerm subroutine returns a value of 0. Otherwise, a value of -1 is returned and the global variable errno is set to identify the error.
Error Values
Related Information
Subroutines: swclockGetIncrement, swclockInit, swclockRead, swclockReadSec
Header file: swclock.h
Purpose
swtbl_adapter_connectivity - Returns the current state of connectivity for the specified adapter on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h>
int swtbl_adapter_connectivity(int version,char *adapter,\
unsigned int *connectivity, int *ports)
Parameters
Description
Use this subroutine to obtain the current state of connectivity for the specified adapter on the node from which it is invoked. The connectivity parameter will return a right justified bitmap representing the connectivity of the ports available on the specified adapter. The number of relevant bits in the bitmap is represented by the ports parameter.
A 1 bit indicates that the port has connectivity over the switch for sending and receiving data. A 0 bit indicates that the port is not connected to other ports over the switch.
The effective user ID of the calling process must be the root user ID.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information is recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_adapter_connectivity subroutine returns a value of ST_SUCCESS. Otherwise, it returns an error value defined by the ST_RETURN_CODE enumerator found in st_client.h.
Error Values
Related Information
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_resources, swtbl_clean_table, swtbl_load_job, swtbl_load_table, swtbl_status, swtbl_status_node, swtbl_unload_job
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to obtain the connectivity of css0 on the current node:
#include <st_client.h>
main() {
int rc;
unsigned int connectivity;
int ports;
rc = swtbl_adapter_connectivity(ST_VERSION,"css0", &connectivity,&ports);\
fprintf(stdout,"swtbl_adapter_connectivity returned %d\n",rc);
if (rc == ST_SUCCESS) {
fprintf(stdout,"adapter %s:\n","css0");
if ((ports == 1) || (ports == 2 )) {
fprintf(stdout,"\tport 1:");
if (connectivity == 0)
fprintf(stdout," 0\n");
else if (connectivity == 1)
fprintf(stdout," 1\n");
}
if (ports == 2) {
fprintf(stdout,"\tport 2:");
if (connectivity == 2 || connectivity == 3)
fprintf(stdout," 1\n");
else
fprintf(stdout," 0\n");
}
}
}
Purpose
swtbl_adapter_resources - Returns the configured resources of the specified adapter on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h>
int swtbl_adapter_resources(int version,char *adapter,\
struct ST_ADAPTER_RESOURCES *resources)
Parameters
Description
Use this subroutine to obtain the configured resources of the adapter specified on the node from which it is invoked. The ST_ADAPTER_RESOURCES structure will contain information about the number of logical windows available on the adapter; the maximum and minimum DMA memory available for request per window; the aggregate amount of device memory available for unreserved windows to request; a list of unreserved windows; and a count of the unreserved windows. All memory data is represented in bytes. This information should be used in conjunction with the swtbl_load_table or swtbl_load_job APIs.
The effective user ID of the calling process must be the root user ID.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information will be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_adapter_resources subroutine returns a value of ST_SUCCESS. Otherwise, it returns an error value defined by the ST_RETURN_CODE enumerator found in st_client.h.
The following data members are returned when the st_return_code returns ST_SUCCESS:
Error Values
Related Information
For more information about reserved windows and window memory, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_clean_table, swtbl_load_job, swtbl_load_table, swtbl_status, swtbl_status_node, swtbl_unload_job
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to report the configured resources for css0 on the current node:
#include <st_client.h>
main() {
int rc;
struct ST_ADAPTER_RESOURCES resources;
rc = swtbl_adapter_resources(ST_VERSION,"css0",&resources);
fprintf(stdout,"swtbl_adapter_resources returned %d\n",rc);
if (rc == ST_SUCCESS) {
fprintf(stdout,"\tconfigured schedulable windows = %d\n",\
resources.st_max_windows);
fprintf(stdout,"\tconfigured adapter memory = %d\n",\
resources.st_avail_adapter_memory);
fprintf(stdout,"\tconfigured max adapter window memory = \
%d\n",resources.st_max_window_memory);
fprintf(stdout,"\tconfigured min adapter window memory = \
%d\n",resources.st_min_window_memory);
fprintf(stdout,"\tconfigured window count = %d\n",\
resources.st_window_count);
fprintf(stdout,"\tconfigured window list= ");
for (i=0; i<resources.st_window_count; i++)
fprintf(stdout,"\t%d",resources.st_window_list[i]);
fprintf(stdout,"\t\n");
}
}
Purpose
swtbl_clean_table - Forces the unload of the job switch resource table window on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_clean_table(int version,char *adapter,int option,int window_id);
Parameters
Description
Use this subroutine to override user ID (uid) checking and to unload the job switch resource table window on the node from which it is invoked.
Normal unloading of the job switch resource table window by the swtbl_unload_table API verifies that the uid of the unload matches the uid specified during the load. The swtbl_clean_table API ignores this verification and allows the caller to unload the window from a node.
This subroutine should be used for error recovery and not for normal switch table unloading. For example, when a parallel job has left a process in use and the window did not unload by the swtbl_unload_table API, the caller can use swtbl_clean_table to clean up that node.
If the ST_LEAVE_INUSE option is specified and a process is using the switch, the swtbl_clean_table will not unload the window.
If the ST_ALWAYS_KILL option is specified, and a process is using the switch then the process will be stopped by a SIGKILL signal.
To invoke this interface, the effective userid of the calling process must be the root userid.
The default window is specified within the st_client.h file.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file.
Additional debug information will be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_clean_table subroutine returns a value of ST_SUCCESS. Otherwise, it returns an error value defined by the ST_RETURN_CODE enumerator found in st_client.h.
Error Values
Related Information
For more information about reserved windows, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_adapter_resources, swtbl_load_job, swtbl_load_table, swtbl_unload_job, swtbl_unload_table, swtbl_status, swtbl_status_node
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
To clean up a running process and unload the table from this node:
#include <st_client.h>
main() {
int rc;
enum ST_OPTION option = ST_ALWAYS_KILL;
int window_id = 1;
rc = swtbl_clean_table(ST_VERSION,"css0",option,window_id);
fprintf(stdout,"swtbl_clean_table returned %d\n");
}
Purpose
swtbl_load_job - Loads the job switch resource table on the indicated nodes for a single job.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_load_job(int version,uid_t uid,int job_key,int num_tasks, \ char *job_desc,char *cws, ST_NODE_INFO *nodeinfo);
Parameters
Description
Use this subroutine to load all of the job switch resource tables needed for a single parallel job. A switch table needs to be loaded upon every node used by the job for communication in user space mode over the switch. The JSRT Services should be used by non-reserving components.
An ST_NODE_INFO structure needs to be defined for every task in the parallel job. Each structure defines the task, window, and node relationship, and the array of structures defines how the tasks of the parallel job will communicate. The swtbl_load_job subroutine interfaces with the switchtbld daemon over the network to call the local swtbl_load_table API which loads the table on that node.
The first st_adapter specified in the nodeinfo array is used to open the device and load the job switch resource table.
Valid st_window_memory ranges can be obtained from the swtbl_adapter_resources API. This data member can be optional. A 0 value indicates that the device driver will determine the window size. It will be the smaller value of the following two: available memory or win_maxsize set by the administrator using the chgcss command.
If DCE security checking is being used, the userid of the calling process must have the DCE credentials of the switchtbld-load group to use this function. If DCE security checking is not being used, the effective user ID of the calling process must be the root user ID.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file on the calling node and for all of the nodes within the request. Additional debug information will be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
The default window is defined within the st_client.h header file.
Return Values
Upon successful completion, the swtbl_load_job subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h.
The ST_NODE_INFO member st_return_code is updated to reflect any errors that may have occurred on the individual nodes. This return code corresponds to the return code of the swtbl_load_table API called on that node.
The ST_ALREADY_CONNECTED return code does not indicate an error. It means that the load request was already sent to that node because the st_node_name was defined within a previous nodeinfo structure.
The ST_UNLOADED return code indicates that the switch table was unloaded upon that node after another node within the same request encountered an error.
Error Values
Related Information
For more information about reserved windows and window memory, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_resources, swtbl_adapter_connectivity, swtbl_clean_table, swtbl_load_table, swtbl_status, swtbl_status_node, swtbl_unload_job, swtbl_unload_table
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to load the job switch resource table for a job that will be executing on two nodes:
|#include <st_client.h> | main() { | int rc; | int job_key; | int num_tasks = 2; | struct ST_NODE_INFO node[num_tasks]; | struct hostent *hp; | uid_t uid; | | uid = set_user_id(); /* User defined routine to get uid */ | job_key = set_unique_key(); /* User defined routine to get job_key */ | | strcpy(node[0].st_node_name,"Node1"); | node[0].st_window_id = 0; | node[0].st_virtual_task_id = 0; | node[0].st_window_memory = get_valid_window_memory(); | node[0].st_adapter = CSS0; | | hp = gethostbyname("Node2"); | bcopy(hp->h_addr_list[0],&node[1].swtbl_addr,hp->h_length); | node[1].st_window_id = 1; | node[1].st_virtual_task_id = 1; | node[1].st_window_memory = get_valid_window_memory(); | node[1].st_adapter = CSS0; | | rc = swtbl_load_job(ST_VERSION,uid,job_key,num_tasks,"User1_job",NULL,node); | fprintf(stdout,"swtbl_load_job returned %d\n",rc); | }
Purpose
swtbl_load_table - Loads a job switch resource table on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_load_table(int version,uid_t uid,pid_t pid,int job_key, \ char *requester_node, int num_tasks,char *job_desc,\ ST_NODE_INFO *nodeinfo);
Parameters
Description
Use this subroutine to load the job switch resource table on the node from which it is invoked. This switch table is used by parallel jobs running user space over the switch. The JSRT Services should be used by non-reserving components.
An ST_NODE_INFO structure needs to be defined for every task in the parallel job. Each structure defines the task, window, and node relationship, and the array of structures defines how the parallel job tasks will communicate.
The first st_adapter specified in the nodeinfo array is used to open the device and load the job switch resource table.
Valid st_window_memory ranges can be obtained from the swtbl_adapter_resources API. This data member can be optional. A 0 value indicates that the device driver will determine the window size. It will be the smaller value of the following two: available memory or win_maxsize set by the administrator using the chgcss command.
The effective userid of the calling process must be the root userid.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information can be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
The default window is defined within the st_client.h header file.
Return Values
Upon successful completion, the swtbl_load_table subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h.
The ST_NODE_INFO member st_return_code is not updated by this subroutine.
Error Values
Related Information
For more information about reserved windows and window memory, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_resources, swtbl_adapter_connectivity, swtbl_clean_table, swtbl_load_job, swtbl_status, swtbl_status_node, swtbl_unload_job, swtbl_unload_table
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to load the job switch resource table for a job that will be running on 2 nodes:
#include <st_client.h>
main() {
int i,rc;
struct ST_NODE_INFO node[2];
uid_t uid;
pid_t pid;
int job_key;
int num_tasks=2;
char hostname[MAXHOSTNAMELEN];
uid = set_user_id(); /* User defined routine to get uid */
pid = getpid();
gethostname(hostname,MAXHOSTNAMELEN);
job_key = set_unique_key(); /* User defined routine to get job_key */
node[0].st_virtual_task_id = 0;
node[0].st_window_id = 0;
node[0].st_switch_node_num = get_num_from_SDR(); /* get switch num */
node[0].st_adapter = CSS0;
node[0].st_window_memory = get_valid_window_range();
node[1].st_virtual_task_id = 1;
node[1].st_window_id = 1;
node[1].st_switch_node_num = get_num_from_SDR(); /* get switch num */
node[1].st_adapter = CSS0;
node[1].st_window_memory = get_valid_window_range();
rc = swtbl_load_table(ST_VERSION,uid,pid,job_key,hostname,num_tasks,
"User1_job",node);
fprintf(stdout,"swtbl_load_table returned %d\n",rc);
}
Purpose
swtbl_query_adapter - Returns the status of the adapter specified on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_query_adapter(int version,char *adapter,\ enum ST_ADAPTER_STATUS *status)
Parameters
Description
Use this subroutine to obtain the current status of the adapter specified on the node from which it is invoked. The ST_ADAPTER_STATUS variable will contain ADAPTER_READY or ADAPTER_NOTREADY. ADAPTER_READY indicates that the node has connectivity over the switch for sending and receiving data. ADAPTER_NOTREADY indicates that the node is not connected to other nodes over the switch.
The effective userid of the calling process must be the root userid.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information can be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_query_adapter subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h.
Error Values
Related Information
Commands: st_clean_table, st_status
Subroutines: swtbl_clean_table, swtbl_load_job, swtbl_load_table, swtbl_status, swtbl_status_node, swtbl_unload_job
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to query css0 on the current node:
#include <st_client.h>
main() {
int rc;
enum ST_ADAPTER_STATUS status;
rc = swtbl_query_adapter(ST_VERSION,"css0",&status);
fprintf(stdout,"swtbl_query_adapter returned %d\n",rc);
fprintf(stdout,"status = %d\n",status);
}
Purpose
swtbl_status - Returns the status of all job switch resource table windows upon a node.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_status(int version,int num_nodes,ST_STATUS *status_info);
Parameters
Description
Use this subroutine to return the status of all job switch resource table windows on the nodes specified within each ST_STATUS structure. This subroutine interfaces with the switchtbld daemon to call the local swtbl_status_node API on each node. Each node returns a linked list of ST_STATUS structures representing the windows defined upon that node. Status will be reported for reserved and non-reserved windows. The caller is responsible for freeing the memory allocated for the linked list. A NULL *next pointer indicates the end.
If a window is loaded, the corresponding ST_STATUS structure will contain information about who made the load request, which user was designated to use the table and when the request was made. If a window is not loaded or an error occurred, the st_return_code contains the corresponding error value. If an error occurs that is related to a node and not a window, for example ST_CANT_CONNECT, the ST_STATUS structure will not contain window or adapter information.
If DCE security checking is being used, the calling process must have the DCE credentials of the switchtbld-status group to use this function.
The swtbl_status API gives no information about whether the switch table is in use or not.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file on the calling node and for all of the nodes within the request. Additional debug information can be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
The swtbl_status subroutine returns a value of ST_SUCCESS when status has been obtained from all of the nodes requested. An error value indicates that an error occurred getting the status. The status of each individual node's windows are represented by the st_return_code data member of the ST_STATUS linked list. This return code corresponds to the return code of the swtbl_status_node API called on that node.
All return codes are defined by the ST_RETURN_CODE enumerator found in st_client.h.
The following data members are returned when the st_return_code returns ST_SUCCESS. This indicates that the switch table window is loaded:
The following data members are returned when the st_return_code returns ST_RESERVED. This return code does not indicate an error. It indicates that the window is reserved by a reserving component.
Error Values
Related Information
For more information about reserved windows, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_adapter_resources, swtbl_clean_table, swtbl_load_job , swtbl_load_table, swtbl_status_node, swtbl_unload_job , swtbl_unload_table
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to get the status for three nodes:
#include <st_client.h>
main() {
int i,rc;
int num_nodes = 3;
struct ST_STATUS status[num_nodes];
strcpy(status_info[0].st_node_name,"k10n09");
strcpy(status_info[1].st_node_name,"129.40.161.74");
strcpy(status_info[2].st_node_name,"k10n11");
rc = swtbl_status(ST_VERSION,num_nodes,status_info);
fprintf(stdout,"swtbl_status returned %d\n",rc);
print_header();
for (i=0; i<num_tasks; i++) {
/* Print out each member of the struct */
print_status(status_info[i]);
}
}
Purpose
swtbl_status_node - Returns the status of all job switch resource table windows on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> swtbl_status_node(int version, ST_STATUS *status_info);
Parameters
Description
Use this subroutine to return the status of all job switch resource table windows on the node from which it is invoked. The caller must supply the first ST_STATUS structure but the API will allocate any remaining structures depending on the number of windows defined for that node. These structures will be linked to the first ST_STATUS by the next pointer. The caller is responsible for freeing all allocated memory. If a window is loaded, the corresponding ST_STATUS structure will contain information about who made the load request, which user was designated to use the table and when the request was made. If a window is not loaded or an error occurred, the st_return_code contains the corresponding error value.
The swtbl_status_node API gives no information about whether the switch table is in use or not.
The effective userid of the calling process must be the root userid.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information can be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_status_node subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h.
The following data members are returned when the switch table is loaded:
The following data members are returned when the st_return_code returns ST_RESERVED. This return code does not indicate an error. It indicates that the window is reserved by a reserving component.
Error Values
Related Information
For more information about reserved windows, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_adapter_resources, swtbl_clean_table, swtbl_load_job , swtbl_load_table, swtbl_status, swtbl_unload_job , swtbl_unload_table
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to get the status for this node:
#include <st_client.h>
main() {
int rc;
struct ST_STATUS status[1];
rc = swtbl_status_node(ST_VERSION,status_info);
fprintf(stdout,"swtbl_status_node returned %d\n",rc);
print_header();
print_status(status_info); /* Print out each member of the struct */
}
Purpose
swtbl_unload_job - Unloads the job switch resource tables on the indicated nodes for a single job.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_unload_job(int version,uid_t uid,int num_tasks,\ ST_NODE_INFO *nodeinfo);
Parameters
Description
Use this subroutine to unload all of the job switch resource tables needed for a single parallel job. This switch table is used by parallel jobs running user space over the switch. The JSRT Services should be used by non-reserving components.
An ST_NODE_INFO structure needs to be defined for every task that needs to have the switch table unloaded. The swtbl_unload_job subroutine interfaces with the switchtbld daemon over the network to call the local swtbl_unload_table API and unload every window within the table on that node.
If DCE security checking is being used, the calling process must have the DCE credentials of the switchtbld-load group to use this function. If DCE security checking is not being used, the effective user ID of the calling process must be the root user ID.
The default window is defined within the st_client.h header file.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file on the calling node and for all of the nodes within the request. Additional debug information will be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_unload_job subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h. The ST_NODE_INFO member st_return_code is updated to reflect any errors that may have occurred on the individual nodes. This return code corresponds to the return code of the swtbl_unload_table API called on that node.
Error Values
Related Information
For more information about reserved windows, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_adapter_resources, swtbl_clean_table, swtbl_load_job , swtbl_load_table, swtbl_status, swtbl_status_node , swtbl_unload_table
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to unload the job switch resource table windows for a job that was previously loaded for two nodes:
#include <st_client.h>
main() {
int rc;
int num_tasks = 2;
struct ST_NODE_INFO node[num_tasks];
uid_t uid;
uid = set_user_id(); /* User defined routine to get uid */
strcpy(node[0].st_node_name,"Node1");
node[0].st_window_id = 1;
node[0].st_adapter = CSS0;
strcpy(node[1].st_node_name,"129.40.161.74");
node[1].st_window_id = 2;
node[1].st_adapter = CSS0;
rc = swtbl_unload_job(ST_VERSION,uid,num_tasks,node);
fprintf(stdout,"swtbl_unload_job returned %d\n",rc);
}
Purpose
swtbl_unload_table - Unloads the job switch resource table window on the node from which it is invoked.
Library
Job Switch Resource Table Services library (libswitchtbl.a)
Syntax
#include <st_client.h> int swtbl_unload_table(int version, char *adapter, \ uid_t uid, int window_id);
Parameters
Description
Use this subroutine to unload the job switch resource table window on the node from which it is invoked. This switch table is used by parallel jobs running user space over the switch. This subroutine checks that the uid provided matches the one that is stored during the swtbl_load_table call. Each window within the job switch resource table must be unloaded individually. The JSRT Services should be used by non-reserving components.
The effective user ID of the calling process must be the root user ID.
The default window is defined within the st_client.h header file.
Any information or error messages are recorded in the /var/adm/SPlogs/st/st_log file. Additional debug information will be recorded in the log by setting the SWTBLAPIERRORMSGS environment variable to yes.
Return Values
Upon successful completion, the swtbl_unload_table subroutine returns a value of ST_SUCCESS. Otherwise, it returns an integer value defined by the ST_RETURN_CODE enumerator found in st_client.h.
Error Values
Related Information
For more information about reserved windows, see the chgcss command.
Commands: st_clean_table, st_status
Subroutines: swtbl_adapter_connectivity, swtbl_adapter_resources, swtbl_clean_table, swtbl_load_job , swtbl_load_table, swtbl_status, swtbl_status_node , swtbl_unload_job
Files: /usr/lpp/ssp/include/st_client.h, /var/adm/SPlogs/st/st_log
Examples
Code fragment to unload window 1 on the current node:
#include <st_client.h>
main() {
int i,rc;
uid_t uid;
int window = 1;
uid = set_user_id(); /* User defined routine to get uid */
rc = swtbl_unload_table(ST_VERSION,"css0",uid,window);
fprintf(stdout,"swtbl_unload_table returned %d\n",rc);
}