BEA eLink Platform Reference

 

This section provides you with basic information about BEA eLink Platform and FML buffers. The following topics are covered:

• BEA eLink Platform Architecture

• ATMI Runtime ServicesFML32

• eLink Commands

 

---

BEA eLink Platform Architecture

The eLink Platform communications application programming interface, Application to Transaction Monitor Interface (ATMI), is a collection of runtime services that can be called directly by a C (or COBOL) application. These runtime services provide support for communications, distributed transactions, and system management.

The Management Information Base (MIB) maintains a virtual repository of all the configuration and operational information for a runtime eLink environment. The eLink services are implemented using a shared bulletin board (BB) that contains configuration information. This is the dynamic part of the eLink. Servers advertise their services in the Bulletin Board. The Bulletin Board Liaison (BBL) is an administrative eLink server that is the keeper of the Bulletin Board. There is a BBL on every machine participating in the integration infrastructure; the BBL coordinates changes to the local copy of the MIB. The Distinguished Bulletin Board Liaison (DBBL) is responsible for propagating global changes to the MIB and is the keeper of the static part of the MIB. The MASTER node is the computer where the DBBL runs.

Administrators use an ASCII file to specify eLink system configuration. This file, called the UBBCONFIG file, is used as input by the configuration loading utility, tmloadcf. The tmloadcf utility generates a binary version of the configuration called the tuxconfig file. This binary file is used by the system to construct the Bulletin Board and contains the persistent part of the MIB.

Servers are processes that provide one or more services. They continually check their message queue for service requests. A service is the name of a server interface. Many servers can support a single service, thereby providing for load balancing and a fail-safe mechanism. The mapping of services to servers is recorded in the Bulletin Board. When a service request is made, the Bulletin Board forwards the request to a server (eLink Adapter) that advertises that service. An eLink server advertises a service by posting its name in the Bulletin Board.

 

---

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. See the BEA Tuxedo Reference Guide at http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux65/index.htm for detailed information on all the ATMI primitives.

Table 7-8 ATMI Primitives for the C Binding

API Group	C API Name	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 7-14 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 an eLink server 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.).

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 eLink clients and servers. For more complete details and code examples, see the BEA Tuxedo Reference Guide at http://edocs.beasys.com/tuxedo/tux65/index.htm

Table 7-9 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.

Table 7-10 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.
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 7-11 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.