Returns the text representation of an error, reason, event, or command code from a particular Natural Access Server.
DWORD ctaGetTextEx ( char addr, CTAHD ctahd, unsigned code, char *buffer, unsigned size)
|
Argument |
Description |
|
addr |
Natural Access Server address. |
|
ctahd |
Context handle. Use a void context handle if the text is not associated with a context or a context is not available. |
|
code |
Natural Access code (either a general code or a code defined by a Natural Access service). |
|
buffer |
Pointer to a buffer to receive the text string. buffer should contain a minimum of 40 characters. |
|
size |
Size of buffer in bytes. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
buffer is NULL. |
|
CTAERR_BAD_SIZE |
size is too small to receive the text. |
|
CTAERR_INVALID_CTAHD |
An invalid context handle was passed as an argument to a function, or the context was destroyed by another thread. |
|
CTAERR_NOT_FOUND |
Service to translate code is not found. |
|
CTAERR_NOT_IMPLEMENTED |
Function is not available in the execution mode associated with the specified context. |
|
CTAERR_NOT_INITIALIZED |
Natural Access is not initialized. Call ctaInitialize first. |
|
CTAERR_SVR_COMM |
Server communication error. |
ctaGetTextEx returns a text string in buffer corresponding to the Natural Access error, reason, event, or command code. If ctahd is a valid context, this function retrieves the text string from the server associated with the context.
ctahd can be a void context handle. A void context handle refers only to the server on which the commands are executed and not to any real context object. Each server has a unique void context handle.
If a void context handle is used for ctahd, ctaGetTextEx retrieves the text string from the global defaults and executes on the server specified by the void context handle. Global defaults are either statically defined values maintained within a process or dynamically defined values maintained by the Natural Access Server.
If the context handle is equal to NULL_CTAHD, the function retrieves the text string from the server specified by addr. If addr is equal to NULL or is an empty string, the function retrieves the text string from the default server.
The size argument specifies the amount of available memory at the buffer and must be large enough to contain the returned text string.
Refer to Handling Natural Access errors for more information.
void DemoShowError( char *preface, DWORD errcode )
{
char text[40];
ctaGetTextEx( "localhost", NULL_CTAHD, errcode, text, sizeof(text) );
printf( "\t%s: %s\n", preface, text );
}