Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink Adapter Development Kit Doc Home | Previous Topic | Next Topic | Contents |

Understanding the BEA eLink Platform

This chapter discusses the following topics:

- ATMI Runtime Services

- FML32

- eLink Commands

- Hardware Requirements for the eLink Platform

- Special Instructions for Installing the Tuxedo Core

- Preparing the License File

- About the Tuxedo Simple Application

Before you install the BEA eLink Platform, which is available separately, it is helpful to understand the Application to Transaction Manager Interface (ATMI), the 32-bit Field Manipulation Language (FML32), FML buffers, and some commonly used eLink commands. The ATMI runtime services provide support for communications, distributed transactions, and system management. FML32 is a BEA native data structure and function library that allows associative access to fields of a data record. Commands are used to configure and administer the BEA eLink environment.

ATMI Runtime Services

The eLink Platform ATMI is a collection of runtime services that can be called directly by a C (or COBOL) application. The ATMI is a compact set of primitives used to open and close resources, begin and end transactions, allocate and free buffers, and provide the communication between adapters and other requestors or responders.

Following is a list of ATMI primitives for the C binding. For more complete details of the ATMI primitives you will most commonly use, see ATMI References. See the BEA Tuxedo Reference Guide at http://edocs.beasys.com/tuxedo/tux65/index.htm for detailed information on all the ATMI primitives.

####

Table 2-1 ATMI Primitives for the C Binding

API Group | C API Name | Detailed in Appendix B | Description
--- | --- | --- | ---
Client Membership | tpchkauth tpinit tpterm | * * | Check if authentication is needed Used by a client to join an application Used by a client to leave an application
Buffer Management | tpalloc tprealloc tpfree tptypes | * * * * | Create a message Resize a message Free a message Get a message type and subtype
Message Priority | tpgprio tpsprio |  | Get the priority of the last request Set priority of the next request
Request/Response | tpcall tpacall tpgetreply tpcancel | * * * * | Synchronous request/response to service Asynchronous request Receive asynchronous response Cancel asynchronous request
Conversational | tpconnect tpdiscon tpsend tprecv |  | Begin a conversation with a service Abnormally terminate a conversation Send a message in a conversation Receive a message in a conversation
Reliable Queueing | tpenqueue tpdequeue |  | Enqueue a message to an application queue Dequeue a message to an application queue
Event-based | tpnotify tpbroadcast tpsetunsol tpchkunsol tppost tpsubscribe tpunsubscribe |  | Send unsolicited message to a client Send message to several clients Set unsolicited message callback Check arrival of unsolicited message Post an event message Subscribe to event messages Unsubscribe to event messages
Transaction Management | tpbegin tpcommit tpabort tpgetlev tpsuspend tpresume tpscmt |  | Begin a transaction Commit the current transaction Rollback the current transaction Check if in transaction mode Suspend the current transaction Resume a transaction Control commit return
Service Entry and Return | tpsvrinit tpsvrdone tpreturn tpforward | * * * * | Server initialization Server termination End service function Forward request
Dynamic Advertisement | tpadvertise tpunadvertise | * * | Advertise a service name Unadvertise a service name
Resource Management | tpopen tpclose |  | Open a resource manager Close a resource manager

FML32

FML is a set of C language functions for defining and manipulating storage structures called fielded buffers, which contain attribute-value pairs called fields. The attribute is the field's identifier and the associated value represents the field's data content.

FML32 uses 32-bit values for the field lengths and identifiers. BEA eLink Adapters use FML32. FML32 allows for about 30 million fields, and field and buffer lengths of up to about 2 billion bytes. The definitions, types, and function prototypes for FML32 are located in fml32.h and functions are located in -lfml32. All definitions, types, and function names for FML32 have a "32" suffix (for example, MAXFBLEN32, FLDID32, Fchg32). Also the environment variables are suffixed with "32" (for example, FLDTBLDIR32, FIELDTBLS32).

Note: FML has two interfaces. The original FML interface is based on 16-bit values for the length of fields and for containing information identifying fields. The original interface should not be used when creating eLink Adapters.

FML Buffers

A fielded buffer is composed of field identifier and field value pairs for fixed length fields (for example, long, short), and field identifier, field length, and field value triples for varying length fields.

Figure 2-1 Example of a Fielded Buffer

A field identifier is a tag for an individual data item in a fielded buffer. The field identifier consists of the name of the field number and the type of data in the field. The field number must be in the range 1 to 33,554,431 inclusive for FML32, and the type definition for a field identifier is FLDID32.

