This section introduces the WTX C API and provides an extensive code example. To experiment interactively with the WTX protocol, you may wish to work through the examples given in the 4.4 WTX Tcl API. All WTX primitives are available to both APIs; thus a single detailed explanation of many items that are common to both the Tcl and C APIs is included in that section.

The WTX C API is a binding of the WTX protocol to the ANSI C language. This allows C applications to call target server services. Every WTX protocol request is accessible through the WTX C interface.

There is a WTX C routine for each WTX protocol request. For example, the C function wtxMemRead( ) corresponds to WTX_MEM_READ. The names of all WTX C routines are derived from the protocol request names according to the VxWorks Programmer's Guide: Coding Conventions; in other words, underscores are removed and all words but the first are capitalized.

Each WTX C interface has an online reference entry under Tornado API Guide>WTX C Library. For information on the online reference material, see the Tornado User's Guide: Documentation Guide and Tornado Getting Started. All WTX C routines provide access to error status through wtxErrorGet( ). Throughout the remainder of this section, please refer to the reference entries for more information on the WTX C API.

The WTX C API is archived in installDir/host/hostType/lib/libwtxapi. For a complete description of the use of this library to build a Tornado application see 6. Adding Tools to Tornado.

Before connecting an application to a particular target server you must initialize a session by calling wtxInitialize( ). The following code example initializes the specified session handle wtxh:

