Configuring the Environment for the eLink Adapter for Vantive

This chapter consists of the following topics:

Defining the ELINKVANO Server

As with any TUXEDO server, you must update the SERVERS section of the UBBCONFIG file to establish a server group for the eLink Adapter for Vantive in the BEA TUXEDO configuration.

See the BEA TUXEDO Administrator's Guide for more information about the UBBCONFIG file. For more information about the UBBCONFIG file specific to servers, refer to the "Updating the SERVERS Section" of this document.

Note: Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *. The asterisk is required when specifying a section name.

Updating the SERVERS Section of the UBBCONFIG File

This section explains how to specify servers in the BEA TUXEDO configuration.

Define the ELINKVANO Server

You define the ELINKVANO server in the SERVERS section of the TUXEDO UBBCONFIG file as follows:

To define this server, add the ELINKVANO information in the SERVER section of the UBBCONFIG file. The following parameters are required for defining the ELINKVANO server.

Listing 3-1 Syntax for ELINKVANO Server Definition in the UBBCONFIG File

*SERVERS

ELINKVANO
	SRVGRP=.. SRVID=..
	CLOPT = " -- -i unique_id -C configuration filename"

For more information about the SRVGRP, SRVID, and CLOPT parameter syntax and definitions, refer to the BEA TUXEDO Reference Manual.

CLOPT= " -- -i unique_id"

specifies the unique id identifying the label section in the environment file containing the adapter environment variables. This is optional. If it is not specified, then the unique id will default to the process name.

"-C configuration filename"

specifies the configuration file specifying the detailed adapter configuration information.

Sample UBBCONFIG File

Listing 3-2 is a sample UBBCONFIG file. In this sample, the ELINKVANO server is defined in the SERVER section with the required CLOPT options specified.

Listing 3-2 Sample UBBCONFIG File

*RESOURCES

IPCKEY		123791
DOMAINID		simpapp
MASTER		simple

*MACHINES

DALNT6 
	LMID		= simple
	TUXDIR		= "\tuxedo"
	TUXCONFIG		= "\myappdir\tuxconfig"
	APPDIR		= "\myappdir"
	FIELDTBL		= "sample.fml"
	FIELDTBL32		= "sample.fml"
	FLDTBLDIR		= "\myappdir"
	FLDTBLDIR32		= "\myappdir"
	ULOGPFX		= "\myappdir\ULOG"
					# LD_LIBRARY_PATH=\vantive
					# SHLIB_PATH=\vantive
					PATH=\vantive


*GROUPS

eLINK
	LMID=simple		GRPNO=1

*SERVERS

DEFAULT:
	CLOPT="-C"

ELINKVANO
	SRVGRP=eLINK			SRVID=10
	REPLYQ=N
	CLOPT="-- -i unique_id -C elinkvantive.cfg"

*SERVICES

*ROUTING

Setting Up the eLink Adapter for Vantive Configuration File

The eLink Adapter for Vantive retrieves configuration information from its own configuration file (elvan_env.cfg) located in the APPDIR directory. This configuration parameters file defines detailed configuration information required by the eLink Adapter for Vantive. The eLink Adapter for Vantive reads-in the adapter label section of the specified environment file.

Note: The configuration file must be specified in the CLOPT line of the UBBCONFIG file or the eLink Adapter for Vantive will generate an error and exit the startup.

If you are unsure of a parameters value, consult your Vantive System Administrator for the proper configuration file values.

The eLink Adapter for Vantive configuration file consists of the following sections.

*SERVER

The configuration file SERVER section defines the parameters needed to establish connections with the Vantive application, and to set any global flags (such as debug flags) within the server. The beginning of the SERVER section is denoted by a line containing the following text string "*SERVER".

NAME =<adapter unique id>

Defines the label section containing the adapter environment variables. The adapter unique id will either be the value of the -i flag on the CLOPT line, or if not specified, then the default value of the process name.

EXIT_CONNECT_LOSS=<Y\>

Optional. Specifies if the eLink Adapter for Vantive is to exit when it detects that it has lost the connection to the Vantive application server. If not specified or defined as a value other then Y, then the eLink Adapter for Vantive will not exit upon losing the connection and will try to restore the connection.

TRACE=<Y>

Optional. Defines if trace output will be produced. If not specified or defined as a value other than Y, then no trace output will be produced.

VANTIVE_HOST=<Vantive application server host name>