Field numbers 1 to 100 are reserved for system use and should be avoided. The field types can be any of the standard C language types: short, long, float, double, and char. Two other types are also supported: string (a series of characters ending with a null character) and carray (character arrays). These types are defined in fml32.h as FLD_SHORT, FLD_LONG, FLD_CHAR, FLD_FLOAT, FLD_DOUBLE, FLD_STRING, and FLD_CARRAY.

For FML32, a fielded buffer pointer is of type FBFR32 *, a field length has the type FLDLEN32, and the number of occurrences of a field has the type FLDOCC32.

Fields are referred to by their field identifier in the FML32 interface. However, it is normally easier to remember a field name. There are two approaches to mapping field names to field identifiers. One is a compile-time mapping, the other is a run-time mapping.

Mapping Field Names to Field Identifiers

To avoid naming conflicts, BEA eLink Adapters must use the following run-time mapping method. Field name/identifier mappings can be made available to FML32 programs at run-time through field table files. Field data types must be specifiable within field table files.

The FML32 interface uses the environment variables, FLDTBLDIR32 to specify a list of directories where field tables can be found and FIELDTBLS32 to specify a list of the files that are to be used from the table directories.

Note: The environment variables, FLDTBLDIR32 and FIELDTBLS32, must be set prior to using FML32.

Within application programs, the FML32 function, Fldid32, provides for a run-time translation of a field name to its field identifier, and Fname32 translates a field identifier to its field name. Type conversion should be performed implicitly via FML library functions. Implicit type conversion facilitates component reuse.

Use FML32 symbolic names and retrieve their values using FLDID32. The Mkfldhdr32 function must not be used to build the adapter because it may cause conflicts with other field IDs.

Any field in a fielded buffer can occur more than once. Many FML32 functions take an argument that specifies which occurrence of a field is to be retrieved or modified. If a field occurs more than once, the first occurrence is numbered 0 and additional occurrences are numbered sequentially. The set of all occurrences make up a logical sequence, but no overhead is associated with the occurrence number (that is, it is not stored in the fielded buffer). If another occurrence of a field is added, it is added at the end of the set and is referred to as the next higher occurrence. When an occurrence other than the highest is deleted, all higher occurrences of the field are shifted down by one (for example, occurrence 6 becomes occurrence 5, 5 becomes 4, etc.).

Creating Field Names

Wherever possible, field names should match application field names one-to-one. Equivalent field names make the configuration easier to understand and manage. Field names must follow the convention of using only uppercase alphanumeric characters and underscores. This is a requirement of the Business Process Option (BPO).

Adapter-specific fields must not be required; they must be optional. Optional adapter-specific fields allow component reuse. Adapter-specific fields break the business process abstraction, requiring the designer of a process flow to have an understanding of the specific adapter for a given process step. Wherever possible, all adapter-specific field names should be configurable to avoid conflicts with other field names. Adapters should use a prefixing convention for any adapter-specific field names to avoid conflicts with other field names.

ud32 Client

There is an eLink-supplied client, ud32, that reads a tab delimited text file and uses the information from the file to construct an FML32 buffer. The ud32 client sends the buffer to a service that the user designates in the text file. ud32 is useful for testing. For an example of a text-delimited file that ud32 could use as input, see the ud, ud32, wud, wud32 section in Tuxedo Commands.

Refer to the Example of a Server that Uses FML32 section in FML32 API, for an example of simple code for a server that uses FML32.

FML32 Primitives

Following is a summary of some of the FML32 primitives that are used for all eLink programs including general eLink services and adapters. This subset of FML32 primitives should be sufficient to create most adapters. For more complete details and code examples, see FML32 API, and the BEA Tuxedo Reference Guide at http://edocs.beasys.com/tuxedo/tux65/index.htm

####

Table 2-2 FML32 Primitives

FML Primitive | Description
--- | ---
Fadd32 | Add new field occurrence
Fchg32 | Change field occurrence value
Ffind32 | Find field occurrence in buffer
Fget32 | Get copy and length of field occurrence
Fielded32 | Return true if buffer is fielded
Finit32 | Initialize fielded buffer
Fldid32 | Map field name to field identifier
Fneeded32 | Compute size needed for buffer
Fsizeof32 | Returns the size of an FML32 buffer

Warning: The Falloc function allocates FML buffers; however, buffers allocated using Falloc cannot be passed in a tpcall. FML32 buffers that will be passed using the tpcall or tpacall ATMI primitives should be allocated by using a tpalloc with type parameter set to FML32.

