Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |
eLink Adapter for Kenan Arbor/BP Doc Home   |   BEA eLink Adapter for Kenan Arbor/BP User Guide   |   Previous Topic   |   Next Topic   |   Contents   |

This chapter contains the following topics:

• Defining the Server

• Configuring the eLink Adapter for Kenan Arbor/BP

• Understanding Service Invocation Requirements

• Understanding Kenan Arbor/BP Adapter Services

Before running the eLink Adapter for Kenan Arbor/BP, you must identify the ELINKABPO server in the UBBCONFIG file. A sample UBBCONFIG file is provided on the installation CD-ROM. You can use this sample file as a base for creating your own UBBCONFIG file. Listing 3-1 shows the syntax for defining the ELINKABPO server in the UBBCONFIG file.

ELINKABPO
   SRVGRP="identifier" SRVID="number'
   CLOPT= " -- -i "unique_id  -e configuration_file_name"

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

-- -i unique_id

identifies the label section in the configuration file containing the eLink Adapter for Kenan Arbor/BP environment variables. This is optional. If not specified, it defaults to the process name.

-e configuration_file_name

specifies the name of the eLink Adapter for Kenan Arbor/BP configuration file.

The elabp_env.cfg file controls the operation of the eLink Adapter for Kenan Arbor/BP server (ELINKABPO). Following are the sections of the configuration file and the parameters you can define for each section. A sample configuration file is provided in the Sample eLink Adapter for Kenan Arbor/BP Configuration File section.

Note: elabp_env.cfg is a generic filename. You can name this file anything you choose, but the filename must match the -e configuration_file_name parameter you specify in the eLink Platform UBBCONFIG file. (See Understanding Service Invocation Requirements for instructions on configuring the ELINKABPO server in the UBBCONFIG file.)

The eLink Adapter configuration file is divided into the following sections:

• SERVER

  Contains the general parameters required during server startup.

• SERVICE

  Contains a list of services to be performed and the parameters required for each service.

The syntax for the SERVER section of the eLink Adapter for Kenan Arbor/BP configuration file is as follows:

[SERVER=identifier]
EXIT_CONNECT_LOSS=Y
TRACE=Y
CAT_SERVER=server name
CAT_DATABASE=database name
CAT_USERNAME=user name
CAT_PASSWORD=password
APPNAME=application name
DATE_FORMAT=MMDDYYYY
RESPONSE_BUFFER_SIZE=buffer size
SERVICE_LIST=service1, service2, service3

The following parameters must be defined in the SERVER section:

SERVER

A unique identifier for this specific instance of the adapter. Alphanumeric.

CAT_SERVER

The catalog server to be connected.

CAT_DATABASE

The catalog database to be connected.

CAT_USERNAME

Login name to be used to for logging in to the database.

CAT_PASSWORD

Password associated with the CAT_USERNAME.

APPNAME

The name or ID of the application being used by Kenan Arbor/BP. Cannot contain more than 8 characters.

DATE_FORMAT

The date format to be used.

SERVICE_LIST

The names of the services to be advertised. List each service name, separated by commas.

RESPONSE_BUFFER_SIZE

Sets the size of the response buffer in bytes. Default is 10,000.

The following parameters are optional in the SERVER section:

EXIT_CONNECT_LOSS

Specifies whether the eLink Adapter for Kenan Arbor/BP should exit when it detects that the connection to the Kenan Arbor/BP server has been lost.

TRACE

Indicates whether trace output should be produced.

The syntax for the SERVICE section of the eLink Adapter for Kenan Arbor/BP configuration file is as follows:

[SERVICE=service name]
SERVICE_OBJECT=business object name
SERVICE_METHOD=business object method
SERVICE_TYPE=type of service
FIELD_NAME=M,O,K,R

The following parameters must be defined in the SERVER section:

SERVICE

The name of the service being advertised.

SERVICE_OBJECT

The business object with which the service is identified. This tells the eLink Adapter for Kenan Arbor/BP which type of initialization to perform.

SERVICE_METHOD

The business method with which the service is identified. This tells the eLink Adapter for Kenan Arbor/BP the type of functionality that needs to be invoked for the service request.

FIELD_NAME

The name of each field to be used by this service, and a value indicating whether the field is mandatory or optional, whether the field is a key field, and whether the field is part of the request or response buffer. Valid values are:

M=Mandatory for input
O=Optional for input
K=Key field; used for update operations in which some key fields cannot be updated
R=Required as a response

The M, O, or K value is presented first, followed by the R value.

