Remote initialization

Initialization functions related to Remote AEs.

They are used to:

Create a connection point.
Listen using that connection point.
Accept a Data Connection API handle or accept an AE Environment.

Data structures

struct NZAECONPT_HANDLE: The ConnectionPoint Handle. An opaque handle used with Connection Point AE functions.
struct NZAEREMPROT_HANDLE: The Remote Protocol Handle. An opaque handle used with Remote Protocol AE functions.
struct NzaeremprotInitialization: Initializes a Remote AE Notification Connection.

Typdefs

NzaeRemprotCallback: Callback typedef.

Functions

NzaeRemprotRcCode nzaeRemprotAcceptApi(NZAEREMPROT_HANDLE handle, NzaeApi *result): Returns an AE API Handle from the connection point.
NzaeRemprotRcCode nzaeRemprotAcceptApiWithTimeout(NZAEREMPROT_HANDLE handle, int timeoutMilliseconds, NzaeApi *result): Returns an AE API Handle from the connection point.
NzaeRemprotRcCode nzaeRemprotAcceptEnvironment(NZAEREMPROT_HANDLE handle, NZAEENV_HANDLE *result): Returns an AE Environment from the connection point.
NzaeRemprotRcCode nzaeRemprotAcceptEnvironmentWithTimeout(NZAEREMPROT_HANDLE handle, int timeoutMilliseconds, NZAEENV_HANDLE *result): Returns an AE Environment from the connection point.
void nzaeRemprotClose(NZAEREMPROT_HANDLE handle): Closes a listener.
NzaeRemprotRcCode nzaeRemprotCreateListener(NzaeremprotInitialization *args): Creates a new listener on a connection point.
void nzaeRemprotFreeResources(NZAEREMPROT_HANDLE handle): Releases resources such as handles and memory without shutting down the underlying communication connection.
int nzaeRemprotGetAcceptSocket(NZAEREMPROT_HANDLE handle: Returns the socket used to accept Remprot commands.
NzaeRemprotCallback nzaeRemprotGetCallback(NZAEREMPROT_HANDLE handle, void **userContext): Gets the Remote protocol Callback. A remote protocol handler function is used to handle remote commands such as stop and status.
NzaeApiTypes nzaeRemprotGetEnvironmentApiType(NZAEENV_HANDLE hEnv): Gets the API type from the environment.
char* nzaeRemprotGetLastErrorText(NZAEREMPROT_HANDLE handle): Gets the text of the last error.
int32_t nzaeRemprotGetRemoteDataSliceId(): Gets the remote name from the environment.
int32_t nzaeRemprotGetRemoteSessionId(): Gets the remote session ID from the environment.
int64_t nzaeRemprotGetRemoteTransactionId(): Gets the remote transaction ID from the environment.
int nzaeRemprotIsError(NZAEREMPROT_HANDLE handle): Returns TRUE if an error has occurred; FALSE if not.
void nzaeRemprotSetCallback(NZAEREMPROT_HANDLE handle, NzaeRemprotCallback call-back, void *userContext): Sets the Remote Protocol Callback. A remote protocol handler function is used to handle re-mote commands such as stop and status.
NzaeRemprotRcCode nzaeRemprotWaitForPingOrStop(NZAEREMPROT_HANDLE handle, int *bStopCommand): Waits for ping or stop.

Enumerations

enum NzaeRemprotCmd { NZAE_REMPROT_CMD_REQUEST, NZAE_REMPROT_CMD_PING, NZAE_REMPROT_CMD_STATUS, NZAE_REMPROT_CMD_STOP, NZAE_REMPROT_CMD_CON-TROL_DATA, NZAE_REMPROT_CMD_SIGNAL }: Remote AE Messages. Only NZAE_REMPROT_CMD_STATUS, NZAE_REMPROT_CMD_STOP, NZAE_REMPROT_CMD_SIGNAL, and NZAE_REMPROT_CMD_CONTROL_DATA are received by a user call back function.
enum NzaeRemprotRcCode { NZAEREMPROT_RC_ERROR= -1, NZAEREMPROT_RC_NORMAL= 0, NZAEREMPROT_RC_TIMEOUT= 1 }: Remote Protocol return codes.

Detailed descriptions

Initialization functions related to Remote AEs. They are used to:

Create a connection point.
Listen using that connection point.
Accept a Data Connection API handle or accept an AE Environment.

Type documentation

typedef int(* NzaeRemprotCallback)(void *userContext, int code, int dataLen, const char *data, NzaeRemprotCallbackResult *result)

Callback typedef.

Parameters:

userContext
Any user application-specific data. May be NULL.
code
The remote message received (NZAE_REMPROT_CMD_STATUS, NZAE_REMPROT_CMD_STOP, NZAE_REMPROT_CMD_SIGNAL, NZAE_REMPROT_CMD_CONTROL_DATA).
dataLen
The argument data length. May be 0.
data
The argument data. May be NULL.
result
The structure to place callback function result.

Returns A value of 0 on success, -1 on error.

Function documentation

NzaeRemprotRcCode nzaeRemprotAcceptApi(NZAEREMPROT_HANDLE handle, NzaeApi *result)

Returns an AE API Handle from the connection point.

Parameters:

handle
The remote protocol handle.
NzaeApi result
The accepted API.

Returns

NzaeRemprotRcCode

The return code.

The caller has ownership of the returned handle. Waits indefinitely.

NzaeRemprotRcCode nzaeRemprotAcceptApiWithTimeout(NZAEREMPROT_HANDLE handle, int timeoutMilliseconds, NzaeApi *result)

Returns an AE API Handle from the connection point.

Parameters:

handle
The remote protocol handle.
NzaeApi result
The accepted API.
timeoutMilliseconds
The timeout in milliseconds.

Returns

NzaeRemprotRcCode

The return code.

The caller has ownership of the returned handle. Waits for a connection for the given number of millseconds.

NzaeRemprotRcCode nzaeRemprotAcceptEnvironment(NZAEREMPROT_HANDLE handle, NZAEENV_HANDLE *result)

Returns an AE Environment from the connection point.

Parameters:

handle
The remote protocol handle.
result
The accepted Environment handle.

Returns

NzaeRemprotRcCode

The return code.

The caller has ownership of the returned handle. Waits indefinitely.

NzaeRemprotRcCode nzaeRemprotAcceptEnvironmentWith- Timeout(NZAEREMPROT_HANDLE handle, int timeoutMilliseconds, NZAEENV_HANDLE *result)

Returns an AE Environment from the connection point.

Parameters:

handle
The remote protocol handle.
result
The accepted Environment handle.
timeoutMilliseconds
The timeout in milliseconds.

Returns

NzaeRemprotRcCode

The return code.

The caller has ownership of the returned handle. Waits for a connection for the given number of mill-seconds.

void nzaeRemprotClose(NZAEREMPROT_HANDLE handle)

Closes a listener.

Parameters:

handle
The remote protocol handle.

NzaeRemprotRcCode nzaeRemprotCreateListener(NzaeremprotInitialization *args)

Creates a new listener on a connection point.

Parameters:

NzaeremprotInitialization args
The initalization arguments.

Returns

NzaeRemprotRcCode

The return code.

void nzaeRemprotFreeResources(NZAEREMPROT_HANDLE handle)

Releases resources such as handles and memory without shutting down the underlying communication connection.

Parameters:

handle
The remote protocol handle.
Usually called by a child process forked from a Remote AE parent. Note that nzaeRemprotFreeResources and nzaeRemprotClose are never called in the same process. Typically nzaeRemprotClose is called in a Remote AE.

int nzaeRemprotGetAcceptSocket(NZAEREMPROT_HANDLE handle)

Returns the socket used to accept Remprot commands.

Parameters:

handle
The remote protocol handle.

Returns

The remote socket.

Once identified, the socket can be used with Linux select or poll.

NzaeRemprotCallback nzaeRemprotGetCallback(NZAEREMPROT_HANDLE handle, void **userContext)

Gets the Remote protocol Callback. A remote protocol handler function is used to handle re-mote commands such as stop and status.

Parameters:

handle
The remote protocol handle.
userContext
The returned argument to callback.

Returns

NzaeRemprotCallback

The callback.

NzaeApiTypes nzaeRemprotGetEnvironmentApiType(NZAEENV_HANDLE hEnv)

Gets the API type from the environment.

Parameters:

hEnv
The Environment handle.

Returns

NzaeApiTypes

API type.

char* nzaeRemprotGetLastErrorText(NZAEREMPROT_HANDLE handle)

Gets the API type from the environment.

Parameters:

handle
The remote protocol handle.

Returns

The message text of the last occurring error.

int32_t nzaeRemprotGetRemoteDataSliceId

Gets the remote dataslice ID from the environment.

Returns

The remote dataslice ID.

Set if the AE launcher is used. Returns -1 if a dataslice ID is not found.

const char* nzaeRemprotGetRemoteName()

Gets the remote name from the environment.

Returns

The remote dataslice ID.

The Remote Name.

Set if the AE launcher is used. Returns NULL if a name is not found.

int32_t nzaeRemprotGetRemoteSessionId()

Gets the remote session ID from the environment.

Returns

The remote session ID.

Set if the AE launcher is used. Returns -1 if a session ID is not found.

int64_t nzaeRemprotGetRemoteTransactionId()

Gets the remote transaction ID from the environment.

Returns

The remote session ID.

Set if the AE launcher is used. Returns -1 if a session ID is not found.

int nzaeRemprotIsError(NZAEREMPROT_HANDLE handle)

Returns TRUE if an error has occurred; FALSE if not.

Parameters:

handle
The remote protocol handle.

Returns

TRUE if an error occurred.

void nzaeRemprotSetCallback(NZAEREMPROT_HANDLE handle, NzaeRemprotCallback callback, void *userContext)

Sets the Remote Protocol Callback. A remote protocol handler function is used to handle remote com-mands such as stop and status.

Parameters:

handle
The remote protocol handle.
NzaeRemprotCallback callback
The callback function.
userContext
The argument to callback.

NzaeRemprotRcCode nzaeRemprotWaitForPingOrStop(NZAEREMPROT_HANDLE handle, int *bStop-Command)

Waits for ping or stop.

Parameters:

handle
The remote protocol handle.
bStopCommand
The pointer to the returned boolean, which indicates whether the AE is stopped.

Returns

NzaeRemprotRcCode

The return code.

This function is not used in a normal data-driven Remote AE. The code to accept AE APIs and AE Environments by default services ping and stop requests.

Thus, this function is only used in a launched Remote AE used as a control program, not as a true data AE. A launched Remote AE calls this function once on execution to satisfy the Netezza system AE launcher.

You can handle subsequent pings and stops in one of the two following ways:

Use a dedicated thread that invokes the nzaeRemprotWaitForPingOrStop command while the function waits indefinitely until it receives a message or is interrupted. When the function is in the wait state, it returns if it is interrupted by a signal even if no ping or stop message is re-ceived.

Use the select() or poll() C function calls on the AE Remote Protocol (remprot) accept socket file descriptor to check for pending actions with an appropriate timeout. If a pending action is detected, call the nzaeRemprotWaitForPingOrStop command, which does not block and should return a boolean value immediately. If no pending actions are detected via select or poll, regular operations are done and the call to nzaeRemprotWaitForPingOrStop is skipped. The whole process will then repeat.

When using this function, be careful of race conditions.

bStopCommand evaluates to TRUE if a stop request has been received, otherwise it is FALSE.

Enumeration type documentation

enum NzaeRemprotCmd: Remote AE Messages. Only NZAE_REMPROT_CMD_STATUS, NZAE_REMPROT_CMD_STOP, NZAE_REMPROT_CMD_SIGNAL, and NZAE_REMPROT_CMD_CONTROL_DATA are received by a user call back function.
NZAE_REMPROT_CMD_REQUEST
NZAE_REMPROT_CMD_PING
NZAE_REMPROT_CMD_STATUS: The Remote AE is queried for status. Status data may be re-turned.
NZAE_REMPROT_CMD_STOP: The Remote AE is being stopped.
NZAE_REMPROT_CMD_CONTROL_DATA: The Remote AE is being sent control data. Data may be returned.
NZAE_REMPROT_CMD_SIGNAL: The Remote AE has received a supported signal.
enum NzaeRemprotRcCode: Remote Protocol return codes.
NZAEREMPROT_RC_ERROR
NZAEREMPROT_RC_NORMAL
NZAEREMPROT_RC_TIMEOUT