4 Deploying the COM Solution for Business Function Execution

This chapter contains the following topics:

• Section 4.1, "Understanding COM Server Deployment for Business Function Execution"

• Section 4.2, "Setting Up the DCOM Server for Business Function Execution"

• Section 4.3, "Installing COM Connector"

• Section 4.4, "Using OCM Support with COM Connector"

• Section 4.5, "Using BHVRCOM with COM"

• Section 4.6, "Use IJDETimeZone Interface"

• Section 4.7, "Requesting Inbound XML Using COM Server"

• Section 4.8, "Using COM Reliability"

• Section 4.9, "Using COM Tracing and Logging"

4.1 Understanding COM Server Deployment for Business Function Execution

The COM server uses socket-based middleware to access the JD Edwards EnterpriseOne application server. The jdeinterop.ini file must be configured to specify the JD Edwards EnterpriseOne server. The COM server reads the jdeinterop.ini file and opens the socket connection to the specified application server.

This diagram illustrates COM server deployment:

Figure 4-1 COM server deployment

Description of "Figure 4-1 COM server deployment"

4.2 Setting Up the DCOM Server for Business Function Execution

This section provides an overview of the DCOM server and discusses how to:

• Set up DCOM for a server environment.

• Set up security on the COM server.

• Set up the identity as interactive user.

• Set up DCOM for a client environment.

4.2.1 Understanding DCOM Server Set Up

You can set up a DCOM server on a JD Edwards EnterpriseOne server machine. DCOM enables COM objects in a distributed environment. To ensure that the interoperability client works properly, you must set up DCOM for both a server environment and for a client environment.

4.2.2 Setting Up DCOM for a Server Environment

Use these steps to set up DCOM for a server environment:

1. Run GenCOM on a JD Edwards EnterpriseOne client machine, with these options:

   gencom /out <path> /tempout <path> /cmd App.cmd

   Because GenCOM is a JD Edwards EnterpriseOne client-side only tool, you must perform this step on a JD Edwards EnterpriseOne client machine.

2. Copy the App.dll file and the App.tlb file generated by GenCOM to the COM server machine.

3. On the COM server machine, from the command line:

   • Run jdecomconnector2.exe /RegServer.

   • Run regsvr32 App.dll.

   • Set the correct security level for jdecomconnector2.exe and App.dll.

4.2.3 Setting Up Security on the COM Server

Use these steps to set up security on the COM server:

1. From the Start menu, select Run.

2. Enter Dcomcnfg.exe.

3. On Distributed COM Configuration Properties, click the Default Security tab.

4. Click the Edit Default Button in Default Access Permissions group.

   The Registry Value Permissions form appears. Some entries might already be present.

5. On Registry Value Permissions, click Add.

6. On Add Users and Groups, select the appropriate domain from the List Names From option.

7. Click Everyone, and then click Add.

   Type of access should be Allow Access.

8. Click OK.

   Repeat Steps 4 through 7 for default launch permissions. No setup is required for default configuration permissions.

4.2.4 Setting Up the Identity as Interactive User

Use these steps to set up the identity as interactive user:

1. Run DCOMCnfg.

2. On Distributed COM Configuration Properties, select JDECOMConnector2, and then click Properties.

3. On JDECOMConnector2Properties, click the Identity tab, and then select the interactive user option.

4. Click Apply to apply the change.

   Note:

   You must perform this task every time you register the connector. If you copy the JDECOMConnector2.exe using Explorer, Explorer reruns the registration, and you must repeat these steps.

To use Callbacks (Connection Points) with the COM solution, repeat the same procedure on the COM client machine. Most of the shipped examples use Callbacks and require that you open the security on the client machine.

4.2.5 Setting Up DCOM for a Client Environment

Use these steps to set up DCOM for a client environment:

1. From a DOS prompt on the DCOM client machine, run jdecomconnector2.exe /RegServer.

2. At the prompt, enter oleview.exe.

3. From the menu bar, select oleview.

4. Click View and select Expert Mode.

5. In the oleview window under Object Classes, double-click All Objects, and wait for all objects to appear.

6. Under All Objects, find and click Connector Class.

7. Click the Implementation tab on the right-side panel, and then click the local server and remove anything that appears in the editing window.

8. On the Activation tab, select the Launch as Interactive User option.

9. In Remote Machine Name, enter the COM server machine name.

10. Repeat steps 5 through 8 for MathNumeric Class.

11. Start the DCOM client application.

    Note:

    Client-only business functions are not reachable.

4.3 Installing COM Connector

This section discusses how to install the COM connector in a non-JD Edwards EnterpriseOne client environment.