Defines the host name on which the Vantive application server (iwserver) resides.

VANTIVE_PORT=<Vantive Application Server port number>

Defines the port number to connect to for the Vantive application server (iwserver).

SERVICE_LIST=<list of services to be advertised>

Defines the services that the eLink Adapter for Vantive will advertise. The services will be specified as a list which is comma-delimited: service_1, service_2, service_3,...

LOGIN_NAME=<Vantive application login name>

Defines the login name to be used while connecting to the Vantive server. Every Vantive user is assigned a unique login name and it is configured using the VanTools utility. Each user is a part of a "group". Every group has access to specific Vantive applications such as Vantive Sales, Field Service, or Quality. Depending on the permissions assigned to every group, the user can access specific Vantive forms.

PASSWORD=<Vantive Application login password>

Defines the password to be used along with the login name while connecting to the Vantive application server.

FUNCTION_NAME=<Vantive interface function name>

Optional. Defines the Vantive interface function that is to be executed when the service specified in the label is invoked. If not specified, then the service name will be used as the interface function name. The set of interface function names will be specified by the eLink Adapter for Vantive and define the Vantive functionality that can be invoked.

Refer to the Vantive documentation for the specific format of the FUNCTION_NME parameter.

*SERVICE

For each service that is advertised by the adapter, a SERVICE section must be specified in the configuration file that defines what the service does within the Vantive application. Each SERVICE section defines the operation and data that is to be manipulated within Vantive. The beginning of the SERVICE section is denoted by a line containing the following text string "*SERVICE".

NAME=<service name>

For each service in the list defined by the SERVICE_LIST parameter, a label will exist where the label is the service name. For each service, the label section will contain parameters that define configuration information particular to that service. The parameters that are applicable to specific services are defined in the section describing that service.

PRIMARY_KEY=<Primary Key field for the parent object>

Specifies the name of the primary key for the parent Vantive object. When an operation is performed on a vantive child object, it needs the parent object name (OBJECT_NAME) and the primary key for the parent.

OBJECT_NAME=<Vantive business object name>

Defines the Vantive object name on which the service will operate. This object name along with the form name will be used by the VANAPI to access the Vantive business object related information from the Vantive application database. In case of a service operating on child form/object, this variable defines the parent object name.

Refer to the Vantive documentation for the specific format of the OBJECT_NAME parameter.

FORM_NAME=<Vantive form name>

Every TUXEDO service will manipulate a given Vantive business object. Every object is associated with a Vantive Form. Different groups can have different forms for the same business object to manipulate specific information. This variable will indicate which form the service will use to manipulate the given business object. Only the forms associated with child objects and/or tables will be aded to the configuration file. If this parameter is defined, then the form will be opened as a child form and the OBJECT_NAME will be used as parent object name.

Refer to the Vantive documentation for the specific format of the FORM_NAME parameter.

If the form name is not mentioned for the given service then it is the service dealing with main business object and main form associated with it.

OPERATION=<requested operation>

Specifies the operation to be performed on a Vantive object. The permitted values are

New: Specifies to create a new Vantive business object.
Read: Specifies to read the Vantive business object fields. This operation may return more than one instance of the object to satisfy the search criteria. Only the values of the fields specified in the OUTFLD_LIST variable in the configuration file will be returned to the caller. Every field will have as many occurrences as there are instances of the object returned by the VANAPI function.
Update: Specifies to update the existing Vantive business object fields. This operation will work for only one object at every invocation of the service. Therefore, the input field and mandatory field values should be able to identify a unique object so as to perform the operation successfully.
Delete: Specifies to delete the Vantive business object. This operation works only for one object at every invocation of the service. Therefore, the input field and mandatory field values should be able to identify a unique object so as to perform the operation successfully. Note: Update and Delete operations require a record to be uniquely identified. When working with child objects in Vantive, the input fields and mandatory fields should uniquely identify the child record irrespective of selection criteria used for the parent object.

INPFLD_LIST=<Input fields received by the service>

Defines the field names that can be expected as input to the given service. This list should contain the mandatory fields for the execution of the service. The input fields will be specified as a list which is comma-delimited.

Refer to the Vantive documentation for the specific format of the INPFLD_LIST parameter.

MANFLD_LIST=<Mandatory Input fields received by the service>

