This document covers the following topics:
All the Software AG IDL data types are mapped to the COM data types as shown in the table below.
| IDL Data Type | C++/COM Data Type | Visual Basic Data Type | Note |
|---|---|---|---|
| A | BSTR | String | See note below. |
| AV | BSTR | String | See note below. |
| B | unsigned char | Byte | See note below. |
| BV | SAFEARRAY(unsigned char) | Byte | See note below. |
| D | DATE | DATE | |
| F4 | float | Single | |
| F8 | double | Double | |
| I1 | short | Integer | Range is -128 to 127. |
| I2 | short | Integer | |
| I4 | long | Long | |
| K | BSTR | String | See note below. |
| KV | BSTR | String | See note below. |
| L | VARIANT_BOOL | Boolean | |
| N | BSTR/double | String/Double | Depending on code generation option Code Type. |
| P | BSTR/double | String/Double | Depending on code generation option Code Type. |
| T | DATE | DATE |
Note:
The maximum length you can specify depends on your hardware
configuration and your software environment apart from EntireX. There is,
however, an absolute limit (1 GB) that cannot be exceeded.
The DCOM Wrapper is used to generate an ActiveX automation server from an IDL file. The DCOM Wrapper Wizard generates a batch (script) file in the directory where the IDL file resides:
<idl-filename>.bat on Windows (see Platform Coverage)
This file uses the Software AG IDL Compiler and appropriate C++ development tools to generate the ActiveX automation server code. See Software AG IDL File in the IDL Editor documentation for IDL file specifications.
The locations of generated Wrapper objects depend on the directory containing the corresponding IDL file. The names of generated Wrapper objects depend on the names of the libraries defined in the IDL file.
Wrapper automation objects may be renamed using the Naming Options dialog, but the names of the generated Wrapper files remain unaffected.
The automation object name is used to define the COM program and application ID (ProgID and AppID). A separate Wrapper object is generated for each library defined in an IDL file. To avoid name clashes because of different Wrapper objects having the same name, we recommend that you put all programs contained in one library into one IDL file.
Assume the IDL file is named calc.idl and defines a program calc in the library Example. The default Wrapper automation object name is therefore EOL.Example.
The DCOM Wrapper Wizard first generates a batch file calc.bat in directory calc. The appropriate subdirectories and GUID files are created as necessary. If you run the batch file calc.bat, a platform-dependent subdirectory Example is created in directory calc as described below. For each library defined in the IDL file, a subdirectory with the same name as the library is created in the platform-dependent subdirectory.
The generated Wrapper object is located in directory calc\win32\Example and is named Example.dll. If the Generate DCOM Proxy box has been checked, the directory will also contain the proxy object pExample.dll.
Note:
Declaring long library names within the Software AG IDL file will
also result in long folder names, which in certain circumstances may cause
problems.
In addition to the parameter descriptions of the remote procedures as specified in the IDL file, every automation object supports broker and RPC server related properties. Methods are available to set and/or retrieve these properties. For more information, see API Data Descriptions for the C Wrapper.
| Property Name | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
BrokerSecurity |
Get/Set Broker Kernel Security. Corresponds to Broker ACI field
KERNELSECURITY. See KERNELSECURITY.
|
||||||||
Codepage |
Get/Set the codepage. This property allows RPC clients generated with the DCOM Wrapper to assign a codepage other than the
default Windows ANSI codepage (CP_ACP).
For more information see Using Internationalization with the DCOM Wrapper. |
||||||||
Compression |
Used to set and/or retrieve the compression value. | ||||||||
CompressLevel |
Compression level. Valid values: N/Y/0-9.
Only the first character of the string will be used for the compression. If you type YES, the character Y will be used and ES will be cut off. See also Data Compression in EntireX Broker. |
||||||||
ErrorClass |
Used to retrieve the error class of last object call. | ||||||||
ErrorMessage |
Used to retrieve the error message of last object call. | ||||||||
ErrorNumber |
Used to retrieve the error number of last object call. | ||||||||
ForceLogon |
Determines whether explicit or autologon is used by the caller. | ||||||||
get_StatusOfMessage(messageID) |
Gets the status of the message identified by the message ID (valid for reliable RPC). See Reliable RPC for DCOM Wrapper. | ||||||||
GetVersion |
Get the version of DCOM Wrapper generated object:
|
||||||||
Library |
Used to set and/or retrieve the Natural library. The default for Library is the library name used in the IDL file. | ||||||||
MessageID |
Gets the message ID (valid for reliable RPC). See Reliable RPC for DCOM Wrapper. | ||||||||
NaturalLogon |
Used to set and/or retrieve the Natural logon value. The default
is no Natural logon. Valid parameters are Y or N. The parameter must be a
single character string. If the property has been set to Y, the next call to
the Natural server will cause a Natural Logon. The properties RpcPassword and
RpcUserID will be used to check the user's authentication.
|
||||||||
NewPassword |
Used only for changing the user password. The user password cannot be retrieved. | ||||||||
PassWord |
Used only for setting the user password. The user password cannot be retrieved. The default is to use no password. | ||||||||
Reliable |
Used to set and/or retrieve the mode for reliable RPC. See Reliable RPC for DCOM Wrapper. | ||||||||
ReliableCommit |
Commit a transaction (unit of work) for reliable RPC. | ||||||||
ReliableRollback |
Roll back a transaction (unit of work) for reliable RPC. | ||||||||
RpcPassword |
Used only for setting the RPC user RPC password. The RPC user RPC password cannot be retrieved. The default is the value of property PassWord. | ||||||||
RpcUserID |
Used to specify RPC user ID. It can also be used to retrieve the current RPC user ID. The default for RPC user ID is the value of property userID. | ||||||||
SecurityToken |
Security token generated by EntireX Security and EntireX Broker
after successful security validation. Do not overwrite or change it.
Corresponds to the Broker ACI field SECURITY-TOKEN. See SECURITY-TOKEN and also
Introduction to EntireX Security.
|
||||||||
ServerAddress |
Used to set and retrieve the server address. The default is the value entered in the DCOM Wrapper Options dialog. | ||||||||
SetInfo |
This method accepts named parameters. Clients can set all or any of the above attributes using this method. See Examples for more information. | ||||||||
SSLString |
Used for setting the SSL parameters. | ||||||||
TimeOut |
User can set and/or retrieve the timeout value. The default value is 50 seconds. | ||||||||
Token |
Used to set and/or retrieve the Token. | ||||||||
UserID |
Used to specify user ID. It can also be used to retrieve the current user ID. The default for user ID is USER. |
ActiveX automation technology supports only a restricted set of data types.
The DCOM Wrapper supports the use of arrays with up to three dimensions. For all base types, the DCOM Wrapper uses the so-called SAFEARRAY data type for the mapping of arrays to ActiveX data types.
Note:
If the SAFEARRAY data type is used, the system expects the array to
have the correct size. It is not recommended that you leave any member of an
array undefined.
This section covers the following topics:
...
Program 'CPROG' is
Define data parameter
1 IVALUE (I4) IN
1 IARRAY (A80/1:9) IN
end-define
...
dim arr()
redim arr(8)
...
for n = 0 to 8
arr(n) = "ONLY IN " & (n+1)
document.write arr(n)
next
WrapperObject.CPROG 123, arr
...
long i4_single = 12345678;
SAFEARRAY *iarray;
SAFEARRAYBOUND rgsabound_dim1[] = {9, 0};
char temp [32];
OLECHAR wtemp[32];
iarray = SafeArrayCreate(VT_BSTR, 1, rgsabound_1 );
for (i = 0; i <9; i++)
{
sprintf (temp,"I%d",(i+1)*1);
mbstowcs(wtemp, temp, 80);
iarray[i] = SysAllocString(wtemp);
}
VARIANTARG args[2];
VariantInit(args);
VariantInit(args+1);
DISPPARAMS params;
V_ARRAYREF(args+1) = & iarray;
V_VT(args+1) = VT_ARRAY|VT_BSTR|VT_BYREF;
V_I4REF(args) = &i4_single;
V_VT(args) = VT_I4|VT_BYREF;
params.rgvarg = args;
params.rgdispidNamedArgs = cNames > 1 ? id+1 : 0;
params.cArgs = 2;
params.cNamedArgs = cNames-1 ;
EXCEPINFO pExcpInfo;
res = pDspObj->Invoke( id[0],
IID_NULL,
0,
DISPATCH_METHOD,
¶ms,
NULL,
&pExcpInfo,
0 );
...
...
Program 'APROG' is
Define data parameter
1 IVALUE (I4) IN
1 IOARRAY (A80/1:10) IN OUT
end-define
...
dim arr()
redim arr(9)
...
for n = 0 to 9
arr(n) = "INOUT" & (n+1)
document.write arr(n)
next
WrapperObject.APROG 123, arr
For each strval in arr
Document.write strval
Next
...
long i4_single = 12345678;
SAFEARRAY *ioarray;
SAFEARRAYBOUND rgsabound_dim1[] = {10, 0};
char temp [32];
OLECHAR wtemp[32];
ioarray = SafeArrayCreate(VT_BSTR, 1, rgsabound_1 );
for (i = 0; i <10; i++)
{
sprintf (temp,"I%d",(i+1)*1);
mbstowcs(wtemp, temp, 80);
ioarray[i] = SysAllocString(wtemp);
}
VARIANTARG args[2];
VariantInit(args);
VariantInit(args+1);
DISPPARAMS params;
V_ARRAYREF(args+1) = & ioarray;
V_VT(args+1) = VT_ARRAY|VT_BSTR|VT_BYREF;
V_I4REF(args) = &i4_single;
V_VT(args) = VT_I4|VT_BYREF;
params.rgvarg = args;
params.rgdispidNamedArgs = cNames > 1 ? id+1 : 0;
params.cArgs = 2;
params.cNamedArgs = cNames-1 ;
EXCEPINFO pExcpInfo;
res = pDspObj->Invoke( id[0],
IID_NULL,
0,
DISPATCH_METHOD,
¶ms,
NULL,
&pExcpInfo,
0 );
...
...
Program 'BPROG' is
Define data parameter
1 IVALUE (I4) IN
1 IARRAY (A80/1:10) OUT
end-define
...
dim arr()
'redim arr(10)
...
WrapperObject.BPROG 123, arr
For each strval in arr
Document.write strval
Next
See Notes on Visual Basic below.
In the C/C++ language, the INOUT and OUT parameters behave in the same
way. See C/C++ example for INOUT parameters above.
After the call that creates this array, you can check the array bounds with the Visual Basic functions LBound and UBound.
Visual Basic arrays start with index 0. VBScript does not support the "dim myarray(... to ...)" notation. Because array sizes are checked, you must dimension your array n -1 when it contains n elements.
IN, OUT arrays must be defined like OUT arrays and then redimensioned to the required size.
EntireX DCOM Wrapper version 5.1 and above creates objects that support VARIANT references. Scripting languages such as VBScript pass output parameters by VARIANT references and not by exactly defined type. For example, when a method of a COM interface has an OUT parameter of type string, Visual Basic passes a reference to a VARIANT to get the OUT parameter. DCOM Wrapper objects try to convert these references into the required reference type.
VBScript supports VARIANT reference.
If you are using PERL for Win32 or JScript, refer to the appropriate documentation for information whether the used version supports VARIANT reference.
The IDL syntax allows you to define (remote) procedures only. This is similar to Natural, which knows only procedures (referred to in Natural as subprograms). Neither IDL nor Natural have the concept of a function. A function is a procedure which, in addition to the parameters, returns some value.
It is possible to treat the OUT parameter of a procedure as the return value of a function. Using this technique, a procedure can be used as a function. The DCOM Wrapper generates a function rather than a procedure when the following two conditions are met:
the last parameter of the procedure definition is of type OUT
this last parameter of the procedure definition has the name
Function_Result
As an example, see the following IDL program definition:
Program 'Calc' Is Define Data Parameter 1 Operator_ (A1) In 1 Operand_1 (I4) In 1 Operand_2 (I4) In 1 Function_Result (I4) Out End-Define
From the above specification, the DCOM Wrapper generates an object that can be called from Visual Basic as follows:
Dim result As Long
. . .
result = CALCOLEObj.calc ("+", 1234, 1234)
If the last parameter had a name other than
Function_Result in the IDL file, the call in Visual
Basic would look as follows:
CALCOLEObj.calc "+", 1234, 1234, result
For an explicit logon, each Wrapper object that is generated supports
the methods Logon and Logoff.
During logon, user ID and password are validated by EntireX Broker and EntireX
Security. Logoff frees allocated resources in EntireX Broker and EntireX
Security, which results in fewer bottlenecks.
Issue a logon once for every EntireX Broker you deal with, normally at the start of the application. Do not issue separate logons for every Wrapper object when using multiple objects in an application.
Issue a logoff whenever an EntireX Broker is not needed for a longer period, and always issue a logoff at the end of the application.
Issue a logon and a logoff for every token used.
Dim OLEObj as Object ' Create the Object OLEObj.UserID = "<User ID>" 'Set the User ID OLEObj.Password = "<Password>" ' Set the Password OLEObj.Logon ' Sign on ... OLEObj.Logoff ' Sign off
This section contains the following topics:
The basic method of communication for both the EntireX and the Natural RPC is non-conversational (also known as connectionless communication). Using this method, each RPC message is isolated and has no relationship to any other RPC message.
The DCOM Wrapper also supports conversational communication (also known as connection-oriented communication), where the two partners (client and server) retain a communication link over several remote procedure calls.
Conversational communication facilitates a more object-oriented design
approach. In addition, a context can be maintained on the server side when a
Natural RPC Server is in use. See the DEFINE DATA
CONTEXT statement in the appropriate Natural Documentation.
The conversation is handled by the following standard Wrapper methods:
| Method Name | Description |
|---|---|
| OpenConversation | Used to open a conversation to the named server. Until one of
the CloseConversation methods is used, all subsequent
RPC messages belong to the opened conversation. A Wrapper object is either in
non-conversational or conversational mode. A mixture of the two modes is not
possible.
|
| CloseConversation | Used to close the previously opened conversation. When the
partner is a Natural RPC Server, it implicitly executes a database
BACKOUT TRANSACTION before closing the conversation. When the partner is an
EntireX RPC server, no database backout is executed. All other database
operations are the responsibility of the user.
|
| CloseConversationCommit | Used to close the previously opened conversation. When the
partner is a Natural RPC Server, it implicitly executes a database END
TRANSACTION before closing the conversation. When the partner is an EntireX RPC
server, no database commit is executed. All other database operations are the
responsibility of the user.
|
On Error Goto ErrHandling
Dim OLEObj as Object ' Create Object
Set OLEObj = CreateObject("ObjectName")
OLEObj.OpenConversation ' Open the Conversation
OLEObj.<RPC Message 1> ' first RPC Message
OLEObj.<RPC Message 2> ' second RPC Message
..
OLEObj.<RPC Message n> ' n th RPC Message
OLEObj.CloseConversationCommit ' Close the Conversation with END TRANSACTION
ErrHandling:
OLEObj.CloseConversation ' Close the Conversation with BACKOUT TRANSACTION
The OpenConversation call establishes the
conversation with the previously specified server. Assuming the RPC messages
contain database update operations, the
CloseConversationCommit makes the database
modifications active by implicitly executing the END TRANSACTION operation.
When an error occurs within the conversation, the database operations are
backed out implicitly by the CloseConversation call.
When an END TRANSACTION or BACKOUT is needed within the conversation
(without closing the conversation) simply define Backout
and Commit in the IDL file as programs and implement
them on the server. Backout or Commit can then be invoked as OLEObj.Backout and
OLEObj.Commit.
If you need to have a second conversation in parallel, simply define a second object in your application.
Dim OLEObj1 as Object ' Create first object Dim OLEObj2 as Object ' Create second object
Try to keep the duration of the conversations to a minimum when the
Natural RPC Server is in use. Remember the server is blocked and in
exclusive use by the calling client and cannot be used in parallel by other
clients. Prestarting enough server replicas could improve this performance
problem; using the EntireX Attach Manager would solve it. However, the EntireX
RPC Server can be set up to create a replica for each new conversation. Always
remember to code a CloseConversation call.
The method can be used to set more than one property at a time. Each
property will be passed with named variables. For an example see
Setting up User ID and Timeout Value using Method SetInfo.
To fine tune the behavior of the DCOM Wrapper object, the
following features are available. If you prefer the defaults of EntireX
versions up to 5.3, use put_Feature("EXX53", true).
| Feature | Default | Description | Note on Versions up to 5.3 |
|---|---|---|---|
| StringTrimming | ON | Trim trailing space characters from the string for the received string. The String (An,Kn,AV,KV,AVn,KVn) will not be trimmed during transmission. Only the received string will be trimmed | Default: OFF. Strings not trimmed on output. |
| StringCutting | OFF | While using An or Kn the string will cut at the given fixed size. If this feature is switched off a string longer than the given fixed size will cause an exception. This feature does not touch the data types AVn and KVn. If an AVn or KVn was longer than the given maximum size an exception will be thrown. | Default: ON. Strings that are too long are cut. |
| ExactValue | ON | Check N,P,NU,PU data types after converting from a double to the data type used for internal transmission, if the value was still exactly the same. If the feature is on, it will cause an exception if the value was not exactly the same. The feature is only valid if the "Numeric/Packed decimal to double" (see Setting DCOM Wrapper Properties) switch was on while the DCOM object was being generated. See also IDL Data Types. | Default: OFF. No verification of any modification during value conversion (string/number to number). |
put_Feature("<feature>", <true|false>)
get_Feature("<feature>") return a Boolean value
where <feature> is one of the features in the table above.
Dim STrim as Boolean
obj.put_Feature "StringTrimming", True
STrim = obj.get_Feature("StringTrimming")
During the generation process, the DCOM Wrapper object links the shared C Runtime library (CRT) of the used C/C++ compiler environment. The version and the name of the C Runtime library depends on the vendor and version of the C/C++ compiler used. The required shared C Runtime library must be distributed together with the DCOM Wrapper object.
The requirement of the runtime environment for your C/C++ compiler is described in the product documentation of your C/C++ compiler.
The shared C Runtime (CRT) DLL was distributed by Microsoft in the past as a shared system component. The C Runtime libraries of newer Microsoft Visual C++ compilers are no longer considered system files; therefore, the C Runtime libraries have to be distributed with any application that relies on them.
| C++ Compiler | C Runtime |
|---|---|
| Microsoft Visual C++ .NET 2002 | Msvcr70.dll |
| Microsoft Visual C++ .NET 2003 | Msvcr71.dll |
| Microsoft Visual C++ .NET 2005 | Msvcr80.dll |
| Microsoft Visual C++ .NET 2008 | Msvcr90.dll |
| Microsoft Visual C++ .NET 2010 | Msvcr100.dll |
For more information see Microsoft Support document 326922.
Each ActiveX automation server must be registered (in the Windows registry) so that it is recognized as an ActiveX object. When you run the Wizard, the generated Wrapper object is registered automatically. You can also register an automation object manually. This is necessary if you want to transfer the Wrapper object to another machine, or when you move the generated object to another directory.
To register the Wrapper object
Run the program Regsvr32.exe with the full name of the Wrapper object (generated DLL) as parameter. Regsvr32.exe is part of Microsoft Visual C++. A copy is installed in the Windows system directory.
Make sure the path includes the directory
<drive>:\Program Files\Common Files\Software AG.
Otherwise Regsvr32 returns an error such as: LoadLibrary
("xyz.dll") failed. GetLastError returns 0x0000007e..
To unregister the Wrapper object
Run Regsvr32 with the
/u switch. This removes all registry entries for the
Wrapper object. You should do this before deleting the generated object,
otherwise the system registry will contain unwanted entries.
To use a Wrapper object on a machine other than the machine on which
you generated the object
Make sure that EntireX Runtime is installed on the machine on which you want to use the Wrapper object.
Copy the generated object and then register the Wrapper object as described under Registering a Wrapper Object above.
You can use objects generated by the DCOM Wrapper with DCOM on Windows platforms. A Wrapper object installed on one Windows machine that performs Remote Procedure Calls via EntireX Broker can be accessed from other clients via DCOM.
To enable use of DCOM
Check the Generate DCOM proxy box in the Software AG Designer before generating the object.
The generated object (e.g. Example.dll) must be installed on the machine that will access the Broker (see Deployment of Wrapper Objects). This object is ready to be used as a DCOM server. The security/identity settings for this object can be changed with the DCOMCNFG.EXE utility.
The proxy object (e.g. pExample.dll) must be registered on every DCOM client machine. The purpose of the proxy object is twofold:
To register and unregister the Wrapper object on the client machines (registration on a DCOM client machine is different from registration on a DCOM server machine).
To provide the type library for applications running on the client side.
For more information, see Proxy Objects with the DCOM Wrapper.