The following parameters are optional in the SERVICE section:

SERVICE_TYPE

Provides the control information associated with the service.

Listing 3-4 shows an example of the adapter configuration file that is provided with the eLink Adapter for Kenan Arbor/BP. The concepts discussed in the Configuring the eLink Adapter for Kenan Arbor/BP section are illustrated in this file.

[SERVER=2]
TRACE=Y
RESPONSE_BUFFER_SIZE=12000
CAT_SERVER=beabp
CAT_DATABASE=beabp
CAT_USERNAME=arbor
CAT_PASSWORD=arbor123
APPNAME=my_app
DATE_FORMAT=MMDDYYYY

SERVICE_LIST=Create_Account1,Create_Account2,Update_Account1,List_Account1,Select_Account1,Get_Act_Status1,Cease_Acct,Activate_Acct,Reactivate_Acct,Reinstate_Acct,Suspend_Acct,Terminate_Acct,Writeoff_Acct,Prov_Serv1,Prov_Serv2,List_Serv1,List_Serv2,Sel_Serv1,Sel_Serv2,GetStat_Serv1,GetStat_Serv2,SetStat_Serv1,SetStat_Serv2,Update_Serv1,Update_Serv2,Provision_ppkg,Set_status_ppkg,Get_status_ppkg,List_ppkg,Select_ppkg,Update_ppkg,Provision_ac,Set_status_ac,List_ac,Select_ac,Update_ac,Get_status_ac,Provision_sv,Set_status_sv,List_sv,Select_sv,Update_sv,Get_status_sv

[SERVICE=Create_Account1]
SERVICE_OBJECT=ACCOUNT
SERVICE_METHOD=CREATE
SERVICE_TYPE=ACTIVE
ACCOUNT_CATEGORY=M		
ACCOUNT_TYPE=M		
ACCT_SEG_ID= R		
ALT_BANK_ACC_NUM=  O	
AVS_ADDRESS_ID=OR  
AVS_RESPONSE_CODE= O		
BANK_AGENCY_CODE=O
BANK_AGENCY_NAME=O
BILL_ADDRESS1=M
BILL_ADDRESS2=O
BILL_ADDRESS3=O
BILL_CITY=M
BILL_COMPANY=O
BILL_COUNTRY_CODE=M
BILL_COUNTY=O
BILL_DISP_METH=M
BILL_FMT_OPT=M
BILL_FNAME=M
BILL_FRANCHISE_TAX_CODE=O
BILL_GEOCODE=O
BILL_HOLD_CODE=O
BILL_LNAME=O
BILL_MINIT=O
BILL_NAME_GENERATION=O
BILL_NAME_PRE=O
BILL_PERIOD=O
BILL_STATE=O
BILL_TITLE=O
BILL_ZIP=O
BILLING_FREQUENCY=O
CCARD_ACCOUNT=O
CCARD_CARRIER=O
CCARD_CLEARING_HOUSE_ID=O
CCARD_EXPIRE=O
CCARD_ID_SERV=O
CCARD_OWNR_NAME=O
CHARGE_THRESHOLD=O
CHG_WHO=O
CHILD_COUNT=O
CLEARING_HOUSE_ID=OR            
CODEWORD=OR			
COLLECTION_HISTORY=OR
COLLECTION_INDICATOR=MR
COLLECTION_STATUS=MR
CONTACT1_NAME=OR
CONTACT1_PHONE=OR
CONTACT2_NAME=OR
CONTACT2_PHONE=OR
CONVERTED=R
CRED_STATUS=MR

CREDIT_RATING=O
CREDIT_THRESH=OR
CURRENCY_CODE=MR
CUST_ADDRESS1=MR
CUST_ADDRESS2=OR
CUST_ADDRESS3=OR
CUST_BANK_ACC_NAME=OR