4.3.1 Installing COM Connector on a Non-JD Edwards EnterpriseOne Client Environment

Use these steps to install the COM connector on a non-JD Edwards EnterpriseOne client machine:

1. Copy these files from the JD Edwards EnterpriseOne server (system\bin32) to a directory on the desired machine. For example, copy the files in c:\program files\JDEdwards to a non-JD Edwards EnterpriseOne client machine.

   • CallObject.dll

   • ClientService.dll

   • comlog.dll

   • EventHandler.dll

   • EventListner.dll

   • icui18n.dll

   • icuuc.dll

   • JDECOMConnector2.exe

   • jdecommn.dll

   • jdel.dll

   • jdeunicode.dll

   • PSThread.dll

   • ustdio.dll

   • XERCES4C.dll

   • XercesWrapper.dll

   • XERCESDDOM.dll

   • xmlinterop.dll

   • XMLRequest.dll

2. Create a new directory Icu\data\ on the machine where the COM server is located. Copy all of the files from the JD Edwards EnterpriseOne server in folder system\Locale\xml\*.* into Icu\data\. Create a new system variable, ICU_DATA, in the environment variables of the system properties and specify the path to the Icu\data\ as the value.

3. Execute this command on the target location to register the COM connector components:

   JDECOMConnector2.exe /RegServer
   

4. Run GenCOM on a JD Edwards EnterpriseOne client machine and copy the output DLL and the wrapper components (for example, wrapper.dll).

5. Execute this command to register the COM wrapper components:

   regsvr32 wrapper.dll
   

6. Create the JDEinterop.ini file.

   Set the JD Edwards EnterpriseOne server and port values to the JD Edwards EnterpriseOne application server with which you want the COM server to communicate.

   The COM server is now ready.

To unregister the COM server, use the /unreserved option. For example:

JDECOMConnector2.exe /unreserved

To unregister the COM wrapper, use the /u option. For example:

regsvr32 /u wrapper.dll

See Also:

• Understanding jdeinterop.ini for COM Connector.

4.4 Using OCM Support with COM Connector

You use Object Configuration Manager (OCM) to map business functions to a JD Edwards EnterpriseOne server so that the COM connector can access OCM to run business functions. You no longer configure the jdeinterop.ini file to define the JD Edwards EnterpriseOne server from which you want to execute business functions. Using OCM support should result in increased performance, scalability, and load balancing. OCM mapping enables the COM interoperability server to distribute the processes of the COM connector client to various JD Edwards EnterpriseOne servers' requests, depending on the user, environment, and role name.

To take advantage of COM connector OCM support, the system administrator should:

• Get the GenCOM JD Edwards EnterpriseOne 8.10 (or later) version and regenerate the business wrapper function.

• Configure the OCM and map the business function on the enterprise server.

• Add these settings in the jdeinterop.ini configuration file.

4.4.1 [INTEROP]

Setting	Explanation
EnterpriseServer = ntropt1	For COM events and backward compatibility.
SecurityServer = ntropt1	Validates the login.
Port = 6079	The port number.

The database administrator or JD Edwards EnterpriseOne administrator can provide these settings for the [OCM] section of the jdeinterop.ini configuration file. This information is used for database connectivity.

4.4.2 [OCM]

Setting	Explanation
DSN=ODA ITTND17	The data source name from the system DSN of the ODBC setting.
OCM Datasource = COM OCM	System data source for JD Edwards EnterpriseOne client.
DB User = JDE	User for the data source connection.
DB Pwd = JDE	Password for the data source connection.
Object Owner = SYS9	For UNIX platforms, this is the object owner in the [DB SYSTEM SETTINGS].
Seperator=.	For Oracle, SQL and UDB databases, the separator is a period (.); for IBM i, the separator is a slash (/).

If you use a client machine, the settings can be found in the client jde.ini file. An example of the database name and object owner is: JDE9.SYS9, where JDE9 is the database name and SYS9 is the object owner.

4.5 Using BHVRCOM with COM

JD Edwards EnterpriseOne clients use the BHVRCOM structure to control the execution of business functions. A COM client can use the IBHVRCOM interface to set and get BHVRCOM values for business functions. The interface definition is in the jdeconnector2.idl file.

This Visual Basic code demonstrates how to query the IBHVRCOM interface and pass values to business functions:

