EAI DLL and EAI File Transports

This chapter discusses the EAI DLL Transport and EAI File Transport business services. It includes the following topics:

About the EAI DLL Transport

You use the EAI DLL Transport when you want to call a function that exists in an external DLL. You must know the exported function in the DLL that you want to invoke. You specify the EAI DLL Transport as one of the business services in your workflow.

Note: The EAI DLL Transport only accepts String type as input or output to the external DLL. The external function also must return String type.

The following topics are discussed here:

EAI DLL Transport Methods

The EAI DLL Transport supports sending messages using the following methods:

Send
SendReceive

EAI DLL Transport Parameters

Use the Send or SendReceive method as needed when you want to pass data from the Siebel Database to an external system. These methods require an input property set. In addition to the common parameters described in EAI Transports and Interfaces Overview, the EAI DLL Transport takes the parameters presented in the following table

Argument	Description
DLLName	Name of the (request/response) DLL.
ExternalFunction	Function in the DLL to invoke.
Return Value	The return value from the function called. This value is an output property.

Calling a Function in an External DLL

The following procedure shows how to call a function in an external DLL.

To call a function in an external DLL

Create a workflow.

Note: For details on creating workflows, see Siebel Business Process Framework: Workflow Guide.
Set the first business service, after the Start, to use the EAI DLL Transport. Usually, this object is named Send.
Double-click to set the input properties for the EAI DLL Transport.
Select a method, either Send, or Send and Receive Response.
Select the input arguments that you want to use from the list that appears (the arguments are described in the table in EAI DLL Transport Parameters.
Enter any output arguments required and save your work.

Creating a DLL to Call a Function in an External DLL

The following procedure illustrates how to create a DLL to use the EAI DLL Transport business service to call a function in an external DLL.

As of Siebel Innovation Pack 2014, a new mechanism is provided to free memory allocated. The creator of the external DLL can now expose additional API functions to free memory. Two new business service method arguments, DLLExternalFunction and DLLExternalFunctionFreeMemory, are added to the Send and SendReceive methods. Both arguments are optional input arguments.

To use the new mechanism for memory deallocation, you must use both of these arguments together: DLLExternalFunction and DLLExternalFunctionFreeMemory.
Customers can optionally use the old approach of only exposing the old argument, ExternalFunction, instead of exposing the new memory freeing API functions. If you continue to use ExternalFunction instead of the new arguments, then the old mechanism is used for memory deallocation. With the old mechanism, failure might occur when the EAI DLL Transport business service performs the memory deallocation.

The signature for the new memory freeing function would resemble the following:

extern "C" int __declspec(dllexport) TestFree(void* Value)

To create a DLL

Open a VC++ project by choosing the Open menu, then New.
Select a Win32 Dynamic Link Library and give a name to the project, such as MyDLL.
In the next dialog box, select the option Simple dll project.
The following files are created by default:
- MyDLL.cpp
- StdAfx.h
- StdAfx.cpp

Make the following changes in the StdAfx.h and Main.cpp files and check the results in the process simulator:

// MyDLL.cpp : Defines the exported functions for the DLL application.
//

#include "stdafx.h"


#include <string.h>
#include <stdio.h>
#include <io.h>
#include <malloc.h>


extern "C" int __declspec(dllexport) TestEAI(const XMLDataBuf* pValue, XMLDataBuf* Value)
{

  FILE *fp = NULL;
  int retf = 0;
  int rc = 0;

  if ((fp = fopen("testeai.txt", "wb")) != NULL)
  {
    fprintf(fp, "Before test");
    fwrite(pValue->pData, sizeof(char), (size_t)pValue->nLength, fp);
    fprintf(fp, " After Test");
    fclose(fp);
  }
  else return -1;

  if ((fp = fopen("testeai.txt", "rb")) != NULL)
  {
    rc = (int)_filelength(_fileno(fp));
    Value->pData = (void *)malloc((size_t)(rc + 1));
    rc = (int)fread(Value->pData, sizeof(char), (size_t)rc, fp);

    fclose(fp);
    Value->nLength = rc;
    ((char*)Value->pData)[rc] = (char)NULL;
  }
  else return -2;

  return rc;

}

extern "C" int __declspec(dllexport) TestFree(void* Value)
{
  if(Value != NULL)
  {
    free (Value);
    Value = NULL;
  }

  return 0;

}

About the EAI File Transport

The EAI File Transport helps move data between a Siebel application and an external file.

Note: The EAI File Transport is different from EAI XML Read from File. The EAI XML Read from File uses a Siebel Message in Hierarchical format as the output property. When reading in data, the EAI File Transport uses a process property with Data Type of Binary as the output property by default; if CharsetConversion is set, then it uses a string output property instead.

The following topics are discussed here:

EAI File Transport Methods

The EAI File Transport supports two transport modes: sending messages and receiving messages. It uses the following methods:

Send
SendReceive
Receive
ReceiveDispatch
ReceiveDispatchSend

Using the EAI File Transport Methods

You create a workflow to use the EAI File Transport, defining and refining the workflow as needed to meet your unique business requirements.

To create a workflow using the EAI File Transport

Create a workflow in Siebel Tools.

Note: For details on creating workflows, see Siebel Business Process Framework: Workflow Guide.
Set up a step in the workflow to use the EAI File Transport. Usually, this object is named Send.
Double-click to set the input properties for the EAI File Transport.
Select a method that fits your business needs.
Select the input arguments that you want to use from the list of arguments. The full list is presented in the table in EAI File Transport Parameters.
Enter any output arguments required and save your work.

Generating Unique Filenames

When using the EAI File Transport, you can have the system generate unique file names for you, as needed. One way is to specify the directory name only. The other way is to include $$ in the filename.

Note: If a directory is not specified when using the EAI XML Write to File, EAI XML Read from File, or the EAI File Transport business service, then the FileName input argument defaults to the directory where the Siebel application is running.

Directory Only. To generate the unique file name, only enter the directory name. For example, instead of specifying the filename as d:\data\record1.xml, just specify d:\data. For every call of the workflow, a unique name is generated in the directory. To find out the file name generated, specify FileName as an output argument for the File Transport Workflow Step.
Using $$. For generating filenames based on the $$ wildcard, specify the filename in the form d:\data\record$$.xml. At run time, Siebel application replaces the $$ with a unique row ID, for example:
```
d:\data\record3-149.xml
```

Note: The file name generated by using $$ is not returned as the output filename property.

EAI File Transport Parameters

In addition to the common parameters presented in Common EAI Transport Parameters, the EAI File Transport takes the parameters presented in the following table. These parameters can be specified as service method arguments, subsystem parameters, or user properties.

Display Name	Parameter	Description
Append To File	AppendToFile	Default is False. A value of True means that, if the file exists, then the method appends the message to the existing file. A value of False specifies that the method overwrites any existing file.
Delete File after Receive	DeleteFile	Default is False. A value of True means that an attempt is made to delete the file after receiving it. If permissions prevent deletion, then no error is given, but the information is traced.
File Name	FileName	The name of the file to be received by the file transport. For the Send method, if a file name is not provided, then a random name is used for the output file. You must specify an explicit path for file name. You can also use `$$` as the wildcard symbol in the file name. For example, if you specify a file name of `“file$$.xml”`, then Siebel CRM creates files like `file1-134.xml`, `fileA25.xml`, and `file242_12B.xml`. For the Receive method, a specific file name must be provided. The use of wildcards such as `$$` is not allowed. The source file is deleted upon receiving if DeleteFile is set to True. If DeleteFile is set to False (the default), then the source file is not deleted.
Response File Name	RespFileName	Name of the file containing the response when using the SendReceive Method.
Sleep Time	FileSleepTime	The timeout interval on receive calls, in milliseconds. This specifies the maximum amount of time that the service waits for a response. Default is 20000 milliseconds.

Enabling Write Access for the EAI File Transport

The EAIFileTransportFolders parameter allows you to enable write access for the EAI File Transport for specific folders within the Siebel file system. The EAIFileTransportFolders parameter can be set at the enterprise or server level as a semicolon-separated list.

By default, the Siebel temporary folder, SIEBSRVR_ROOT\TEMP, is a permitted folder and is not required to be explicitly configured with the EAIFileTransportFolders parameter. If the parameter is not configured, then writing is allowed only to the Siebel temporary folder; any attempt to write a file to a folder other than the Siebel temporary folder fails.

Caution: Do not allow write access to the SIEBSRVR_ROOT\BIN folder. Write access to the BIN folder allows anyone to overwrite Siebel system DLL files.

Configuring the EAIFileTransportFolders Parameter at the Enterprise Level

You use the srvrmgr utility to configure the EAIFileTransportFolders parameter at the enterprise level.

To configure the EAIFileTransportFolders parameter at the enterprise level

Use the following command in srvrmgr:

change ent param EAIFileTransportFolders=\\fileserver\fs1;\\fileserver2\fs2

Configuring the EAIFileTransportFolders Parameter at the Server Level

You use the srvrmgr utility to configure the EAIFileTransportFolders parameter at the server level.

To configure the EAIFileTransportFolders parameter at the server level

Use the following command in srvrmgr:

change param EAIFileTransportFolders=\\fileserver\fs1;\\fileserver2\fs2 for server servername

Configuring the EAIFileTransportFolders Parameter in the Application Configuration File

You add a new section to the application configuration file to configure the EAIFileTransportFolders parameter.

To configure the EAIFileTransportFolders parameter in the application configuration file

Open the application configuration file, such as uagent.cfg, in a text editor.

Add the following section:

[EAIFileTransportConfigSubsys]
EAIFileTransportFolders = \\fileserver\fs1;\\fileserver2\fs2

EAI File Transport Named Subsystem

The EAI File Transport can read parameters from a named subsystem. For the EAI File Transport, the named subsystem type is FileTranspSubsys.

The following example shows how to use the FileTranspSubsys named subsystem with EAI File Transport business service methods.

Receiving a Message and Writing It to a File

This example uses the Receive method of the EAI File Transport business service to receive a message as a file, then it uses the Send method of the EAI File Transport business service and the FileTranspSubsys named subsystem to write the message to a file.

To receive a message and write it to a file

Define an EAI File Transport named subsystem, for example:

create named subsystem FileConnSubsys_sub for subsystem FileTranspSubsys with 
FileName="D:\temp\FileOut.txt", AppendToFile=true

Create a workflow containing the following steps, as shown in the following image:
1. Receive
2. Write to File
Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.

Define the following process properties:

Name	Data Type	In/Out	Default String
BinaryMsg	Binary	In/Out	Not applicable
Error Code	String	In/Out	Not applicable
Error Message	String	In/Out	Not applicable
Object Id	String	In/Out	Not applicable
Process Instance Id	String	In/Out	Not applicable
Siebel Operation Object Id	String	In/Out	Not applicable

Set up the first business service step to use the EAI File Transport business service with the Receive method and the following input and output arguments:

Input Argument	Type	Value
FileName	Literal	D:\temp\InputToFile.txt

Property Name	Type	Output Argument
BinaryMsg	Output Argument	<Value>

Set up the second business service step to use the EAI File Transport business service with the Send method and the following input arguments:

Input Argument	Type	Value	Property Name
<Value>	Process Property	Not applicable	BinaryMsg
ConnectionSubsystem	Literal	FileConnSubsys_sub	Not applicable