[SERVICE=Create_Account2]
SERVICE_OBJECT=ACCOUNT
SERVICE_METHOD=CREATE
SERVICE_TYPE=PENDING
ACCOUNT_CATEGORY=M		
ACCOUNT_TYPE=M		
ACCT_SEG_ID= R		
ALT_BANK_ACC_NUM=  O	
AVS_ADDRESS_ID=OR  
AVS_RESPONSE_CODE= O		
BANK_AGENCY_CODE=O
BANK_AGENCY_NAME=O
BILL_ADDRESS1=M
BILL_ADDRESS2=O
BILL_ADDRESS3=O
BILL_CITY=M
BILL_COMPANY=O
BILL_COUNTRY_CODE=M
BILL_COUNTY=O
BILL_DISP_METH=M
BILL_FMT_OPT=M
BILL_FNAME=M
BILL_FRANCHISE_TAX_CODE=O
BILL_GEOCODE=O
BILL_HOLD_CODE=O
BILL_LNAME=O
BILL_MINIT=O
BILL_NAME_GENERATION=O
BILL_NAME_PRE=O
BILL_PERIOD=O
BILL_STATE=O
BILL_TITLE=O
BILL_ZIP=O
BILLING_FREQUENCY=O
CCARD_ACCOUNT=O
CCARD_CARRIER=O
CCARD_CLEARING_HOUSE_ID=O
CCARD_EXPIRE=O
CCARD_ID_SERV=O
CCARD_OWNR_NAME=O

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

The eLink Adapter for Kenan Arbor/BP has a generic service that processes all the service requests. When invoked, the service code determines the service name that was used to invoke it. The service code then calls a function that processes the request, depending on the operation requested. This function takes the service name and FML32 request buffer as input parameters and returns the FML32 response buffer and error information (if any) as output parameters.

From the service name, the function determines the SERVICE_OBJECT, the SERVICE_METHOD, and the SERVICE_TYPE configuration parameters associated with the service. By analyzing these parameters, the eLink Adapter for Kenan Arbor/BP determines the functionality to invoke. The function then processes the FML32 request buffer, invokes the Kenan Arbor/BP functionality, and returns the response parameters in an FML32 buffer. If any errors occur, the function returns error information.

If the Kenan Arbor/BP interface functionality was invoked successfully, a TPSUCCESS code is returned, with the tpurcode set to 0. If the invocation failed, the service code returns the error code and error message as parameters of tpreturn() call.

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

The table below illustrates the mapping between Kenan Arbor/BP data types and FML buffer data types.

Kenan Arbor/BP Data Types	FML Buffer Data Types
Char	Short
Char[]	String
Int	Long
Short	Short
Numeric	String
Date	String

Note: The maximum number of characters an FML field name can contain is 30. Several fields in the Service Instance Object contain more than 30 characters. These fields are abbreviated in the FML buffer. The following table shows the field names and their abbreviations.

Kenan Arbor/BP Field Name	Abbreviated FML Field Name
external_account_no	EXT_ACCOUNT_NO
external_account_no_bill_nrc	EXT_ACCOUNT_NO_BILL_NRC
external_account_no_bill_nrc_type	EXT_ACCOUNT_NO_BILL_NRC_TYPE
external_account_no_bill_rc	EXT_ACCOUNT_NO_BILL_RC
external_account_no_bill_rc_type	EXT_ACCOUNT_NO_BILL_RC_TYPE
external_account_no_bill_usg	EXT_ACCOUNT_NO_BILL_USG
external_account_no_bill_usg_type	EXT_ACCOUNT_NO_BILL_USG_TYPE
external_account_no_type	EXT_ACCOUNT_NO_TYPE

When a service request is received, the eLink Adapter for Kenan Arbor/BP reads the SERVICE_OBJECT, SERVICE_METHOD, and, if applicable, the SERVICE_TYPE parameters in the configuration file to determine the required action. For example, a request is made for a new account to be created. The eLink Adapter for Kenan Arbor/BP determines the name of the service that initiated the request, in this case, Create_Account1. The eLink Adapter for Kenan Arbor/BP then finds this service in the configuration file and reads the SERVICE_OBJECT, SERVICE_METHOD, and SERVICE_TYPE parameters. For this service, the values for these parameters are:

SERVICE_OBJECT=Account
SERVICE_METHOD=Create
SERVICE_TYPE=Active

By reading these parameters, the eLink Adapter for Kenan Arbor/BP determines that it needs to create a new account with a status of Active.

As another example, a second request is made for a new account to be created. This time the calling service is Create_Account2. The eLink Adapter for Kenan Arbor/BP reads the configuration parameters for this service and finds the following:

SERVICE_OBJECT=Account
SERVICE_METHOD=Create
SERVICE_TYPE=PENDING

Both of the above examples create new accounts, but with different statuses. Some services have identical names, but different numbers, such as Create_Account1 and Create_Account2. The only difference between these two services is the status of the object that is created. This facilitates maximum functionality for the eLink Adapter for Kenan Arbor/BP without having to restart the EL_ARBOR_IN service.

The table below lists the service names and the specialized functionality that can be performed on service objects. For more detailed information, refer to the Kenan Arbor/BP API Guide and Kenan Arbor/BP API Reference.