Use FML32 symbolic names and retrieve their values using Fldid32. Field IDs must be determined dynamically at runtime or during initialization at boot time. The Mkfldhdr32 function must not be used to build the adapter because it may cause conflicts with other field IDs.

eLink Commands

Commands are used to configure and administer the eLink runtime environment. Refer to Administering the BEA Tuxedo System for procedures and administrative tasks that are based on the command-line interface. For details about individual commands, refer to the BEA Tuxedo Reference Manual. Both documents may be found online at http://edocs.beasys.com/tuxedo/tux65/index.htm

Commonly Used Tuxedo Commands

Following is a list of the Tuxedo commands that are most commonly used for adapters. For complete details and code examples for each of the following commands, refer to Tuxedo Commands.

####

Table 2-3 Commonly Used Tuxedo Commands

Tuxedo Commands | Description
--- | ---
buildclient | Constructs a BEA Tuxedo client module. This command combines the files supplied by the -f and -l options with the standard BEA Tuxedo libraries to form a load module and invokes the platform's default compiler to perform the build.
buildserver | Constructs a BEA Tuxedo server load module. This command generates a stub file containing a main() function and invokes the platform's default compiler to perform the build.
tmadmin | Invokes the BEA Tuxedo bulletin board command interpreter. Refer to the Commonly Used tmadmin Commands section for more information.
tmboot | Invokes a BEA Tuxedo application with a configuration defined by the options specified.
tmloadcf | Parses a UBBCONFIG file and load binary TUXCONFIG configuration file.
tmshutdown | Shuts down a set of BEA Tuxedo servers.
ud32 | Runs the BEA Tuxedo ud32 client that reads a tab delimited text file, produces an FML32 buffer, and uses the buffer to make a request to a specified service.

Commonly Used tmadmin Commands

The tmadmin command allows you to inspect and dynamically configure your eLink application. There are many commands that can be invoked from tmadmin, probably the most important being help. Several of the most useful commands are summarized in the following table.

####

Table 2-4 Commonly Used tmadmin Commands

Command | Description
--- | ---
help | Prints help messages.
quit | Terminates the session.
pclt | Prints information for the specified set of client processes.
psr | Prints information for application and administrative servers.
psc | Prints information for application and administrative services.
susp | Suspends services.

For details about tmadmin commands, refer to the BEA Tuxedo Reference Manual at http://edocs.beasys.com/tuxedo/tux65/index.htm.

Hardware Requirements for the eLink Platform

The ADK hardware requirements are dictated by eLink adapter requirements. The MS VC++ v5.x command line compiler should be used for NT platforms.

Special Instructions for Installing the Tuxedo Core

For NT, use the InstallShield installer. For Unix, use the install.sh Korn shell script in the top level of the CD directory structure. Follow the instructions in the BEA Tuxedo Installation Guide, but pay special attention to the following tips.

- The default path for installation on Windows NT is under the Program Files directory. Using a directory with spaces in the name has presented a problem in prior releases of some of the Tuxedo utilities. Using spaces in the path directories should not be a problem with Tuxedo 6.5, but if you experience problems, choose a path name without spaces for installation.

- To be MS Windows 2000 compliant, all programs must be installed in the Program Files directory.

- The Web GUI is not required.

- Important! When InstallShield asks if you want to install your Tuxedo license file at this time, answer NO. See the following section for instructions on preparing the license file.

Preparing the License File

In order to use the ADK you need a license for both the eLink Platform and the ADK. The license files are delivered on a floppy disk and should have accompanied your order of the eLink Platform and ADK. To use the license files, perform the following steps:

1. Copy the LIC.TXT file into the TUXDIR/udataobj directory.

2. This license file must have sections for [Tuxedo 6.5], [eLink Platform], and [eLink Adapter Development Kit]. Refer to your Tuxedo documentation at http://edocs.beasys.com/tuxedo/tux65/index.htm for information about the Tuxedo license file.

   Note: If you previously installed the eLink Platform the content of the supplied license files should be added to the LIC.TXT.

About the Tuxedo Simple Application

The Tuxedo Simple Application provides a way to verify your installation of Tuxedo as well as provide a working example of a Tuxedo application. A more comprehensive description of the Simple Application can be found in the Tuxedo Application Development Guide. The information provided here is specific to running the Tuxedo Simple Application in preparation for using the ADK.

All necessary code is located in the directory, $TUXDIR\apps\simpapp, where $TUXDIR is the directory where Tuxedo is installed. The Simple Application consists of a single server offering a single service. The service is called TOUPPER. You run the client with a single argument, which is a string to convert to upper case. The client calls the service, which returns the converted string. The client then prints the string.

