This document describes in six steps how to write your first C client program.
The example given here demonstrates how to write a single-threaded C RPC
client application. It demonstrates an implicit broker logon (because no broker
logon/logoff calls are implemented), where it is required to switch on the
AUTOLOGON feature in the broker attribute file.
The following steps describe how to write a single-threaded C client program. We recommend reading them first before writing your first RPC client program and following them where appropriate.
Define the generated client header file. This header file includes the RPC runtime header file erx.h and defines structures and prototypes for your RPC requests.
/* include generated header file */ #include "example.h"
For single-threaded clients you have to declare in your main program the following global variables, used for communication with the interface objects:
/* Needed global variables for the CLIENT interface object */ ERXCallId ERXCallId; ERXeReturnCode ERXrc; ERX_ERROR_INFO ERXErrorInfo; ERX_Server_ADRESS ERXServer; ERX_CLIENT_IDENTIFICATION ERXClient;
For implicit broker logon, if required in your environment, the client password can be given here. It is provided then through the interface object call.
/* set client identification */ memset( &ERXClient, 0, sizeof(ERXClient) ); strcpy( (char*) ERXClient.szUserId, "ERX-USER" ); strcpy( (char*) ERXClient.szPassword, "ERX_PASS");
Your application will wait a maximum of 55 seconds for a server response. If the server does not answer within this period, the broker gives your program control again with an error code 00740074.
ERXServer.Medium = ERX_TM_BROKER; ERXServer.ulTimeOut = 55; /* set Broker-Id, server-name, class-name and service-name */ strcpy( (char*) ERXServer.Address.BROKER.szEtbidName, "ETB001" ); strcpy( (char*) ERXServer.Address.BROKER.szServerName, "SRV1" ); strcpy( (char*) ERXServer.Address.BROKER.szClassName, "RPC" ); strcpy( (char*) ERXServer.Address.BROKER.szServiceName, "CALLNAT" );
As a general rule, before using the RPC runtime you have to register it. After registration, the RPC runtime holds information on a per-thread basis. See Using the RPC Runtime for more information.
/* register to the RPC runtime */
ERXrc = ERXRegister( ERX_V81 );
If ( ERX_FAILED( ERXrc ) )
{
/* code for error handling */
}
The RPC interface object CALC is called as C function (see
Calling Servers as Procedures or Functions).
/* do the remote procedure call */ result = CALC( '+', 123456, 78910 );
When a return from the RPC request has been received, check whether the call was successful with the macro ERX_FAILED.
if( ERX_FAILED( ERXrc ) )
{
/* code for error handling */
}
Detailed information about an error can be retrieved with the function
ERXGetLastError. For the error messages returned, see Error Messages and Codes.
As a general rule, after using the RPC runtime you should unregister from it. This will free all resources held by the RPC runtime for the caller. See Using the RPC Runtime for more information.
/* unregister to the RPC runtime */ ERXUnregister();