The C Wrapper provides access to RPC-based components from C applications and enables you to develop both clients and servers. This section introduces the various possibilities for RPC-based client applications written in C.
Using the C Wrapper in Single-threaded Environments (UNIX, Windows)
Using the C Wrapper in Multithreaded Environments (UNIX, Windows)
This mode applies to UNIX and Windows.
(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.
To use the C Wrapper in single-threaded environments
Generate the RPC client, see Generate C Source Files from Software AG IDL Files
and select the Mapping Options according to your needs.
Do not switch on the check box Multithreaded Client, see Generate RPC Client.
If necessary, use FTP to transfer your application and the interface object(s) to the target platform where you write your application.
Write your application. See Writing a Single-threaded C RPC Client Application.
If necessary, transfer your application and the client interface object(s) to the target platform where you compile your application, using FTP.
Using a C compiler supported by the C Wrapper and compile
the generated client interface object(s)
your C RPC client customer application.
Use the standard C/C++ compiler of your target platform. Please note platform-specific settings.
Using the linker (binder), link (bind)
the compiled client interface object(s)
your C RPC client customer application
the broker stub
under Windows: the RPC C runtime library delivered as a library and DLL named erx.lib and erx.dll
under UNIX: the RPC C runtime library delivered as a shared object or shared library named liberx.so or liberx.sl
Use the standard C/C++ linker of your target platform. Please note platform-specific settings.
This mode applies to UNIX and Windows.
(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.
To use the C Wrapper in multithreaded environments
Generate the RPC Client, see Generate C Source Files from Software AG IDL Files
and select the Mapping Options according to your needs
and switch on the check box Multithreaded Client, see Generate RPC Client.
If necessary, transfer your application and the client interface object(s) to the target platform where you write your application, using FTP.
Write your multithreaded C RPC Client application, see Programming Multithreaded RPC Clients.
If necessary, transfer your application and the client interface object(s) to the target platform where you compile your application, using FTP.
Using a C compiler supported by the C Wrapper, compile:
the generated client interface object(s)
your C RPC client customer application
Use the standard C/C++ compiler of your target platform. Please note platform-specific settings.
Using the linker (binder), link (bind)
the compiled client interface object(s)
your C RPC client customer application
the broker stub
under Windows: the RPC C runtime library delivered as a library and DLL named erx.lib and erx.dll
under UNIX: the RPC C runtime library delivered as a shared object or shared library named liberx.so or liberx.sl.
Use the standard C/C++ linker of your target platform. Please note platform-specific settings.
The C Wrapper provides access to RPC-based components from C applications and enables you to develop both clients and servers. 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 and IBM i.
(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.
To use the C Wrapper
Generate the RPC Server, see Generate C Source Files from Software AG IDL Files, and
select the Mapping Options according to your needs.
The interface objects and the server (skeleton) must be generated with the same mapping options, otherwise results will be unpredictable.
Note:
For z/OS, the limitation of 8 characters per (physical) member name must be considered
when defining the IDL library (see library-definition in the Software AG IDL file.
The client interface object will be generated with a prefix letter "D".
Therefore an IDL library name "EXAMPLE" within the IDL file results in a
physical member name "DEXAMPLE".
We suggest using an IDL library name of up to 7 characters in length; if the name is longer,
you will not be able to transfer (using FTP) the generated objects to the mainframe.
If necessary, use FTP to transfer your server (skeleton) and the server interface object(s) to the target platform where you write your application.
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):
rename the server from F<library>.c to <library>.c (or to any other suitable name)
or move the server F<library>.c to a different directory (folder)
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 transferred depend on the platform:
your server and the interface objects to a PDS, CA Librarian etc.
your server and the interface objects to your application library. Note that the header files delivered in the LMS library LMS.EXP103.CSRV are required.
your server and the interface object source files to the source file QCSRC in your application library
header files to the source file H of your application library.
your server and the interface objects to a suitable directory (folder).
With a C compiler supported by the C Wrapper, compile the following objects, depending on the platform:
the generated interface object
your server (including your application logic)
the generated interface object
your server (including your application logic).
Use any C/C+ ILCS-enabled compiler on BS2000.
the generated interface object
your server (including your application logic).
Use the standard ILE C compiler invoked by the following
commands for compiling: CRTCMOD MODULE(X) SRCFILE(..)
SRCMBR(..).
EPM-style C programs are not supported.
the generated interface object
your server (including your application logic).
Use the standard C/C++ compiler of your target platform. Please note platform-specific settings.
Using the linker (binder), link (bind) the following objects, depending on the platform:
Create dynamic-link libraries (DLLs) for the client interface objects and RPC server. See Building and Using Dynamic-link Libraries (DLLs) in the z/OS C/C++ Programming Guide, Order No. SC09-2362-03 or later, available through IBM and Architecture and Software Support in IBM S/390 Parallel Enterprise Servers for IEEE Floating-Point Arithmetic - References under http://www.research.ibm.com/journal/rd/435/abbotref.html (subscription required).
There are various possibilities to combine the client interface objects and RPC server together and create dynamic-link libraries (DLLs). We suggest you keep the generated client interface object DLLs separate from RPC server DLLs:
Create two larger DLLs, one containing all your client interface objects and one containing all your RPC servers, and use
the FIX(ddlname) configuration of the parameter library of the RPC Server for Batch.
Create separate DLLs, one for each client interface object and each RPC server and use the PREFIX(prefix) configuration with prefix "D", that is, PREFIX(D)-PREFIX() of the parameter library of the RPC Server for Batch.
the interface object as a shared object or shared library. If, for example, the library name within the Software AG IDL file is HUGO, the standard name of the dynamically callable interface object is DHUGO.so or DHUGO.sl. The standard name can be changed (see the Parameter Libraries of the RPC Server).
your server as a shared object or shared library. If, for example, the library name within the Software IDL file is HUGO, the standard name of the dynamically callable server is HUGO.so or HUGO.sl.
Use the standard C/C++ linker of your target platform. Please note platform-specific settings.
the interface object as a DLL. If, for example, the library name within the Software IDL file is HUGO, the name standard name of the dynamically callable interface object is DHUGO.dll. The standard name can be changed (see the Parameter Libraries of the RPC Server).
your server as a DLL. If, for example, the library name within the Software IDL file is HUGO, the standard name of the dynamically callable server is HUGO.dll.
Use the standard C/C++ linker of your target platform. Please note platform-specific settings.
the interface object as an LLM, using BINDER
your server as an LLM, using BINDER
There is no need to link the object modules with the BS2000 Common Runtime Environment (CRTE) library. The CRTE is loaded once dynamically in the corresponding worker task of the RPC server where the server program is executed.
the interface object, the RPC server (EXPRUNTIME) and the broker
stub (EXA) to a service program (type *SRVPGM)
your server, the RPC server (EXPRUNTIME) and the broker stub (EXA)
to a service program (type *SRVPGM)
Use the standard binder invoked by the following commands for
binding: CRTSRVPGM SRVPGM(X) MODULE(X Y Z)
The activation group must be ACTGRP(*CALLER). This guarantees the
server application runs in the same activation group as the RPC server.
Use the standard linker of your target platform.
Provide the interface object library and the server library accessible to the RPC server according to the rules of your operating system.
This section describes how to generate C source files from Software AG IDL files. It covers the following topics:
From the context menu, choose and to generate the C source files.
For the RPC client
this creates for each library defined in the IDL file the client interface object and its associated header file. All files will be stored in parallel to the IDL file.
In command-line mode, use the command -c:client. See Using the C Wrapper in Command-line Mode.
For the RPC server
this creates for each library defined in the IDL file, the server interface object, its associated header file and the server skeleton file for your server implementation. All files will be stored in parallel to the IDL file.
In command-line mode, use the command -c:server. See Using the C Wrapper in Command-line Mode.
 |
Warning: Take care not to overwrite an existing server implementation with a server skeleton. We recommend you move your server implementation to a different folder, or rename the server implementation. |
For both RPC client and RPC server
If you generate using the GUI and generated files exist from a previous generation, you are prompted to overwrite them.
If you generate using command-line mode, existing files are always overwritten.
The header file created is the same for the RPC client as for the RPC server side and contains, for example, C structure definitions for groups in the IDL file and the prototypes for your server. Use these generated C structures in your RPC client application and server implementation as required.
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.
Select the mapping options according to your needs. All mapping options are available for RPC clients and RPC server. See also Mapping IDL Data Types to C Data Types.
| 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 If the check box is not checked, the IDL data type:
|
| 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 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 |
| 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 If the check box is not marked, the IDL data type U is
mapped to the C data type |
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.
Select the 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). |
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, IBM i).