Modeler Extensions Framework
API Service Functions to be implemented by the extension module.

Functions

CLEMEXT_API CLEMEXTStatus clemext_initialise (CLEMEXTHostHandle host, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_cleanup (CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_getModuleInformation (char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_create_peer (CLEMEXTNodeHandle node, int nodeType, const char *nodeId, CLEMEXTPeerHandle *peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_destroy_peer (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_configure (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getDataModel (CLEMEXTPeerHandle peer, int mode, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getExecutionRequirements (CLEMEXTPeerHandle peer, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getCatalogueInformation (CLEMEXTPeerHandle peer, const char *catalogId, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_beginExecution (CLEMEXTPeerHandle peer, CLEMEXTIteratorHandle iterator, CLEMEXTProgressHandle listener, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_endExecution (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_cancelExecution (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_nextRecord (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getRecordValue (CLEMEXTPeerHandle peer, size_t index, void **value, size_t *value_length, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getSQLGeneration (CLEMEXTPeerHandle peer, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getErrorDetail (CLEMEXTPeerHandle peer, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_beginInteraction (CLEMEXTPeerHandle peer, CLEMEXTChannelHandle channel, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_endInteraction (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_request (CLEMEXTPeerHandle peer, const char *request, size_t request_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getRequestReply (CLEMEXTPeerHandle peer, char *reply_buffer, size_t reply_buffer_size, size_t *reply_data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_getPsmControlInformation (CLEMEXTPeerHandle peer, char *buffer, size_t buffer_size, size_t *data_size, CLEMEXTErrorCode *errorCode)
 
CLEMEXT_API CLEMEXTStatus clemext_peer_psmMerge (CLEMEXTPeerHandle peer, CLEMEXTErrorCode *errorCode)
 

Detailed Description

Function Documentation

CLEMEXT_API CLEMEXTStatus clemext_cleanup ( CLEMEXTErrorCode errorCode)

Called by the host when the module is unloaded

Parameters
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_create_peer ( CLEMEXTNodeHandle  node,
int  nodeType,
const char *  nodeId,
CLEMEXTPeerHandle *  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to create the peer

Parameters
nodehandle on the corresponding node in the host
nodeTypethe type of the node (reader,transformer,writer,etc)
nodeIdstring identifying the module (if extension supports multiple modules)
peerpointer to a peer handle to return the created peer object
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_destroy_peer ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to destroy the peer

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_getModuleInformation ( char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to collect information on the module

The details are passed back in XML form (see example)

Parameters
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_initialise ( CLEMEXTHostHandle  host,
CLEMEXTErrorCode errorCode 
)

Called by the host when the module is loaded

Parameters
hosta CLEMEXTHostHandle allowing the module to call host services
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_beginExecution ( CLEMEXTPeerHandle  peer,
CLEMEXTIteratorHandle  iterator,
CLEMEXTProgressHandle  listener,
CLEMEXTErrorCode errorCode 
)

Called by the host to indicate that execution should begin

Parameters
peerindicates which peer this call should be directed to
iteratorthe iterator that will provide input data to the module (NULL if node is a CLEMEXT_NODE_DATA_READER)
listenera listener that can be used to pass status information back to the host (clemext_progress_report)
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_beginInteraction ( CLEMEXTPeerHandle  peer,
CLEMEXTChannelHandle  channel,
CLEMEXTErrorCode errorCode 
)

Called by the host to indicate the start of interaction with a peer. If the call succeeds, the peer is interacting. The peer can use the supplied channel handle to pass asynchronous messages to the client node.

This is an optional function; its definition indicates that the peer supports interaction.

Parameters
peerindicates which peer this call should be directed to
channela channel of communication to the client node
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_cancelExecution ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to request that execution be interrupted

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_configure ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to instruct the peer to configure itself. The peer in turn will likely invoke the node callbacks clemext_node_getParameters and clemext_node_getDataModel during the exection of this call

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_endExecution ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to indicate that execution has ended

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_endInteraction ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to indicate the end of interaction with a peer. The call invalidates the channel handle supplied by clemext_peer_beginInteraction.

This function is required if the peer supports interaction.

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getCatalogueInformation ( CLEMEXTPeerHandle  peer,
const char *  catalogId,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to obtain catalogue information the catalogue details are passed back in XML form

Parameters
peerindicates which peer this call should be directed to
catalogIdthe id of the catalog requested
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getDataModel ( CLEMEXTPeerHandle  peer,
int  mode,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to obtain information on the module's ouptut data model. the data model details are passed back in XML form (see example)

Parameters
peerindicates which peer this call should be directed to
modeindicates if the data model returned is for QUERY or EXECUTE
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getErrorDetail ( CLEMEXTPeerHandle  peer,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to get information on an error

the error details are passed back in XML form (see example)

Parameters
peerindicates which peer this call should be directed to
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail on the problem
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getExecutionRequirements ( CLEMEXTPeerHandle  peer,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to obtain information on the module's execution requirements the details are passed back in XML form (see example)

Parameters
peerindicates which peer this call should be directed to
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getPsmControlInformation ( CLEMEXTPeerHandle  peer,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to retrieve a PsmControlInformation document after the execution of a PSM-protocol CLEF peer (acting as a PSM manager)

Parameters
peerindicates which peer this call should be directed to
bufferbuffer to recieve the returned document
buffer_sizethe length of the buffer, in bytes
data_sizereceives the length of the document, in bytes
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getRecordValue ( CLEMEXTPeerHandle  peer,
size_t  index,
void **  value,
size_t *  value_length,
CLEMEXTErrorCode errorCode 
)

Called by the host to get a field value from the current output record produced by the module

The value is returned in a pointer which is valid until the next call to clemext_peer_nextRecord or clemext_peer_endExecution

Parameters
peerindicates which peer this call should be directed to
indexthe position of the field in the input data model
valueaddress of pointer to set to the result value (or NULL)
value_lengththe number of bytes in the returned value
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getRequestReply ( CLEMEXTPeerHandle  peer,
char *  reply_buffer,
size_t  reply_buffer_size,
size_t *  reply_data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to retrieve the reply to a successful interactive request. The call is valid only while the peer is interacting, and when the last call to clemext_peer_request returned CLEMEXT_OK. The peer returns its reply in the reply buffer. If the reply buffer is too small to receive the request, the peer must set the required length in the reply_data_size and return CLEMEXT_ERR_INSUFFICIENT_BUFFER in which case the caller will resize the buffer and resubmit the call.

This function is required if the peer supports interaction.

Parameters
peerindicates which peer this call should be directed to
reply_bufferreceives the reply string from the peer
reply_buffer_sizethe length of the reply buffer, in bytes
reply_data_sizereceives the length of the reply string, in bytes
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_getSQLGeneration ( CLEMEXTPeerHandle  peer,
char *  buffer,
size_t  buffer_size,
size_t *  data_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to get information on an error

the error details are passed back in XML form (see example)

Parameters
peerindicates which peer this call should be directed to
bufferbuffer to receive the result
buffer_sizethe current size of the buffer in bytes
data_sizepointer to a value set to the number of bytes required to store the result in a buffer
errorCodea CLEMEXT error code providing more detail on the problem
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_nextRecord ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to request the next output record produced by the module

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_psmMerge ( CLEMEXTPeerHandle  peer,
CLEMEXTErrorCode errorCode 
)

Called by the host to instruct a peer to perform the merge phase of the PSM protocol

Parameters
peerindicates which peer this call should be directed to
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code
CLEMEXT_API CLEMEXTStatus clemext_peer_request ( CLEMEXTPeerHandle  peer,
const char *  request,
size_t  request_size,
CLEMEXTErrorCode errorCode 
)

Called by the host to perform an interactive request on a peer. The call is valid only while the peer is interacting. The request buffer contains the request string passed from the client node. If the call succeeds, the host will call clemext_peer_getRequestReply to retrieve the reply string.

This function is required if the peer supports interaction.

Parameters
peerindicates which peer this call should be directed to
requestthe request string from the client node
request_sizethe length of the request string, in bytes
errorCodea CLEMEXT error code providing more detail if a problem is encountered
Returns
CLEMEXT status code