Dim conn As New Connector  '//COM Connector
DIM WithEvents OW As OneWorldInterface  '//OneWorldInterface
Dim myBHVRCOM As IOneWorldBHVRCOM  '//BHVRCOM
Dim AB As JDEAddressBook  '// AddressBook
Dim phone As D0100032  '//Data source
1 = conn.Login("JDE", "JDE", "M7332RS02")
Set OW = conn.CreateBusinessObject("OneWorld.FunctionHelper.1",1)
Set myBHVRCOM = OW  '// query the IOneWorldBHVRCOM interface
MyBHVRCOM.iBobMode = 8  '// set BHVRCOM values
MyBHVRCOM.szApplication = "myApp"
MyBHVRCOM.szVersion = "myVersion"
Set AB = conn.CreateBusinessObject("AddressBook.JDEAddressBook",1)
Set phone = AB.CreateGetPhoneParameterset
Phone.mnAddressNumber = 1
AB.GetPhone phone, OW, conn, 1  '// business function is executed with 
the BHVRCOM values

This table explains some of the code:

Code	Explanation
myBHVRCOM.iBobMode=	BobMode is the mode (add, update, delete) of the interactive application. Values for BobMode are: BOB_MODE_UNDEFINED = 0 BOB_MODE_SPECIAL = 1 BOB_MODE_ADD = 2 BOB_MODE_ADD_PRIMARY = 3 BOB_MODE_ADD_SPECIAL = 4 BOB_MODE_DELETE = 5 BOB_MODE_UPDATE = 6 BOB_MODE_UPDATE_SPECIAL = 7 BOB_MODE_INQUIRE = 8 BOB_MODE_COPY = 9
myBHVRCOM.szApplication=	The value is the name of the interactive application.
MyBHVRCOM.szVersion=	The value is the version of the interactive application. This field can be used for localizations of the applications.

4.6 Use IJDETimeZone Interface

To modify and display the JDEUTIME data type in the appropriate format, the COM client and GenCOM must use the JDEUTIME APIs. Date and time information is displayed in a time based on the date and time that is in the personal profile or a time zone specified by an application.

These steps, along with sample code, illustrate how to use the IJDETimeZone Interface.

• Create the IJDETimeZone interface.

  MULTI_QI mqi = { &IID_IJDETimeZone, 0, 0 };
  hr = CoCreateInstanceEx(CLSID_JDETimeZone, 0, CLSCTX_ALL, 0, 1, &mqi);
  if (SUCCEEDED(hr) && SUCCEEDED(mqi.hr)) 
  {
     *ppJdeTimeZone = reinterpret_cast<IJDETimeZone*>(mqi.pItf); 
  }.
  

• Set the time for a time zone (UTC-5:30) for the data structure DXXXXXX.

  If a time zone is not specified, the time is considered to be at UTC. If an invalid time zone string is passed, then an error occurs.

  DATE dt;
  BSTR bstrUTC = SysAllocString(L"UTC-5:30");
  pJDETimeZone->put_DateTime(bstrUTC,&dt);
  DXXXXXX->put_jdOrderDate(pJDETimeZone);
  

• Get a time for a given time zone from JD Edwards EnterpriseOne.

  If a time zone string is not passed, the time and date stored in JD Edwards EnterpriseOne, which is at UTC, is returned. If an invalid time string is passed, then an error occurs.

  DXXXXXX->get_jdOrderDate(pJDETimeZone);
  DATE dt;
  BSTR bstrUTC = SysAllocString(L"UTC-5:30");
  pJDETimeZone->get_DateTime(bstrUTC,*dt);
  

4.6.1 XML File generated by GenCOM for IJDETimeZone

For each data item whose data type is JDEUTIME in the data structure DXXXXXX, GenCOM generates this XML file:

<Signature environment="Environment Name">
 <Interface name="Interface Name">
    <Method name="BSFN">
        <Param name="DXXXXXX" type="u" />
    </Method>
 </Interface>
</Signature>

4.7 Requesting Inbound XML Using COM Server

You can use the COM connector to send inbound synchronous XML requests (such as XML CallObject, XML List, and XML UBE) to the JD Edwards EnterpriseOne server.

See Also

• "Submit a UBE from XML" in the JD Edwards EnterpriseOne Tools Interoperability Guide.

• "Understanding XML CallObject" in the JD Edwards EnterpriseOne Tools Interoperability Guide.

• "Understanding XML List" in the JD Edwards EnterpriseOne Tools Interoperability Guide.

This sample code shows how to use the COM connector to execute an inbound XML request.

// File : testDriver.cpp 
// Purpose      : a test driver to submit the xml request document to OneWorld through
// ThinNet 
// Usage        : testDriver <input xml doc> <host> <port> <timeout>
// Platform     : Win32 Console Program. 
// DLL requirement:      xmlinterop.dll, jdeunicode.dll, jdel.dll, jdethread.dll.
 
 
#include "iostream"
#include "fstream"
#include "string"
#include   <jde.h>
#include <jdeunicode.h>
 