Defines the field names that are mandatory as input to the given service. The optional fields are listed in the input field list and the fields shall not be repeated in both the input and mandatory field lists. When this field list is used for the Update operation, it will contain all the mandatory fields (Id fields) required to uniquely identify the record. All the linked fields such as swRegionId | sw_region.swName will be added to the list in its entirety.

Refer to the Vantive documentation for the specific format of the MANFLD_LIST parameter.

OUTFLD_LIST=<Output fields returned by the service>

Defines the field names that will be returned by the service on completion. The output fields will be specified as a list which is comma-delimited.

Refer to the Vantive documentation for the specific format of the OUTFLD_LIST parameter.

KEYFLD_LIST=<Key fields for parent object>

Defines the key fields that will be used to identify the parent object when working with child forms and objects/records. When more than one field is mentioned, an AND condition will be assumed for locating the object/record.

Refer to the Vantive documentation for the specific format of the KEYFLD_LIST parameter.

KEYFLD=<Object name associated with every key field>

Specifies the associated object name for every key field mentioned in the KEYFLD_LIST. Whenever Vantive contains more than one linked fields (those associated with the child objects) it is necessary to identify every key field with the corresponding Vantive object. This section repeats for every key field mentioned in the KEYFLD_LIST array and defines the Vantive object to which it is associated. The actual key is the primary key of the linked (child) table associated with the main form. In many cases the Key Field itself is a primary of the child table, in which case the actual key can be left blank.

Refer to the Vantive documentation for the specific format of the KEYFLD_LIST parameter.

Sample Configuration File

Listing 3-1 is a sample configuration file. The elvan_env.cfg file is the configuration file that the server reads.

Listing 3-3 Sample Environment Configuration File

*SERVER
NAME=SALES
VANTIVE_HOST=127.0.0.1
VANTIVE_PORT=1540
TRACE=Y
RESPONSE_BUFFER_SIZE=12000
LOGIN_NAME=vantest1
PASSWORD=vantest1
SERVICE_LIST=RdCustSales,NewCustSales,UpdCustSales,DelCustSales, NewSiteSales, UpdSiteSales, RdSiteSales, DelSiteSales, NewContSales, UpdContSales, RdContSales, DelContSales, NewIndSales, UpdIndSales, RdIndSales, DelIndSales, NewRegSales, UpdRegSales, RdRegSales, DelRegSales, NAddCustSales, UAddCustSales, RAddCustSales, DAddCustSales, NAddSiteSales, RAddSiteSales, DAddSiteSales, UAddSiteSales, NJorContSales, UJorContSales, RJorContSales, DJorContSales

*SERVICE
NAME=RdCustSales
OBJECT_NAME=CUSTOMER
OPERATION=Read
MANFLD_LIST=swName
OUTFLD_LIST=swName, swParentId|sw_Customer.swname, swStatus, swCreditRating, swMainPhoneCntry, swMainPhoneArea, swMainPhone, swMainFaxCntry, swMainFaxArea, swMainFax, swType, swDuns, swUrl, swOwnership, swRevenue, swRegionId|sw_Region.swName, swGeoCode, swLocType, swEmpTotal, swIndustryId|SW_INDUSTRY.swName, swDefaultReplyVia, swTpm, swCarrier, swNote

*SERVICE
NAME=NewCustSales
OBJECT_NAME=CUSTOMER
OPERATION=New
INPFLD_LIST=swParentId|SW_CUSTOMER.swName, swStatus, swCreditRating, swMainPhoneCntry, swMainFaxCntry, swType, swDuns, swUrl, swOwnership, swRevenue, swRegionId|SW_REGION.swName, swGeoCode, swLocType, swEmpTotal, swIndustryId|SW_INDUSTRY.swName, swDefaultReplyVia, swTpm, swCarrier, swNote
MANFLD_LIST=swName, swMainPhoneArea, swMainPhone, swMainFaxArea ,swMainFax
KEYFLD_LIST=swParentId, swRegionId, swIndustryId
swParentId=CUSTOMER, swCustomerId
swRegionId=REGION
swIndustryId=INDUSTRY
OUTFLD_LIST=swCustomerId

