This document covers the following topics:

• Writing a Client Application

• Writing a .NET Server Assembly

• Creating ASP.NET Web Services

• Using SSL/TLS

• Using Internationalization with the .NET Wrapper

---

Writing a Client Application

• Required Steps

• Creating a Microsoft Visual Studio Solution

• Creating the .NET Wrapper Client Stub Library (Assembly)

• Creating the .NET Wrapper Client Application

Required Steps

Writing a client application with the EntireX .NET Wrapper typically requires the following steps:

• Starting from an IDL file, generate a C# client interface object as described under Using the .NET Wrapper. From the context menu of the IDL file, choose Other > Generate NET > RPC Client. As an alternative, use the Microsoft Visual Studio Wizard for EntireX .NET Wrapper. Both approaches generate C# sources from an IDL file. If there is a related client-side mapping file (Natural | COBOL), this is also used (internally).

• Create a Visual Studio Solution. See Creating a Microsoft Visual Studio Solution.

• Build a .NET assembly from the generated C# client interface object. See Writing a Client Application.

• Create an application that uses the generated client interface object assembly and the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll. See Creating the .NET Wrapper Client Application.

The following description outlines as an example the steps required to build a .NET Wrapper client application (solution) with the Microsoft Visual Studio.

Creating a Microsoft Visual Studio Solution

1. Start Microsoft Visual Studio.

2. From the File menu, choose New > Blank Solution.... and choose an appropriate name for the solution.

Creating the .NET Wrapper Client Stub Library (Assembly)

1. Select the solution and choose Add, choose New Project.

2. In the New Project dialog, choose Visual C# Projects and Class Library. Choose an appropriate name for the class library, e.g. "exampleClientStub".

3. Delete the default class file Class1.cs.

4. Select the new project and choose Add > Add Existing Item and add the example.cs file generated previously.

5. Select References, choose Add Reference and add the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll.

6. Build the class library.

Creating the .NET Wrapper Client Application

1. Add a new project to the solution: Choose the solution, Add, New Project..., Visual C# Projects, Console Application. Choose an appropriate name for the project, for example, "exampleClient".

2. Rename the default class file Class1.cs as appropriate.

3. Choose References > Add Reference and add the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll.

4. Choose References > Add Reference > Projects and add the .NET Wrapper client interface object exampleClientStub.

5. Now implement your client application. Add the following lines to the top of the class file:

   using SoftwareAG.EntireX.NETWrapper.Runtime;
   using SoftwareAG.EntireX.NETWrapper.Generated.example;

6. In a method of the application class implement the connection to an EntireX Broker, for example:

   Broker broker = new Broker("localhost:1971", "ERX-USER");
   broker.Logon("ERX-PASS");

   and an EntireX RPC service, for example:

   Service service = new Service(broker, "RPC/SRV1/CALLNAT", "EXAMPLE");
   service.UserIDAndPassword("RPC-USER", "RPC-PASSWORD");

7. The example class can now be instantiated, for example:

   Example e = new Example( service );

   and the example methods called, for example:

   int result = ex.Calculator( "+", 10, 15);

Writing a .NET Server Assembly

Writing a .NET server assembly with the EntireX .NET Wrapper typically requires the following steps:

• Generate a C# file as described under Using the .NET Wrapper. From the context menu of the IDL file, choose Other > Generate NET > RPC Server. As an alternative, use the Microsoft Visual Studio Wizard for EntireX .NET Wrapper.

• Insert your server-specific code at the required positions (C# methods).

• Build a .NET Server assembly (DLL) from the generated C# file, following the rules for building a client stub library with the Microsoft Visual Studio.

  Note:
  The file name of the .NET Server assembly and the name of the library/class in the generated C# file must be identical.

• Make the .NET Server assembly available to the RPC Server for .NET, see Locating and Calling the Target Server in the RPC Server for .NET documentation.

• To start, stop and configure the RPC Server for .NET to suit your needs, see Administering the RPC Server for .NET in the RPC Server for .NET documentation.

Creating ASP.NET Web Services

The generated C# client interface object can be used in an ASP.NET Web service to publish EntireX RPC services as Web services. With Visual Studio you can easily create an ASP.NET Web service that publishes methods of the EntireX RPC service (or your own methods that just use the EntireX RPC service).

Example

You have built the .NET Wrapper example EntireX\examples\RPC\dotNetClient as described in the README file.

Then create a new "ASP.NET Web service" project with references to the generated client interface object and the .NET Wrapper runtime.

You can use the following example code (in the .asmx file) to implement a Web method add that exposes the calc method of the example.

using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.Diagnostics;
using System.Web;
using System.Web.Services;
using System.Text;
using SoftwareAG.EntireX.NETWrapper.Runtime;
using SoftwareAG.EntireX.NETWrapper.Generated.example;

namespace WebService1
{
/// <summary>
/// Summary description for Service1.
/// </summary>
public class Service1 : System.Web.Services.WebService
{
public Service1()
{
//CODEGEN: This call is required by the ASP.NET Web Services Designer
InitializeComponent();
}

#region Component Designer generated code

//Required by the Web Services Designer
private IContainer components = null;

/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private void InitializeComponent()
{
}

/// <summary>
/// Clean up any resources being used.
/// </summary>
protected override void Dispose( bool disposing )
{
if(disposing && components != null)
{
components.Dispose();
}
base.Dispose(disposing);
}

#endregion

// WEB SERVICE EXAMPLE
 [WebMethod]
public int add(int sum1, int sum2)
{
Example e = new Example();

int result = e.calc("+", sum1,sum2);
return result;
}
}
}

Using SSL/TLS

RPC client applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based clients are always SSL clients. The SSL server can be either the EntireX Broker or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS and Certificates with EntireX in the EntireX Security documentation.

With the .NET Wrapper, the SSL parameters (e.g. certificates) are appended to the Broker ID, separated by a question mark (?). See URL-style Broker ID under EntireX RPC Programming.

To use SSL

1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

2. Specify the Broker ID using URL style, for example:

   ssl://localhost:2010

   If no port number is specified, port 1958 is used as default.

3. Specify SSL parameters, for example:

   "VERIFY_SERVER=N&TRUST_STORE=c:\\certs\\CaCert.pem"

   If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused. You can disable this check with SSL parameter verify_server=no.

   If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.

   The ampersand (&) character cannot appear in the password.

   SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.

4. Make sure the SSL server to which the .NET client connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Direct RPC. See Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE.

Using Internationalization with the .NET Wrapper

RPC clients generated with the .NET Wrapper use by default the "current locale" encoding set up on the Windows system for converting UNICODE (UTF-16) representations of strings to single-byte or multibyte representations that are sent to the Broker, and vice versa. The codepage name is also transferred to tell the broker the encoding of the data. If you want to adapt the locale settings of your Windows system, use the Regional and Language Options in the Windows Control Panel.

The Broker class of the .NET Wrapper Runtime makes use of the .NET Framework class System.Text.Encoding for character conversion.

Refer also to the .NET Framework class library documentation for System.Text.Encoding.

The CharacterEncoding property of the Broker class that guides the character conversion is initialized with System.Text.Encoding.GetEncoding(0) (current locale). The application programmer can also assign a custom encoding object to the Broker class's CharacterEncoding property for custom character conversions. If an encoding object is provided, the corresponding codepage is transferred to the Broker instead of the default Windows locale.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.