extern "C" ZCHAR * JDEWINAPI jdeXMLRequest(const JCHAR *szHostName, unsigned short usPort, const int nNetTimeout, void *xml, int size);
extern "C" void JDEWINAPI jdeFreeXMLResponse(ZCHAR *szResp);
 
 
int _cdecl wmain(int argc, wchar_t* argv[], wchar_t* envp[])
{
 
   ZCHAR     *buf;
   DWORD    dwSize;
   DWORD    dwBytesRead;
   HANDLE   hFile;
 
   if( argc != 5 )
   {
           std::wcout << _J("Usage: cotest <input xml doc> <host> <port> <timeout>");
      return 0;
   }
 
 
  // read the <XML input doc>. 
  // Note: the APIs for reading the file are only avaliable in win32. 
  if(INVALID_HANDLE_VALUE == (hFile = CreateFile(argv[1], GENERIC_READ,
    0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL)))
    return 0;
 
  if(0xFFFFFFFF == (dwSize = ::GetFileSize(hFile, NULL)))
    return 0;
 
  buf = new ZCHAR[dwSize + 1];
  memset( buf, 0, dwSize+1 );
  if(!ReadFile(hFile, buf, dwSize, &dwBytesRead, NULL))    
    return 0;
  
  CloseHandle(hFile);   
 
   // call C thinNet API to send XML request document 
   ZCHAR* presp = jdeXMLRequest(argv[2], jdeAtoi(argv[3]), jdeAtoi(argv[4]), buf, 0);
 
 
  // write the XML response into a log file <xmlDoc.log>
  // Note: the APIs for writing the file are only avaliable in win32. 
   std::wstring outFile( (JCHAR*)argv[1] );
   std::wstring outExt ( _J(".log") );
 
   int i;
   if(  (i = outFile.find( _J(".") )) > 0 )
   {
      outFile.replace( i, 4, outExt);
 
   }
   else
   {
      outFile.append( outExt );
   }
   ZCHAR *outfile = new ZCHAR[jdeStrlen(outFile.c_str())+1];
   jdeFromUnicode(outfile, outFile.c_str(), jdeStrlen(outFile.c_str())+1, NULL);
 
   std::ofstream outf(outfile);
 
   outf << presp;
 
   // free the resource 
   delete [] buf;
   delete[] outfile;
   jdeFreeXMLResponse(presp);
   
 
        return 0;
}

4.8 Using COM Reliability

Graceful fail-over and fault tolerance mechanisms are important, especially for applications that require high availability. The COM connector provides basic support for fault tolerance at the protocol level.

You should take additional precautions to provide further reliability. After you use the COM connector to enter an order or execute a business function, the process should:

• Handle transaction failures.

  Transactions can fail because of communication line failures. Sometimes transactions must be aborted because of errors in input or deadlocks. These failures must be handled appropriately.

• Wait for the confirmation or success notification from the business function to ascertain that the call was successfully committed.

• Query on the order entered to make sure that it has been committed to the database.

  Due to high network traffic, a business function can properly execute, but the confirmation message might not reach you.

4.9 Using COM Tracing and Logging

You use COM tracing and logging to help you debug the COM applications. You use the jdeinterop.ini file to configure tracing and logging settings. The logging format is similar to the JD Edwards EnterpriseOne logging format. For example, both logging formats include the Time Thread ID [User ID] and Description, as illustrated:

Thu Mar 02 14:48:01 2000 294 [AR618238] Failed to Login to Environment <ADEVHPO2>

Errors are written to the JobFile and trace messages are written to the Debug File. When trace is enabled, error messages go into both trace and error logs.

You can change the jdeinterop.ini settings while the connector is running by completing these the steps:

1. Modify the jdeinterop.ini file.

2. Right-click the Connector System Tray button.

3. Select the menu item ChangeIniSettings.

   If an option in the jdeinterop.ini file does not have an entry, the default value is used.

4.9.1 Resolving Tracing Issues

Tracing affects performance. You do not need to use tracing unless you are debugging an application. If performance is negatively affected, ensure that the tracing level is set to zero.

If no logs are generated, complete these steps:

• Ensure that you have specified the proper path in the ini file.

• Verify that disk space and the permissions on the file system are correct.

• Verify whether the default log files have been generated.

• Check the interop.log to see if any errors corresponding to logging have been generated.

• Check the interop.log file to see if the ini settings that are being used are the same as what you have specified elsewhere.