*SERVICE
NAME=UpdCustSales
OBJECT_NAME=CUSTOMER
FORM_NAME=
OPERATION=Update
INPFLD_LIST= swParentId|SW_CUSTOMER.swName, swStatus,  swMainPhoneCntry,  swType,  swUrl,  swRegionId|sw_Region.swName,  swIndustryId|SW_INDUSTRY.swName, swDefaultReplyVia, swTpm, swCarrier, swNote, swMainPhoneArea, swMainPhone, swMainFaxArea ,swMainFax
MANFLD_LIST=swName
OUTFLD_LIST=swCustomerId
KEYFLD_LIST=swParentId, swRegionId, swIndustryId
swParentId=CUSTOMER, swCustomerId
swRegionId=REGION
swIndustryId=INDUSTRY

*SERVICE
NAME=DelCustSales
OBJECT_NAME=CUSTOMER
FORM_NAME=
OPERATION=Delete
INPFLD_LIST=
MANFLD_LIST=swName
OUTFLD_LIST=swName

*SERVICE
NAME=NewSiteSales
OBJECT_NAME=SITE
PRIMARY_KEY=
FORM_NAME=
OPERATION=New
INPFLD_LIST=swLanguage, swRegionId|sw_Region.swName, swRepairDepotSite, swOfficePhoneCntry, swOfficePhoneArea, swFaxCntry, swFaxArea, swFax, swOfficeCode
MANFLD_LIST=swSiteName, swCustomerId|sw_customer.swName
KEYFLD_LIST=swCustomerId, swRegionId
swCustomerId=CUSTOMER
swRegionId=REGION
OUTFLD_LIST=swSiteId

*SERVICE
NAME=UpdSiteSales
OBJECT_NAME=SITE
PRIMARY_KEY=
FORM_NAME=
OPERATION=Update
INPFLD_LIST=swLanguage, swRegionId|sw_Region.swName, swRepairDepotSite, swOfficePhoneCntry, swOfficePhoneArea, swFaxCntry, swFaxArea, swFax, swOfficeCode
MANFLD_LIST=swSiteName
KEYFLD_LIST=swRegionId
swRegionId=REGION
OUTFLD_LIST=swSiteId

*SERVICE
NAME=RdSiteSales
OBJECT_NAME=SITE
PRIMARY_KEY=
FORM_NAME=
OPERATION=Read
INPFLD_LIST=
OUTFLD_LIST=swLanguage, swRegionId|sw_Region.swName, swRepairDepotSite, swOfficePhoneCntry, swOfficePhoneArea, swFaxCntry, swFaxArea, swFax, swOfficeCode
MANFLD_LIST=swSiteName

*SERVICE
NAME=DelSiteSales
OBJECT_NAME=SITE
PRIMARY_KEY=
FORM_NAME=
OPERATION=Delete
INPFLD_LIST=
OUTFLD_LIST=swSiteName
MANFLD_LIST=swSiteName

*SERVICE
NAME=NewContSales
OBJECT_NAME=OUTSIDECONTACT
PRIMARY_KEY=
FORM_NAME=
OPERATION=New
INPFLD_LIST=swTitle, swCustomerId|sw_Customer.swName, swSiteId|sw_Site.swSiteName, swRegionId|sw_Region.swName, swDepartment, swJobTitle, swType, swSalutation, swEmailType, swLo



 Understanding Service Invocation Requirements

Each unique business-level function that can be invoked by the eLink Adapter for Vantive is advertised as a TUXEDO service. To invoke a service, a calling application prepares an FML32 request buffer specifying the input values that are to be passed to Vantive. The calling application then invokes the corresponding  TUXEDO service, passing the FML32 request buffer.

The eLink Adapter for Vantive has a generic EL_VANTIVE_IN service that processes all the service requests. When invoked, the service code determines what service name is used to invoke it. The service code then calls a function that processes the requests. This function takes the service name and FML32 request buffer as input parameters, and returns the FML32 response buffer and error information as ouput parameters. From the service name, the function determines the Vantive functionality to invoke. The function that processes the FML32 request buffer, invokes the Vantive functionality, and then returns the response parameters in an FML32 buffer. If any errors ocur, then the function returns error information.

The service code processes the response from the function. If the Vantive functionality was invoked successfully, then it will return  TPSUCCESS with the tpurcode set to 0. If the invocation failed then the service code returns the corect error indication.

The eLink Adapter for Vantive uses only FML32 Field names, not Field IDs, when processing the request and response buffers. The Field names must be defined in the TUXEDO FML Field Table file. This allows the actual Field IDs to be customer-defined.



 
 [Table of Contents] [Prev] [Next]