Using the Sample Application

 

The BEA eLink Adapter into WebLogic Enterprise CORBA software includes a Sample Application. This Sample Application provides sample source code, make files, configuration files, and field definitions to help you build an eLink client. You may use this sample application to test your installation of BEA eLink Adapter into WebLogic Enterprise CORBA.

The following topics are discussed in this section:

• What is Included in the Sample Application

• Building and Running the Sample Application on Unix

• Building and Running the Client Program on Windows NT

 

---

What is Included in the Sample Application

The Sample Application provided with the BEA eLink Adapter into WebLogic Enterprise CORBA distribution is an eLink client program. The client program, e2aclient.c, makes an ATMI service call using the tpcall() function passing data in an FML32 buffer. The client program makes one of the two preconfigured service calls, UPPER or LOWER. UPPER converts a string of text to all upper case letters and LOWER converts a string of text to all lower case letters.

The sample configuration files provided as part of this distribution create an environment where the eLink Adapter for CORBA, e2a, is the only server that will respond to the UPPER and LOWER service calls. A complete list and description of all files provided as part of this sample can be found in Table A-1.

Table A-1 List of Sample Application Files

File	Description
e2aclient.c	Client source code.
makefile.nt	NT makefile (MS VC++ 6).
makefile.unix	UNIX makefile.
e2alocal.dom	DM configuration file for e2a to run on UNIX and and handle both local and remote requests from NT.
e2alocal.ubb	UBB configuration file for e2a to run on UNIX and and handle both local and remote requests from NT.
e2aclient.txt	Adapter Configuration file. This lists the services being advertised. This is the command line argument to e2a as specified in the CLOPT= line.
e2aclient.flds	Output from the FTGEN Command Line Tool. Note that this file contains the FML32 field definitions that must be manually added.
e2aremote.dom	DM configuration file for e2aclient to run on NT and communicate with e2a on UNIX.
e2aremote.ubb	UBB configuration file for e2aclient to run on NT and communicate with e2a on UNIX.
setenv.sh	A sample script that sets environment variables.

The Sample Application provided with this distribution requires part of the CORBA Simpapp Application provided with the WebLogic Enterprise distribution. The binary server, simple_server, is created by building the Simpapp and is used as the CORBA application server. When the eLink Adapter for CORBA translates the service calls to method invocations, the CORBA object, Simple, is the target object that responds to the method invocation(s). The adapter configuration, e2aclient.txt, maps the UPPER service call to the to-upper method and the LOWER service call to the to-lower method of the Simple object.

The following diagram shows an example of the Sample Application process with a tpcall to UPPER initiated from the eLink Domain.

Figure 5-1 Example of Sample Application Process

 

---

Building and Running the Sample Application on Unix

The Sample Application contains a single eLink client program, e2aclient.c. Review the following prerequisites and perform the following steps to build the client program and create the Sample Application domains, eLink (e2alocal) and WLE (e2aremote).

Prerequisites

Before you begin building the sample programs, the following prerequisites should be considered:

• Your environment must be properly configured for the eLink Adapter for CORBA. A setenv.sh file ia provided as a sample script for setting the environment variables. Refer to eLink Adapter for CORBA Configuration, for more information about configuring the environment.

• Review your WLE documentation and make sure you are familiar with the WLE Simpapp Application.

• The BEA eLink Adapter into WebLogic Enterprise CORBA is installed in your WLE installation directory, $TUXDIR.

Step 1 - Building the SIMPAPP Test Server

Since the eLink Adapter for CORBA only runs on Unix, you need only build the Unix version of the Test Server.

1. Compile the Simpapp application in the $TUXDIR/samples/corba/simpapp directory. The Readme.txt file in that directory contains build instructions. There is also a runme file that automates the process.

   Note: The use of the Solaris 5.x compiler is required for Solaris.

2. Create a test directory, copy the simple_server executable and simple.idl file to your test directory, and add the simple_server entry under the *SERVERS section of the UBB file.

Step 2 - Creating the Interface Repository

Using the WLE utility function, idl2ir, create an Interface Repository (.ifr) file from the simple.idl file by entering the following command:

idl2ir -f e2aclient.ifr simple.idl

Edit the CLOPT line for the UBB file SERVER entry for TMFIFRSVR to use the Interface Repository (ifr) file created above.