include "wtx.h" 
... 
{ 
HWTX                wtxh; 
... 
/* initialize session */ 
 
if (wtxInitialize (&wtxh) != OK) 
    return (ERROR);

The Tornado registry maintains information about executing target servers. To find the list of registered target servers, you can call wtxInfoQ( ). To find information on a particular target server, you can call wtxInfo( ).

#include "wtx.h" 
... 
WTX_DESC * pWtxDesc; /* target server information */ 
... 
/* get information about a target server using the Tornado registry*/ 
 
if ((pWtxTsInfo = wtxInfo (wtxh, "tJohn")) == NULL) 
    return (ERROR); 
...

An application must bind an initialized handle to an executing target server before the majority of the WTX C interface routines can be called. This can be accomplished calling wtxToolAttach( ), which takes an initialized HWTX handle, a regular expression, and a tool name. The regular expression must uniquely match a registered server for the binding to succeed. The tool name is the application name. The target server records it and reports this name to any tool that requests a list of attached tools with wtxTsInfoGet( ).

#include "wtx.h" 
... 
/* attach to a target server */ 
 
if (wtxToolAttach (wtxh, "tJohn.*", "newapp") != OK) 
    { 
    wtxTerminate (wtxh); /* terminate session */ 
    return (ERROR); 
    } 
...

The following code examples demonstrate a complete application of the WTX C API. This application attaches to the specified target server and allocates and de-allocates target memory in an endless cycle. Note that the number of blocks to allocate is specified in a separate header file to conform to the Wind River coding conventions. For more information about compiling this example see 6. Adding Tools to Tornado.

To observe this application, start the target browser as well as the application:

% wtxapp targetServerName & 
% browser targetServerName &

If you place the browser in auto-update mode, the memory usage charts demonstrate the functionality of this simple application. On UNIX, if the Tornado launcher is running and your target server is selected, you can observe wtxapp in the list of attached tools.

Example 4-2:  WTX C API Application

/* wtxapp.h - Simple WTX C API application header */ 
 
/* Copyright 1995-99 Wind River Systems, Inc. */ 
 
/* 
modification history 
-------------------- 
01a,08apr95-99,p_m  written 
*/ 
 
/* defines */ 
 
#define NUM_BLOCKS 26           /* number of memory blocks to allocate */

---

/* wtxapp.c - Simple WTX C API application */ 
 
/* Copyright 1995-99 Wind River Systems, Inc. */ 
 
/* 
modification history 
-------------------- 
01c,05jan99,fle doc : made it documentable 
01b,11jul95,p_m  implemented better error reporting and added comments 
                                 added signals handling 
 
01a,08apr95,p_m  written 
*/ 
 
#include <signal.h> 
#include <stdio.h> 
#include "host.h" 
#include "wtx.h" 
#include "wtxapp.h" 
 
/*  
DESCRIPTION 
 
This is a simple program demonstrating the use of the WTX C API.  It  
attaches to a target server and allocates and free memory from the target 
memory pool managed by the target server. 
 
SEE ALSO 
tgtsvr, wtxtcl, wtx, WTX 
*/ 
 
/* defines */ 
 
/* globals */ 
 
HWTX             wtxh;                   /* WTX API handle */ 
TGT_ADDR_T       blockTab[NUM_BLOCKS];   /* allocated blocks table */ 
 
/* forward declarations */ 
 
LOCAL STATUS        wtxAppSigInit (void); 
 
#ifdef WIN32 
    BOOL WINAPI     wtxAppSigHandler (DWORD dwCtrlType); 
#else 
    LOCAL void      wtxAppSigHandler (int signal, int code); 
#endif 
LOCAL void          wtxAppTerminate (void); 
 
/*********************************************************************** 
* 
* wtxapp - Simple WTX application example 
* 
* This is a simple WTX tool example showing the WTX C API.  It 
* allocates blocks of memory from the target-server-managed target memory 
* pool then frees them.  The effects of this program can be easily 
* viewed by using a Tornado browser attached to the same target server. 
*/ 
 
int main  
    ( 
    int             argc,       /* number of arguments */ 
    char *          argv[]      /* table of arguments */ 
    ) 
    { 
    UINT32          ix = 0;     /* useful counter */ 
    UINT32          blockSize;  /* size of a memory block */ 
    WTX_MEM_INFO *  pMemInfo;   /* target memory pool info */ 
 
    /* check input arguments */ 
 
    if (argc != 2)  
        { 
        printf ("Usage: wtxapp targetServerName\n"); 
        exit(0); 
        } 
      
    /*  
    * Initialize signal handlers. This is necessary to avoid a tool 
    * killed via Control-C or another signal remaining attached to a  
    * target server. 
    */ 
 
    if (wtxAppSigInit() != OK) 
        { 
        printf ("Error: cannot initialize signal handler\n"); 
        exit (0); 
        } 
 
    /* initialize WTX session */ 
 
    if (wtxInitialize (&wtxh) != OK) 
        { 
        printf ("Error: cannot initialize WTX API\n"); 
        exit (0); 
        } 
 
    /* attach to target server */ 
 
    if (wtxToolAttach (wtxh, argv[1], "wtxapp") != OK) 
        { 
        printf ("Error: cannot attach to target server: %s\n", argv[1]); 
        wtxTerminate (wtxh); 
        exit (0); 
        } 
 
    printf ("Attaching to target server done\n"); 
 
    /* register for events we want to hear about */ 
 
    if (wtxRegisterForEvent (wtxh, ".*") != OK) 
        { 
        printf ("Error: cannot register for events\n"); 
        wtxAppTerminate (); 
        } 
 
    /* get memory pool information */ 
 
    if ((pMemInfo = wtxMemInfoGet (wtxh)) == NULL) 
        { 
        printf ("Error: cannot get target memory information\n"); 
        wtxAppTerminate (); 
        } 
 
    printf ("Starting target memory allocate/free demonstration\n"); 
    printf ("Type Control-C to stop\n"); 
 
    /* allocate approx. 1/NUM_BLOCKS of the biggest available blocks */ 
 
    blockSize = pMemInfo->biggestBlockSize / NUM_BLOCKS - 200; 
 
    for (;;) 
        { 
        /* allocate blocks */ 
 
        for (ix = 0; ix < NUM_BLOCKS; ix++) 
            { 
            printf ("Allocating block #%02d\r", ix+1); 
            blockTab [ix] = wtxMemAlloc (wtxh, blockSize); 
 
            if (blockTab[ix] == (TGT_ADDR_T) 0) 
                { 
                printf ("Error: cannot allocate target memory\n"); 
                wtxAppTerminate (); 
                } 
 
            #ifdef WIN32 
                Sleep (1000);       /* wait 1 second */ 
            #else 
                sleep (1);          /* wait 1 second */ 
            #endif 
                fflush (stdout); 
            } 
 
        /* free blocks */ 
 
        for (ix = 0; ix < NUM_BLOCKS; ix++) 
            { 
            printf ("Freeing block #%02d   \r", ix+1); 
 
            if (wtxMemFree (wtxh, blockTab [ix]) != OK) 
                { 
                printf ("Error: cannot free target memory\n"); 
                wtxAppTerminate (); 
                } 
            blockTab [ix] = (TGT_ADDR_T) 0;      
            #ifdef WIN32 
                Sleep (1000);       /* wait 1 second */ 
            #else 
                sleep (1);          /* wait 1 second */ 
            #endif 
            fflush (stdout); 
            } 
        } 
    return 0; 
    } 
 
/******************************************************************* 
* 
* wtxAppSigInit - initialize signal handlers 
* 
* wtxAppSigInit() installs the signal handlers needed by wtxapp. 
* 
* RETURNS: N/A 
*/ 
 
STATUS wtxAppSigInit (void) 
    { 
    #ifndef WIN32 
        int                 ix; 
        struct sigaction    sv; 
        struct sigaction    bb; 
 
        /* setup default signal handler */ 
 
        sv.sa_handler = (VOIDFUNCPTR) wtxAppSigHandler; 
        sigemptyset (&sv.sa_mask); 
        sv.sa_flags   = 0; 
 
        for (ix = SIGHUP; ix < SIGALRM; ix++)   /* capture errors */ 
            sigaction (ix, &sv, &bb); 
 
        sigaction (SIGTERM, &sv, &bb);          /* terminate */ 
    #else 
        SetConsoleCtrlHandler(wtxAppSigHandler, TRUE);  /* trap signals */ 
    #endif 
    return OK; 
    } 
 
/********************************************************************* 
* 
* wtxAppTerminate - terminate wtxapp properly 
* 
* This routine performs all necessary cleanup required when an attached tool 
* finishes a WTX session with a target server.  
* 
* RETURNS: N/A 
*/ 
 
LOCAL void wtxAppTerminate (void) 
    { 
    int ix; 
 
    printf ("\nFreeing all the memory blocks\n"); 
    for (ix = 0; ix < NUM_BLOCKS; ix++) 
        { 
        if (blockTab [ix] != (TGT_ADDR_T) 0) 
            { 
            wtxMemFree (wtxh, blockTab [ix]); 
            } 
        } 
    wtxToolDetach (wtxh);           /* detach from target server */ 
    wtxTerminate (wtxh);            /* terminate WTX session */ 
 
    exit (0);                               /* bye */ 
    } 
 
/******************************************************************* 
* 
* wtxAppSigHandler - wtxapp signal handler 
* 
* This function is the signal handler for wtxapp.  It calls 
* wtxAppTerminate() to perform the WTX session closing. 
* 
* RETURNS: N/A 
*/ 
 
#ifdef WIN32 
    BOOL WINAPI wtxAppSigHandler  
    ( 
    DWORD                   dwCtrlType 
    ) 
#else 
    LOCAL void wtxAppSigHandler  
    ( 
    int                             signal, 
    int                             code 
    ) 
#endif 
 
    { 
    wtxAppTerminate ();             /* terminate session cleanly */  
    #ifdef WIN32 
    return 0; 
    #endif 
    }