Controlling a running remote AE

The AE capability provides an SQL table function, nzaejobcontrol, that controls running remote AEs. The syntax is (with arguments described in the following table):

nzaejobcontrol <operation><dataslice for locus><connection point string
name><remote_name>{TRUE | FALSE}{NULL | 0 | <transaction ID>}{NULL | 0 | <session
ID>}

Table 1. nzaejobcontrol argument descriptions
Argument	Description
Operation to perform	Operations include pinging a remote AE, stopping a remote AE, returning Linux process information about a remote AE, and sending signals to a remote AE. There are commands for operating on a specific remote AE connection point and on a subset of connection points, including all of them.
Dataslice/locus of the remote AE (SPUs or host)	This argument is specified using literal integer zero (0) for host or a set of non-literal integer dataslice IDs for SPU. The set of dataslice IDs come from system view _v_dual_dslice (or something equivalent).
String name portion of the connection point address	For a single connection point command, this name must be specified. For a multiple connection point command, it may be NULL or ‘’ (empty string), in which case it specifies all names.
Boolean (Dataslice ID)	TRUE means use dataslice ID in connection point address; FALSE means do not use it. For multiple connection point commands, this argument must be FALSE.
Bigint (Transaction ID)	NULL means do not use transaction ID. 0 means use the current transaction ID function that table function nzaejobcontrol was called in; greater than 0 means use the specified transaction ID.
Bigint (Session ID)	NULL means do not use session ID. 0 means use the current session ID that table function nzaejobcontrol was called in; greater than 0 means use the specified session ID.

Single Connection Point Commands

Single connection point commands operate on exactly one connection point, which might consist of multiple processes on multiple machines. These are the command names that can be used in the operation argument of nzaejobcontrol.

ping—Sends a short message to a connection point to determine if it is active and responding. It returns data for all output columns listed below. (See Table Function Output Columns.)
ps—Returns process information about a remote AE listening on a connection point. This command can complete even if the AE is not responding on the connection point. It returns data for all output columns that do not require direct communication with the remote AE.
stop—Stops a remote AE listening on a connection point. If the remote AE process does not respond to the message, the remote AE process is sent a SIGKILL signal.
status—Returns status information from a remote AE listening on a connection point. By creating a remote AE message callback routine, a remote AE application can return its own customized message and return code. Certain Linux signal commands can be sent to remote AEs. The signal sent is indicated in the operation field of the table function nzaejobcontrol commands sighup, sigint, sigkill, sigusr1, sigusr2, sigterm, sigcont, and sigstop.
clean—Deletes temporary synchronization files left on the SPUs. This command is used after the stop command has completed. The disk space involved is usually insignificant, except when many different connection point names are being created using session ID and transaction ID.

Multiple Connection Point Commands

The single connection point commands act on exactly one connection point, which may be in use by multiple processes on the SPUs. Except for the clean command, all the nzaejobcontrol table function commands have a corresponding multi-connection point version.

For these commands, the connection point arguments to table function nzaejobcontrol act as a selection filter. For example, if remote name is specified as NULL or ‘’ (empty string) the command operates on connection points with all names. It is therefore possible to send a command to all remote AEs or a set of remote AEs, for example, all remote AEs using a connection point created with a particular session ID.

These commands include pingall, stopall, psall, statusall, sighupall, sigintall, sigkillall, sigusr1all, sigusr2all, sigtermall, sigcontall, sigstopall. These commands operate similarly to the single connection point version, but instead for multiple AEs.

Table Function Output Columns

When using the nzaejobcontrol function in the INZA database directly in SQL, the selected column should be aeresult. The nzaejobcontrol function can also be used by a GUI program using SQL; therefore, information is also returned in individual columns. Not all commands set all return columns. Table function nzaejobcontrol returns zero to multiple rows.

