Using COM Technologies in Microsoft Dynamics NAV

Article
06/05/2016

Dynamics NAV supports COM technologies in two ways: using custom controls (OCXs) and as an automation controller.

Limitations

The COM support has the following limitations:

Only non-visual controls are supported. A control cannot be used to add graphical elements to a Dynamics NAV object. For example, you cannot add a third-party control to a page. However, the control can display information and interact with the user in a window of its own.
Exception handling is not supported. Information about exceptions cannot be retrieved from a control or automation server through the Invoke method of the IDispatch interface and the EXCEPINFO structure.
Unlike Microsoft Dynamics NAV 2009, automation objects in Microsoft Dynamics NAV 2018 cannot target the computer that is running the Microsoft Dynamics NAV Server. Only client-side automation objects are supported. Instead of implementing server-side automation object, you can use Microsoft .NET Framework Interoperability. For more information, see Extending Microsoft Dynamics NAV Using Microsoft .NET Framework Interoperability.

Parameters, Return Values, and Data Types

The mechanisms for calling methods in a control, passing parameters, and receiving return values are somewhat complex. Using tools such as the wizards in Microsoft Visual C++ shields you from most of the complexities. However, there is no one-to-one relationship between the data types that you can use when you implement methods in, for example, Visual C++ and the data types in C/AL. Some of the COM data types are not supported in C/AL and some have a limitation imposed on their usage.

When you use the C/AL Symbol Menu, you can see the syntax for a method or property that has the return value and the parameters shown with the COM data types.

Mapping C/AL Data Types to COM Data Types

The following table shows how C/AL data types map to COM data types.

C/AL data type	COM data type	Comment
Boolean Data Type	VARIANT_BOOL (VT_BOOL)
Option Data Type	long (VT_I4)
Integer Data Type	long (VT_I4)
BigInteger Data Type	long (VT_I4)
Decimal Data Type	CURRENCY (VT_CY)	The CURRENCY type in COM is a special data type with a fixed point that has 15 digits to the left of the decimal point and 4 to the right. The Decimal type in C/AL does not have a fixed point and can have a total of 18 digits. This could lead to rounding being performed when a Decimal type number is passed to a method that expects a CURRENCY. The server changes that number and returns it as a CURRENCY. No matter how many digits the original Decimal had to the right of the decimal point, the returned CURRENCY will have no more than 4 digits.
Char Data Type	BSTR (VT_BSTR)
Text Data Type	BSTR (VT_BSTR)
Code Data Type	BSTR (VT_BSTR)
Date Data Type	DATE (VT_DATE)
Time Data Type	void (VT_VOID)
DateTime Data Type	DATE (VT_DATE)
Automation Data Type	TypedObject, UntypedObject (VT_DISPATCH)
InStream	VT_STREAM
OutStream	VT_STREAM
Variant Data Type	VARIANT (VT_VARIANT)

Mapping COM Data Types to C/AL Data Types

The following table shows how to map COM data types to C/AL data types.

COM data type	C/AL data type	Comment
VT_UNKNOWN	InStream and OutStream Data Types	Only the IID_IStream and IID_SequentialStream interfaces are supported. If you pass any other IUnknown interface, an error will occur at runtime.
short (VT_I2)	Integer Data Type
long (VT_I4)	Integer Data Type BigInteger Data Type
float (VT_R4)	Decimal Data Type
double (VT_R8)	Decimal Data Type
CURRENCY (VT_CY)	Decimal Data Type	The CURRENCY type in COM is a special data type with a fixed point, which has 15 digits to the left of the decimal point and 4 to the right. The Decimal type does not have a fixed point and can have a total of 18 digits.
DATE (VT_DATE)	Date Data Type DateTime Data Type	The COM DATE type contains both a date and a time value. C/AL has Date and Time as separate data types. Therefore, the time part of a COM DATE type will be lost when the COM DATE type is mapped to the Date C/AL data type. To keep the date and the time, map the COM Date type to the C/AL DateTime data type.
BSTR (VT_BSTR)	Text Data Type
VARIANT_BOOL (VT_BOOL)	Boolean Data Type
TypedObject/ UntypedObject (VT_DISPATCH)	Automation Data Type OCX Data Type
VT_EMPTY	Text Data Type
VARIANT (VT_VARIANT)	Variant Data Type

Unsigned char (VT_UI1), SCODE (VT_ERROR), and SAFEARRAY (VT_ARRAY)

You can use the C/AL variant data type to pass unsigned char, SCODE, or SAFEARRAY to another variant that supports these types. You cannot assign them to C/AL data types.

Remarks

When you call a method with a ByRef parameter, the typical C/AL type conversions do not occur. For example, this means that if the parameter is of type float, you have to use a C/AL variable of type Decimal. You cannot use Integer and have C/AL convert it for you.

Note

If the value that you want to pass has the incorrect type, when, for example, it is a value from a database record field, then you can assign it to a C/AL variable of the correct type before you call the COM object method.

You will sometimes see a COM object method or a property in the C/AL Symbol Menu that has type IDispatch. This means that the method or property returns or expects a COM object. In this case, you must use a C/AL Automation variable that has been declared, through the Subtype, to be the correct COM object. You will have to study the documentation for the automation server to gain the necessary information.

You will also see properties and methods that do not have one of the expected types. For example, a method in Microsoft Office Excel can have a return value of type WORKBOOK. This means that the automation server has implemented a USERDEF type. Dynamics NAV supports USERDEF types in two contexts: IDispatch and Enumeration.

If the USERDEF type is an IDispatch, it means that it is an interface (sometimes also called class or object) with a specific GUID. You will have to use the same object for a return value or parameter. You do this by creating an Automation variable with the correct subtype. For example, Microsoft Excel has several methods that return a WORKBOOK variable. This means that you must declare a variable of type Automation and subtype 'Microsoft Excel 8.0 Object Library'.Workbook.

If the USERDEF type is an enumeration, you cannot use the symbolic name, for example, xl3DPie, but instead must use the enumerator, for example, -4102. For Microsoft Office products, you can find this value by using the VBA Object Browser.

Share via