Step 3 - Configuring the Adapter

Configuring the adapter requires to you to modify a adapter configuration file. A sample e2aclient.txt adapter configuration file installs as part of the product for the sample application and is available for use.

1. Use the CFGEN utility to create a skeleton Adapter configuration file. Refer to Generating the Adapter Configuration File for more information on creating a configuration file with CFGEN. The hostname and port input to this program can be found in the CLOPT line for the ISL server in the UBB configuration file (in the form //hostname:port) and the interface name input is the object name from the simple.idl file containing the methods to be called (for example, Simple).

   Note: WLE (including ISL and TMFIFRSVR) must be booted before running the CFGEN utility.

2. Edit the skeleton file generated in the previous step as follows:

   *SERVER Section

   MINMSGLEVEL
   MAXMSGLEVEL

   Coupled together, these parameters control tracing. They can be left blank (which implies a setting of {0,0}) for minimal tracing or set to {0,9} for maximum tracing. This affects the number of log messages placed in the ULOG file.

   *SERVICE Section(s)

   The following SERVICE entries need to be filled in for each of the methods that your client program accesses. Note that the entries filled in by CFGEN (SERVICENAME, OBJECTNAME, METHOD, PARAMS, and RETURN) should not be edited, since any changes to this file may require changes in other files. The data for the FACTORYMETHOD and FACTORYOBJECT fields can be found in the simple.idl file.

   SERVICENAME

   The advertised service name can be any name. The client program uses this name to request the service from e2a.

   REGISTRYTYPE

   The Registry location to be used for obtaining an object reference For this example, the REGISTRYTYPE is defined as FactoryFinder.

   REGISTERED

   The name of the registered factory. You can find the proper value for this field by running the ir2idl utility using as input the interface repository file you created in Step 2 - Creating the Interface Repository.

   For example:

   idl2ir -f filename.ifr

   The output consists of a number of lines; use the one that starts with #pragma ID SimpleFactory.

   For example:

   #pragma ID SimpleFactory "IDL:beasys.com/SimpleFactory:1.0"

   METHOD

   The CORBA method to be invoked when the service is called (for this client, to_lower and to_upper).

   OBJECTNAME

   The object name containing the method to be used (for example, Simple).

   FACTORYMETHOD

   The factory method that returns an OBJECTNAME type object (for example, find_simple).

   FACTORYOBJECT

   The factory interface that contains FACTORYMETHOD (for example, SimpleFactory).

   FACTORYPARAMS

   Leave blank. find_simple() does not take arguments.

   PARAM

   A comma-separated FML field list of arguments matching the prototypes of METHOD in the IDL file. The actual names can be anything.

   RETURN

   An FML32 field name matching the METHOD return type. If void, use the key word 'void' and it will not be interpreted as a FML32 field.

   Notice that the two methods defined in simple.idl (to_lower and to_upper) have different function prototypes. While both take an input string, to_upper does the conversion in place and does not return a result. On the other hand, to_lower returns the converted string.

   The PARAMS and RETURN entries for to_upper should be set as follows:

   PARAMS=val

   RETURN=void

   The corresponding entries for to_lower should be set as follows:

   PARAMS=val

   RETURN=Simpleto_lower_RTN

3. Make sure the CLOPT entry for e2a in the WLE UBBCONFIG file uses the name of the Adapter Configuration file created in step 2 above.

4. Create the FML32 Field Table file. The FTGEN command line utility can be used to generate this file. Refer to Generating an FML32 Field Table File for more information on using this utility. The hostname and port input to this program can be found in the CLOPT line for the ISL server in the UBB configuration file (in the form //hostname:port) and the configuration file input is the file previously generated in step 1.

   If e2a is your first eLink Adapter server, you will need to add the following entries to this file:

   *base 2000
   ELINK_ADAPTER_ERR 1 string - -
   ELINK_ADAPTER_ERR_CODE 2 string - -

   WLE locates this file using the following two environment variables that designate the path and file name of the FML32 Field Table File generated above:

   FIELDTBLS32 contains a list of the table file names.

   FLDTBLDIR32 contains a list of directories to search for the FIELDTBLS32 files.

Step 4 - Building the Client

The following procedure assumes some familiarity with writing WLE or eLink Platform client applications. Refer to the "Programming" section in the BEA Tuxedo online documentation at /http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux65/ for more information on writing clients.

Note: All parameters to e2a are passed via FML32 buffers.

1. The FML32 Field Table File can be used to generate the FLDID32 #defines needed by the client program using the WLE mkfldhdr32 utility:

   mkfldhdr32 e2aclient.flds

   The output file is e2aclient.flds.h, which you can #include in the client source code file.

   Note: The names used in the PARAMS and RETURN entries in the adapter configuration file (see step 1) are listed in the output file from FTGEN tool and are defined as macros in the .h file created by mkfldhdr32.

2. In the client source code file, enter a #include line to include the .h output file you created from the mkfldhdr32 program in the prior step.

   The FML32 buffer to be passed through tpcall() must contain all of the input parameters expected by the server program. When adding these fields to the FML32 buffer, the fieldid parameter of Fadd32() must be one of the #define FLDID32 macros listed in the .h file generated by the mkfldhdr32 program.

3. The svc parameter to tpcall() requesting a service must be the SERVICENAME parameter used in the eLink Adapter configuration file created in the second task of Step 3 - Configuring the Adapter.

4. When extracting the returned data, make sure you access the proper return value by checking the fieldid parameter returned by Fnext32 as you iterate through the returned FML32 field(s).

5. Compile the client program using the WLE command line utility, buildclient.

6. Run the program, making sure that it communicates with the server.

 

---

Building and Running the Client Program on Windows NT

The prior section described building and running the Client Program on a single Unix domain. While the BEA eLink Adapter for CORBA is available only for HP-UX and Solaris platforms, the sample client program can be built on Windows NT either as a Tuxedo or WLE client and configured to talk to a Unix-based WLE server. The sample e2aclient.c file compiles on both NT and Unix with no changes. The UBB and DOM files distributed with the sample application support running the client on NT with a remote connection to a Unix platform and are useful reference material.

Step 1 - Configuring the Server Program

1. Add DMADM, GWADM and GWTDOMAIN entries to the SERVERS group of the existing Server UBBCONFIG file.

2. Create a DMCONFIG file for the Server containing DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_TDOMAIN and DM_LOCAL_SERVICES sections. Refer to Creating the DMCONFIG File for information on these sections.

Step 2 - Running the Server Program

1. Compile the Server UBBCONFIG and DMCONFIG files and boot WLE by entering the following commands in order:

   1. tmloadcf -y e2alocal.ubb

   2. dmloadcf -y e2alocal.dom

   3. tmboot -y

2. Verify that the local connection still works by running the Unix client program.

Step 3 - Building the Client Program on NT

1. Copy the e2aclient.flds.h, created as part of the Sample Application provided with this distribution requires part of the CORBA Simpapp Application provided with the WebLogic Enterprise distribution. The binary server, simple_server, is created by building the Simpapp and is used as the CORBA application server. When the eLink Adapter for CORBA translates the service calls to method invocations, the CORBA object, Simple, is the target object that responds to the method invocation(s). The adapter configuration, e2aclient.txt, maps the UPPER service call to the to-upper method and the LOWER service call to the to-lower method of the Simple object., from Unix to Windows NT.

2. Compile the client program using the WLE command line utility, buildclient (see makefile.nt for an example of usage).

   Note: The Microsoft Visual C++ 6.x compiler and nmake is required.

Step 4 - Configuring the Client Program

1. Create a UBBCONFIG file for the Client that contains server entries for DMADM, GWADM, and GWTDOMAIN. See Adding the e2a Server to the UBBCONFIG File and Defining the Domains Environment in the eLink and WLE UBBCONFIG Files for more information on the required server entries .

2. Create a DMCONFIG file for the client containing DM_LOCAL_DOMAINS, DM_REMOTE_DOMAINS, DM_TDOMAIN, and DM_REMOTE_SERVICES sections. Refer to Creating the DMCONFIG File for information on these sections.

Step 5 - Running the Client Program

1. Compile the client UBBCONFIG and DMCONFIG files and boot Tuxedo or WLE by entering the following commands in order:

   1. tmloadcf -y e2aremote.ubb

   2. dmloadcf -y e2aremote.dom

   3. tmboot -y

2. Verify that things are working properly by running the client program (e2aclient).