Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |   Glossary
eLink Adapter Development Kit Doc Home   |   Previous Topic   |   Next Topic   |   Contents   |

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.

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

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.

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.

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.

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.).

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.

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.

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.

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

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.

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

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.

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.

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.

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:

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.

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

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.

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.

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.