Example: simpcl "Hello World"

Returned string is: HELLO WORLD

The Simple Application is designed so that it can be running within minutes after installing the Tuxedo software. You should probably copy the simpapp files to your own directory, since the configuration file must be edited and you might also want to experiment with the client and server code. Refer to the "Running a Sample Application" section of the BEA Tuxedo Installation Guide at http://edocs.beasys.com/tuxedo/tux65/index.htm for more information about running the Simple Application.

Setting Environment Variables

You need to set several environment variables before using the eLink Platform, running any eLink adapters, or running the Simple Application. Refer to the "Setting Up Your Environment" section of the BEA Tuxedo Installation Guide at http://edocs.beasys.com/tuxedo/tux65/index.htm for more information about setting environment variables. The following table lists the environment variables you need to set for any eLink Adapter.

Table 2-5 Environment Variables Used By the ADK

####

Variable Name | Description
--- | ---
TUXDIR | Base directory of the Tuxedo software.
APPDIR | Base directory for applications such as the sample program.
PATH | Must include $TUXDIR/bin.
TUXCONFIG | Full pathname of binary tuxconfig file.
LD_LIBRARY_PATH | Must include $TUXDIR/lib on systems that use shared libraries (except HP-UX and AIX).
SHLIB_PATH | HP-UX only - Must include $TUXDIR/lib.
LIBPATH | AIX only - Must include $TUXDIR/lib.

Following is an example of a script for Windows NT that could be used to set system variables:

Listing 2-1 Script for Setting System Variables for Windows NT

>     set TUXDIR=C:\tuxedo
>     set APPDIR=C:\simpapp
>     set PATH=%TUXDIR%\bin;%APPDIR%;%PATH%
>     set TUXCONFIG=%APPDIR%\tuxconfig

You must also set other environment variables if you are using a Workstation client.

Scripts are often used to save time in setting environment variables in a development directory. The following scripts are provided to set these variables for you, but the scripts must be edited for your environment.

- $TUXDIR\apps\simpapp\setenv.cmd for NT

- $TUXDIR/tux.env for Unix

Configuring the Simple Application

You configure the Simple Application by editing the sample configuration file, ubbsimple, and then submitting the tmloadcf command to create a binary configuration file for Tuxedo tuxconfig.

To configure the Simple Application, perform the following steps:

1. Edit the sample configuration file, ubbsimple, to replace the bracketed items with values appropriate to your installation.

   Note: Your TUXDIR and TUXCONFIG environment variables must match the values in the configuration file.

2. After editing ubbsimple, create the binary TUXCONFIG file with the command:

   tmloadcf ubbsimple

3. Answer y if you are asked whether to proceed.

   Note: After you create the initial TUXCONFIG file, you may recreate it using a -y command line option with tmloadcf to suppress the prompt.
   For example:
   tmloadcf -y ubbsimple

eLink creates a log file called ULOG.mmddyy. The default directory where this log resides is the application directory, $APPDIR. The creation of the binary file, TUXCONFIG, is logged in the ULOG. Any time there is some type of error or failure in your eLink adapter or eLink environment, the ULOG is one of the first places you should look.

Building the Client and Server for the Simple Application

For UNIX Operating Systems

The client and server for the Simple Application are already built. The executables are named simpcl and simpserv.

Or you can also build the client and server yourself by entering the following commands:

buildclient -o simpcl -f simpcl.c
buildserver -o simpserv -f simpserv.c -s TOUPPER

For Windows NT Operating Systems

You can build the server and client executables using the makefile simpapp.nt.

Or you can use the buildclient and buildserver commands described for UNIX operating systems in the previous section.

Booting the Simple Application

The Simple Application can be booted with the following command:

tmboot -y

After booting the system examine the ULOG. You will see a welcome message that is printed to the ULOG when simpserv is booted.

Then you can run simpcl as described in the About the Tuxedo Simple Application section above. simpcl can be run as many times as you wish.

Use the administrative command, tmadmin, to display and modify the parameters of the running application. For example, try any of the following parameters:

####

Parameter | Description
--- | ---
psr | Printserver-Print information for application and administrative servers.
psc | Printservice-Print information for application and administrative services.
susp | Suspend-Suspend services.

In particular, try suspending the TOUPPER service and then running the client. Refer to the BEA Tuxedo Reference Manual at http://edocs.beasys.com/tuxedo/tux65/index.htm for information about using commands.

Shutting Down the Simple Application

When you are done, you can shut down the Simple Application with the following command:

tmshutdown -y

Examine the ULOG after shutdown to review the messages that result from a shut down.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.