Service Name	Action Performed
Create_Account1 and Create_Account2	Creates an Account.
Update_Account1	Updates an account
List_Account1	Lists account(s)
Select_Account1	Selects account(s)
Get_Act_Status1	Gets the status of an account
Cease_Acct	Ceases an account
Activate_Acct	Activates an account.
Reactivate_Acct	Reactivates an account
Reinstate_Acct	Reinstates an account
Suspend_Acct	Suspends an account
Terminate_Acct	Terminates an account
Writeoff_Acct	"Writes-off" an account
Prov_Serv1 and Prov_Serv2	Provisions a Service Instance
List_Serv1 and List_Serv2	Lists Service Instances
Sel_Serv1 and Sel_Serv2	Selects Service Instances
GetStat_Serv1 and GetStat_Serv2	Gets Service Instance status
SetStat_Serv1 and SetStat_Serv2	Sets the status of a Service Instance
Update_Serv1 and Update_Serv2	Updates a Service Instance
Provision_ppkg	Provisions a Product Package
Set_status_ppkg	Sets the status of a Product Package
Get_status_ppkg	Gets the status of a Product Package
List_ppkg	Lists a Product Package
Select_ppkg	Selects a Product Package
Update_ppkg	Updates a Product Package
Provision_ac	Provisions a Product Package Account
Set_status_ac	Sets the status of a Product Package Account
Get_status_ac	Gets the status of a Product Package Account
List_ac	Lists a Product Package Account
Select_ac	Selects a Product Package Account
Update_ac	Updates a Product Package Account
Provision_sv	Provisions a Product Package Service Instance
Set_status_sv	Sets the status of a Product Package Service Instance
Get_status_sv	Gets the status of a Product Package Service Instance
List_sv	Lists a Product Package Service Instance
Select_sv	Selects a Product Package Service Instance
Update_sv	Updates a Product Package Service Instance

The eLink Adapter for Kenan Arbor/BP can perform actions on the following objects. These objects are listed in the configuration file as the SERVICE_OBJECT for each service.

• Account objects

• Service Instance objects

• Product Package objects

• Product Package Account objects

• Product Package Service Instance objects

Understanding the SERVICE_METHOD

The eLink Adapter for Kenan Arbor/BP can perform the following actions on the service objects. These actions are listed in the configuration file as the SERVICE_METHOD for each service. The table below lists and describes the actions that can be performed.

SERVICE_METHOD	Description
Create/Provision	Creates new objects.
Update	Updates an existing object, but generally cannot change the status of an object.
List	Retrieves a list based on the input criteria specified in the FML buffer.
Select	Returns one object based on its primary keys. The returned values of that object are specified in the configuration file ('R').
Get Status	For Account SERVICE_OBJECT, gets the "net" status of an account object. For all other SERVICE_OBJECTs, returns the status of that object.
Set Status	Sets the status of an object. This service does not apply for accounts.

The eLink Adapter for Kenan Arbor/BP reads the SERVICE_OBJECT, SERVICE_METHOD, and SERVICE_TYPE parameters in the configuration file to determine the action to be performed. The tables below list the values that are required for these parameters for each service.

Table 3-1 lists the values that are required for these parameters for each Account service.

Table 3-1 Configuration Parameters for Account Services

Service Name	SERVICE_ OBJECT	SERVICE_ METHOD	SERVICE_TYPE
Create_Account1 or Create_Account2	ACCOUNT	CREATE	ACTIVE PENDING
List_Account1	ACCOUNT	LIST	ACTIVE lists only Active Accounts that match your criteria. If not specified, all accounts that match your criteria are returned. Selection criteria is specified in the input (request) FML fields.
Select_Account1	ACCOUNT	SELECT	NONE to specify this parameter is not used for this service.
Update_Account1	ACCOUNT	UPDATE	NONE to specify this parameter is not used for this service.
Get_Act_Status1	ACCOUNT	GET_STATUS	NONE to specify this parameter is not used for this service.
Cease_Acct	ACCOUNT	SET_STATUS	CEASE
Activate_Acct	ACCOUNT	SET_STATUS	ACTIVE
Reactivate_Acct	ACCOUNT	SET_STATUS	REACTIVATE
Reinstate_Acct	ACCOUNT	SET_STATUS	REINSTATE
Suspend_Acct	ACCOUNT	SET_STATUS	SUSPEND
Terminate_Acct	ACCOUNT	SET_STATUS	TERMINATE
Writeoff_Acct	ACCOUNT	SET_STATUS	WRITE_OFF

