wtx.html

vxworks相关论文

            }

    /* Catch any other errors in one handler and print error message */

    WTX_CATCH_ALL (hWtx)
        fprintf (stderr, "%s\n", wtxErrMsgGet (hWtx));

    /* Finish the try block and resume normal error handling */

    WTX_TRY_END (hWtx);

    /*
     * Normal error handling is now restored - the WTX_TRY_END macro
     * must be executed for this to occur.
     */
     
    /* wtxTerminate() will also detach the tool if already attached */

    wtxTerminate (hWtx);
</pre>

In certain circumstances, it may be useful to generate a user-defined
error or to simulate an API error from within user code. This may be
done using the <b>WTX_THROW</b> macro, which causes execution to jump to the
nearest handler for the error thrown or to the nearest "catch all"
handler.
<p>
Many of the C API calls are very similar to the equivalent WTX
protocol calls and the user may also refer to the appropriate section
in the <i>WTX Protocol</i> reference for further information.
<p>
</blockquote><h4>INCLUDE FILES</h4><blockquote><p>
<b>wtx.h</b>
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./wtx.html#top">wtx</a></b>

<hr>
<a name="wtxToolAttach"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxToolAttach</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxToolAttach</i>(&nbsp;)</strong> - connect a WTX client to the target server</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wtxToolAttach
    (
    HWTX         hWtx,       /* WTX API handle */
    const char * serverName, /* Target Server name */
    const char * toolName    /* tool name */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine establishes a connection to the target server
called <i>serverName</i> and announces the client as a WTX tool called
<i>toolName</i>. If <i>serverName</i> does not contain an <b>@</b> character, it is
used as a regular expression; if it matches more than one (registered)
target server name, an error is returned.  If <i>serverName</i> contains 
an <b>@</b> character then it must be an exact match for a valid target 
server name.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<b>WTX_OK</b> or <b>WTX_ERROR</b> if the attach fails.
<p>
</blockquote><h4>ERRORS</h4><blockquote><p>
<p>
<dl>
<dt>
<b>WTX_ERR_API_ALREADY_CONNECTED</b>
<dd>

The handle is already connected to a target server.
<p>
<dt>
<b>WTX_ERR_API_SERVER_NOT_FOUND</b>
<dd>

<i>serverName</i> does not match a target server name using the above criteria.
<p>
<dt>
<b>WTX_ERR_API_AMBIGUOUS_SERVER_NAME</b>
<dd>

<i>serverName</i> matches more than one target server name.
<p>
<dt>
<b>WTX_ERR_SVR_DOESNT_RESPOND</b>
<dd>

<i>serverName</i> is dead : no RPC connection can be achieved
<p>
<dt>
<b>WTX_ERR_SVR_IS_DEAD</b>
<dd>
 <i>serverName</i> is dead : server has been found dead
<p>
</dl>

</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="../wtxpcl/wtx.html#WTX_TOOL_ATTACH" >WTX_TOOL_ATTACH</a></b>, <b><i><a href="./wtx.html#wtxToolDetach">wtxToolDetach</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxToolConnected">wtxToolConnected</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxInfoQ">wtxInfoQ</a></i>(&nbsp;)</b>

<hr>
<a name="wtxToolConnected"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxToolConnected</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxToolConnected</i>(&nbsp;)</strong> - check to see if a tool is connected to a target server</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>BOOL32 wtxToolConnected
    (
    HWTX hWtx /* WTX API handle */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine checks if the tool represented by <i>hWtx</i> is currently
connected to a target server. 
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
If <i>hWtx</i> is an invalid handle then FALSE is returned.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
TRUE if the tool is connected, FALSE otherwise.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><i><a href="./wtx.html#wtxErrClear">wtxErrClear</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxErrGet">wtxErrGet</a></i>(&nbsp;)</b>

<hr>
<a name="wtxToolDetach"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxToolDetach</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxToolDetach</i>(&nbsp;)</strong> - detach from the target server</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wtxToolDetach
    (
    HWTX hWtx /* WTX API handle */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine detaches from the target server. 
The connection status for <i>hWtx</i> is cleared and any memory
allocated by the tool attach is freed. 
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
Even if the detach fails internally (for example, the server
it is attached to has died), the API still puts the handle into a
detached state and performs all necessary internal cleanup. In this
case the internal error is <b>not</b> reported since the tool is no longer
attached and the handle can subsequently be attached to another server.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<b>WTX_OK</b> or <b>WTX_ERROR</b>.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="../wtxpcl/wtx.html#WTX_TOOL_DETACH" >WTX_TOOL_DETACH</a></b>, <b><i><a href="./wtx.html#wtxToolAttach">wtxToolAttach</a></i>(&nbsp;)</b>

<hr>
<a name="wtxInitialize"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxInitialize</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxInitialize</i>(&nbsp;)</strong> - initialization routine to be called by the WTX client</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wtxInitialize
    (
    HWTX * phWtx /* RETURN: handle to use in subsequent API calls */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine allocates a handle structure for the tool's use and
does any initialization required for use of the WTX interface.  All
subsequent calls by the tool should use the handle returned in <i>phWtx</i>.
If <b>WTX_ERROR</b> is returned and the handle <i>phWtx</i> is zero, then the
initialization failed because the internal handle structure could
not be allocated. Otherwise use <b><i><a href="./wtx.html#wtxErrMsgGet">wtxErrMsgGet</a></i>(&nbsp;)</b> to find the cause
of the error.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<b>WTX_OK</b> or <b>WTX_ERROR</b> if the initialization fails.
<p>
</blockquote><h4>ERRORS</h4><blockquote><p>
<p>
<dl>
<dt>
<b>WTX_ERR_API_INVALID_ARG</b>
<dd>

The pointer <i>phWtx</i> is NULL.
<p>
<dt>
<b>WTX_ERR_API_MEMALLOC</b>
<dd>
 The handle cannot be allocated.
<p>
</dl>

</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><i><a href="./wtx.html#wtxTerminate">wtxTerminate</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxVerify">wtxVerify</a></i>(&nbsp;)</b>

<hr>
<a name="wtxTerminate"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxTerminate</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxTerminate</i>(&nbsp;)</strong> - terminate the use of a WTX client handle</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wtxTerminate
    (
    HWTX hWtx /* WTX API handle */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine destroys the specified context handle so it may no
longer be used in WTX API calls.  If the tool is attached to a
target server, it is first detached. (It is forcibly detached if
errors make a normal detach impossible.)  Any memory allocated by 
the handle is freed and the handle is invalidated; any subsequent 
use causes an abort.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<b>WTX_OK</b> or <b>WTX_ERROR</b>.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><i><a href="./wtx.html#wtxInitialize">wtxInitialize</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxVerify">wtxVerify</a></i>(&nbsp;)</b>

<hr>
<a name="wtxErrSet"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxErrSet</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxErrSet</i>(&nbsp;)</strong> - set the error code for the handle</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS wtxErrSet
    (
    HWTX   hWtx,   /* WTX API handle */
    UINT32 errCode /* error value to set */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine sets the error value <i>errCode</i> in the handle specified 
by <i>hWtx</i> so that <b><i><a href="./wtx.html#wtxErrGet">wtxErrGet</a></i>(&nbsp;)</b> can return <i>errCode</i> as the error.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
Error handlers for the handle are not called. To set the error
code and call the registered error handlers, use <b><i><a href="./wtx.html#wtxErrDispatch">wtxErrDispatch</a></i>(&nbsp;)</b>.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
<b>WTX_OK</b> or <b>WTX_ERROR</b>.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><i><a href="./wtx.html#wtxErrGet">wtxErrGet</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxErrMsgGet">wtxErrMsgGet</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxErrClear">wtxErrClear</a></i>(&nbsp;)</b>, <b><i><a href="./wtx.html#wtxErrDispatch">wtxErrDispatch</a></i>(&nbsp;)</b>.

<hr>
<a name="wtxErrGet"></a>
<p align=right>
<a href="rtnIndex.html"><i>WTX C Library :  Routines</i></a></p>

</blockquote><h1><i>wtxErrGet</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>wtxErrGet</i>(&nbsp;)</strong> - return the last error for a handle</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>WTX_ERROR_T wtxErrGet
    (
    HWTX hWtx /* WTX API handle */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine returns the last error that occurred for the <i>hWtx</i> handle.
The error code is only valid after an error is reported by one of the
API calls. To check for an error after a series of API calls use 
<b><i><a href="./wtx.html#wtxErrClear">wtxErrClear</a></i>(&nbsp;)</b> to clear the error status at the start and call <b><i><a href="./wtx.html#wtxErrGet">wtxErrGet</a></i>(&nbsp;)</b>