|
|
|
|
|
|
Understanding Adapter Architecture and Design
This chapter discusses the following topics:
eLink Adapter Architecture Overview
The standard design for an eLink adapter consists of at least two distinct program modules, the Server Module and the Configuration Processing Module.
Figure 3-1 Standard Adapter Design
The Server Module contains the code for the functions that perform the services advertised by the server. The Server Module also contains the code for the tpsvrinit function, which is called when the server is booted, and the tpsvrdone function, which is called at server shutdown time.
The tpsvrinit function performs the following tasks:
Warning! eLA_chkeLinkLic must be called to verify the eLink platform release. Failure to do so may result in incorrect runtime behavior in the adapter.
Functions in the ADK library or the ATMI API facilitate most of these tasks.
The following table provides descriptions of the calls made by the tpsvrinit function.
|
tpsvrinit Tasks |
Description |
|---|---|
|
Check the license |
Call eLA_chkeLinkLic() |
|
Open catalog file |
Call eLA_OpenCatalogFile() |
|
Get configuration file |
Call eLA_GetConfigFileName() |
|
Read trace level |
Call eLA_SetServerMsgLevel() |
|
Parse, process, and store configuration data |
Call loadConfigurationInformation and cleanupConfigurationResources. |
|
Advertise services |
Call tpadvertise |
The Configuration Processing Module
Parsing and processing of the configuration file is done by the loadConfigurationInformation and cleanupConfigurationResources functions in the Configuration Processing Module. These functions make use of the ADK API functions for parsing, processing, and storing the configuration data.
Adapter Design Pseudo Code
Following is an example of a pseudo code outline that gives an overview of the general design of an adapter. The pseudo code outline follows these conventions:
In the pseudo code example, the server module has functions that support N services named SERVICE_1 through SERVICE_N; however, SERVICE_1 is the only service with any example code given.
Note: For an example of the general form of an application to eLink adapter that uses an FML32 buffer, see the sample application to eLink adapter that is shipped with the kit. However, the sample application to eLink adapter is not a complete example because it does not use a configuration file or the ADK library. For a complete working example see the sample eLink to application adapter code that is installed with the ADK.
Listing 3-1 Server Module Pseudo Code
/* tpsvrinit is called when a server is booted */
tpsvrinit( )
{
/* Check license */
eLA_chkeLinkLic( )
/* Open the message catalog file. */
eLA_OpenCatalogFile()
/* Get the configuration file name. */
eLA_GetConfigFileName()
/* Read the trace level. */
eLA_SetServerMsgLevel()
/* Process configuration file */
loadConfigurationInformation( ) /* See configuration module below. */
/* Call tpadvertise for each service name */
for(i=0; i < numServices; i++)
{
tpadvertise( ) ;
}
}
/* tpsvrdone is called at server shutdown time */
tpsvrdone( )
{
/* Close the message catalog file. */
eLA_CloseCatalogFile()
cleanupConfigurationResources( ) /* See configuration module below. */
}
/*
** Supply functions that perform the actual services available to and or
** requested by the client. The argument to each is a structure TPSVCINFO
** (see definition following the code) containing, among other things a pointer ** to the data buffer, and the length of the data buffer.
*/
SERVICE_1(TPSVCINFO * request)
{
/* Check the type of the data member of the incoming TPSVCINFO struct */
tptypes( )
Insert code to perform the actual service here. This will probably involve interacting with the third-party API in some way.
/* Return the transformed buffer to the requestor. */
tpreturn( )
}
....
....
....
SERVICE_N(TPSVCINFO * rqst)
{
}
/* End of Server module */
Listing 3-2 Configuration Processing Module Pseudo Code
/* The following function is called in tpsvrinit to process the configuration file information */
loadConfigurationInformation( )
{
/* Allocate hash table for service information */
eLA_InitHashtable( )
/* Open Configuration */
eLA_OpenTagFile( )
/* Parse SERVER section, insure proper configuration file */
eLA_GetFirstSection( )
while( ADK_SUCCESS )
{
/* Parse properties for each SERVER section */
eLA_GetFirstProperty( )
while( ADK_SUCCESS )
{
eLA_GetNextProperty( )
}
eLA_GetNextSection(sHandle)
}
eLA_CloseTagHandle( )
/* Parse SERVICE(s) data for this SERVER */
eLA_GetFirstSection( )
/* Begin Services loop */
while( ADK_SUCCESS )
{
/* Get first property for this service */
eLA_GetFirstProperty( )
/* begin Property loop */
while( ADK_SUCCESS )
{
Insert code here to process properties for each service.
eLA_GetNextProperty( )
} /* end Property loop */
/* Add service data element to hash table */
eLA_put( )
eLA_GetNextSection( )
} /* End Services loop */
eLA_CloseTagFile( )
eLA_CloseTagHandle( )
}
/* This function was called in tpsvrdone to clean up any allocated resources. */cleanupConfigurationResources( )
{
/* Deallocate the hashtable allocated in loadConfigurationInformation */
eLA_DestHashtable( )
}
The TPSVCINFO Structure
As shown in the SERVICE_1 and SERVICE_N lines of the above pseudo code, the argument to a function that performs an eLink service is a structure called TPSVCINFO. TPSVCINFO contains, among other things, a pointer to the data buffer, and the length of the data buffer. The full definition is given below:
Listing 3-3
Struct tpsvcinfo {char name[32]; /* Service name */
long flags; /* Options about the request */
char *data; /* Request data */
long len; /* Request data length */
int cd; /* Connection descriptor */
long appkey; /* Application key */
CLIENTID cltid; /* Client identifier */
};
typedef struct tpsvcinfo TPSVCINFO;
Application to eLink Adapters
Application to eLink adapters translate requests initiated by the third-party software (for example, SAP, Broadvision, or MQseries) into standard eLink ATMI calls, such as a tpcall. The application to eLink adapter is an eLink server that will probably run as a "daemon" process. You can run the server as a daemon process by making a tpacall with the TPNOREPLY flag set to the daemon service from the server's tpsvrinit function. The daemon process starts when the server is booted. The code for the daemon service contains an infinite loop. Inside the loop, the server checks for input from the third-party software.
The method of communication between the third-party software and the adapter depends on the third-party interface. For example, for an MQSeries adapter, requests are written to a queue by MQSeries and the adapter monitors that queue. The eLink Platform routes the request. The Bulletin Board Liaison (BBL) consults the Bulletin Board to find the name of the server that has advertised the requested service. The BBL then resolves the service name into a fully qualified address and sends the request to the server. The server or other adapter that advertises the desired service must be provided by the customer and is not part of the application to eLink adapter. However, in order to test an adapter, the adapter must be able to call an eLink service, so an eLink server that processes such a request should be part of a test for the adapter.
Note: All communication between the originating adapter and the adapter that services the request should be in FML32.
Following is an example of the server code that is specific to application to eLink adapters.
Listing 3-4 Server Module Code
tpsvrinit(argc,argv){
....
tpacall("DAEMON",...,TPNOREPLY);
return(0);
}
DAEMON (...){
....
for(;;)
{
//Check for requests from third-party application
}
....
}Following is an illustration of the typical request path for an application to eLink adapter.
Figure 3-2 Typical Request Path for an Application to eLink Adapter
eLink to Application Adapters
eLink to application adapters translate requests made by requesting applications into calls to the API of third-party software. The eLink to application adapter is a server. A tpcall (or tpacall) initiates the request. The service name is defined by a parameter in the tpcall. The eLink Platform makes an association between the service name and a server, or adapter, that advertises that service. The service, a function defined in the adapter, makes a call to the third-party API. The interface between the adapter and the third-party software is defined by the third-party software.
The sample eLink to application adapter included with the ADK is a complete working example of an eLink to application adapter. Client code is provided to initiate the request. In real environments this originating call might be from another adapter or the Business Process Option. This code is not part of the adapter, however such a client should be written to test the adapter.
Following is an illustration of the typical request path for an eLink to application adapter.
Figure 3-3 Typical Request Path for an eLink to Application Adapter
eLink Adapter Configuration
The eLink Adapter configuration is defined in the SERVERS section of the UBBCONFIG file. The UBBCONFIG file is located in the directory specified by the configuration. You must create a custom UBBCONFIG file and add the configuration information for the eLink Adapter to the SERVERS section.
The method of configuring adapters and how the adapter processes that configuration, follows a standard format. All adapter code and any test configurations must follow this standard.
Standards for Adding an eLink Adapter to the UBBCONFIG File
In a UBBCONFIG file, lines beginning with an asterisk (*) indicate the beginning of a specific section. The name of the section immediately follows the *. The beginning of the SERVERS section is marked *SERVERS. Parameters are generally specified by KEYWORD= value. Entries in the SERVERS section have the form:
AOUT required parameters [optional parameters]
where AOUT specifies the file (string_value) to be executed by tmboot.
Required parameters are:
SRVGRP = string_value
which specifies the name for the group in which the server is to run. The string_value must be the logical name associated with a server group in the GROUPS section. The string_value must be 30 characters or less. This association with an entry in the GROUPS section means that AOUT is executed on the machine with the Logical Machine ID (LMID) specified for the server group. The GROUPS section also specifies the GRPNO for the server group and parameters to pass when the associated resource manager is opened. All server entries must have a server group parameter specified:
SRVID = number
which specifies an integer that uniquely identifies a server within a group. Identifiers must be between 1 and 30,000 inclusive. This parameter must be present on every server entry.
All adapter entries in the UBBCONFIG file are required to have the CLOPT parameter (although it is listed as optional in the Tuxedo online documentation.) CLOPT specifies servopts options to be passed to the server when booted. "--" marks the end of system-recognized arguments and the start of arguments to be passed to a subroutine within the server. All eLink adapters will have exactly one argument after the --, the -C option followed by the name of the adapter-specific configuration file. All other configuration parameters specific to the adapter should appear in the adapter-specific configuration file. For more details on the CLOPT parameter see Servopts.
Listing 3-5 Example of the CLOPT Parameter Entry
*SERVERS
elinkmqi
SRVID="number"
REPLYQ=N
CLOPT="-- -C configuration_file_name"
Sample UBBCONFIG File
Listing 3-6 Sample UBBCONFIG File
*RESOURCES
IPCKEY 123791
DOMAINID simpapp
MASTER simple
*MACHINES
DALNT6
LMID= simple
TUXDIR= "\tuxedo"
TUXCONFIG= "\myappdir\tuxconfig"
APPDIR= "\myappdir"
FIELDTBL32= "sample.fml"
FLDTBLDIR32= "\myappdir"
ULOGPFX= "\myappdir\ULOG"
*GROUPS
eLINK
LMID=simple GRPNO=1
*SERVERS
DEFAULT:
CLOPT="-A"
elinkmqi
SRVGRP=eLINK
SRVID=10
CLOPT="-- -C config.file"
*SERVICES
*ROUTING
eLink Adapter Configuration Files
In addition to the configuration information contained in the application's UBBCONFIG file, each adapter must have its own specific configuration file. You must create the configuration file following the guidelines specific to the type of adapter.
The adapter configuration file defines aliasing of service names, tracing parameters, and the names of outside resources to be used. Aliasing allows the names of advertised services to be related to the business logic and also allows for many service names to be mapped to a single implementation. In the configuration file, users can activate tracing and specify the level of tracing that is done. If a server needs to retrieve information from outside resources, for example read requests from a queue, the names of the outside resources are specified in the configuration file.
The eLink Adapter reads the configuration file at startup. The configuration file is an ASCII text file that the user creates for the adapter. The user arbitrarily chooses the name of this file, but it must match what is specified by the CLOPT parameter in the UBBCONFIG file (as described in Standards for Adding an eLink Adapter to the UBBCONFIG File). This configuration file must be located in the application directory (APPDIR) for the end-user's application.
Structure of the eLink Adapter Configuration File
The adapter configuration file is divided into several sections. Each adapter configuration file contains one, and only one, SERVER section. The configuration file may also contain one or more SERVICE sections and one or more FIELDMAP sections.
When you create an eLink Adapter configuration file, some standard conventions apply to the format. Following are the standard conventions that should be used for the adapter configuration file:
Phone \#-800.555.1212 returns Phone #-800.555.1212
Example of the format of a configuration file section and parameter:
*<NAME OF SECTION>
<PARAMETER NAME>=<PARAMETER VALUE>
The SERVER Section
There is only one SERVER section in each configuration file. In this section, the only required parameters are the MAXMSGLEVEL and MINMSGLEVEL tracing level parameters. The following table provides descriptions for these parameters:
|
Parameter Name |
Description |
|---|---|
|
MAXMSGLEVEL=<int> |
Indicates the maximum level of tracing messages the adapter is to log. |
|
MINMSGLEVEL=<int> |
Indicates the minimum level of tracing messages the adapter is to log. |
For more information about the trace levels, refer to the Tracing section in this chapter.
The SERVICE Section
You must define the services that will be advertised in the SERVICE sections of the configuration file. Each defined service has a corresponding section in the configuration file. Each defined service section has exactly one required parameter, NAME. The NAME parameter must be 15 characters or less in length. The following table provides a description for this parameter.
|
Parameter Name |
Description |
|---|---|
|
NAME=<Name> |
Defines the eLink service name that is to be advertised. |
The SERVICE section is where names advertised by eLink and related to business logic are mapped to the names of the actual functions that perform the services.
For example, the eLink Adapter for XML performs data format conversion between FML and XML data formats. For each conversion, you must create a SERVICE section in the adapter configuration file. This SERVICE section describes an eLink service that the adapter advertises in order to perform a conversion. End-user applications then request this service to perform the necessary conversion.
The SERVICE definition maps an eLink service name to a specific type of conversion. The service name is arbitrarily chosen. These SERVICE definitions allow different conversions to be represented by different eLink service names. For example, you could define services CONVERT_A, MAKEXML, or MYFMLXML that are all FML to XML conversions. This allows many conversions to be mapped to one implementation. However, these SERVICE names cannot equal the CONVERSION type parameter.
The FIELDMAP Section
A field map is a set of mappings of the names of fields used by the third-party software to the names of the corresponding FML32 fields. A field map must be defined in a section called FIELDMAP. The first parameter of the FIELDMAP section must be FMID (field map identifier). This parameter identifies a field map and is referenced by the service definition using the map. A field map may be referenced by more than one service, if applicable.
The following format is used in adapter configuration files to define each mapping in a field map:
Application Name:FML32 Field Name:input/output:field designator
where
Application Name is the name of the application field
FML32 Field Name is the name of the FML32 field associated with this Application field name.
Input/output defines whether a field is expected as input or passed as output or both. Valid values are I, O, and IO.
Field designator is an adapter-defined designator for the defined field. This parameter can be used to designate required fields, key fields, optional fields, etc.
R = Required Field
O = Optional Field
K = Key Field
P = Parent Key Field
L = Link Field
G = Group Field
Additional values can be defined by the adapter, if necessary
Example:
*SERVICE
NAME=NwCont
BUSINESS_OBJECT=Account
BUSINESS_COMPONENT=Contact
OPERATION=NEW
FMID=Map1
*FIELDMAP
FMID=Map1
Birth Date:EL_SBL_BIRTH_DATE:I:O
Comment:EL_SBL_COMMENT:I:O
Credit Agency:EL_SBL_CREDIT_AGNCY:I:O
Credit Score:EL_SBL_CREDIT_SCORE:I:O
Email:EL_SBL_EMAIL:I:O
Address:EL_SBL_ADDRESS:I:O
Job Title:EL_SBL_JOB_TITLE:I:O
First Name:EL_SBL_FIRST_NAME:I:R
Last Name:EL_SBL_LAST_NAME:I:R
Id:EL_SBL_ID:O:R
In the above example, the application field "Birth Date" maps to the FML32 field EL_EBL_BIRTH_DATE. This field is an optional (designated by an O) input (indicated by the I/O type of I) field. The application field "ID" is mapped to EL_SBL_ID. This field is defined as a required output field.
The ADK contains the following functions that are used to parse the field map sections in the adapter configuration file: eLA_GetFieldMap, eLA_GetFirstField, eLA_GetNextField. For complete details and code examples see the "Configuration Processing API" section in Appendix A.
Sample Adapter Configuration File
The following is an example of a configuration file for an adapter that difines one service.
Listing 3-7 Adapter Configuration File
# This is a comment
*SERVER
MAXMSGLEVEL=10
MINMSGLEVEL=0
*SERVICE
NAME=CONVERT_WITHDRAWAL
CONVERSION_TYPE=FMLMTI2XML
MTI_NAME=withdraw.mti
*SERVICE
NAME=CONVERT_DEPOSIT
CONVERSION_TYPE=FML2XML
LIST_TAG_SUFFIX=_LIST
FMID=Map1
*FIELDMAP
FMID=Map1
Birth Date:EL_SBL_BIRTH_DATE:I:O
Comment:EL_SBL_COMMENT:I:O
Credit Agency:EL_SBL_CREDIT_AGNCY:I:O
Credit Score:EL_SBL_CREDIT_SCORE:I:O
Email:EL_SBL_EMAIL:I:O
Address:EL_SBL_ADDRESS:I:O
Job Title:EL_SBL_JOB_TITLE:I:O
First Name:EL_SBL_FIRST_NAME:I:R
Last Name:EL_SBL_LAST_NAME:I:R
Id:EL_SBL_ID:O:R
API to Parse and Store Configuration Data
The ADK includes an API to facilitate the parsing of the Adapter configuration file and to store configuration information for quick lookup.
API to Parse the Configuration File
The following API functions may be used to facilitate the parsing of the Adapter configuration file. For complete details and code examples see the Configuration Processing API section in eLink Adapter Development Kit References.
|
Configuration Processing API Name |
Description |
|---|---|
|
eLA_OpenTagFile |
Opens a Tag (or config.) file, and reads it into memory. |
|
eLA_CloseTagFile |
Closes a handle returned by eLA_OpenTagFile. |
|
eLA_CloseTagHandle |
Closes a handle returned by eLA_GetFirstSection. |
|
eLA_GetFirstSection |
Searches the config file memory image for desired section. |
|
eLA_GetNextSection |
Finds next occurrence of desired section. |
|
eLA_GetFirstProperty |
Retrieves Tag/Value pair for first property in a section. |
|
eLA_GetNextProperty |
Retrieves Tag/Value pair for successive properties in a section. |
|
eLA_GetPropertyValue |
Retrieves value for first occurrence of a tag in a section. |
|
eLA_GetFieldMap |
Searches for the named *FIELDMAP section. |
|
eLA_GetFirstField |
Retrieves the information for the first line in a fieldmap section. |
|
eLA_GetNextField |
Retrieves the information for successive lines in a fieldmap section. |
API to Store the Configuration Data
After the configuration information has been parsed, it can be stored in a hash table to facilitate quick lookup. The hash table API is included in the ADK. A summary of the available functions is provided here. For complete details and code examples see the Hash Table API section in eLink Adapter Development Kit References.
|
Hash Table API Name |
Description |
|---|---|
|
eLA_InitHashTable |
Creates a hash table. |
|
eLA_DestHashTable |
Frees all dynamic memory in the hash table. |
|
eLA_put |
Adds a new element to the hash table. |
|
eLA_get |
Retrieves an element from the hash table. |
|
eLA_hash |
Returns the hash value for a given key. |
Error Handling
Error handling may be accomplished through error logging and tracing. Error logging is mandatory and must always be "turned on", while tracing can be activated or deactivated by the user.
If an eLink to application adapter successfully completes a service request, then the adapter returns with tpreturn (TPSUCCESS, .). The tpurcode, the second parameter in tpreturn, should be set to the value of the third-party API return code (if available and applicable). This is to ensure that other eLink components can determine that the application request has been successfully executed.
Errors from eLink to application adapters should return in a consistent manner. Consistency allows other eLink components, such as the Data Integration Option (DIO) or the Business Process Option (BPO), to detect and respond to errors.
eLink adapters need to handle two types of errors, business level exceptions and infrastructure errors. Proper error handling ensures that all the eLink components recognize error codes that are returned for eLink to application adapters.
Business Level Exceptions
Business level exceptions are those that occur when the advertised service is successfully invoked by the adapter, but the called application is unable to complete the requested operation. For example, if the business service advertised is "Ship Order", the service may fail if one of the items to be shipped is out of stock and the incomplete order may not be shipped. This exception must be returned to the caller but will not be logged.
If a business-level exception occurs, then the adapter returns with tpreturn (TPFAIL, 0, ...). The details of the error, for example the application error code, are returned in the ELINK_APP_ERR FML32 field. This is a string field. Using the recommended CFchg32() call, the adapter may populate the ELINK_APP_ERR FML32 field with either an error number or error string without further conversion.
Infrastructure Level Exceptions
Infrastructure level exceptions are those in which the adapter encounters an uncorrectable error, for example, a failure to allocate an FML32 buffer or other memory allocation errors within the adapter code. All infrastructure level errors are returned to the caller and logged using the eLA_log() function that is included in the ADK. A message catalog should be used (See the following Message Catalog section). The eLA_catentry function is used to retrieve the actual message string from the catalog using a message number.
If an eLink to application adapter fails because of an infrastructure level error, then the adapter returns with tpreturn (TPFAIL, !0, ...). The FML32 field, ELINK_ADAPTER_ERR, contains an error message. The category of adapter error is indicated in the FML32 ELINK_ADAPTER_ERR_CODE field. The content of this string field is a single keyword. A predefined set of categories is described in the list below. Whenever possible, errors should be mapped to these categories. Adapter authors may define additional categories, however, third-party additions should omit the "ELINK_" prefix.
|
Category |
Description |
|---|---|
|
ELINK_EAPP_API |
The application's API returned an error. Note that this refers to the application's API returning an infrastructure level error rather than a business level error. |
|
ELINK_EAPP_UNAVAIL |
The application was unavailable. |
|
ELINK_EATMI |
An ATMI error occurred. |
|
ELINK_ECONFIG |
An error occurred with the adapter configuration data. |
|
ELINK_EFML |
An FML error occurred. |
|
ELINK_EINVAL |
Invalid value/argument error. For example, an FML32 request buffer is sent to an adapter without all the required FML32 fields being present. |
|
ELINK_EITYPE |
An input type mismatch. For example, converting between FML32 and application data types on the input. |
|
ELINK_ELIMIT |
Out of range value. |
|
ELINK_ENOENT |
No entry found. The application functionality corresponding to the service could not be found. |
|
ELINK_EOS |
An operating system error. For example, a memory allocation error. |
|
ELINK_EOTYPE |
An output type mismatch. For example, converting between FML32 and application data types on the output. |
|
ELINK_EPERM |
A permissions error. |
|
ELINK_EPROTO |
A protocol error. |
|
ELINK_ETIME |
A timeout error. For example, timing-out while waiting for the application to process the request. |
|
ELINK_ETRAN |
A transaction error. |
All error and tracing messages should be put in a message catalog file. The catalog file is assumed to be a text file (.txt) whose message lines adhere to the rules outlined in the HP-UNIX gencat() MAN pages. The MAN pages provide reference information in an online format.
For example:
10 "WARN: Existing parameter %s = %d, cannot change to %d"
11 "ERROR: Memory allocation failure"
The message numbers should be in ascending order, but the numbers need not be contiguous. Double quotes are stripped and lines starting with comments ('$') are disregarded. Sets are not supported.
These catalog files are required to be located in the $TUXDIR\ELINK\CATALOGS directory. However, the ADK utility function that is used to open the catalog file, eLA_OpenCatalogFile(), expects a fully qualified path name.
In the event that the message number is not found in the catalog file, a string similar to "Message xxx not found" is returned to the caller.
API to Access the Message Catalog File
The ADK includes an API to access the message catalog file. A summary of the available functions is provided here. For complete details see the Utility Functions and Macros section in eLink Adapter Development Kit References.
|
Message Catalog API Name |
Description |
|---|---|
|
eLA_OpenCatalogFile |
Open the message catalog file |
|
eLA_CloseCatalogFile |
Close the message catalog file |
|
eLA_catentry |
Retrieve the message corresponding to the entry number |
The following code segment illustrates how these functions are used:
Listing 3-8 Code for Catalog File Functions
ADK_CAT_HANDLE rHandle;
char catFileName[MAX_FNAME];
char msgbuffer[1024];
....
rHandle = eLA_OpenCatalogFile(catFileName);
....
eLA_catentry(msgbuffer, sizeof(msgbuffer), rHandle, 11);
....
eLA_CloseCatalogFile(rHandle);
Tracing
eLink adapters should be written to allow tracing to be enabled through the adapter-specific configuration file. Tracing can then be activated or deactivated by the user.
Trace Levels
A trace level parameter is associated with each tracing message. The MAXMSGLEVEL and MINMSGLEVEL parameters are set in the adapter configuration file to specify the range of trace messages to be printed. The MAXMSGLEVEL and MINMSGLEVEL parameters are read in the tpsvrinit function by calling the eLA_SetServerMsgLevel function. They are then stored in the corresponding fields of a MSG_LEVEL structure. For more information, refer to the Definitions and Typedefs section in eLink Adapter Development Kit References.
MAXMSGLEVEL and MINMSGLEVEL parameters have a range of values from 0 to 9. If both the MAXMSGLEVEL and MINMSGLEVEL parameters are set to 0, then no tracing is done. Following are guidelines for assigning a message level to each individual trace statement.
|
Level Range |
Corresponding Tracing |
|---|---|
|
1-3 |
Minimal level of tracing. Log module, program, or major function entry points only. |
|
4-6 |
Moderate level of tracing. Log entry into major control blocks or execution of key events in the program. Log exit points from modules, programs, and functions. |
|
7-9 |
Very detailed level of tracing. All function calls and return codes are printed. All buffers are hex dumped. Entry and exit from all functions are logged. |
If there is any code in the adapter that does signal or event handling, it is advisable to use a trace level in the 7-9 range so that the signal or event handling is turned off for the purposes of debugging. Actual usage of trace values should be described in user documentation for the adapter.
Tracing Functions and Macros
In addition to the eLA_log function, there are two other functions included in the ADK to help with tracing, eLA_hexdump and eLA_catentry. eLA_hexdump performs a formatted hexdump of a buffer. eLA_catentry retrieves an entry from the message catalog. The macro, ELACATENTRY, serves as a cover for the eLA_catentry function.
The ADK includes two macros, ELATRACE and ELAIFTRACE, that are specifically designed to aid in tracing. ELATRACE has three arguments: VAR, LVL and ARGS. If the LVL argument is between the values of the fields of the MSG_LEVEL structure VAR (inclusively), then the argument ARGS is substituted into an eLA_log function call. ELAIFTRACE has two arguments: VAR and LVL. ELAIFTRACE evaluates to an if statement that checks to see if LVL is between the values of the fields of the MSG_LEVEL structure VAR. ELAIFTRACE can be used to check if bracketed code immediately following it should be evaluated.
The following code segment illustrates the use of the tracing functions and macros:
Listing 3-9 Code for Tracing Functions and Macros
MSG_LEVEL zLevel = {0,0};
char configFileName[MAX_FNAME];
...rc = eLA_GetConfigFileName(configFileName, MAX_FNAME, argc, argv);
printf("eLA_GetConfigFileName - rc = %d\n", rc);
if(rc == -1)
printf("Buffer not large enough\n");
else if(rc == 0)
printf("File Name parameter not found\n");
else
printf("File Name = %s\n", configFileName);
...
rc = eLA_SetServerMsgLevel(configFileName, &zLevel);
printf("SetServerMsgLevel - rc = %d\n",rc);
if(rc == ADK_SUCCESS)
printf("min, max = %d, %d\n", zLevel.minMsgLevel, zLevel.maxMsgLevel);
for(i = 0;i < 10;i ++)
{ ELAIFTRACE(zLevel, i) printf("Level = %d\n", i);}
for(i = 0;i < 10;i ++)
ELATRACE(zLevel, i, ("Log msg level %d", i));
...
Deployment and Installation of eLink Adapters
Adapters should be compatible with all the following platforms supported by eLink Platform v1.1 or higher. Additional operating systems may be supported in future releases of the eLink Platform and the ADK.
For HP-UX builds, the +DAportable compilation flag should be used to make the resulting object files portable across PA-RISC 1.1 and 2.0 workstations. Other important build flags are -Wl,+s. This is actually a command for the linker to use the SHLIB_PATH environment variable to locate shared libraries.
As an example, CFLAGS should at least use the following parameters:
CFLAGS=+DAportable -Wl,+s
Installation Directory Structure for Components
Adapters are installed in the eLink Platform using the traditional configuration shown in the following table. Your code needs to work in this environment. In the table, adapter should be replaced by the name of your adapter (PeopleSoft, SAP, etc.).
|
Directory |
Contents |
|---|---|
|
$(TUXDIR)/bin |
Executables and dynamic link libraries. |
|
$(TUXDIR)/lib |
Library objects (*.so, *.a, *.sl, *.lib). |
|
$(TUXDIR)/include |
Include files needed for customer applications. |
|
$(TUXDIR)/ELINK/CATALOGS |
Message catalog files. |
|
$(TUXDIR)/udataobj |
FML fldtbls for internal adapter use and binfiles.adapter. |
|
$(TUXDIR)/adapter |
Adapter-specific files and samples. It may contain subdirectories. |
|
$(TUXDIR)/adapter/mysample |
Sample applications provided with the adapter where mysample is the name of the sample application provided. |
Each Adapter should provide a flat text file named binfiles.adapter for inclusion in the $(TUXDIR)/udataobj directory. The flat text file lists the files that are deliverables for this product. These deliverables should be placed in the following directory paths:
|
Directory |
Deliverables |
|---|---|
|
/(base directory for installation) |
All make, bat, script files and readme files. |
|
/doc |
All documentation. |
|
/src |
All source code. |
|
/include |
All include files. |
|
/bin |
All binary command line executables (if any). |
|
/dll |
All dlls (if any). |
|
/lib |
All libs (.SL, .SO, .LIB, etc.) (if any). |
|
/demo |
Any demo code, sample programs, etc. |
|
/test |
All test material (scripts, data, and programs). |
Naming Convention for Source and Executable Files
The source and executable files for all adapters must follow specific naming conventions.
The naming convention for source files is:
eLink<abbeviation><i or o>.c
where <abbreviation> is the two or three letter abbreviation associated with the adapter and i is for inbound (application to eLink) and o is for outbound (eLink to application).
The naming convention for executable files is:
ELINK<abbreviation><I or O>
where <abbreviation> is the two or three letter abbreviation associated with the adapter (in caps this time) and I is for inbound (application to eLink) and O is for outbound (eLink to application). Using all caps for the names of servers is an eLink convention.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|