Version 9.5 SP1
 —  EntireX C Wrapper  —

Using the C Wrapper


Using the C Wrapper for the Client Side

The C Wrapper provides access to RPC-based components from C applications and enables users to develop both clients and server. This section introduces the various possibilities for RPC-based client applications written in C.

Using the C Wrapper in Single-threaded Environments (UNIX, Windows)

This mode applies to UNIX and Windows.

graphics/cWrapper_batch.png

(1) For generation, see Generate C Source Files from Software AG IDL Files.

In this scenario, the C RPC client customer application, every generated interface object and the RPC C runtime library (erx) are linked (bound) together to an executable application.

Start of instruction setTo use the C Wrapper in single-threaded environments

  1. Generate the RPC client, see Generate C Source Files from Software AG IDL Files

  2. If necessary, use FTP to transfer your application and the interface object(s) to the target platform where you write your application.

  3. Write your application. See Writing a Single-threaded C RPC Client Application.

  4. If necessary, transfer your application and the client interface object(s) to the target platform where you compile your application, using FTP.

  5. Using a C compiler supported by the C Wrapper and compile

    Use the standard C/C++ compiler of your target platform. Please note platform-specific settings and see also the README.TXT file of the Delivered Examples for the C Wrapper.

  6. Using the linker (binder), link (bind)

    Use the standard C/C++ linker of your target platform. Please note platform-specific settings and see also the README.TXT file of the Delivered Examples for the C Wrapper.

Using the C Wrapper in Multithreaded Environments (UNIX, Windows)

This mode applies to UNIX and Windows.

graphics/cWrapper_batch.png

(1) For generation, see Generate C Source Files from Software AG IDL Files.

In this scenario, the C RPC client customer application, every generated client interface object and the RPC C runtime library (erx) are linked (bound) together to an executable application.

Start of instruction setTo use the C Wrapper in multithreaded environments

  1. Generate the RPC Client, see Generate C Source Files from Software AG IDL Files

  2. If necessary, transfer your application and the client interface object(s) to the target platform where you write your application, using FTP.

  3. Write your multithreaded C RPC Client application, see Programming Multithreaded RPC Clients.

  4. If necessary, transfer your application and the client interface object(s) to the target platform where you compile your application, using FTP.

  5. Using a C compiler supported by the C Wrapper, compile:

    Use the standard C/C++ compiler of your target platform. Please note platform-specific settings and see also the README.TXT file of the Delivered Examples for the C Wrapper.

  6. Using the linker (binder), link (bind)

    Use the standard C/C++ linker of your target platform. Please note platform-specific settings and see also the README.TXT file of the Delivered Examples for the C Wrapper.

Top of page

Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000/OSD, IBM i)

The C Wrapper provides access to RPC-based components from C applications and enables users to develop both clients and server. This section introduces the various possibilities for RPC-based server applications written in C.

This section applies to the operating systems z/OS, UNIX, Windows, BS2000/OSD and IBM i.

graphics/cWrapper_ims.png

(1) For generation, see Generate C Source Files from Software AG IDL Files.

For C, the RPC server works with server interface objects. Your server is called dynamically using standard call interfaces.

Start of instruction setTo use the C Wrapper

  1. Generate the RPC Server, see Generate C Source Files from Software AG IDL Files, and

  2. If necessary, use FTP to transfer your server (skeleton) and the server interface object(s) to the target platform where you write your application.

  3. Use the generated server (skeleton) and complete it by applying your application logic. To prevent loss of implementation code when re-generating, we suggest the following before you add any implementation code to the server (skeleton):

  4. If necessary, transfer your server and the server interface object(s) to the target platform where you compile your application, using FTP. The objects to be transfered depend on the platform:

  5. With a C compiler supported by the C Wrapper, compile the following objects, depending on the platform:

  6. Using the linker (binder), link (bind) the following objects, depending on the platform:

  7. Provide the interface object library and the server library accessible to the RPC server according to the rules of your operating system.

Top of page

Generate C Source Files from Software AG IDL Files

This section describes how to generate C source files from Software AG IDL files. It covers the following topics:

Select an IDL File and Generate RPC Client or RPC Server

From the context menu, choose Generate C from Software AG IDL > RPC Client and ... > RPC Server to generate the C source files.

graphics/select_idl.png

For the RPC client

For the RPC server

For both RPC client and RPC server

Settings

Use the properties of the IDL file - initialized from the C Wrapper preference page when used for the first time - to manipulate the mapping between Software AG IDL and the C source. A multithreaded client can be enforced.

Client settings

graphics/client_settings.png

Server settings

graphics/server_settings.png

Mapping Options

Select the mapping options according to your needs. All mapping options are available for RPC clients and RPC server.

Option Description
Map IDL N, P, NU and PU fields to double

If the check box is checked, the IDL data types N, NU, P and PU are mapped to the C data type double.

If the check box is not checked, the IDL data type:

  • N and NU are mapped to the C data type unsigned char[..] with unpacked (mainframe Natural, COBOL, PL/I style) contents.

  • P and PU are mapped to the C data type unsigned char[..] with packed (mainframe Natural, COBOL, PL/I style) contents.

Map IDL A fields to C style strings (null terminated)

If the check box is marked, the IDL data type A is mapped to a C style string (C data type char[.. + 1] with null termination). This is recommended and comfortable for C programmers and is intended to be used with the C str... functions. This mapping does not allow use of trailing blanks and null values to send/receive.

If the check box is not marked, the IDL data type A is mapped to the C data type unsigned char[..] without null termination (mainframe Natural, COBOL, PL/I style). This allows the use of trailing blanks, null values and is intended to be used with the C mem... functions.

Map IDL U fields to wide char strings (null terminated)

If the check box is marked, the IDL data type U is mapped to a C style wide character string ( C data type wchar_t[.. + 1] with null termination). This is recommended and comfortable for C programmers and is intended to be used with the C wcs... functions. This mapping does not allow use of trailing wide character blanks (Unicode character x3000) and null values (x0000) to send/receive.

If the check box is not marked, the IDL data type U is mapped to the C data type unsigned wchar_t[..] without null termination (mainframe Natural, COBOL, PL/I style). This allows the use of trailing blanks, null values and is intended to be used with the C mem... functions.

If the settings for the client side need to be different from the settings for the server side, generate the RPC client in a directory other than the RPC server directory.

Generate RPC Client

Select the Multithreaded Client option according to your needs.

Option Description
Multithreaded Client

If the check box is not marked, the generated client interface object(s) can be used in single-threaded client environments. Use this option if you want to build an RPC client application as described under Using the C Wrapper in Single-threaded Environments (UNIX, Windows).

If the check box is marked, the generated client interface object(s) are thread-safe and can be used in multithreaded client environments. Use this option if you want to build an RPC client application as described under Using the C Wrapper in Multithreaded Environments (UNIX, Windows).

Generate RPC Server

If you want to build an RPC server application, follow the instructions given under Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000/OSD, IBM i).

Top of page