Table 2. nzaejobcontrol returned columns
Column	Description
aeresult	Status message
aerc	Return code for the command: 0 = success, -1 = error, +1 = stop unsuccessful but subsequent kill signal successful
aetotal	Total rows returned for command, repeated in each row
aename	Connection point name
aedslice	Connection point dataslice ID
aesession	Connection point Session ID
aetrans	Connection point Transaction ID
aehostname	Host name AE process is running on
aepid	Linux process ID of remote AE
aecommand	AE command line
aetid	Linux thread ID that the connection point is being listened on
aebuild	The AE build number of the remote AE
aenzrepver	The nzrep version the remote AE is using
aenzrepver	If TRUE the AE build number or the nzrep version of the remote AE does not match the current the NPS system kit, otherwise FALSE.

Host Examples

The following examples illustrate how single commands work on the host. (They assume that an AE called my_remote_ae exists and can be called.)

Ping a remote AE not using dataslice ID in the connection point:

SELECT aeresult FROM TABLE WITH FINAL(inza..nzaejobcontrol('ping', 0,
     'my_remote_ae', false, NULL, NULL));

Ping a remote AE using dataslice ID in the connection point:

SELECT aeresult FROM TABLE WITH FINAL(inza..nzaejobcontrol('ping', 0, 
     'my_remote_ae', true, NULL, NULL));

Ping all remote AEs:

SELECT aeresult FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, 
     NULL, false, NULL, NULL));

Ping all remote AEs with a connection point using session ID = 1000:

SELECT aeresult FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, 
     NULL, false, NULL, 1000));

SPU Examples

The following examples illustrate how single commands work on a SPU. (They assume that an AE called my_remote_ae exists and can be called.)

Ping a remote AE that has one instance per SPU:

SELECT aeresult FROM _v_dual_dslice, TABLE WITH 
     final(inza..nzaejobcontrol('ping', dsid, 'my_remote_ae', false, NULL,
NULL));

Ping a remote AE that has one instance per dataslice:

SELECT aeresult FROM _v_dual_dslice, TABLE WITH 
     final(inza..nzaejobcontrol('ping', dsid, 'my_remote_ae', true, NULL, NULL));

Ping all remote AEs:

SELECT aeresult FROM _v_dual_dslice, TABLE WITH 
     final(inza..nzaejobcontrol('pingall', dsid, NULL, false, NULL, NULL));

Ping all remote AEs with a connection point using session ID = 1000:

SELECT aeresult FROM _v_dual_dslice, TABLE WITH 
     final(inza..nzaejobcontrol('pingall', dsid, NULL, false, NULL, 1000));

Single Column Examples on the Host with Output

The following shows varied column results of pinging all remote AEs on the host:

SELECT aeresult FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL, 
 false, NULL, NULL));

AERESULT
-----------------------------------------------------------------------------
netezzahost 24872 (datamatrix dataslc:-1 sess:-1 trans:-1) thread: 24873 AE
Build: 10 nzrep version: 9
netezzahost 30264 (testcapi dataslc:-1 sess:-1 trans:-1) thread: 30264 AE Build:
10 nzrep version: 9

SELECT aerc FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL, false,
NULL, NULL));

AERC
------
0
0

SELECT aetotal FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AETOTAL
---------
2
2

SELECT aename FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AENAME
------------
datamatrix
testcapi

SELECT aedslice FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AEDSLICE
----------
-1
-1

SELECT aesession FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AESESSION
-----------
-1
-1

SELECT aetrans FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AETRANS
---------
-1
-1

SELECT aehostname FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AEHOSTNAME
--------------
netezzahost
netezzahost

SELECT aepid FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AEPID
-------
24872
30264

SELECT aecommand FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AECOMMAND
----------------------------------------------------------
/nz/export/ae/languages/java/6.13.0/jdk1.6.0_13/bin/java
/nz/export/ae/aebin/host/testcapi

SELECT aetid FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AETID
-------
24873
30264

SELECT aebuild FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AEBUILD
---------
10
10

SELECT aenzrepver FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0, NULL,
false, NULL, NULL));

AENZREPVER
------------
9
9

SELECT aevermismatch FROM TABLE WITH FINAL(inza..nzaejobcontrol('pingall', 0,
NULL, false, NULL, NULL));

AEVERMISMATCH
---------------
f
f