Table 3-2 lists the values that are required for these parameters for each Service Instance service.

Table 3-2 Configuration Parameters for Service Instance Services

Service Name	SERVICE_ OBJECT	SERVICE_ METHOD	SERVICE_TYPE
Prov_Serv1 and Prov_Serv2	SERVICE_INSTANCE	PROVISION	NONE to specify this parameter is not used for this service.
List_Serv1 and List_Serv2	SERVICE_INSTANCE	LIST	ACTIVE to specify listing only Active Service Instances. ALL to specify all Service Instances will be listed.
Sel_Serv1 and Sel_Serv2	SERVICE_INSTANCE	SELECT	NONE to specify this parameter is not used for this service.
Update_Serv1 and Update_Serv2	SERVICE_INSTANCE	UPDATE	NONE to specify this parameter is not used for this service.
GetStat_Serv1 and GetStat_Serv2	SERVICE_INSTANCE	GET_STATUS	NONE to specify this parameter is not used for this service.
SetStat_Serv1 and SetStat_Serv2	SERVICE_INSTANCE	SET_STATUS	CEASE ceases a Service Instance. REACTIVATE reactivates a disconnected Service Instance.

Table 3-3 lists the values that are required for these parameters for each Product Package service.

Table 3-3 Configuration Parameters for Product Package Services

Service Name	SERVICE_ OBJECT	SERVICE_ METHOD	SERVICE_TYPE
Provision_ppkg	PRODUCT_PACKAGE	PROVISION	NONE to specify this parameter is not used for this service.
List_ppkg	PRODUCT_PACKAGE	LIST	ALL to specify that all Product Packages should be listed. ACTIVE to specify that only Active Product Packages should be listed.
Select_ppkg	PRODUCT_PACKAGE	SELECT	NONE to specify this parameter is not used for this service.
Update_ppkg	PRODUCT_PACKAGE	UPDATE	NONE to specify this parameter is not used for this service.
Set_status_ppkg	PRODUCT_PACKAGE	SET_STATUS	ACTIVE marks Product Package as ACTIVE. CEASE ceases a Product Package. REMOVE removes a Product Package.
Get_status_ppkg	PRODUCT_PACKAGE	GET_STATUS	NONE to specify this parameter is not used for this service.

Table 3-3 lists the values that are required for these parameters for each Product Package Account service.

Table 3-4 Configuration Parameters for Product Package Account Services

Service Name	SERVICE_OBJECT	SERVICE_METHOD	SERVICE_TYPE
Provision_ac	PROD_PKG_ACCT	PROVISION	NONE to specify this parameter is not used for this service.
List_ac	PROD_PKG_ACCT	LIST	ALL to specify that all Product Package Accounts should be listed. ACTIVE to specify that only Active Product Package Accounts should be listed.
Select_ac	PROD_PKG_ACCT	SELECT	NONE to specify this parameter is not used for this service.
Update_ac	PROD_PKG_ACCT	UPDATE	NONE to specify this parameter is not used for this service.
Set_status_ac	PROD_PKG_ACCT	SET_STATUS	ACTIVE marks Product Package Account as ACTIVE. CEASE ceases a Product Package Account. REMOVE removes a Product Package Account.
Get_status_ac	PROD_PKG_ACCT	SELECT	NONE to specify this parameter is not used for this service.

Table 3-3 lists the values that are required for these parameters for each Product Package Service Instance service.

Table 3-5 Configuration Parameters for Product Package Service Instance Services

Service Name	SERVICE_OBJECT	SERVICE_METHOD	SERVICE_TYPE
Provision_sv	PROD_PKG_SERV_ INST	PROVISION	NONE to specify this parameter is not used for this service.
List_sv	PROD_PKG_SERV_ INST	LIST	ALL to specify that all Product Package Service Instances should be listed. ACTIVE to specify that only Active Product Package Service Instances should be listed.
Select_sv	PROD_PKG_SERV_ INST	SELECT	NONE to specify this parameter is not used for this service.
Update_sv	PROD_PKG_SERV_ INST	UPDATE	NONE to specify this parameter is not used for this service.
Set_status_sv	PROD_PKG_SERV_ INST	SET_STATUS	ACTIVE marks Product Package Service Instance as ACTIVE. CEASE ceases a Product Package Service Instance. REMOVE removes a Product Package Service Instance.
Get_status_ac	PROD_PKG_SERV_ INST	SELECT	NONE to specify this parameter is not used for this service.